T-7D9E-design-deterministic-site
Status: closed/done · Impact: high · Complexity: large
Produce the design every M-0005 implementation task depends on: how the docs site becomes a pure build artifact (deterministic assembly of pages and nav from planning entities, plugin surface, and declared supplemental content), the supplemental-content mapping API and its collision semantics, how each planning entity type projects onto the site, and where the supporting code lives — module layout, per-entity placement, templating, and CLI surface.
| Location | Role today |
|---|---|
plugin/lib/services/docs/site.ts | Generates reference pages, glossary/references rosters + child pages, data-model page, appendix_sidebar.mjs; pages built by string concatenation |
site/astro.config.mjs | Hand-maintained sidebar except the Appendix splice |
site/src/content/docs/ | Generated content root with seven undeclared hand-written pages inside it; no collision detection |
docs/planning/<plural>/ | Planning corpus with no site projection (only terms/references project) |
Proposed
Section titled “Proposed”D-0010-deterministic-site-assembly — authored alongside this task
and reviewed in the same PR. It specifies: the pure-build-artifact
ownership rule with banner-split foreign-file handling; the
site/site.yaml manifest (site/supplemental/ authoring home,
two-level nav, mixed supplemental/generated groups); the route
registry with NAMESPACE_CONFLICT collision failures; the generated
sidebar module; the generic-plus-overrides projection framework; the
generated Roadmap page; Eta templating for all page families; and the
--check drift gate. Its Migration section enumerates the eight
implementation phases that become M-0005’s member tasks.
Approach
Section titled “Approach”- Aggregate prior art: D-0009/D-B4CA pattern, T-ETML coupling
concern, M-GJBW site-strategy overlap, current
site.tsand nav state. (done) - Resolve scope with the user: full-corpus projections, supplemental authored outside the content root, roadmap generated, 3-stage PR stack. (done)
- Author D-0010 with options-considered tables and a phased migration plan. (done)
- Review via this PR; on acceptance flip D-0010 to
open/acceptedand close this task.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
docs/planning/decisions/D-0010-deterministic-site-assembly.md | new | The design |
docs/planning/milestones/M-0005.md | new | The milestone this task roots |
docs/planning/milestones/M-GJBW.md | modify | Relevance note: site-strategy slice lands via D-0010/M-0005 |
docs/index.md | modify | Regenerated (new entities) |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: D-0010 specifies the ownership rule, manifest shape, collision semantics with exit code, nav generation, projection framework with override mechanism, templating, and CLI surface — concretely enough that each migration phase is implementable without further design sessions.
- AC-2: Every D-0010 migration phase maps to exactly one member
task under M-0005 with
depends_onedges (created in the follow-up tickets PR). - AC-3: D-0010 reviewed and flipped to
open/accepted.
Out of scope
Section titled “Out of scope”- Implementation of any phase — member tasks own that.
- M-GJBW’s taxonomy/audience/drift strategy.
Dependencies
Section titled “Dependencies”- Stacked on the D-0009-reference-entity-and-docs-appendix implementation chain (PRs #335–#342) — the projection framework generalizes its P6 pattern.
Discovery context
Section titled “Discovery context”Commissioned 2026-06-06 in-session: aggregate site/docs prior art into a distinct milestone with a dependency tree of tasks, root task defining the plan, stacked PRs atop the D-0009 reference-entity work.