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); first seven Stage B group/slice migrations merged (7/18). All nine merged delivery FEATs (FEAT-014/015/018–024) are verified in current origin/main (3f3aa9ed7). FEAT-024 merged through #5951 as a58e96d40; FEAT-025 is next.
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.

    [!NOTE]
    Current-main verification (2026-09-07): all completed delivery FEATs are present. PR merge commits for FEAT-014, FEAT-015, and FEAT-018 through FEAT-024 are ancestors of current origin/main (3f3aa9ed7). FEAT-024 landed through #5951 (a58e96d40) after owner feedback was addressed in final contributor head d4b68963d; the complete GitHub and Buildkite matrix was green on that exact head before merge. The migration frontier remains config, core, debug, and session because FEAT-025 and FEAT-026 still own the remaining session slices.

    EPIC-006 current state: Stage A is complete (2/2); Stage B has 7/18 FEATs merged; 9/33 EPIC-006 FEATs are merged overall; 24 remain submitted; FEAT-025 is the next milestone.

    • FEAT-018: Utility group — shipped in #5525 via v0.9.11 (2026-08-23); complete utility group adopted external command shapes in place
    • FEAT-019: Memory group — merged to main via maintainer re-land #5833 (ad813cda6) after review fixes/current-main reconciliation through #5839; original #5609 retained as harvested provenance
    • FEAT-020: Plugins group — merged into main via current-main re-land #5865 (2026-09-05, dcd4c200f), preserving original #5657 authored history, reconciling FEAT-019/021/022 plus current plugin/marketplace behavior, and restoring three current-main CI blockers with a fully green final matrix
    • FEAT-021: Project group — merged into main in #5717 (2026-08-30, merge commit 2f200ee) — first Stage B FEAT to land directly on main; exact least-authority facets (/init=workspace, /lsp and /share=project, /goal=project+presentation). Subsequent FEAT-019/020/022 reconciliation preserves these declarations; current frontier has four groups
    • FEAT-022: Skills group — merged into main via maintainer replacement #5829 (2026-09-02, 84b3dd694); contributor PR #5825 closed as superseded after its work was harvested and co-author credited
    • FEAT-023: Session lifecycle leaves — merged into main in #5902 (2026-09-06, merge commit 41fecf8a4); nine handlers migrated with a dedicated least-authority facet, /compact and /purge remain pure, concrete lifecycle machinery remains TUI-owned, and TUI-only acceptance/regression tests stay outside the movable group; final maintainer nit kept CommandCapabilities at u16 with bit 13 assigned to SESSION_LIFECYCLE
    • FEAT-024: Session control / remote paths — merged into main in #5951 (2026-09-06, merge commit a58e96d40); six handlers use CommandSessionControlContext with exact least-authority declarations; owner feedback was addressed in d4b68963d, and the complete GitHub/Buildkite matrix was green before merge
    • 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-23 | EPIC-006 / FEAT-018 | #5525 | MERGED (shipped v0.9.11) | 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. |
| 2026-09-03 | EPIC-006 / FEAT-019 | #5833 + fix #5839 (harvests #5609) | MERGED — ad813cda6 | Maintainer re-land #5833 restored the memory capability/facet/portable handlers to main after #5839 resolved the migration blocker, least-authority/safe-failure review findings, and current-main/FEAT-022 reconciliation. Full updated-head matrix passed, including Linux/macOS/Windows, lint, Safety gate, Buildkite, CodeQL, and OHOS cargo check. |
| 2026-08-30 | EPIC-006 / FEAT-021 | #5717 | MERGED (into main, merge commit 2f200ee) | Project group adopted external command shapes in place on main's no-bitmask model: new CommandProjectContext facet, /init=WORKSPACE//lsp=project//share=project//goal=project+presentation via exact facet destructuring + safe missing-facet errors, /lsp config bridge routed through the TUI adapter, project removed from both frontiers; FEAT-037/FEAT-041 dependency-removal obligations enumerated. Rebased onto main per maintainer request (integration branch will not land); full matrix green after the maintainer's sandbox fix #5724; owner APPROVED with both nits fixed. |
| 2026-09-05 | EPIC-006 / FEAT-020 | current-main re-land #5865, preserving original #5657 | MERGED INTO main — dcd4c200f | Forward-port retained original authored commits, appended PLUGIN after published project/skill identities, preserved marketplace suggestions/reload nudge/shared Runtime API loader/canonical tokens, and did not resurrect the retired computer-use catalog. Three current-main CI blockers were repaired; the final Linux/macOS/Windows and supporting matrix was green. Verified in current origin/main (82b2efaef). |
| 2026-09-02 | EPIC-006 / FEAT-022 | #5829 (supersedes #5825) | MERGED INTO main (84b3dd694) | Maintainer rebased/harvested FEAT-022 after #5826, credited @aboimpinto as co-author, and merged the skills command shapes through replacement PR #5829. Original contributor PR #5825 is closed as superseded, not rejected. |
| 2026-09-06 | EPIC-006 / FEAT-023 | #5902 | MERGED — 41fecf8a4 | Nine session lifecycle handlers adopt a dedicated portable facet with exact capability declarations; pure /compact and /purge build no host bundle; concrete lifecycle machinery remains in the TUI adapter; TUI acceptance/regression fixtures stay outside the future movable group. The final maintainer nit was addressed in 52a53ce3a: CommandCapabilities remains u16, with SESSION_LIFECYCLE on available bit 13. Full CI passed before merge. |
| 2026-09-06 | EPIC-006 / FEAT-024 | #5951 | MERGED — a58e96d40 | Six session-control handlers adopt CommandSessionControlContext; exact declarations are SESSION_CONTROL for five handlers and SESSION_CONTROL | PRESENTATION only for /remote-env. Concrete session, persistence, picker, Git, browser, and remote-service behavior remains TUI-owned; the full host regression surface remains outside the movable group. Owner feedback was addressed in final contributor head d4b68963d; the complete GitHub/Buildkite matrix and Devin review were green before owner merge. |

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

[aboimpinto]

FEAT-018 implementation complete — utility group shape adoption

Draft PR: #5525

FEAT-018 is the first completed Stage B slice. It rewires all seven utility commands (/attach, /automation, /jobs, /mcp, /network, /task, /update) through the external command contract while keeping the files in codewhale-tui.

Boundary status:

• all seven commands use portable RegisterCommand<CommandResult> registrations;
• utility handlers contain no concrete App access and no executable TUI-helper dependency;
• presentation, atomic media attachment, and canonical operation digest cross narrowly scoped external facets implemented by the TUI host;
• codewhale-command-contract remains independent of codewhale-tui;
• utility is removed from both migration-frontier representations.

The remaining CommandResult, AppAction, AutomationAction, ShellJobAction, and McpUiAction references are the explicitly bounded, data-only compatibility references assigned to FEAT-037. They do not expose executable TUI behavior. FEAT-037 will move their ownership before FEAT-038 physically moves the utility group, preventing a circular dependency at extraction time without expanding FEAT-018 into shared-type relocation.

The issue checklist, EPIC-006 status, and PR log now reference #5525. I am monitoring the complete PR check matrix and will keep the draft current until every required check is green.

Paulo Aboim Pinto

[aboimpinto]

FEAT-018 CI is now fully green on PR #5525: 15 checks passed, 7 conditional checks were skipped as expected, and there are no failed, cancelled, or pending checks.

The PR remains a draft with a clean merge state. The Epic tracker now records the green check matrix. No Gherkin integration test files changed because command behavior was preserved; the added coverage instead verifies the external-shape dependency boundary and portable command-group wiring. The intentionally temporary result/action data references remain documented as FEAT-037 follow-up work, with physical extraction assigned to FEAT-038.

Paulo Aboim Pinto