Section 05: plan_corpus Schema v3 + Subsumption Validators

Goal: Make subsumption a first-class schema concept — subsumes: and subsumed_by: are typed fields the corpus validator can enforce, not free-form prose subject to reviewer interpretation.

Success Criteria: see frontmatter.

Implementation Sketch

scripts/plan_corpus/ already validates plan-bug relationships for blocked-by: (BUG_BLOCKER_CYCLE, BUG_BLOCKER_DEAD_REF — see CLAUDE.md §Bug-Bug Blocker Chains for the precedent at validate_bug_blocker_corpus in scripts/plan_corpus/bug_validators.py:484+). Subsumption follows the same pattern with three additions beyond blocked-by::

1. Bidirectional pointer enforcement — unlike blocked-by: which is one-directional (bug A blocks bug B; B doesn’t claim A back), subsumption REQUIRES both directions (plan claims bug; bug claims plan). The validator MUST check both ends.
2. Conflict detection with blocked-by: — same bug cannot be both subsumed and a prerequisite (§01 banned pattern). Cross-field validator emits SUBSUMES_AND_BLOCKED_BY_CONFLICT.
3. Bug-bug blocker-chain orphan detection — when a subsumed bug is target of another bug’s blocked_by: chain (e.g., BUG-04-111 blocked_by: ["BUG-04-118"] per bug-tracker/plans/BUG-04-111/00-overview.md:5-6), filtering the subsumed bug from the queue (per §04) leaves the dependent pointing at hidden work. Validator emits SUBSUMED_BLOCKER_ORPHAN unless the dependent is ALSO subsumed by the same plan OR the blocker-edge has been rehomed to point at the owning plan.

Schema-version bookkeeping (corrected per Step 4 blind-spot 2): the prior plan revision claimed schema-v3 was the new version, but scripts/plan_corpus/version.py:33 already reads CURRENT_SCHEMA_VERSION: int = 3, and migrations/003_in_review_status.py already exists. This section ships v4 with migrations/004_subsumption_fields.py. Per routing.md §5 Migration precedent (schema v1 → v2 ordering primitives), forward-only migration backfills defaults; consumer pin advances on next sync.

Pre-flight race guard (per Step 4 blind-spot 10 + Risk #2 in 00-overview.md): §05.1 first item runs python -m scripts.plan_corpus check --json and asserts zero MIGRATION_REQUIRED findings before committing the v3 → v4 bump. If §27 (skill-ecosystem-coherence) has not yet cleared the bulk-stamp, §05 BLOCKS — does not begin migration authoring until §27 closes.

OverviewSchema housing (per scripts/plan_corpus/schemas.py:217-235): the schema is shared by plan overviews + bug overviews + roadmap overviews. The new subsumes: field lives here for plan overviews; the new subsumed_by: field lives here for bug overviews. Schema validation differentiates by overview type (plan vs bug vs roadmap) — verify the existing differentiation pattern by reading :217-235 in implementation; if no differentiation exists today, add a discriminator (e.g., presence of bug: block ⇒ bug overview ⇒ allow subsumed_by:, disallow subsumes:).

Implementation Items

• §05.1 PRE-FLIGHT (blocking gate). Run python -m scripts.plan_corpus check --json | jq '[.findings[] | select(.subtype == "MIGRATION_REQUIRED")] | length'. Assert result is 0. If non-zero, BLOCK §05 — §27 (skill-ecosystem-coherence) must clear the bulk-stamp first per cross-plan depends_on:. Document the pre-flight outcome in this section’s HISTORY block before proceeding.
• §05.1 Add subsumes: list[SubsumptionClaim] field to the plan-overview path of OverviewSchema (per scripts/plan_corpus/schemas.py:217-235). Define @dataclass class SubsumptionClaim with fields bug: str, verification_test: str, subsumption_evidence: dict. Default subsumes: list = [] (factory-default, not shared mutable). Per-entry validation: claim.bug matches ^BUG-\d{2}-\d{3}$; claim.verification_test is a non-empty string; claim.subsumption_evidence is a dict with keys replaced_subsystem (str), root_cause_pointer (str), verification_test_pointer (str).
• §05.1 Add subsumed_by: str | None field to the bug-overview path of OverviewSchema. Default None. Non-null regex validation: ^plans/[a-z][a-z0-9-]*/$. Add discriminator if OverviewSchema does not already differentiate plan vs bug overviews (presence of bug: block ⇒ bug overview).
• §05.1 Extend OVERVIEW_STATUSES (scripts/plan_corpus/schemas.py:43): add subsumed, abandoned. Extend FIX_STATUSES (:44): add subsumed. SECTION_STATUSES unchanged. Verify existing tests still pass under the broadened enums.
• §05.1 Add cross-field invariant validators to the schema layer:
  • subsumed_by: set requires status == "subsumed" (or vice versa).
  • subsumes: non-empty disallowed on bug overviews; subsumed_by: disallowed on plan overviews.
  • SubsumptionClaim entries with duplicate bug values within a single plan rejected (no double-claim).
• §05.2 Author scripts/plan_corpus/migrations/004_subsumption_fields.py. Forward migration: read every plan-overview, write subsumes: [] if absent; read every bug-overview, write subsumed_by: null if absent. Preserve all existing fields. Idempotent (re-running on already-migrated plans is no-op). Use the existing migration framework — model after migrations/003_in_review_status.py.
• §05.3 Bump scripts/plan_corpus/version.py CURRENT_SCHEMA_VERSION 3 → 4 (NOT 2 → 3). Update consumer-pin protocol per /sync-from-orilang Step 6.5: pin file advances on next sync. Verify the existing invariant CURRENT_SCHEMA_VERSION == latest_registered_version() holds (ensures 004_subsumption_fields.py lands BEFORE the version bump per version.py:24-31 documentation).
• §05.4 Author validate_subsumes_corpus() in scripts/plan_corpus/bug_validators.py. Model the function shape after the existing validate_bug_blocker_corpus() at :484+. Algorithm — 5 passes:
  • Pass 1 (per-plan): for each plan with non-empty subsumes:, for each claim in the array: verify bug-tracker/plans/<claim.bug>/00-overview.md exists; verify bug’s frontmatter subsumed_by: equals plans/<plan-name>/; verify bug’s status == "subsumed". Emit SUBSUMES_DEAD_REF with sub-classification per failure mode (missing-bug / wrong-pointer / wrong-status).
  • Pass 2 (per-bug): for each bug with non-null subsumed_by:: verify owning plan exists; verify plan’s subsumes: includes a claim with claim.bug == this-bug-id. Emit SUBSUMED_BY_DEAD_REF per failure.
  • Pass 3 (cross-field per-plan): for each plan, intersect claim bug set with the plan’s blocked-by: set. Non-empty intersection → emit SUBSUMES_AND_BLOCKED_BY_CONFLICT Critical per overlapping bug.
  • Pass 4 (verification-test resolution): for each claim, attempt to resolve claim.verification_test via git ls-files or Path.exists. Unresolved → emit SUBSUMES_TEST_REF_DEAD Major.
  • Pass 5 (bug-blocker orphan, per Step 4 blind-spot 9): for each subsumed bug B, scan all bug overviews for blocked_by: arrays containing B’s id. For each dependent D found: emit SUBSUMED_BLOCKER_ORPHAN Major UNLESS (a) D is also in plan’s subsumes: (co-subsumed) OR (b) D’s blocked_by: for B has been replaced with a path-style reference plans/<plan>/ (rehomed). Cite the BUG-04-111 → BUG-04-118 chain at bug-tracker/plans/BUG-04-111/00-overview.md:5-6 as the canonical example exercising this pass.
  • All passes return list[Finding]; severity per the success_criteria block; per-finding metadata includes the bug-id, plan-name, and sub-classification.
• §05.4 Add unit tests for each pass in compiler_repo/tests/plan-audit/ (or analogous test dir) — mirror the existing validate_bug_blocker_corpus test pattern. Fixture corpus: synthetic plans + bugs covering each pass’s positive and negative cases.
• §05.5 Cross-reference category names. Add a comment block in bug_validators.py near the validator citing impl-hygiene.md §Finding Categories — STRUCTURE as the host of the category definitions; do NOT inline definitions. The host file is owned by skill-ecosystem-coherence §22 (in-progress); coordinate with that section’s close so category text lands there. Five new categories register: SUBSUMED_BY_DEAD_REF, SUBSUMES_DEAD_REF, SUBSUMES_AND_BLOCKED_BY_CONFLICT, SUBSUMES_TEST_REF_DEAD, SUBSUMED_BLOCKER_ORPHAN.
• §05.6 Cross-plan sequencing. Frontmatter depends_on: on this section already includes ["01"]; ADD cross-plan dependency declared in section text: cross_plan_depends_on: ["plans/skill-ecosystem-coherence/section-27-plan-migration-and-schema-version.md"] (frontmatter convention TBD per routing.md §5 ordering primitives — if cross_plan_depends_on is not yet a schema-blessed key, encode as <!-- cross-plan-blocked-by: plans/skill-ecosystem-coherence/section-27-... --> HTML comment per existing convention). /continue-roadmap resolves the chain before §05 begins. Verify §27’s MIGRATION_REQUIRED bulk-stamp completed before §05 commits its v4 bump (already enforced by §05.1 pre-flight).

Test Strategy

This section modifies plan-corpus schema. Test matrix:

Semantic pins (Rust-style positive/negative pin discipline applies even though this is Python-side):

• Positive: bidirectionally-correct subsumes: + subsumed_by: pair validates clean. Reverting either side surfaces SUBSUMES_DEAD_REF or SUBSUMED_BY_DEAD_REF.
• Negative: bug appearing in BOTH subsumes: of plan-A AND blocked-by: of plan-A → SUBSUMES_AND_BLOCKED_BY_CONFLICT Critical. Test that this configuration is REJECTED, not silently absorbed.
• Migration idempotency: running 003_subsumption_fields.py twice produces same output as running once.

Intelligence Reconnaissance

(2026-05-09) Section modifies scripts/plan_corpus/schemas.py (PlanIndexSchema, BugPlanSchema), scripts/plan_corpus/bug_validators.py (new validate_subsumes_corpus), scripts/plan_corpus/version.py (CURRENT_SCHEMA_VERSION bump), and authors scripts/plan_corpus/migrations/003_subsumption_fields.py. All targets are Python and graph-indexed. Pre-implementation graph queries reserved per compose-intel-summary.md Step D protocol — direct Read of existing schema classes suffices for the schema-extension pattern (BUG_BLOCKER_CYCLE / BUG_BLOCKER_DEAD_REF in validate_bug_blocker_corpus is the canonical precedent verified at bug_validators.py). At implementation time, callers PlanIndexSchema --repo ori, callees CURRENT_SCHEMA_VERSION --repo ori, file-symbols scripts/plan_corpus/migrations/ --repo ori MUST run to verify blast-radius before schema-version bump. Recording recon-deferred (not unavailable) per docs-vs-implementation distinction; recon executes when §05 begins implementation.

Cross-References

• §01 — routing rule the schema fields encode.
• §07 — lifecycle gates that READ schema fields to enforce reversibility.
• §08 — migration pass that POPULATES subsumes: on existing plans (data-side migration; this section is schema-side).
• plans/skill-ecosystem-coherence/section-22-structure-category-impl-hygiene.md (in-progress) — host of finding-category definitions referenced (NOT defined) here.
• plans/skill-ecosystem-coherence/section-27-plan-migration-and-schema-version.md (in-progress) — schema-version bookkeeping; §05 sequences after §27 closes.
• scripts/plan_corpus/schema.py BUG_BLOCKER_CYCLE / BUG_BLOCKER_DEAD_REF — established precedent for plan-bug relationship validation.

05.1

Add subsumes/subsumed_by fields to PlanIndexSchema + BugPlanSchema

• (placeholder — replace with concrete work that closes subsection 05.1)

05.2

Author migrations/003_subsumption_fields.py forward migration

• (placeholder — replace with concrete work that closes subsection 05.2)

05.3

Bump CURRENT_SCHEMA_VERSION 2 → 3

• (placeholder — replace with concrete work that closes subsection 05.3)

05.4

Author validate_subsumes_corpus() in bug_validators.py

• (placeholder — replace with concrete work that closes subsection 05.4)

05.5

Cross-reference impl-hygiene.md STRUCTURE block (owned by ecosystem §22)

• (placeholder — replace with concrete work that closes subsection 05.5)

05.6

Coordinate sequencing with ecosystem §27 (cross-plan depends_on)

• (placeholder — replace with concrete work that closes subsection 05.6)

05.R

Third Party Review Findings

• (placeholder — replace with concrete work that closes subsection 05.R)

05.N

Completion Checklist

• (placeholder — replace with concrete work that closes subsection 05.N)