handbook: LLM-index discoverability (#90) + Quality Gate / AI Usage / Planning restructure (epic #92)

[github-actions]

Summary

This branch carries two changes:

1. LLM-index discoverability (closes #90)

Make /llms.txt and /llms-full.txt discoverable to page-reading agents: a
visible, server-rendered hint baked into the static HTML (not display:none,
not a hydrated component), plus a <link rel="alternate"> head hint and a
robots.txt LLM-index line. A neutral WebFetch of a page reliably surfaces
visible text; a hidden hint does not.

2. Handbook restructure — epic #92, fully delivered (closes #92)

Reorganise the handbook around OSBR's own spine — a 3-lens Quality Gate
(Reliability / Security / Sustainability) as the definition of done, an
AI-native operating model, and a pre-work Planning phase — keeping the
existing policies as the standards the gate references rather than restates.

• 33 full standard pages (12 Engineering Standards, 8 AI operating model,
  8 Planning, 4 Design, 1 Privacy Policy) with 4 concise hub pages; sidebar
  fully wired. Every Epic: Close the gaps between the handbook and the engineering standard #92 checklist item is closed — see the Epic: Close the gaps between the handbook and the engineering standard #92 full-delivery
  comment for the item-to-page mapping.
• Jurisdiction: legal pages ground on Malaysia's PDPA 2010 (+2024
  amendment), with Japan's APPI and the EU/US baseline layered on.
• Review mechanism: the AI code review is run by the engineer from their
  own agent (/code-review, asvs-audit) when a change is declared
  Impl Review — alongside CI, not part of it.
• Adversarial content review applied: contradictions found across the
  hubs/standards/legal pages (gate board position, PII-masking and
  real-dependency requirement levels, legacy dev-guide defects) were fixed in
  this PR.

Test Plan

• ✅ pnpm run docs:build passes locally (55 markdown files, llms-full.txt
  generated, zero errors).
• ✅ Sidebar/page integrity verified: 56 sidebar links = 56 pages, no dead
  links, no orphan pages, no dangling internal links, section anchors resolve.
• ✅ Previewed via docs:preview; new pages render and appear in the sidebar.
• ⏳ Post-deploy (the one open item, for LLMs don't discover /llms.txt — page-reading agents miss the LLM index #90's acceptance criterion): a
  neutral-prompt WebFetch of the deployed landing page returns the /llms.txt
  line. Run once after merge + deploy, paste the output here, then close LLMs don't discover /llms.txt — page-reading agents miss the LLM index #90.

🤖 PR body updated by Claude Code

[sn0wm1ku]

Checked this diff against the fix list in #90 — no gap found. All four layers are implemented:

#90 fix	Status	Where
1. Primary (load-bearing): visible, non-JS, server-rendered line on the landing page	✅	doc/index.md — plain markdown after the frontmatter, so SSG bakes it into the static HTML. Not display:none, not a hydrated component.
2. Convention: root /llms.txt + /llms-full.txt	✅	Already generated by vitepress-plugin-llms (doc/.vitepress/config.mts); no change needed.
3. Head (belt & suspenders): <link rel="alternate" type="text/plain">	✅	doc/.vitepress/config.mts. The comment correctly records why there's no matching HTTP Link: header (GitHub Pages is a static host).
4. robots.txt visible LLM-index line	✅	New doc/public/robots.txt. Verified this actually serves at /robots.txt: build root is doc (vitepress build doc), so publicDir resolves to doc/public — same directory as the already-served favicon.svg / logo1.svg.

Two notes, neither blocking:

• The acceptance criterion is still unverified. LLMs don't discover /llms.txt — page-reading agents miss the LLM index #90 asks for a neutral-prompt WebFetch of the landing page to return the /llms.txt line — that's only checkable after deploy, so it stays open until then. Worth running that one fetch post-merge before closing LLMs don't discover /llms.txt — page-reading agents miss the LLM index #90; it's the whole point of the issue and the only thing that proves page-reading agents stop missing the index.
• The PR checklist (§4 Self Review / Evidence) is unticked and §5 Evidence is empty. For this change the post-deploy neutral fetch output is the natural evidence to paste in.

Nothing for me to ticket here — the implementation matches the spec. Ready for review/merge, then verify.

---

_{🤖 auto-posted by sn0wm1ku/ghDuty · co-authored by Claude (claude-opus-4-8)}

[sn0wm1ku]

Follow-up to my 2026-07-15 comment — 15 new commits since (a81094f…9056bdc) grew this PR from the #90 fix into the full epic #92 delivery, so I re-checked the expanded scope. Still no gap found; nothing to ticket.

Epic #92 (restructure + 33 standard pages):

• All 33 pages listed in the Epic: Close the gaps between the handbook and the engineering standard #92 full-delivery comment are present in this diff (12 Engineering Standards, 8 AI operating model, 8 Planning, 4 Design, plus /privacy-policy), alongside the 4 hub pages (/quality-gate, /ai-usage-guideline, /design-guidelines, /ethical-design-policy).
• Sidebar wiring verified against config.mts at head 9056bdc: every new page is linked (Design Guidelines, Planning & Shaping, Quality Gate, and AI Usage Guideline groups nested under Development Guide; Ethical Design + Privacy Policy under Policies), and every sidebar link resolves to a page in this PR or a pre-existing doc.
• The Epic: Close the gaps between the handbook and the engineering standard #92 checklist itself has zero unchecked items remaining.

#90 (LLM-index discoverability): the four layers assessed in my previous comment are unchanged and intact.

Remaining before closing the issues — same two items as before, still non-blocking for review:

1. npm run docs:build has not been run anywhere yet (per the Test Plan). Worth one run where deps are installed before merge — 33 new pages is exactly where a dead internal link would surface.
2. LLMs don't discover /llms.txt — page-reading agents miss the LLM index #90's acceptance criterion (neutral-prompt WebFetch of the deployed landing page returning the /llms.txt line) is only checkable post-deploy.

One stale-wording nit: the PR body still says "see that issue's progress comment for the … still-open list", but the later #92 comment reports all items closed — worth a one-line body touch-up so reviewers don't hunt for a gap that no longer exists.

Ready for the requested review.

---

_{🤖 auto-posted by sn0wm1ku/ghDuty · co-authored by Claude (claude-opus-4-8)}

[sn0wm1ku]

Both non-blocking items from the ghDuty re-check are now addressed in the PR body:

1. docs:build — has been run locally (pnpm): 55 markdown files, llms-full.txt generated, zero errors; sidebar/page integrity checks (no dead links / orphans / dangling internal links) also pass. Test Plan updated to record this.
2. Stale "still-open list" wording — removed; the body now states epic Epic: Close the gaps between the handbook and the engineering standard #92 is fully delivered and points at the item-to-page mapping comment.

#90's neutral-WebFetch acceptance check remains the one post-deploy step, noted in the Test Plan.

🤖 Posted by Claude Code

[sn0wm1ku]

Reviewed across mechanical checks (no competitor mentions, no draft/XML leftovers, link + sidebar integrity, build passing) and an adversarial content pass (contradictions found were fixed in-branch: gate board position, requirement-level mismatches, review mechanism, jurisdiction grounding). ghDuty's re-check reports no gap; remaining item is #90's post-deploy verification, recorded in the Test Plan.

🤖 Approved via Claude Code on the author's instruction