T-9LZ4-site-supplemental-migration
Status: closed/done · Impact: medium · Complexity: medium
Move the hand-written pages out of the generated content root and
mirror them back in through the manifest — after this task, zero
undeclared files live under site/src/content/docs/ and the §1
ownership sweep can enforce that invariant for good.
D-0010-deterministic-site-assembly §2, Migration Phase 3.
| Location | Role today |
|---|---|
site/src/content/docs/index.md | Hand-written landing page inside the generated root |
site/src/content/docs/architecture/ | Four hand-written prose pages (data-model is generated) |
site/src/content/docs/changelog.md | Hand-written release notes |
site/supplemental/ | Does not exist |
Proposed
Section titled “Proposed”supplemental.ts mirrors each manifest-declared page from
site/supplemental/ into the content root (route from path,
registered through the P1 registry; frontmatter passed through
verbatim). The landing slot maps site/supplemental/index.md to the
content-root index.md. The hand-written pages move:
index.md, architecture/{overview,deterministic-first, harness-agnostic,github-ref-leases}.md, changelog.md →
site/supplemental/, with site.yaml entries reproducing today’s
nav (Architecture group slots generated: data-model between its
file children).
Approach
Section titled “Approach”supplemental.ts: mirror step with route registration and pass-through frontmatter.landing:slot handling.git mvthe seven pages; write their manifest entries.- Verify: full pass leaves zero undeclared files; site build green; routes unchanged (same slugs).
- Tests: mirror fixtures, landing fixture, undeclared-supplemental fixture.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/lib/services/docs/site/supplemental.ts | new | Mirror step |
site/supplemental/ | new | The seven relocated pages |
site/src/content/docs/index.md | modify | Becomes mirrored output |
site/src/content/docs/architecture/ | modify | Prose pages become mirrored output |
site/src/content/docs/changelog.md | modify | Becomes mirrored output |
site/site.yaml | modify | Landing + Architecture group + changelog entries |
plugin/lib/services/docs/tests/ | modify | Mirror suites |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: After a full pass, every file under
site/src/content/docs/was placed by the generator (sweep reports zero foreign files). - AC-2: All seven page routes resolve unchanged; site build green.
- AC-3: Editing a page under
site/supplemental/and re-running the pass updates exactly that mirrored page. - AC-4: A file under
site/supplemental/absent from the manifest fails validation.
Out of scope
Section titled “Out of scope”roadmap.md— retired by T-9LHH-site-roadmap-generated; it stays hand-written in place until then.
Dependencies
Section titled “Dependencies”- T-G5ND-site-generated-sidebar — nav slots for
file:/group:entries.
Discovery context
Section titled “Discovery context”Extracted from D-0010-deterministic-site-assembly Migration Phase 3.