0%

Section 04: Generator

Goal: A generator regenerates every markdown clause/annex file, operator-rules.md, and grammar.ebnf from the Section 03 JSON corpus, byte-for-byte identical to the untouched originals.

Success Criteria:

  • python -m scripts.spec_corpus generate --diff-only against the pre-cutover corpus reports zero diff for all 34 generated files (byte-for-byte, including grammar.ebnf per its flat-string storage)
  • website_repo’s Astro content-collection glob + zod docsSchema validate the regenerated files with ZERO website_repo code changes (read-only spot-check per the global per-file approval restriction on that repo)

Context: Blocked by Section 01 (writes land inside the hook-gated tree). Because grammar.ebnf is stored as a flat {name, section_grouping, raw_rhs} list (decisions/01), its round-trip fidelity gate is byte-for-byte identical to every other generated artifact — no separate “semantic equivalence” gate is needed.

Depends on: Section 01 (proposal approval); Section 03 (bootstrap corpus).

Intelligence Reconnaissance

Queries run 2026-07-09: website_repo/src/content.config.ts read in full — confirmed the Astro spec content collection glob pattern + zod docsSchema fields (title, description, order, section, sidebar_*) that the generator’s frontmatter output must match exactly.

Results summary [ori]: zero website_repo changes are structurally achievable since the website consumes these markdown files directly with no separate transform step.

04.1 Markdown + Operator-Rules Generator

File(s): scripts/spec_corpus/generator/markdown_generator.py

  • Implement JSON -> markdown generator for clause/annex files + operator-rules.md, preserving exact frontmatter field order and heading depth/numbering from the source Clause/Annex model

  • Subsection close-out (04.1)

    • Generator output byte-diffed against originals for all 4 research-sample files; zero diffs

04.2 grammar.ebnf Generator

File(s): scripts/spec_corpus/generator/grammar_generator.py

  • Implement JSON -> grammar.ebnf generator: fixed legend/header text + per-production raw_rhs strings grouped by section_grouping with their // See: comment restored verbatim

  • Subsection close-out (04.2)

    • Generated grammar.ebnf byte-diffed against the original; zero diff

04.3 Round-Trip Fidelity Harness

File(s): scripts/spec_corpus/tests/test_roundtrip.py

  • Implement the import -> generate -> diff test harness asserting zero diff for all 34 files against the pre-cutover v2026/spec/ tree (captured as a pinned baseline snapshot before any cutover)

  • Subsection close-out (04.3)

    • Harness runs in ./test-all.sh; asserts zero diff

04.4 Website Spot-Check (read-only)

  • Build the Astro site locally against the regenerated files (read-only; NO website_repo edits) and confirm it renders without error; if a change to website_repo DOES turn out to be needed, STOP and route it through the global per-file AskUserQuestion approval gate — do not edit website_repo directly

  • Subsection close-out (04.4)

    • Spot-check passes with zero website_repo edits, OR a needed change is documented and routed through the approval gate (not applied inline)

04.R Third Party Review Findings

  • None.

04.N Completion Checklist

  • All subsections (04.1-04.4) [x], status complete
  • Round-trip harness green in ./test-all.sh
  • Website spot-check passed with zero unauthorized website_repo edits
  • /tpr-review passed
  • /impl-hygiene-review passed

Exit Criteria: scripts.spec_corpus generate --diff-only reports zero diff for every generated artifact; website renders unchanged.