0%

Section 07: Cutover & Command Repurposing

Goal: The markdown clause files, annexes, operator-rules.md, and grammar.ebnf become purely generated artifacts (checked in, never hand-edited); /sync-spec and /sync-grammar are repurposed into JSON-consistency validators.

Success Criteria:

  • .claude/rules/spec.md describes the new workflow: edit the JSON corpus under spec/corpus/, run the generator; the existing proposal-gate hook still applies to the whole v2026/spec/ tree unchanged
  • /sync-spec and /sync-grammar internals are repurposed to diff-check JSON-vs-generated-markdown consistency rather than manually reconcile prose; their command surfaces are preserved (not deleted)
  • Full retirement of the OLD manual-reconciliation logic inside those two commands is tracked as a dated follow-up gated on 3 successful post-cutover round-trip cycles — NOT executed in this section (a stalled/late-discovered round-trip issue must not force premature removal of the safety net)

Context: Per Step 8B /tp-help consensus (3-of-4 reviewers, corroborated by the user’s approved sequencing decision): repurpose, do not immediately fully retire. Premature removal of /sync-spec//sync-grammar’s reconciliation logic before the new pipeline has proven itself across multiple real edit cycles risks leaving no safety net if Section 04’s round-trip fidelity regresses after cutover.

Depends on: Section 01 (proposal approval); Section 04 (generator proven).

Intelligence Reconnaissance

Queries run 2026-07-09: read .claude/commands/sync-spec.md and .claude/commands/sync-grammar.md — both confirmed as LLM-driven markdown-to-markdown reconciliation commands (not scripts), existing specifically because spec content and grammar.ebnf drift by hand today.

Results summary [ori]: both commands’ reconciliation job becomes redundant once JSON is canonical, but their command SURFACES (invocation contract) are worth preserving as consistency-validators rather than deleting outright.

07.1 Cutover to Generated-Only

  • Mark all 34 clause/annex/operator-rules/grammar.ebnf files as generated-only in a header comment (or equivalent marker); the JSON corpus under spec/corpus/ becomes the sole hand-edited surface going forward

  • Subsection close-out (07.1)

    • Generated-only marker present; a test asserts hand-editing a generated file (not the JSON corpus) is caught by the round-trip harness on next generation

07.2 Update spec.md Workflow Description

File(s): .claude/rules/spec.md

  • Update the “Required workflow” section to describe editing the JSON corpus + running the generator, keeping the SAME proposal-gate mechanics (hook, ORI_SPEC_PROPOSAL/marker bypass) unchanged

  • Subsection close-out (07.2)

    • spec.md updated; prose-lint clean (per CLAUDE.md §NO PROSE)

07.3 Repurpose /sync-spec + /sync-grammar

  • Repurpose both commands’ internals into JSON-vs-generated-markdown diff-checkers; record the full-retirement trigger (3 successful post-cutover round-trip cycles) as a dated tracked item in this plan’s 00-overview.md Known Bugs/follow-up table — NOT executed now

  • Subsection close-out (07.3)

    • Both commands repurposed; full-retirement trigger recorded with a concrete, checkable condition (not open-ended)

07.R Third Party Review Findings

  • None.

07.N Completion Checklist

  • All subsections (07.1-07.3) [x], status complete
  • spec.md updated and prose-lint clean
  • ./test-all.sh green
  • /tpr-review passed
  • /impl-hygiene-review passed

Exit Criteria: All spec artifacts are generated-only; spec.md reflects the new workflow; /sync-spec//sync-grammar repurposed with a tracked full-retirement trigger.