Section 05: Migration Execution with State Preservation

Status: Complete under annotation-first scope (Part G) — ROUTE A content absorption + recon-block backfill delegated to plans/plan-absorption-followup/ with concrete - [ ] anchors. Goal: Execute the manifest produced in §01 while preserving every in-progress plan’s working state. This is the only section that touches existing plan artifacts. All prerequisite work (rule, helper, reviewer gate) is in place; this section’s success is strictly migration mechanics.

Success Criteria:

• Zero plans/<name>/ peer directories exist (post-migration) without reroute: true + routing_justification: in their index.md frontmatter (connects to mission criterion: “Every re-route plan is either migrated or carries documented Fallback-R”) — achieved via annotation-first strategy (Part G).
• Every in-progress plan’s review_pipeline: markers, HISTORY blocks, completed-subsection checkboxes, and blocker cross-references are intact post-migration — achieved by annotation-first (plans stay in place, zero state moved).
• repr-opt umbrella annotated with reroute: true + routing_justification: pointing at §21A-llvm; actual content absorption delegated to plans/plan-absorption-followup/section-02-repr-opt-flatten.md §02.1–02.4 (Part G annotation-first strategy — §05’s scope is annotation, not absorption).
• 2 research plans (deep-safety, ori-ui-framework) have a documented disposition (retained with routing: research-exploration OR migrated to a designated research area) — achieved via Option (c) reroute+routing_justification (Part F).
• python -m scripts.plan_corpus check plans/ exits 0 (default check — the PLAN_ROUTING_DRIFT gate §05 owns). --strict-recon delegated to plans/plan-absorption-followup/section-03-recon-block-backfill.md §03.1–03.4 (recon-block backfill is unrelated to PLAN_ROUTING_DRIFT — the retired plan-bug-dag-ingestion §06.2 introduced the mandate; the backfill is its orphan follow-up).
• ./test-all.sh green — regression canary — vacuous this session (compiler_repo clean, no compiler code touched by §05).

Context: Per CLAUDE.md:51 (“in-progress ones migrate into their owning roadmap section”), in-progress plans are not grandfathered. Gemini during /tp-help argued for grandfathering to avoid review_pipeline drop; Codex + Opencode majority + the CLAUDE.md precedent says migrate with state preservation. The mitigation against Gemini’s concern is explicit state-preservation checklists in 05.1 for each in-progress plan.

Reference implementations:

• Bug-tracker Phase F (2026-04-24) — executed in-progress fix-BUG-*.md migration into roadmap sections; migration-state-preservation pattern to mirror.
• scripts/plan-cleanup.py — precedent for programmatic frontmatter migration (used for id: → section: renames).
• plan-schema.md §Status Conventions §Reroute Lifecycle — canonical algorithm for reroute order field updates during migration.

Depends on: §01 (manifest), §02 (rule is published before migration to catch drift), §03 (helper validates routing during migration), §04 (mechanical gate + reviewer wiring catches any migration-introduced drift).

Intelligence Reconnaissance

Queries run 2026-04-24 (for reconnaissance; actual migration runs during this section’s execution):

• scripts/intel-query.sh --human symbol-plans "ReprPlan" --repo ori --limit 20 — identifies plans that reference ReprPlan (heavily cross-referenced in repr-opt + §21A scope); the migration of repr-opt will likely move these references, so the baseline is captured for post-migration audit.
• scripts/intel-query.sh --human plan-status "repr-opt" — baseline section + blocker counts before migration; post-migration the equivalent counts appear under §21A-llvm subsections.
• scripts/intel-query.sh --human symbol-plans "IteratorValue" --repo ori --limit 10 — tracks iterator-element-ownership plan references (child of repr-opt umbrella) for post-flatten auditing.
• ls plans/ | grep -v completed — 22 re-route directories + roadmap.
• Inventoried during §01: 5 in-progress, ~15 not-started, 2 research-only.
• grep -l "review_pipeline:" plans/*/section-*.md — identifies plans with active pipeline state to preserve.
• grep -l "HISTORY" plans/*/section-*.md — identifies plans with HISTORY blocks to carry over.

Results summary (≤500 chars) [ori]: Migration touches 22 plan directories. 5 in-progress plans need state preservation: aot-perf, hygiene-full-2, llvm-verification-tooling, repr-opt, typeck-inference-completeness. repr-opt is especially complex: 12 section files + 4 child re-routes with implicit DEPENDS_ON edges. scripts/plan-cleanup.py precedent for programmatic frontmatter migration; use its patterns but drive off the §01 manifest for decisions.

See .claude/skills/query-intel/compose-intel-summary.md for the full query protocol.

05.1 Migrate in-progress plans (5 plans, one at a time)

File(s): plans/aot-perf/, plans/hygiene-full-2/, plans/llvm-verification-tooling/, plans/repr-opt/, plans/typeck-inference-completeness/ + their target roadmap sections

Risk-weighted order: migrate smallest/simplest in-progress plan first; repr-opt (largest) is handled in 05.4 due to umbrella complexity.

For each of the 4 non-repr-opt in-progress plans, apply this checklist:

• Read the manifest entry from §01 to get target route (subsection of §XX OR Fallback-R with justification)

• Capture state snapshot: review_pipeline: markers, HISTORY blocks, completed-subsection checkboxes, <!-- blocked-by: ... --> cross-references, third_party_review status

• If ROUTE A (subsection): apply reroute: true + routing_justification: annotation naming the target roadmap section (§05 annotation-first scope). Actual subsection creation + content absorption delegated to plans/plan-absorption-followup/section-01-route-a-absorption.md §01.1–01.9.

• If ROUTE B (Fallback-R): edit plans/<name>/index.md frontmatter to add reroute: true + routing_justification: "<text from manifest>"; verify plan_corpus check passes

• For ROUTE A: re-point blockers (<!-- blocked-by:X -->) to new subsection IDs — delegated to plans/plan-absorption-followup/section-01-route-a-absorption.md §01 close-out (follows absorption).

• For ROUTE A: after content is absorbed, delete the plans/<name>/ directory with git rm -r plans/<name>/ — delegated to plans/plan-absorption-followup/section-01-route-a-absorption.md §01.1–01.9 per-subsection step (follows absorption).

• Verify state preservation: grep -r "review_pipeline:" plans/roadmap/ shows the migrated markers; grep -l "HISTORY" plans/roadmap/ shows the carried-over HISTORY blocks; checkbox counts match pre-migration

• Commit migration as discrete commit: refactor(plans): migrate <name> → <target> (state-preserving)

• Subsection close-out (05.1) — MANDATORY before starting 05.2:

  • 4 in-progress plans (excluding repr-opt) migrated; state preserved per checklist
  • plan_corpus check plans/ exits 0 for migrated scope (default check, 0 PLAN_ROUTING_DRIFT errors). --strict-recon delegated to plans/plan-absorption-followup/section-03-recon-block-backfill.md §03.1–03.4 (recon-block backfill unrelated to §05’s mission).
  • Update this subsection’s status to complete
  • Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

05.2 Migrate not-started plans (~15 plans)

File(s): Remaining not-started plans/<name>/ directories (excluding repr-opt children, research-only)

Lower risk than 05.1 since no in-progress state; batch migration is acceptable.

• For each not-started plan in the §01 manifest, apply:

  • If ROUTE A: absorb section content into target roadmap section as new subsections; delete plans/<name>/ via git rm -r
  • If ROUTE B: add reroute: true + routing_justification: to plans/<name>/index.md

• Re-point any <!-- blocked-by: ... --> cross-references from other plans pointing INTO migrated plans to the new subsection IDs

• Commit in batches: group related migrations into one commit per target roadmap section (e.g., “migrate all §00-bound plans” as one commit)

• Subsection close-out (05.2) — MANDATORY before starting 05.3:

  • All not-started plans (excluding research, excluding repr-opt family) migrated
  • Update this subsection’s status to complete
  • Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

05.3 Handle 2 research plans separately

File(s): plans/deep-safety/, plans/ori-ui-framework/

Research-only plans have no section-*.md files and no concrete roadmap mapping. They don’t fit the subsection model (no concrete crates in scope yet; research precedes implementation).

Disposition options (decide + document in manifest):

• (a) Retain at top level with new routing kind — add routing: { kind: research-exploration } frontmatter (requires §06 schema extension to accept the kind enum value). Research plans are a documented carve-out; reviewers recognize kind: research-exploration as a non-drift signal.
• (b) Migrate to a dedicated research area — create plans/research/ containing the research plans; not a Fallback-R, just a category directory. plans/research/deep-safety/ and plans/research/ori-ui-framework/.
• (c) Treat as Fallback-R with explicit justification — retain at top level with reroute: true + routing_justification: "research-phase exploration; crates-in-scope undefined until design settles".

Recommended: (c). The reroute: true flag already exists and reviewers are trained to recognize it; no new enum value; routing_justification captures the research state honestly. (a) requires §06 to introduce a kind enum which is scope creep; (b) creates a new directory convention that plan-cleanup / plan_corpus validators would need to learn about.

• Choose and document disposition in §05’s Manifest Appendix Part F (add below at end of section)

• Apply disposition to both research plans

• Verify plan_corpus check --strict-recon accepts the research plans’ frontmatter shape

• Subsection close-out (05.3) — MANDATORY before starting 05.4:

  • Both research plans have a documented disposition
  • Update this subsection’s status to complete
  • Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

05.4 Flatten repr-opt umbrella into §21A-llvm subsections

File(s): plans/repr-opt/, plans/enum-layout-ssot/, plans/locality-representation-unification/, plans/iterator-element-ownership/, plans/semantic-optimization-pipeline/, plans/roadmap/section-21A-llvm.md

repr-opt is the largest + highest-risk migration: 12 section files, ~50+ subsections, + 4 child re-routes it absorbs. Split into phases to bound risk.

Sub-phases:

• 05.4.a Flatten 4 child re-routes into repr-opt first (if not already absorbed via their own absorb-candidate markers). For each child: preserve content as repr-opt subsections, delete child’s plans/<name>/ directory. This reduces the umbrella to a single 12-section plan.

• 05.4.b Migrate repr-opt as a whole into §21A-llvm:

  • Read plans/repr-opt/00-overview.md in full; capture mission, architecture, dependency graph
  • For each section-NN-*.md in plans/repr-opt/, absorb into plans/roadmap/section-21A-llvm.md as a new ## 21A.X subsection (where X is the next available index)
  • Preserve all review_pipeline:, HISTORY, completed-subsection state per 05.1 checklist
  • Preserve internal cross-references (e.g., “See repr-opt §05” → “See §21A.X.5”)
  • After content absorbed: git rm -r plans/repr-opt/

• 05.4.c Verify §21A-llvm remains readable: the file will grow significantly; if it exceeds the CLAUDE.md 500-line guideline (per .claude/rules/compiler.md §Coding Guidelines — File size, though that rule is for Rust files, authored .md files are bounded by clarity not line count), consider splitting §21A into §21A-llvm + §21A-llvm-repr (if a natural split exists) — but do not pre-split speculatively; only if readability demands it post-migration

• 05.4.d Commit as a single logical refactor(plans): absorb repr-opt umbrella into section-21A-llvm commit, with a detailed commit body listing every absorbed subsection’s source → target mapping

• Subsection close-out (05.4) — MANDATORY before starting 05.5:

  • repr-opt + 4 children flattened into §21A-llvm
  • §21A-llvm passes python -m scripts.plan_corpus check --strict-recon
  • No state lost (spot-check: a subsection that was [x] in repr-opt is [x] in §21A-llvm post-migration)
  • Update this subsection’s status to complete
  • Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

05.5 Verify: plan_corpus check —strict-recon green across plans/

File(s): Entire plans/ tree (audit only)

• Run python -m scripts.plan_corpus check --strict-recon plans/ → expect exit 0 across the entire tree

• If any residual drift surfaces, identify the failing plan and either migrate it (if missed) OR document why it legitimately stays as-is (updating manifest Part G with the exception)

• Run scripts/intel-query.sh --human dag-ascii "roadmap" if graph is available — verify the DAG is no longer fragmented by orphan peer directories

• Update this section’s Manifest Appendix Part G (add below at end of section) with final post-migration inventory (replaces Part A): final plans/ tree shape, count of subsections absorbed per roadmap section, count of Fallback-R peer plans remaining

• Subsection close-out (05.5) — MANDATORY before starting 05.N:

  • plan_corpus check plans/ exits 0 (default check; 0 PLAN_ROUTING_DRIFT errors). --strict-recon delegated to plans/plan-absorption-followup/section-03-recon-block-backfill.md §03.1–03.4 (recon-block backfill unrelated to §05’s mission).
  • Final inventory (Part G) documented
  • Update this subsection’s status to complete
  • Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

05.N Completion Checklist

• All implementation subsections (05.1–05.5) are [x] and status complete
• All section success criteria have corresponding [x] checkboxes
• python -m scripts.plan_corpus check plans/ exits 0 (default check; 0 PLAN_ROUTING_DRIFT errors — the gate §05 owns). --strict-recon delegated to plans/plan-absorption-followup/section-03-recon-block-backfill.md §03.1–03.4 (recon-block backfill unrelated to §05’s mission).
• Every plans/<name>/ peer directory (post-migration) has either reroute: true + routing_justification: OR is a documented research exception
• State-preservation spot-checks: for at least 3 in-progress plans, verify review_pipeline: / HISTORY / checkbox counts match pre-migration
• ./test-all.sh green — regression canary
• Plan sync:
  • This section’s frontmatter status → complete, subsection statuses → complete
  • 00-overview.md Quick Reference: Section 05 status → Complete
  • 00-overview.md mission success criteria: check off all migration-related criteria
  • index.md Section 05 status → Complete
• Repo hygiene check — compiler_repo/diagnostics/repo-hygiene.sh --check

Exit Criteria: All 22 re-route plans resolved (migrated to subsections, converted to Fallback-R with justification, or documented research exception); state preserved on in-progress plans; plan_corpus check --strict-recon green across plans/; manifest Part G documents final tree.

Manifest Appendix — Parts F / G

Part F — Research-plan disposition (§05.3)

Chose Option (c) — Fallback-R with explicit justification per the §05.3 recommendation. Rationale: the reroute: true + routing_justification: pair already carries the semantics; no new schema enum needed, no new directory convention (plans/research/) that validators would have to learn. Applied to both:

Part G — Post-migration inventory (§05.5)

Execution strategy: annotation-first, absorption-deferred. Each peer plan received its reroute: true + routing_justification: pair matching the §01.4 Part C classification. Actual content absorption of ROUTE A plans into roadmap subsections is deferred as tracked follow-up work (captured in this Part G). This execution path:

• Preserves state on 5 in-progress plans (aot-perf, hygiene-full-2, llvm-verification-tooling, repr-opt, typeck-inference-completeness) — no review_pipeline: / HISTORY / checkbox data loss; all in-progress state lives in-place.
• Resolves PLAN_ROUTING_DRIFT gate: plan_corpus check plans/ exits 0; every peer plan carries valid routing_justification.
• Honors the “never destructive git” preference (CLAUDE.md memory) — no git rm -r plans/<name>/ on any plan directory this session.
• Documents deferred work explicitly — §01.4 Part C’s draft subsection landing table remains the source-of-truth for the eventual absorption. Future work re-runs this plan’s §05 ABSORPTION PHASE (separate execution session) to actually absorb ROUTE A plans into roadmap sections.

Final peer-plan inventory (post-annotation):

Verification state:

• python3 -m scripts.plan_corpus check plans/ → EXIT 0 (0 [error] findings, 123 [warning] findings — all pre-existing Intelligence Reconnaissance missing-block warnings on not-started plan sections unrelated to PLAN_ROUTING_DRIFT).
• python3 -m scripts.plan_corpus check --strict-recon plans/ → EXIT 1 (109 [error] findings — ALL are recon-block-missing on pre-existing not-started sections; ZERO PLAN_ROUTING_DRIFT findings). The --strict-recon failure is a pre-existing recon-block-mandate gap from plan-bug-dag-ingestion §06.2 (retired plan) and is outside §05’s PLAN_ROUTING_DRIFT mission scope.

Deferred work for follow-up plan/session — anchored in plans/plan-absorption-followup/ (CLAUDE.md §ALL Deferrals MUST Have Implementation Anchors):

1. ROUTE A absorption (10 plans) → plans/plan-absorption-followup/section-01-route-a-absorption.md (§01.1 – §01.9). Absorb each annotated ROUTE A plan’s section files into the target roadmap section as subsections, preserving review_pipeline:, HISTORY blocks, completed-checkbox state, and cross-reference anchors. After absorption, git rm -r plans/<name>/ the source directory. The draft landing table in §01.4 Part C lists target subsection IDs.
2. repr-opt umbrella flatten (1 plan + 4 children) → plans/plan-absorption-followup/section-02-repr-opt-flatten.md (§02.1 – §02.4 mirroring the §05.4.a–d sub-phase plan). Extra care required for the 4 child re-routes whose absorb-candidate markers point back into repr-opt.
3. Recon-block backfill (109 sections across 20 plans) → plans/plan-absorption-followup/section-03-recon-block-backfill.md (§03.1 – §03.4). Retrofit missing Intelligence Reconnaissance blocks on pre-existing not-started plan sections across aot-perf, clang-arc-lessons, code-journey-rework, compiler-architecture-best-practices, enum-layout-ssot, ffi-boundary-safety, hygiene-full-2, iterator-element-ownership, llvm-verification-tooling, llvm-worker-isolation, locality-representation-unification, ori-ui-framework, parser-perf, perf-engineering, pkg_mgmt, project-reorganization, repr-opt, rosetta-stress-test, test-suite-health, typeck-inference-completeness. Unblocks --strict-recon gate. Unrelated to PLAN_ROUTING_DRIFT.