Site Index Source Policy (M132-C002)

site/index.md is generated output. Manual edits are unsupported.

Generated-Only Policy

  • Canonical output: site/index.md
  • Canonical generator: python scripts/build_site_index.py
  • Canonical drift check: python scripts/build_site_index.py --check
  • CI must fail when generated output drifts from canonical inputs.

Canonical Inputs

Generation input ownership is deterministic and ordered:

  1. site/src/index.contract.json defines the generator contract (site/src/index.body.md, output path, and front matter).
  2. site/src/index.body.md is the canonical public-facing source for the generated site.
  3. The site is a curated overview of the specification and current implementation status; it is not a stitched mirror of spec/*.md.
  4. README.md inputs are excluded from generated output.
  5. Site source files may mark machine-facing appendices with <!-- SITE:EXCLUDE-START --> / <!-- SITE:EXCLUDE-END -->; those blocks are omitted from generated output.

Ownership

  • Source of truth for public site content: site/src/index.body.md.
  • Source of truth for render behavior and policy checks: scripts/build_site_index.py + site/src/index.contract.json.
  • Source of truth for generated bytes: re-run generator and commit updated site/index.md.

Tone and Accessibility Rules

Public site content must optimize for first-read comprehension:

  • lead with current status before future intent,
  • use plain language before implementation jargon,
  • define specialist terms by context instead of assuming prior repo knowledge,
  • prefer short lists and comparison tables over dense paragraphs,
  • give readers a direct next link when a section names a deeper path,
  • keep generated artifact paths and proof inventories out of the public overview unless they are the point of the section.

Non-goals for the public site:

  • milestone closeout narration,
  • machine-facing packet inventories,
  • unexplained abbreviations or internal shorthand,
  • treating the site as a mirror of the archived spec/ corpus.

Manual Edit Policy

If site/index.md was edited directly, treat it as drift:

  1. Re-run python scripts/build_site_index.py.
  2. Review resulting diff against intended source edits under site/src/.
  3. Commit generated output after source-of-truth inputs are correct.