Refactoring roadmap: interleaved simplification + architecture sequence (tracking)

[rianjs]

Tracking issue for the codebase-wide simplification + architecture refactor. Full context lives in docs/refactoring/: roadmap · architecture report (6 judge-endorsed structural proposals) · tactical report (~118 verified line-level items, ~5,000–5,500 LOC net reduction).

Sequencing principle: most tactical batches are the cheap first steps of the architecture moves. Deletions and dedups land before each structural move so there is less code to relocate, fewer symbols to export, and smaller test migrations. Every finding was adversarially verified against the code (166 raw → 151 confirmed → deduplicated).

Sequence

Phases are ordered; each unlocks or shrinks the ones after it. The parallel track has no ordering constraints.

• Refactor Phase 0: dead-code deletion (legacy init wizard, pipeline dead trio, repo-wide sweep) #447 — Phase 0: dead-code deletion. Legacy init-wizard path (~750–840 LOC), pipeline dead trio, ~500 LOC repo-wide sweep. Zero behavior risk; shrinks Phases 4 and 5 substantially.
• Refactor Phase 1: shared leaf packages + mechanical boilerplate (fsatomic, cobra Args, view/progress helpers) #448 — Phase 1: shared leaf packages + boilerplate. internal/fsatomic, cobra Args constructors, configPath/JSON-render/progress-logger dedup, OpenLedger. The vocabulary later moves are written in.
• Refactor Phase 2: extract internal/app composition root (finishes #422/#423) #449 — Phase 2: internal/app composition root. Finishes Architecture refactor 02: extract command-independent runtime assembly #422/Architecture refactor 03: move reusable app contracts out of cmdruntime #423 knownDebt. Keystone: unblocks Phases 3 and 6.
• Refactor Phase 3: declarative LLM runtime registry + llm package dedup #450 — Phase 3: LLM runtime registry. Kills the 6+-site Provider×Auth×Adapter switch drift; constructor map lives in internal/app (needs Phase 2). Includes llm subprocess/stream dedup riders.
• Refactor Phase 4: decompose pipeline.go (in-file dedup, then workbench + dossier extraction) #451 — Phase 4: pipeline.go decomposition. In-file dedup → execute() decomposition → file split → extract internal/workbench, absorb into llmlifecycle/runartifact, extract internal/dossier.
• Refactor Phase 5: split the cr init wizard into internal/cmd/initcmd (trimmed scope) #452 — Phase 5: wizard split into internal/cmd/initcmd. After Phase 0 (~1,700 LOC lighter). Editor-family consolidation → tactical batch → mechanical move → prompter collapse.
• Refactor Phase 6: benchmark dedup + in-process review executor #453 — Phase 6: benchmark dedup + in-process executor. Dedup first; executor needs Phase 2; keep subprocess for --cr-bin.
• Refactor parallel track: independent dedup batches (ledger/outbox/gate, gateio, review-flow, config, support, test infra) #454 — Parallel track: independent batches. Ledger/outbox/gate generics, gateio, review-flow, config, support packages, test infra. Slot anywhere.

Ground rules

• Move-only PRs stay separate from behavior-change PRs. Three deliberate behavior changes each ship alone: closing the claude_cli auth-validation gap, shortSHA 7→12 in agents output, non-atomic→atomic JSON writes.
• Run the architecture harness (internal/architecture, per-pkg imports_test.go) and full test suite per step; add boundary entries as new packages appear.
• Phases 4 and 5 touch the two hottest files in the repo — land those steps quickly or during a lull.
• Coordinate Phase 2 with the Architecture refactor workstream: reusable layers and pipeline simplification #420 workstream (Architecture refactor 02: extract command-independent runtime assembly #422/Architecture refactor 03: move reusable app contracts out of cmdruntime #423 owners).

Suggested first three PRs

1. Phase 0.1 — legacy wizard deletion (Refactor Phase 0: dead-code deletion (legacy init wizard, pipeline dead trio, repo-wide sweep) #447)
2. Phase 1.1 — internal/fsatomic + migrate the three JSON writers (Refactor Phase 1: shared leaf packages + mechanical boilerplate (fsatomic, cobra Args, view/progress helpers) #448)
3. Phase 2.1 — SelectionRuntime into internal/app, repoint benchmarkcmd, delete the Architecture refactor 03: move reusable app contracts out of cmdruntime #423 knownDebt entry (Refactor Phase 2: extract internal/app composition root (finishes #422/#423) #449)