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.
Layer 4.1 (FEAT-007): project, memory, skills, utility + plugins: #3652.
Layer 4.2 (FEAT-008): registry cleanup, docs, and full validation: #3706.

Submitted PRs

Layer	Title	PR	Status
Layer 1	Command-surface cleanup and neutral shared extraction	#2871	✅ Merged
Layer 2	Command parity harness	#2878	✅ Merged
Supporting	Acceptance-test harness proposal/example	#2887	✅ Merged
Layer 3	Internal command boundary helpers	#2888	✅ Closed
Layer 4	Group-owned built-in command files (FEAT-006)	#3330	✅ Merged
Layer 4.1	Project, memory, skills, utility extraction (FEAT-007)	#3652	✅ Merged
Layer 4.2	Registry cleanup, docs, and full validation (FEAT-008)	#3706	✅ Merged
Layer 5.0	Plugins scanner replacement	#3970	🔄 Open
Hunter Replay	Closure/replay PR on hunter branch	#3278	📝 Draft

Direction agreed in #2791

• Keep #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 #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 #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 #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 #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 (FEAT-006). PR #3330.
  • Move toward group-owned command areas for core, config, session, 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 4.1: project, memory, skills, utility extraction (FEAT-007). PR #3652.
  • Move toward group-owned command areas for project, memory, skills, utility.
  • Extract /plugins from the utility group into its own PluginsCommands group (bonus cleanup).
  • Add Gherkin E2E coverage for plugin discovery with approval levels, empty and missing directories.
• Layer 4.2: registry cleanup, docs, and full validation (FEAT-008). Draft PR #3706.
  • Remove temporary adapters, duplicate command lists, compatibility loaders, and migration-only dispatch paths.
  • Add Gherkin E2E integration tests for all command groups (core, config, session, project, memory, skills, utility, debug, plugins).
  • Validate no duplicate command name or alias registration.
  • Update command architecture documentation from source-verified behavior.
  • Finalize EPIC-002 closure evidence linking to EPIC: staged command-boundary refactor for #2791 #2870, Refactor command dispatch from monolithic match to modular strategy pattern #2791, Refactor TUI command groups into focused implementations #2851, and Add Gherkin acceptance E2E harness example #2887.
• Layer 5.0: Plugins scanner replacement. PR #3970.
  • Replace the registry-based plugin architecture with a lightweight filesystem scanner approach.
  • Plugins are discovered from a configured plugin directory instead of an in-memory registry.
  • Removes enable/disable state management layer; plugins are always available when present on disk.
  • Simplifies the plugin command interface to listing and detail display.
• Layer 5.1: Batch Creation Preview And Explicit Apply Contract.
  • Implement a deterministic preview phase that shows child FEAT folders, EPIC table updates, backlinks, and diagram/progress changes.
  • Require one explicit user confirmation before any writes, leaving the filesystem untouched on cancellation.
• Layer 5.2: Batch Creation Idempotency And Document Update Hardening.
  • Make batch FEAT creation resume-safe and duplicate-safe by creating missing child FEATs in dependency order.
  • Update EPIC tables, diagrams, and progress consistently while preserving existing sections, links, and manual edits.
• Layer 5.3: Targeted EPIC Status Synchronization Hardening.
  • Recalculate EPIC progress from linked child FEAT states, updating only known lifecycle tables, progress values, and Mermaid status classes.
  • Preserve manual content outside those regions and handle missing or malformed references gracefully.
• Layer 5.4: EPIC Lifecycle Manual Acceptance And Operator Documentation.
  • Capture manual acceptance evidence and document the preview/apply contract.
  • Describe handling of duplicate links and partial creation.
  • Record limitations or follow-up work and verify the EPIC can close when child FEATs pass acceptance.
• 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