0%

Section 01 — spec scaffold

Goal

docs/compiler/spec/ living-standard structure + clean-room seam-test membership preamble + per-clause enforcement-binding requirement

Spec References

  • Clean-room seam test (membership rule): a fact belongs in the compiler spec iff a second, clean-room implementation of Ori would NOT be bound by it. Implementation-independent observable semantics -> language spec. This-compiler architectural commitments -> compiler spec. Code-incidental (crate names, module layout) -> descriptive design doc, NOT the spec.
  • Enforcement-binding rule (ABSOLUTE): no compiler-spec clause ships without a named enforcement binding — a test / lint / intel-graph check / CI assertion / accepted reviewer-gate that catches a violation. A clause with no binding is a wish, not a spec clause.
  • Bootstrap clause corpus is lifted from .claude/rules/ (canon.md PC-2/§7.1, parse.md ER-/LB-, typeck.md PC-2/SL-*, eval.md+missions.md dual-exec parity, compiler.md crate-DAG) — these are the SSOT seed (catchup = ratify-existing-first).

Implementation Sketch

  • The compiler spec lives at compiler_repo/docs/compiler/spec/ as a lock-governed living standard (stable clause numbers + CHANGELOG); docs/compiler/design/ is the descriptive tier below it.
  • Governance reuses the language-spec proposal+lock flow (create-draft-proposal -> review-draft-proposal -> block-*-edits hook), threaded with a compiler-spec category discriminator.
  • The binding requirement triggers on the clean-room seam test (owns_crates over the compiler workspace = compiler-design-touching).

Work Items

  • Author the living-standard structure: index.md + README.md (clause TOC) + CHANGELOG.md + NN-slug.md clause numbering, mirroring the language spec template.
  • Author the clean-room seam test as the membership preamble + ISO normative shall/may language + the MANDATORY per-clause enforcement-binding field.

Rules embedded for execution

  • TDD: any gate/hook/validator code (sections 03/04/06) writes the failing acceptance test FIRST, then the deliverable; debug + release both green (CLAUDE.md §Fix Completeness).
  • Spec-is-SSOT: a divergence between an implied invariant and the code is a /add-bug (the code is the bug), NEVER a weakened clause (§02.3).
  • Script-first: all gate/lock/classifier logic lands in scripts/create_plan_runtime/ + hook scripts with pytest coverage; the runtime is the sole plan.json writer.