EPIC: staged command-boundary refactor for #2791

[aboimpinto]

Tracking

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

This EPIC tracks the smaller mergeable layers for the command-boundary refactor discussed in #2791. The original intent was to keep #2851 as the proof/reference branch, but land the v0.9 work in smaller PRs. The current closure/replay target is hunter/0.8.62-glm-subagents.

Current closure PR: #3278.
Current Layer 4 PR: #3330.

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. Active draft PR Layer 4: replay FEAT-005 command extraction on Hunter #3330.

  • 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.

Hunter Closure / Replay PR

Draft PR #3278 replays the completed EPIC-001 work onto hunter/0.8.62-glm-subagents semantically rather than by raw cherry-pick:

• FEAT-001 is represented by Hunter's current trait-backed registry and group-owned command tree.
• FEAT-002 is replayed as the dedicated user-command registry boundary.
• FEAT-003 is replayed as public architecture and PR/issue evidence docs.

Draft PR #3330 continues the Layer 4 / FEAT-005 command extraction replay on hunter/0.8.62-glm-subagents:

• Core and session commands are split into focused group-owned command files against the current trait-backed registry.
• /swarm is migrated into the focused command structure while preserving its current gated behavior.
• Core/session Gherkin acceptance coverage and EPIC smoke coverage are restored for the Layer 4 evidence gate.

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

[github-actions]

Thanks @aboimpinto for the report.

This repository is currently observing a maintainer-managed contribution gate in dry-run mode, so this issue is staying open. When enforcement is enabled, issues from contributors who are not listed in .github/APPROVED_CONTRIBUTORS will be closed automatically.

Please read CONTRIBUTING.md for the expected issue shape. A maintainer can grant issue access by commenting /lgtmi on an issue.

[aboimpinto]

Layer 1 draft PR is open here: #2871.

This covers the checked Layer 1 scope in the EPIC: command-surface cleanup, neutral config_persistence / model_routing extraction, and Windows/hermetic test fixes. It leaves the parity harness and group-owned command boundary for the next layers.

Paulo Aboim Pinto