Tracking

Refs #2791.
Reference / proof PR: #2851.

This EPIC tracks the smaller mergeable layers for the command-boundary refactor discussed in #2791. The intent is to keep #2851 as the proof/reference branch, but land the v0.9 work in smaller PRs against codex/v0.9.0-stewardship.

Direction agreed in #2791

• Keep Refactor TUI command groups into focused implementations #2851 as the proof/reference branch.
• Start with protection and cleanup before broad architecture movement.
• Move toward group-owned command files, not a per-command file explosion.
• Avoid a command-by-command temporary dual loader unless the parity harness proves it is needed.
• Use Refs #2791 / partial progress wording for layered PRs.

Layer checklist

• Layer 1: command-surface cleanup and neutral shared extraction. PR Layer 1: clean command support boundaries #2871.

  • Remove command/public APIs that production code no longer calls.
  • Move config persistence used by UI and commands out of commands.
  • Move auto model routing used by UI, runtime, subagents, and commands out of commands.
  • Keep the existing command folder structure intact.
  • Make related command/project-context tests hermetic on Windows.
  • Validate with cargo test --workspace and no warnings.

• Layer 2: command parity harness. PR Layer 2: add command parity harness #2878.

  • Pin registered command names and aliases.
  • Detect duplicate command names/aliases.
  • Cover command metadata and usage/help expectations.
  • Pin slash parsing and argument preservation.
  • Pin unknown command behavior.
  • Cover help/palette rendering expectations where available.
  • Add representative dispatch parity checks per command group.

• Supporting acceptance-test harness proposal/example. PR Add Gherkin acceptance E2E harness example #2887.

  • Add owner-readable Gherkin-style acceptance coverage for the tool lifecycle.
  • Keep this as supporting infrastructure rather than a command-boundary layer.

• Layer 3: internal command boundary helpers. Active draft PR refactor(commands): extract registry and parser helpers #2888.

  • Extract registry ownership into commands/registry.rs.
  • Extract slash parsing into commands/parse.rs.
  • Keep current command-specific help rendering in commands/core.rs; do not add commands/help.rs unless a real shared help/palette ownership boundary appears.
  • Keep behavior protected by the Layer 2 harness.

• Layer 4: group-owned built-in command files.

  • Move toward group-owned command areas for core, config, session, skills, project, memory, utility, and debug.
  • Avoid a long-lived hybrid loader unless Layer 2 proves it is required.
  • Split inside a group only when the group boundary itself becomes unclear.

• Layer 5: user command follow-up.

  • Treat user_commands as a separate follow-up after built-in command boundaries are stable.
  • Keep markdown/frontmatter command behavior pinned by parity tests.

• Layer 6: completion cleanup.

  • Remove any temporary bridge if one was introduced.
  • Re-run full workspace validation.
  • Close Refactor command dispatch from monolithic match to modular strategy pattern #2791 only when the command boundary has actually landed, not from an intermediate layer.

Current Layer 3 PR scope

PR #2888 intentionally does not restructure command handler groups. It moves command registry metadata, command lookup, unknown-command suggestion ranking, and slash command parsing into dedicated helper modules while keeping dispatch in commands/mod.rs.

Validation for PR #2888:

• cargo fmt
• cargo check -p codewhale-tui
• cargo test -p codewhale-tui commands::
• cargo test --workspace
• git diff --check

Paulo Aboim Pinto