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

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

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

• Layer 3: internal command boundary helpers.

  • Extract registry ownership into commands/registry.rs.
  • Extract slash parsing into commands/parse.rs.
  • Extract help/palette rendering into commands/help.rs.
  • 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 1 PR scope

The first PR intentionally does not restructure the command folders. It only removes dead/test-only command surface and extracts neutral modules that are used outside command handlers. This keeps the first layer reviewable while reducing the responsibility blur that made #2851 too broad to merge directly.

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