0%

Section 06: Plan/Bug Schema Extension

Goal: An additive, optional spec_clause_refs[] field lands in plan_corpus schemas, coordinated with the sibling plans/compiler-spec-system effort via a shared corpus discriminator, as a MINOR (not MAJOR) schema-version bump.

Success Criteria:

  • spec_clause_refs: list[SpecClauseRef] | None = None added to PlanSectionSchema/FixBugSchema (and any other section-bearing schema), each entry {clause_id, corpus: "language"|"compiler"}
  • scripts/plan_corpus/version.py CURRENT_SCHEMA_VERSION bumped by exactly 1 (MINOR axis) with a paired migration module at scripts/plan_corpus/migrations/<NNN>_spec_clause_refs.py
  • Field is genuinely additive: existing plans/bugs with no spec_clause_refs remain valid (no retroactive requirement); prose-scrape resolution stays the fallback

Context: All 4 /tp-help reviewers (round 1) converged independently on unifying this citation mechanism with plans/compiler-spec-system’s parallel compiler_spec_refs[] effort rather than building two divergent implementations. Per scripts/plan_corpus/version.py’s own bump policy: “a v7 -> v8 bump is a NEW schema family… BANNED outside a dedicated, user-authorized plan-schema-upgrade plan” — this field MUST stay additive/optional to keep the bump MINOR.

Depends on: Section 02 (field shape design).

Intelligence Reconnaissance

Queries run 2026-07-09: scripts/intel-query.sh plan-status compiler-spec-system -> 7 sections, not-started, zero active work — confirmed safe to coordinate now since no conflicting implementation has landed yet.

Results summary [ori]: plans/compiler-spec-system is not-started; this section’s shared-field design can land first with zero migration conflict risk.

06.1 Additive Schema Field

File(s): scripts/plan_corpus/schemas/section_schemas.py, scripts/plan_corpus/migrations/

  • Add spec_clause_refs: list[dict] | None = None field per the Section 02 shared shape; bump CURRENT_SCHEMA_VERSION by 1; author the paired migration module (VERSION, DESCRIPTION, up(consumer_root) -> MigrationReport, matching the exact pattern from migrations/012_binding_constraints.py)

  • Subsection close-out (06.1)

    • Field validated additive: existing plan_corpus test suite passes unchanged with no spec_clause_refs present on any existing plan/bug

06.2 Cross-Plan Coordination Note

  • Record (in this plan’s decisions/ or 00-overview.md Known Bugs/Cross-Plan section — NOT by editing plans/compiler-spec-system’s files directly, which is out of this plan’s ownership) that plans/compiler-spec-system’s future execution should consume this SAME spec_clause_refs[] field with corpus: "compiler" rather than inventing a separate compiler_spec_refs[] field

  • Subsection close-out (06.2)

    • Coordination note recorded and cross-linked

06.R Third Party Review Findings

  • None.

06.N Completion Checklist

  • All subsections (06.1-06.2) [x], status complete
  • CURRENT_SCHEMA_VERSION bumped by exactly 1; migration module present
  • ./test-all.sh green — no regressions
  • /tpr-review passed
  • /impl-hygiene-review passed

Exit Criteria: spec_clause_refs[] field lands additively; migration authored; cross-plan coordination recorded.