100%

Section 05 — migration

Goal

Retire the JSON+generator+rules_runtime, switch finding emission to PREFIX-NN, and verify old-label alias compatibility.

Implementation Sketch

Delete impl-hygiene-rules.json + its schema + scripts/impl_hygiene_rules_runtime (generator/loader). Finding emission now cites PREFIX-NN ids parsed from the md. Verify every old CATEGORY:subcat label still resolves via the (was ...) alias across consuming rules/skills (no broken cross-references). Update any consumer that imported the retired runtime.

Spec References

routing.md §1.0; SSOT/DRY (no second rule store); the mapping report’s alias table.

Work Items

  • Delete impl-hygiene-rules.json + schema + scripts/impl_hygiene_rules_runtime and update importers
  • Switch finding emission to parsed PREFIX-NN ids (no JSON descriptor read)
  • Verify old-label alias compatibility corpus-wide; no dangling CATEGORY:subcat reference

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “impl-hygiene-rewrite-v3/s-eec100df” }, “generated_at”: “2026-06-23T04:14:01.026989+00:00”, “graph_state”: { “head_sha”: “ddf60faa”, “last_code_import_at”: “2026-06-23T04:12:14.803Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:impl-hygiene-rewrite-v3/s-eec100df] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/impl-hygiene-rewrite-v3” } } }

(full dossier: migration—s-eec100df.intel.json)

HISTORY

  • 2026-06-23 — discovered architectural scope-hole (finding-category-vocabulary re-home blocks the JSON deletion): verify-first grounding found that §05’s w-00a55b5f (“delete impl-hygiene-rules.json + schema + rules_runtime”) would delete the SOLE structured home of the 172-token finding-category vocabulary (26 top categories: LEAK, INVERTED-TDD, LAYER_GAP, LEDGER, SOUNDNESS, GAP, DRIFT, EVIDENCE, PARAM_SPRAWL, PLAN_, STRUCTURE: …). That vocabulary is a DISTINCT concern from the 13-PREFIX / 460-rule hygiene catalog the new impl-hygiene.md carries: it is the reviewer-vote / finding-label taxonomy consumed by scripts/tpr_review_runtime/reviewer_history.py (category_tokens(); the BUG-07-229 canary), scripts/verify_tpr_runtime/{dispatch,gates}.py (transitively), and cited as impl-hygiene.md §Finding Categories by 94 files. The §01 install already replaced the old 1334-line impl-hygiene.md (which carried the §Finding Categories taxonomy) with the PREFIX-rule file that has NO §Finding Categories section → 94 dangling-anchor refs already exist. The JSON deletion is BLOCKED on first designing where the finding-category vocabulary lives post-migration (the v3 plan models the RULE catalog, not the finding-label taxonomy). w-d6c0095a (“no dangling CATEGORY:subcat reference”) cannot pass until the re-home + the 94 §Finding Categories anchors are cured. Resolution needed (architectural): EITHER keep impl-hygiene-rules.json for the finding-category taxonomy alone (retire only its generator + rule-descriptor role, which §03’s rule_router already replaced) OR re-home the 172-token taxonomy into a dedicated structured SSOT + repoint reviewer_history/verify_tpr + the 94 citing files. No breaking deletion executed; section left in-progress pending the re-home design.

  • 2026-06-23 — refined cutover spec (retain-JSON-as-finding-taxonomy; w-00a55b5f mis-premised): deeper grounding fixed the architecture. (1) Intended finding vocabulary: plan-wide sc-0001 names “the 13 [PREFIX] categories” — the impl-hygiene-review RULE catalog (the new impl-hygiene.md). (2) The 172-token / 26-category vocabulary in impl-hygiene-rules.json (LEAK, INVERTED-TDD, LEDGER, PLAN_ROUTING_DRIFT, STRUCTURE:* …) is the PROJECT-WIDE reviewer finding-label taxonomy spanning ALL reviewers (tpr-review / review-work / verify-tpr / reviewer_history), NOT the impl-hygiene-review rule catalog. The OLD impl-hygiene.md served DOUBLE duty (finding-taxonomy SSOT via render_rules_md §Finding Categories + hygiene rules); the §01 install kept only the rule-catalog role, orphaning the finding-taxonomy role. (3) CORRECT, LOWEST-RISK cutover: RETAIN impl-hygiene-rules.json + loader.py + api.py:category_tokens AS the project-wide finding-category-taxonomy SSOT — reviewer_history.py, verify_tpr_runtime, the condensate gate, and block-generated-view-edits.sh all keep working UNCHANGED (zero ecosystem break; content_is_generated correctly returns False on the hand-authored new md). Retire ONLY: the JSON’s rule-SOURCE / generated-view role (render_*_md in generator.py — the md is now hand-authored) + the rails-replaced legacy tier engine in impl_hygiene_review_runtime (tier_engine / detection_descriptor / descriptor_engine and their main tier-scan/descriptor-scan wiring). (4) The 94 dangling impl-hygiene.md §Finding Categories anchors repoint to the retained taxonomy SSOT. (5) w-00a55b5f (“delete impl-hygiene-rules.json”) is ARCHITECTURALLY MIS-PREMISED — the JSON is the finding-taxonomy SSOT, not a pure rule store; re-scope to “retire the JSON’s rule-source/generator role + the legacy tier engine; RETAIN its finding-category-taxonomy role.” No breaking deletion executed; the cutover is a deliberate project-wide refactor across the live reviewer/TPR ecosystem, executed carefully (not rushed per CLAUDE.md THOROUGHNESS-OVER-SPEED / NO-SHORTCUTS).

  • 2026-06-23 — extraction boundary pinned: render_rules_md() (generator.py) reconstructs the WHOLE old impl-hygiene.md (§Finding Categories taxonomy PLUS ## Findings Disposition / ## Paradigms / ## Phase Boundaries / ## Side Logic / ## Data Flow / ## Error Handling / ## Type Discipline / …). The finding-category-taxonomy re-home extracts ONLY the ## Finding Categories section (header → just before ## Findings Disposition) — a header-to-EOF grab wrongly captures all 230 bold-bullets across every section vs the 26 top categories. The standalone .claude/rules/finding-categories.md SSOT carries ONLY that one section (26 categories / 172 tokens) + reviewer-vocab frontmatter; reviewer_history/verify_tpr parse its - **TOKEN** bullets for category_tokens().

  • 2026-06-23 — token-SSOT fork resolved: Option B (retain JSON as machine token SSOT); canary verified: the category_tokens() set = category tokens ∪ cat:sub for non-annotated subcats, where sub['token'] is the JSON’s canonical SLUG (NOT reliably reproducible from finding-categories.md display labels; annotated subcats like (EH-1) excluded). Option A (md-as-token-SSOT) would need the md augmented with explicit slugs + a behavior-preserving parser exactly reproducing the 172-token set — error-prone, risks the BUG-07-229 reviewer_history canary. RESOLVED to Option B: RETAIN impl-hygiene-rules.json + loader.py + api.py:category_tokens + content_is_generated as the project-wide machine finding-token SSOT — reviewer_history.py / verify_tpr_runtime / the condensate gate / block-generated-view-edits.sh ALL unchanged (zero break). finding-categories.md is the human-readable taxonomy doc (anchor target, landed). VERIFIED post-93-anchor-repoint: reviewer_history imports clean, 172 categories intact, 54 history tests pass. REMAINING (careful, full-test): retire the JSON’s rule-SOURCE md-generation role (generator.render_*_md — dead, md is hand-authored) IF unused after slimming api.py + retire the rails-replaced legacy tier engine (impl_hygiene_review_runtime/tier_engine / detection_descriptor / descriptor_engine + main tier-scan/descriptor-scan wiring + self-test legs); KEEP the JSON token-SSOT path. w-00a55b5f re-scoped: “retire rule-source/tier-engine role; RETAIN the JSON finding-token SSOT” (literal “delete the JSON” is mis-premised).

  • 2026-06-23 — CORRECTION: sc-0013 mandates full retirement → Option A (Option B superseded): §05’s owned sc-0013 (“No remaining import of impl_hygiene_rules_runtime; grep for the retired JSON path is clean”) FORBIDS Option B (retain-JSON) — reviewer_history imports impl_hygiene_rules_runtime.api:category_tokens, which sc-0013 requires gone. CORRECT path = Option A, executed BEHAVIOR-PRESERVINGLY: a new scripts/finding_categories/ runtime FREEZES the exact 172-token set (sourced once from impl-hygiene-rules.json’s category_tokens()) + exposes category_tokens(); reviewer_history + verify_tpr repoint to it (identical token set → BUG-07-229 canary safe); then impl-hygiene-rules.json + impl_hygiene_rules_runtime delete + the condensate gate + block-generated-view-edits hook (which use content_is_generated) re-home or retire. sc-0012 (“only hygiene-RULE store is impl-hygiene.md”) holds — finding_categories is the finding-LABEL taxonomy (distinct concern), not a rule store. The frozen-token freeze makes the deletion behavior-preserving (the canary’s 172-token validation is byte-identical pre/post).

  • 2026-06-23 — precise remaining-deletion map (the careful surgery for sc-0013 grep-clean): steps 1-3 landed (finding-categories.md doc SSOT + 93-anchor repoint; finding_categories runtime frozen-token SSOT; 4-consumer repoint reviewer_history/backfill/dispatch/gates — all behavior-preserving, canary 54+10+4 tests green). REMAINING (no live impl_hygiene_rules_runtime IMPORTS remain — verified; residuals are comments/docstrings only): (1) SCRUB comment/docstring refs to impl-hygiene-rules.json / impl_hygiene_rules_runtime (reviewer_history.py lines 4/80-81; rule_router.py lines 11/46 — the baked _SUBCAT_TIER provenance comment; any others) for sc-0013 grep-clean. (2) CURE content_is_generated consumers — .claude/hooks/block-generated-view-edits.sh (premise dead: impl-hygiene.md is hand-authored, not a generated view), scripts/check-condensate-gate.sh (GENERATED_CHECK), .claude/skills/condensate/SKILL.md. (3) DELETE the rails-replaced legacy tier engine in impl_hygiene_review_runtime: tier_engine.py, detection_descriptor.py, descriptor_engine.py, category_coverage.py, prompts.py + the main surgery (remove descriptor-scan / tier-scan subcommands + the cmd_next —advance-tier branches + cmd_self_test tier_engine_ran legs) — PRESERVING rails-start / rails-next (the §02/§03 path). (4) DELETE scripts/impl_hygiene_rules_runtime/ (package + tests) + .claude/rules/impl-hygiene-rules.json + its schema. (5) FULL test: impl_hygiene_review_runtime suite + reviewer_history/verify_tpr canary + sc-0013 grep-clean assertion. The main/package deletion is the migration’s riskiest surgery (shared main + hooks); executed carefully + fully tested per CLAUDE.md NO-SHORTCUTS, never a rushed sweep.

  • 2026-06-23 — final-deletion scope: gut the dead legacy review engine (precise map): steps 1-5 landed + verified (finding-categories.md doc SSOT + 93-anchor repoint; finding_categories frozen-token runtime + 4-consumer repoint; comment-scrub; content_is_generated retirement — hook/gate to literal-banner + condensate/intelligence doc-sync; canary 54+10+4+15 green throughout). FINAL step for sc-0013: the legacy tier-engine modules (detection_descriptor / prompts / category_coverage) fundamentally READ impl-hygiene-rules.json’s detection blocks — they cannot survive the JSON deletion, so they MUST be deleted, which cascades to gutting the ENTIRE legacy file×batch/tier review pipeline (now DEAD — §06 repointed /impl-hygiene-review to the rails). PRECISE GUT MAP (impl_hygiene_review_runtime): DELETE detection_descriptor.py, descriptor_engine.py, tier_engine.py, category_coverage.py, prompts.py + (assess) dispatch.py / seam_scan.py / scope_discovery.py / synthesis.py / finding_emit.py / verification_gate.py / state.RunState — every module of the legacy Phase 0-6 engine; main surgery REMOVE cmd_descriptor_scan / cmd_tier_scan / cmd_seam_scan / cmd_set_scope / cmd_emit_findings / cmd_next / cmd_resume / cmd_record_synthesis / cmd_start / cmd_set_target / cmd_set_report_target / cmd_cleanup + their parser entries; PRESERVE rails-start / rails-next / skeleton-start / skeleton-next + rules_parser + rule_router + rails + spine + state durable-IO; REWRITE cmd_self_test to the rails/spine path only. THEN DELETE scripts/impl_hygiene_rules_runtime/ + .claude/rules/impl-hygiene-rules.json + schema. VERIFY: targeted suite (rails+router+parser+spine+cli) + reviewer_history/verify_tpr canary + sc-0013 grep-clean + threat-model.md §2 row update (generated-view control retired). This engine-gut is the migration’s largest/riskiest surgery; executed as a deliberate careful pass with full testing per CLAUDE.md NO-SHORTCUTS, never rushed.