T-REFM-docs-site-deep-dive

Status: closed/done · Impact: medium · Complexity: medium

Goal

The reference half of the site regenerates from the registry (T-YXM5-site-docs-long-tail), but the hand-written half — index, architecture/*, roadmap, changelog — still narrates the pre-migration system. Deep-dive every hand-written page against the shipped substrate so the site tells one coherent, current story.

Today

Location	Role today
site/src/content/docs/index.md	front page; predates the path[] surface
site/src/content/docs/architecture/overview.md	architecture narrative; pre-D-H7FS
site/src/content/docs/architecture/deterministic-first.md	head/tail story; predates —output contract + render hooks
site/src/content/docs/architecture/data-model.md	entity model; verify against current entities/ops
site/src/content/docs/architecture/harness-agnostic.md	adapter story; predates defineService + projection contract
site/src/content/docs/architecture/github-ref-leases.md	lease narrative; lease noun now registry ops at services/lease
site/src/content/docs/roadmap.md	predates M-0003 completion
site/src/content/docs/changelog.md	no migration entry

Proposed

Every hand-written page semantically verified against the live plugin and rewritten where it drifts: the architecture set describes the op substrate (path[] registry, discovery walk + service peers, generated CLI trie, —output contract, defineService, OpError/SERVICE_ERROR) with refreshed Mermaid diagrams; index reflects the single sdlc surface; roadmap marks M-0003 shipped and points at the genuine next horizon (MCP/HTTP adapters, T-902K transitions, T-U72C); changelog gains a substantive migration entry. Cross-links resolve; build green; dev-update-docs reports no drift.

Approach

1. Read D-H7FS + D-0007 (as amended) + the milestone; inventory each hand-written page’s claims vs the live code.
2. Rewrite architecture/* with current Mermaid diagrams (registry composition, dispatch flow, output contract 2×2, service lifecycle).
3. Refresh index.md and roadmap.md; author the changelog migration entry (surface table summary, breaking notes: scripts/validators deleted, CLI is the only entry).
4. Cross-link audit (internal links + links into /reference/ops).
5. Gates: site build; dev-update-docs semantic verify clean; no stale plugin/scripts/validators/<noun> <verb> shape language.

Files to touch

Location	Kind	Change
site/src/content/docs/index.md	modify	current surface story
site/src/content/docs/architecture/overview.md	modify	substrate narrative + diagram
site/src/content/docs/architecture/deterministic-first.md	modify	output contract, render hooks
site/src/content/docs/architecture/data-model.md	modify	verify/refresh
site/src/content/docs/architecture/harness-agnostic.md	modify	projection contract, defineService
site/src/content/docs/architecture/github-ref-leases.md	modify	lease ops surface
site/src/content/docs/roadmap.md	modify	M-0003 shipped; next horizon
site/src/content/docs/changelog.md	modify	migration entry

Acceptance criteria

• AC-1: every architecture page’s claims verified against live code (cite file:symbol per claim in the PR); diagrams render.
• AC-2: changelog carries the M-0003 migration entry incl. breaking changes.
• AC-3: site build green; internal links + /reference/ops links resolve.
• AC-4: grep for plugin/scripts, plugin/validators, and sdlc <noun> <verb> shape language across site/src/content/docs (non-reference) → zero stale hits.

Out of scope

• Reference pages (registry-generated, T-YXM5).
• docs/planning corpus prose.
• New feature documentation beyond what shipped.

Dependencies

• T-HHR4-retire-skill-forwarders — merged; the surface is final.

Discovery context

• Requested at M-0003 close-out: the reference half regenerates, but the narrative half still describes the pre-migration system. Capstone member of M-0003.

Depends on

T-HHR4-retire-skill-forwarders

---

← Back to Tasks