Section 03: /review-plan Subsumption Staleness Validator

Goal: Catch subsumption drift between plan-creation time and review time — new bugs filed after plan creation that should also be subsumed; stale claims pointing at bugs that have re-classified or been closed.

Success Criteria: see frontmatter.

Implementation Sketch

/review-plan runs periodically on every plan as part of the regular review cycle. Subsumption claims made at plan-creation time (§02) drift over time: new bugs get filed in the plan’s subsystem; existing claimed bugs get reclassified or closed. The validator runs at every review and emits findings into the standard /review-plan finding pipeline.

Two finding categories:

The 3-signal test from §01 is heuristically applied to surface candidate SUBSUMES_STALE_NEW_BUG findings, but the validator never asserts subsumption itself — that violates §01 banned pattern (mechanical inference). The validator surfaces candidates; humans/agents decide.

Implementation Items

• §03.1 Add Subsumption Staleness Validation step to .claude/skills/review-plan/SKILL.md (or appropriate references file at .claude/skills/review-plan/references/subsumption-staleness.md). Document I/O: input = plan path; output = structured findings appended to TPR findings pipeline (categories: SUBSUMES_STALE_NEW_BUG, SUBSUMES_DEAD_REF, SUBSUMES_TEST_REF_DEAD).
• §03.2 Implement bug-enumeration helper. Query scripts/intel-query.sh bugs-for <subsystem> for each path in plan’s touches: (deduplicate by bug-id). Diff against plan’s subsumes: membership (the bug field of each SubsumptionClaim). Open or in-progress bugs not in subsumes: with creation timestamp post-plan-creation (heuristic: git log --diff-filter=A --format=%aI -- bug-tracker/plans/BUG-XX-NNN/00-overview.md | tail -1 > plan’s 00-overview.md first commit timestamp) are SUBSUMES_STALE_NEW_BUG candidates.
• §03.2 Filter candidates by §01 3-signal heuristic: a candidate surfaces only when ≥2 of the 3 signals fire heuristically. Reduces noise; full 3-signal confirmation requires author per §01 banned pattern (no mechanical assertion).
• §03.3 Implement bidirectional pointer integrity check. For each BUG-XX-NNN in plan’s subsumes:, verify bug-tracker/plans/BUG-XX-NNN/00-overview.md exists AND has subsumed_by: pointing back at this plan AND has status: subsumed. Mismatches → SUBSUMES_DEAD_REF (with sub-classification: missing-bug / wrong-status / pointer-mismatch).
• §03.3 Implement verification_test resolution check. For each claim’s verification_test field, run git ls-files <test-path> (or os.path.exists for paths outside the git index). Path that no longer resolves → SUBSUMES_TEST_REF_DEAD finding with resolution options in the finding text.
• §03.4 Implement auto-cleanup for safe SUBSUMES_DEAD_REF cases. If bug’s 00-overview.md does not exist (genuinely deleted/orphaned), remove the entry from plan’s subsumes: silently per feedback_auto_fix_cleanup.md. Log the silent fix in plan’s HISTORY block (“Auto-cleanup 2026-MM-DD: removed dead subsumes: reference to BUG-XX-NNN — bug no longer exists in tracker”). For bidirectional mismatch (bug exists but pointer-back is wrong), DO NOT auto-fix — report as a finding for human resolution.
• §03.4 Auto-cleanup BANNED for SUBSUMES_TEST_REF_DEAD (test-reference repair requires author judgment per §03 success criteria). All test-reference findings are reported, never silently mutated.
• §03.5 Wire findings into /review-plan standard finding pipeline. Findings file as - [ ] items per existing /review-plan filing convention; recorded under third_party_review.findings: if the review run produces a TPR-style report. Severity mapping: SUBSUMES_STALE_NEW_BUG → Major (STRUCTURE:routing-violation:subsumption-stale); SUBSUMES_DEAD_REF (non-auto-cleanup) → High; SUBSUMES_TEST_REF_DEAD → Major (STRUCTURE:routing-violation:subsumption-test-ref-dead).
• §03.5 Author the validator backbone in scripts/plan_corpus/bug_validators.py as validate_subsumes_staleness(plan_dir, bug_tracker_dir) for cross-skill reuse; /review-plan calls it; /review-bugs may call it in future. Wire to validate_subsumes_corpus (§05) which runs the basic integrity check; staleness is the additive check that needs touches: + bug-enumeration context.

Test Strategy

This section modifies /review-plan skill behavior. Test matrix:

Semantic pins:

• Positive: bug filed in plan’s subsystem after plan creation, fires all 3 signals → SUBSUMES_STALE_NEW_BUG finding emitted. Reverting the §03 logic causes the test to silently miss the drift.
• Negative: bug in subsumes: resolved out-of-band (status: closed), auto-cleanup branch silently removes the entry AND records HISTORY — but if the bidirectional pointer mismatched, NO auto-fix runs and a report-only finding is emitted instead.
• Idempotency: running the validator twice produces the same findings; no duplicate report emissions.

Intelligence Reconnaissance

(2026-05-09) Section modifies .claude/skills/review-plan/ (Markdown skill body) and scripts/plan_corpus/bug_validators.py (Python — graph-indexed). The validator algorithm consumes scripts/intel-query.sh bugs-for <subsystem> for current bug-state enumeration. Per compose-intel-summary.md, the skill-body edit is process-flow (no symbol-graph queries needed); the validator function IS Python and graph-queryable (callers validate_subsumes_corpus --repo ori would resolve once §05 ships, but does not exist yet at recon time). Recording graceful-degradation per section. Cross-references verified by direct Read: /review-plan/SKILL.md (Phase 2 design-validation step pattern), feedback_auto_fix_cleanup.md (auto-cleanup discipline), scripts/plan_corpus/bug_validators.py (existing validate_bug_blocker_corpus precedent verified for validate_subsumes_corpus shape).

Cross-References

• §01 — routing rule SSOT for the 3-signal test heuristic.
• §02 — classifier that creates the original subsumes: claims this validator audits.
• §05 — schema fields the validator reads (PlanSectionSchema.subsumes, BugPlanSchema.subsumed_by).
• feedback_auto_fix_cleanup.md — auto-cleanup discipline for SUBSUMES_DEAD_REF auto-fix branch.
• /review-plan SKILL.md — host skill; staleness validator lands as a Phase 2 step.

03.1 Add Subsumption Staleness Validation step to /review-plan SKILL.md

• Add ## Subsumption Staleness Validation step to .claude/skills/review-plan/SKILL.md Phase 2 (design-validation phase). Cite routing.md §2.X (§01 of THIS plan) as the routing SSOT.
• Document inputs: plan path. Outputs: structured findings list — categories SUBSUMES_STALE_NEW_BUG / SUBSUMES_DEAD_REF / SUBSUMES_TEST_REF_DEAD.
• Document the auto-cleanup carve-out: only SUBSUMES_DEAD_REF with sub-class missing-bug is auto-cleanup-eligible per feedback_auto_fix_cleanup.md. All others are reported.
• Add @-include reference to .claude/rules/routing.md (for §2.X) and .claude/skills/query-intel/compose-intel-summary.md (for the bugs-for query) at top of the new step per skill-template.md §2 SSOT consumption discipline.

03.2 Implement bug enumeration + diff against plan’s subsumes: list

• Author validate_subsumes_staleness(plan_dir, bug_tracker_dir) in scripts/plan_corpus/bug_validators.py. Returns list[Finding] with categories per §03.1.
• Implement Pass 1: enumerate current open|in-progress bugs in plan’s touched subsystems via scripts/intel-query.sh bugs-for <subsystem>; aggregate; deduplicate.
• Implement Pass 2: diff against plan’s subsumes: claim-bug-ids; new bugs (not in claim list, filed post-plan-creation per git log first-commit-timestamp comparison) become candidates.
• Implement Pass 3: heuristic 3-signal filter on candidates. Signal #1: bug’s subsystem: overlaps plan’s touches:. Signal #2: bug’s mission/symptom text matches plan’s mission text (substring match for now; embedding-based future). Signal #3: bug’s root-cause text mentions a path in plan’s touches:. Threshold: ≥2 of 3 signals fire heuristically → emit SUBSUMES_STALE_NEW_BUG Major finding for author resolution.
• Add fallback path when scripts/intel-query.sh status reports unavailable: git grep -l 'subsystem: \"<name>\"' bug-tracker/plans/*/00-overview.md per §02.2 fallback pattern.

03.3 Implement bidirectional pointer integrity check + verification_test resolution

• Implement Pass 4: per claim in plan’s subsumes:, verify bug-tracker/plans/<claim.bug>/00-overview.md exists. Missing → SUBSUMES_DEAD_REF/missing-bug.
• Implement Pass 5: per claim, read bug’s frontmatter subsumed_by:; verify it equals plans/<plan-name>/. Mismatch → SUBSUMES_DEAD_REF/pointer-mismatch.
• Implement Pass 6: per claim, read bug’s status:; verify equals subsumed. Mismatch → SUBSUMES_DEAD_REF/wrong-status.
• Implement Pass 7: per claim, resolve claim.verification_test path. Use git ls-files <test-path> for paths starting with compiler_repo/ or tests/; use Path.exists() for absolute or other-prefix paths. Unresolved → SUBSUMES_TEST_REF_DEAD Major finding with resolution-options text.

03.4 Implement auto-cleanup branch for SUBSUMES_DEAD_REF (missing-bug only)

• Implement auto-cleanup branch for SUBSUMES_DEAD_REF/missing-bug only. Behavior: remove the dead claim from plan’s subsumes: array; write the plan’s 00-overview.md atomically (tempfile + os.replace); append HISTORY entry: “Auto-cleanup YYYY-MM-DD: removed dead subsumes: reference to BUG-XX-NNN — bug no longer exists in tracker.”
• Document the BANNED auto-cleanup paths: SUBSUMES_DEAD_REF/pointer-mismatch (potential authoring conflict) and SUBSUMES_DEAD_REF/wrong-status (bug fixed out-of-band — needs human review of whether plan still claims it). Both report only.
• Document the BANNED auto-cleanup path for SUBSUMES_TEST_REF_DEAD (test-reference repair requires author judgment).
• Test case: missing-bug auto-cleanup runs once → idempotent re-run finds nothing to clean (claim already removed); HISTORY entry not duplicated.

03.5 Implement finding emission to /review-plan TPR findings pipeline

• Wire validate_subsumes_staleness() into /review-plan Phase 2. Each Finding becomes a - [ ] line in the section’s TPR findings block following existing /review-plan filing convention (Finding category, file:line if applicable, Severity, Resolution-options text).
• Map severity per impl-hygiene.md §Finding Categories (SSOT): SUBSUMES_STALE_NEW_BUG → Major (STRUCTURE:routing-violation:subsumption-stale); SUBSUMES_DEAD_REF/{missing-bug post-cleanup} → silent fix; SUBSUMES_DEAD_REF/{pointer-mismatch | wrong-status} → High (STRUCTURE:routing-violation:subsumption-dead-ref); SUBSUMES_TEST_REF_DEAD → Major (STRUCTURE:routing-violation:subsumption-test-ref-dead).
• Test case: review-plan run on a plan with mixed-state claims (1 fresh stale, 1 missing-bug auto-cleaned, 1 pointer-mismatch reported, 1 test-ref-dead reported, 1 clean) → 3 findings emitted (1 Major + 1 High + 1 Major), 1 silent auto-cleanup HISTORY entry, 1 untouched.

03.R Third Party Review Findings

• (no findings yet — populated post-TPR by Step 6 /tpr-review round)

03.N Completion Checklist

• All §03.1–§03.5 implementation items checked.
• python3 scripts/prose-lint.py .claude/skills/review-plan/ exit 0.
• python -m scripts.plan_corpus check exit 0 across the corpus (validator regression test).
• grep -nE '\(placeholder' plans/plan-bug-subsumption/section-03-review-plan-staleness-validator.md returns no hits.
• grep -nE '^- \[ \]' plans/plan-bug-subsumption/section-03-review-plan-staleness-validator.md — every remaining unchecked carries a concrete artifact pointer.
• Validator dry-run on a real plan with subsumes: (e.g. post-§08 plans/aims-burden-tracking/) produces expected findings shape.
• Section frontmatter status: flipped not-started → complete; 00-overview.md mission criteria checkbox for §03 flipped [x]; index.md row updated.
• (NOT-APPLICABLE:) compiler_repo/test-all.sh — skill-infra-docs plan; touches .claude/skills/ + scripts/plan_corpus/ (Python tooling; no compiler crate).
• (NOT-APPLICABLE:) /impl-hygiene-review — skill-infra-docs plan, no compiler Rust source touched.