EPIC-005: CodeWhale TUI Crate Decomposition (Umbrella)

[aboimpinto]

EPIC-005: CodeWhale TUI Crate Decomposition — Umbrella EPIC

This issue is the EpicStyle tracking issue for the CodeWhale TUI crate decomposition. It represents the entire structure below: every sub-EPIC and every FEAT reports here when done, and every PR created under this work is logged here.

The decomposition is the direct answer to the compilation-time discussion in #4991 — see the Developer fast loop section below.

Structure

EPIC-005 is the umbrella EPIC. It does not contain FEATs directly — it holds the map of sub-EPICs, each of which contains its own FEATs.

flowchart TD
    U["EPIC-005: TUI Crate Decomposition (umbrella)"]
    U --> E6["EPIC-006: Commands -> codewhale-commands (P1)"]
    U --> E7["EPIC-007: Tools consolidation -> crates/tools (P1)"]
    U --> E8["EPIC-008: Config consolidation -> crates/config (P2)"]
    U --> E9["EPIC-009: Hooks + Execpolicy + MCP (P2)"]
    U --> E10["EPIC-010: Core extraction -> crates/core (P3)"]

Loading

ID	Sub-EPIC	Scope	Status
EPIC-006	Commands → codewhale-commands	crates/tui/src/commands/ (~42k lines incl. tests; 9 groups, registry, discovery)	IN PROGRESS — Stage A complete (2/2); Stage B started with FEAT-018 (#5525)
EPIC-007	Tools consolidation	crates/tui/src/tools/ (~117k lines) → crates/tools (currently 1.3k)	NotStarted
EPIC-008	Config consolidation	crates/tui/src/config/ (~13k lines) → crates/config (currently 33k)	NotStarted
EPIC-009	Hooks + Execpolicy + MCP	hooks/ (7k), execpolicy/ (0.5k), mcp/ (8k) → crates/hooks, crates/execpolicy, crates/mcp	NotStarted
EPIC-010	Core extraction	crates/tui/src/core/ (~42k lines) → crates/core (currently 3.4k); tightly coupled, P3 follow-up	NotStarted

Stays in codewhale-tui: tui/ rendering (~205k lines), fleet/ (~27k lines), and the TUI-specific long tail.

Rules (applied to every sub-EPIC)

1. Behavior-preserving — extraction only, no command/UX behavior changes.
2. Trait-first — define the boundary interface before moving code (pattern: EPIC-006 CommandContext).
3. Compiles at every step — bottom-up extraction, workspace stays green at each commit.
4. CI gate — extracted crate must never depend on codewhale-tui (e.g. cargo check -p codewhale-commands pulls no TUI).
5. Fork-local until complete — rebase onto upstream main frequently; no upstream PR until the sub-EPIC is done.
6. Sequencing — EPIC-006 first, then 007/008, then 009, then 010.

Work summary (to be done)

Estimated FEATs under each EPIC. Check a FEAT off and append its PR link when the PR lands; parent EPICs auto-complete when all their FEATs are done. This section is the visual tracker — the Features Breakdown tables in the MemoryBank EPIC documents are the static FEAT-creation source and are not updated per PR.

• EPIC-006: Commands extraction — staged, one FEAT = one independently green PR
  • Stage A — shapes + infrastructure (COMPLETE 2026-08-19)
    • FEAT-014: Prototype command capability/handler/registration shapes only — merged in #5328 (2026-08-13, merge commit 3b41d0ee); no TUI production rewiring
    • FEAT-015: Add TUI adapters, dual-path dispatch seam, and shrinking migration gate; convert no group — merged in #5506 (2026-08-19, merge commit ae56154c); complete required check matrix green
  • Stage B — adopt shapes inside TUI (files do not move)
    • Least-capability invariant: every contextual registration declares its exact minimum external facet set; the TUI exposes only those facets; pure handlers construct no host bundle; missing required facets fail safely. FEAT-019 through FEAT-035 inherit this pattern, and FEAT-035 enforces it repository-wide.
    • FEAT-018: Utility group — implementation complete in #5525 (ready for review; least-capability hardening in 643b76c5f; complete CI matrix green on e4aad4c06)
    • FEAT-019: Memory group
    • FEAT-020: Plugins group
    • FEAT-021: Project group
    • FEAT-022: Skills group
    • FEAT-023: Session lifecycle leaves
    • FEAT-024: Session control / remote paths
    • FEAT-025: Session export
    • FEAT-026: Session structcopy
    • FEAT-027: Config policy/status
    • FEAT-028: Main config module
    • FEAT-029: Debug diagnostics
    • FEAT-030: Debug mutation paths
    • FEAT-031: Core navigation/display leaves
    • FEAT-032: Core model/provider/setup
    • FEAT-033: Core coordination/workflow
    • FEAT-034: Remaining core policy/interaction
    • FEAT-035: Registry/discovery completion + enforce zero direct concrete-App handlers
  • Stage C — focused prerequisites after in-place decoupling
    • FEAT-036: Extract localization behind the existing compatibility path
    • FEAT-037: Move only shared command outcome/action data proven necessary
  • Stage D — bootstrap then move one already-decoupled group per PR
    • FEAT-016: Bootstrap codewhale-commands + shared registry/discovery boundary; move no group
    • FEAT-038: Move utility
    • FEAT-039: Move memory
    • FEAT-040: Move plugins
    • FEAT-041: Move project
    • FEAT-042: Move skills
    • FEAT-043: Move session
    • FEAT-044: Move config
    • FEAT-045: Move debug
    • FEAT-046: Move core
  • Stage E — final validation
    • FEAT-017: Acceptance-test boundary, compatibility-shim removal, and EPIC validation
• EPIC-007: Tools consolidation
  • FEAT: Audit tools/ vs crates/tools and define the shared boundary
  • FEAT: Move shared tool code into crates/tools
  • FEAT: Wire TUI to the consolidated crate; keep tool UI code in TUI
  • FEAT: Tests, CI gate, and re-export shim
• EPIC-008: Config consolidation
  • FEAT: Audit TUI config/ vs crates/config (overlap, extensions, UI views)
  • FEAT: Extract non-UI config logic to crates/config (or adopt it)
  • FEAT: Wire TUI to codewhale-config; keep UI views in TUI
  • FEAT: Tests, CI gate, and re-export shim
• EPIC-009: Hooks/Execpolicy/MCP consolidation
  • FEAT: Consolidate hooks/ with crates/hooks
  • FEAT: Consolidate execpolicy/ with crates/execpolicy
  • FEAT: Consolidate mcp/ with crates/mcp
  • FEAT: Tests, CI gates, and cleanup
• EPIC-010: Core extraction (follow-up)
  • FEAT: Core audit and coupling map (36 files, ~42k lines)
  • FEAT: Extract decoupled core leaves to crates/core (phase 1)
  • FEAT: Extract remaining core logic (phase 2, after boundary interfaces)
  • FEAT: Wire TUI to codewhale-core; tests and CI gate
• Final: codewhale-tui reduced from ~700k to ~300k lines focused on UI rendering

Developer fast loop

The whole point of this decomposition: once a sub-EPIC's crate exists (EPIC-006 Feature 3 and later), day-to-day development happens entirely outside the TUI monolith (~700k lines). The TUI is only compiled when you explicitly need it — TUI integration tests, cargo test --workspace, or the final pre-PR validation.

cargo check -p codewhale-commands          # production change check — seconds, not minutes
cargo test -p codewhale-commands           # test loop — compiles only the commands crate + thin test binaries, never the TUI
cargo watch -x "check -p codewhale-commands"  # continuous check while editing (cargo-watch)
cargo nextest run -p codewhale-commands    # optional: parallel test runner, faster startup

Why this stays fast:

• cargo build / cargo check never compiles #[cfg(test)] code, so production iteration is bounded to the small crate.
• cargo test compiles each tests/ file as its own small binary crate depending only on the public API — a production change recompiles/relinks only those thin binaries, in parallel.
• The Gherkin acceptance harnesses live in separate test binaries (or a dedicated acceptance crate), so thousands of acceptance-test lines are never part of the production crate compile.
• Small white-box unit tests that need private access stay inline — they are cheap and cannot live outside the crate.

Acceptance criterion for every extracted crate: cargo test -p <crate> must compile only that crate and its test binaries — if it pulls in codewhale-tui, the boundary was cut wrong.

The numbers and impact motivating this are documented in #4991 (Discussion: Compilation times and the TUI crate monolith): 476k lines / 82% of the workspace in one crate, 8–16 min release builds, 30+ min test suite, 2–3 iterations per hour.

PR log (updated as work lands)

Date	EPIC / FEAT	PR	Status	Summary
2026-08-13	EPIC-006 / FEAT-014	#5328	MERGED	Scope-corrected after owner review: small codewhale-command-contract prototype only (7 facets, generic handler/registration shapes, tests, CI guard); no TUI production changes, localization extraction, shared-type move, or command migration. Merged 2026-08-13 (3b41d0ee) after two conflict-resolution merges against main (generated-file regen: source budget 688916, facts v0.9.7; codewhale-core pin 0.9.7).
2026-08-19	EPIC-006 / FEAT-015	#5506	MERGED	TUI-owned implementations of all seven command capability facets, authoritative App delegation, portable registration/localization bridge, dual-path registry dispatch, and baseline-aware shrink-or-documented-split migration gate; no production command group converted or moved.

| 2026-08-20 | EPIC-006 / FEAT-018 | #5525 | OPEN (ready; CI green) | Complete utility group adopted external command shapes in place: seven portable registrations, zero concrete-App handlers, exact least-capability declarations with restricted facet exposure, and utility removed from the migration frontier. Temporary result/action data references remain intentionally assigned to FEAT-037; physical movement remains FEAT-038. |

Reporting contract

• Every FEAT completion updates this issue with its PR link and a one-line summary.
• Every sub-EPIC completion updates the sub-EPIC row above (status + PR links).
• EPIC-005 is closed only when all sub-EPICs above are complete.

Paulo Aboim Pinto

[JayBeest]

I love this initiative. Although I'm still quite unfamiliar with Rust. I am pretty familiar with C.
Re-factoring can be such a pain, but not any more, rly. I don't have to manually write the code nowadays. 😎
In any case the language does not really matter, I think. Just follow what it expects, its strengths. Don't overcomplicate.
And as long as there are good tests (there are) It should be fine? no?

I really love what I see. How you structured this.
I should be more honest. This has momentum, I would only slow it down. Is what I think.
Lot on my plate already, not in the least my ISP...still suffering on the side.

I'm keeping an eye out, for now. 👀

🌊🐋

[SparkofSpike]

It looks like a ton of work – really appreciate it!

[JayBeest]

X-LINK — #5273

[aboimpinto]

FEAT-014 complete — command contract crate boundary (EPIC-006 step 1 of 4).

PR: #5328 (OPEN, fork-local branch, rebased onto current main, 0 behind).

• New codewhale-localization leaf: app-wide i18n (4,245 lines + 16 locale packs) moved out of the TUI, byte-identical (parity gate PASS).
• New codewhale-command-contract leaf: seven independent object-safe facet traits, pure/contextual fn-pointer handler transport (CommandContexts/ContextParts/require_*), RegisterCommand (info() + handler()), the real AppAction (88 variants) + CommandResult, D8 free formatting helpers, exact K3 route predicates.
• CI boundary guard (check-command-crate-boundaries.py): no codewhale-tui edge into either leaf; no widget import, no composite context, no boxed handler.
• Gates: workspace 11,812 tests / 0 failed, strict clippy 0 warnings, budgets PASS.
• Unit tests: 27 (contract) + 32 (localization). Gherkin acceptance is deliberately deferred to FEAT-017 (D6/Q6) so cargo test -p codewhale-commands never compiles the TUI.

Next: FEAT-015 (implement the facets for App + wire dispatch in place, one green sub-PR per command group), then FEAT-016 (mechanical extract), FEAT-017 (test split).

Paulo Aboim Pinto

[aboimpinto]

EPIC-006 plan corrected: one FEAT = one PR

Following the early owner review on draft PR #5328, I expanded EPIC-006 from 4 broad FEATs to 33 narrowly bounded FEATs.

The increase is intentional. The previous plan bundled interface design, localization/shared-type ownership moves, all in-place command rewiring, all physical group moves, and test-boundary cleanup into only four tracking units. Even when behavior-preserving, that produces large mixed diffs that are difficult to review, bisect, and roll back safely.

The corrected delivery model is:

1. FEAT-014 defines shapes only. The broad implementation was rolled back. Draft FEAT-014: Command contract crate boundary (facets + shared types) for the commands extraction #5328 now has no crates/tui production changes, no localization extraction, no shared-type movement, and no command migration.
2. Adopt the shapes inside TUI first, one bounded command group/slice per FEAT and PR. Files stay where they are, and every PR remains independently green.
3. Enforce zero direct concrete-App command handlers before any physical extraction begins.
4. Extract shared prerequisites separately, only after migrated handlers prove they are necessary.
5. Bootstrap codewhale-commands without moving a group, then move one already-decoupled group per FEAT and PR.
6. Complete the acceptance-test boundary and remove compatibility shims only after the final group moves.

Large groups (session, config, debug, and core) are split into bounded in-place adoption slices. The later physical moves remain one group per PR and should be mostly rename-detectable.

This is more tracking work, but materially less implementation and review risk: each FEAT now corresponds to one independently mergeable upstream PR, with a clear rollback point and no dependency on a later PR to restore compilation or behavior.

The issue checklist and EPIC-006 MemoryBank document now contain the expanded FEAT-014 through FEAT-046 roadmap.

Paulo Aboim Pinto

[Hmbown]

oh man. this is just incredible. thank you so much for doing this!!!! if I start moving too fast and it gets hard to stay on track with this idea please let me know - know that my intent is absolutely that we do this!

[aboimpinto]

no problem man!! I will move as fast as possible ... :)

[aboimpinto]

EPIC-006 Stage A complete

Both Stage A FEATs are now merged into upstream main:

• FEAT-014 — command capability, handler, and registration shapes: PR FEAT-014: Command contract crate boundary (facets + shared types) for the commands extraction #5328, merged 2026-08-13.
• FEAT-015 — TUI facet adapters, dual-path dispatch seam, and shrinking migration gate: PR feat(tui): add command context adapters and migration gate (FEAT-015) #5506, merged 2026-08-19 (ae56154c).

The external shapes and migration infrastructure are therefore in place. Stage B is unblocked and begins with FEAT-018, which adopts the shapes in the utility group without moving the command files yet.

The issue status table, Stage A checklist, and PR log have been updated to reflect this milestone.

Paulo Aboim Pinto