| 1 | # EPIC Evidence Preparation |
| 2 | |
| 3 | ## EPIC-002 Closure Evidence (Final — Phase 8 complete; ready for PR) |
| 4 | |
| 5 | **Epic:** EPIC-002 — Command Single Responsibility Extraction |
| 6 | **Related EPIC:** [#2870](https://github.com/Hmbown/CodeWhale/issues/2870) |
| 7 | **Related issues:** [#2791](https://github.com/Hmbown/CodeWhale/issues/2791), |
| 8 | [#2851](https://github.com/Hmbown/CodeWhale/pull/2851), |
| 9 | [#2887](https://github.com/Hmbown/CodeWhale/pull/2887) |
| 10 | |
| 11 | This section records final EPIC-002 closure evidence verified during Phase 8 |
| 12 | (final checkpoint). All evidence below was collected on the current working |
| 13 | tree by running the documented commands. |
| 14 | |
| 15 | ### PR References |
| 16 | |
| 17 | - Layer 4 (FEAT-006): Core, config, session, and debug command extraction |
| 18 | - Layer 4.1 (FEAT-007): Project, memory, skills, utility, and plugins extraction |
| 19 | - Layer 4.2 (FEAT-008): Registry cleanup, documentation, and full validation |
| 20 | |
| 21 | ### Acceptance Evidence |
| 22 | |
| 23 | | AT ID | Check | Result | |
| 24 | |-------|-------|--------| |
| 25 | | AT-001 | `cargo test -p codewhale-tui acceptance` (epic_acceptance_harness + eval_harness) | ✅ 2 passed (0 failed) | |
| 26 | | AT-002 | `every_registered_command_dispatches_to_a_handler` | ✅ Passed (part of 489 command tests) | |
| 27 | | AT-003 | `every_command_alias_dispatches_to_a_handler` | ✅ Passed (part of 489 command tests) | |
| 28 | | AT-004 | Help/palette/completion surface tests (included in 489 command tests) | ✅ Passed | |
| 29 | | AT-005 | `dispatch_prefers_user_command_over_builtin_with_same_name` | ✅ Passed | |
| 30 | | AT-006 | `hidden_user_commands_still_dispatch_directly` | ✅ Passed | |
| 31 | | AT-007 | `unknown_command_suggests_nearest_match` | ✅ Passed | |
| 32 | | AT-008 | `command_registry_has_unique_names_and_aliases` | ✅ Passed (0 duplicate names/aliases) | |
| 33 | | AT-009 | `command_ownership_contract_is_enforced` | ✅ Passed (9 groups, layered ownership) | |
| 34 | | AT-010 | Cleanup inventory — no undocumented migration paths | ✅ Verified (all items permanent exceptions or absent) | |
| 35 | | AT-011 | Final closure matrix (this document) | ✅ Complete | |
| 36 | |
| 37 | ### Permanent Exceptions |
| 38 | |
| 39 | | Exception | Rationale | |
| 40 | |-----------|-----------| |
| 41 | | Config group-local metadata | Config `mod.rs` keeps 11 `CommandInfo` statics and dispatch — permanent structure, not cleanup scope | |
| 42 | | Debug group-local metadata | Debug `mod.rs` keeps 11 `CommandInfo` statics and dispatch — permanent structure, not cleanup scope | |
| 43 | | `/jihua`, `/zidong` | Chinese-language back-compat aliases for `/mode` — predate group-owned registry | |
| 44 | | `/set`, `/deepseek` migration hints | Retired commands, direct typed guidance only, excluded from registry/completion | |
| 45 | | `$skill` prefix | Non-slash compatibility syntax, predates EPIC-002 | |
| 46 | | Skill-name fallback | Slash commands fall back to skill dispatch after built-ins and user commands | |
| 47 | | `command_runs_directly()` palette list | UI policy decision, not registry metadata | |
| 48 | | Public re-export bridge paths | Long-standing public API compatibility | |
| 49 | | User-command compatibility loaders | `.deepseek`, `.claude`, `.cursor` directories — user-command scope, not built-in cleanup | |
| 50 | | `#[allow(clippy::module_inception)]` | Intentional structure for same-named group and child modules | |
| 51 | |
| 52 | ### Validation |
| 53 | |
| 54 | - `cargo fmt --all -- --check` — clean |
| 55 | - `cargo check -p codewhale-tui` — clean (no errors, no warnings) |
| 56 | - `cargo test -p codewhale-tui commands::` — 489 passed (0 failed) |
| 57 | - `cargo test -p codewhale-tui acceptance` — 2 passed (epic_acceptance_harness: 1 scenario, 3 steps; eval_harness: 1 test) |
| 58 | - `cargo test --workspace` — 5344 passed, 1 failed (known flaky: `run_verifiers_background_starts_shell_jobs_and_returns_task_ids`; passes in isolation — pre-existing papercut, not a FEAT-008 regression), 2 ignored |
| 59 | - `git diff --check` — clean (both repos) |
| 60 | - Orphaned file check — no orphaned `.rs` files |
| 61 | |
| 62 | ## FEAT-008 PR Summary Draft |
| 63 | |
| 64 | **Title:** Layer 4.2: Registry cleanup, docs, and full validation (FEAT-008) |
| 65 | |
| 66 | ```markdown |
| 67 | Refs #2870. |
| 68 | |
| 69 | ## Summary |
| 70 | |
| 71 | FEAT-008 completes EPIC-002 (Command Single Responsibility Extraction) by |
| 72 | removing transition-only command scaffolding, validating command and alias |
| 73 | uniqueness, updating source-verified command architecture documentation, and |
| 74 | preparing auditable EPIC closure evidence. This is Layer 4.2 (the final cleanup |
| 75 | and validation layer). |
| 76 | |
| 77 | ## Changes |
| 78 | |
| 79 | - No temporary adapters, duplicate command lists, or migration-only dispatch |
| 80 | paths remain — all §3.2 inventory items confirmed as permanent exceptions or |
| 81 | not present after Phase 3 source verification. |
| 82 | - Command registration ownership follows the final layered model: |
| 83 | top-level group registration → group-owned command modules → command-level |
| 84 | metadata and behavior. |
| 85 | - Architecture documentation (`docs/architecture/command-dispatch.md`) updated |
| 86 | to reflect the finalized dispatch flow and permanent exceptions. |
| 87 | - PR/issue evidence document (`docs/architecture/pr-issue-evidence-prep.md`) |
| 88 | prepared for EPIC-002 closure. |
| 89 | |
| 90 | ## Gherkin / Acceptance Coverage |
| 91 | |
| 92 | - `tests/epic_acceptance_harness.rs` — 1 scenario, 3 steps (AT-001) |
| 93 | - `tests/core_session_command_extraction.rs` — 1 scenario, 4 steps (AT-002/003) |
| 94 | - `tests/eval_smoke_acceptance.rs` — 1 scenario, 4 steps (not AT-004 evidence) |
| 95 | - `tests/plugin_e2e_acceptance.rs` — 4 tests (AT-002/003/004 coverage) |
| 96 | - AT-008: `command_registry_has_unique_names_and_aliases` — enforced by test |
| 97 | - AT-009: `command_ownership_contract_is_enforced` — enforced by test |
| 98 | - AT-010: cleanup inventory verified — no undocumented migration paths |
| 99 | |
| 100 | ## Validation |
| 101 | |
| 102 | | Check | Result | |
| 103 | |-------|--------| |
| 104 | | `cargo fmt --all -- --check` | Clean | |
| 105 | | `cargo check -p codewhale-tui` | Clean (0 errors, 0 warnings) | |
| 106 | | `cargo test -p codewhale-tui commands::` | 489 passed, 0 failed | |
| 107 | | `cargo test -p codewhale-tui acceptance` | 2 passed (epic_acceptance_harness: 1, eval_harness: 1) | |
| 108 | | `cargo test --workspace` | 5344 passed, 1 known-flaky (verifier parallel contention; passes in isolation), 2 ignored | |
| 109 | | `git diff --check` | Clean (both repos) | |
| 110 | | Orphaned file check | No orphaned `.rs` files | |
| 111 | | `git status --porcelain` | Clean (CodeWhale repo) | |
| 112 | |
| 113 | Paulo Aboim Pinto |
| 114 | ``` |
| 115 | |
| 116 | --- |
| 117 | |
| 118 | ## EPIC-001 Hunter Replay Evidence |
| 119 | |
| 120 | **Target branch:** `hunter/0.8.62-glm-subagents` |
| 121 | **Replay branch:** `feat/replay-epic-001-on-hunter` |
| 122 | **Related EPIC:** [#2870](https://github.com/Hmbown/CodeWhale/issues/2870) |
| 123 | **Related issue:** [#2791](https://github.com/Hmbown/CodeWhale/issues/2791) |
| 124 | |
| 125 | This section records the working PR/issue evidence checklist for replaying |
| 126 | EPIC-001 FEAT-001, FEAT-002, and FEAT-003 onto the Hunter branch. |
| 127 | |
| 128 | ## Replay Scope |
| 129 | |
| 130 | | Feature | Hunter replay decision | |
| 131 | |---------|------------------------| |
| 132 | | FEAT-001 | No raw cherry-pick. Hunter already contains the newer group-owned command tree and trait-backed registry. | |
| 133 | | FEAT-002 | Replayed semantically as `user_registry.rs`, wired into dispatch, palette, and slash completion. Adapted to keep newer Hunter command-state reset behavior. | |
| 134 | | FEAT-003 | Replayed as public architecture and PR/issue evidence docs for the Hunter target. Old release-branch validation claims were not copied. | |
| 135 | |
| 136 | ## PR Summary Draft |
| 137 | |
| 138 | ```markdown |
| 139 | ## Summary |
| 140 | |
| 141 | Replays the completed EPIC-001 command-boundary work onto |
| 142 | `hunter/0.8.62-glm-subagents`. |
| 143 | |
| 144 | ## Changes |
| 145 | |
| 146 | - Keep Hunter's existing trait-backed built-in command registry and nested |
| 147 | group-owned command tree as the FEAT-001 result. |
| 148 | - Add a dedicated `UserCommandRegistry` boundary for markdown user commands. |
| 149 | - Route user command dispatch, command palette entries, and slash completion |
| 150 | through the registry. |
| 151 | - Preserve Hunter's newer command-state reset behavior when a user command |
| 152 | starts, including todos and plan state. |
| 153 | - Preserve empty `allowed-tools` semantics: an explicit empty value blocks all |
| 154 | tools. |
| 155 | - Add public architecture and PR/issue evidence docs for the Hunter target. |
| 156 | |
| 157 | ## Validation |
| 158 | |
| 159 | - `cargo fmt --all -- --check` |
| 160 | - `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo check -p codewhale-tui` |
| 161 | - `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui commands::` |
| 162 | - `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui command_palette` |
| 163 | - `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui slash_completion` |
| 164 | - `git diff --check` |
| 165 | ``` |
| 166 | |
| 167 | ## Issue #2870 Comment Draft |
| 168 | |
| 169 | ```markdown |
| 170 | EPIC-001 has been replayed onto the Hunter target as a semantic replay rather |
| 171 | than raw cherry-picks. |
| 172 | |
| 173 | - FEAT-001: represented by Hunter's current trait-backed registry and |
| 174 | group-owned command tree. |
| 175 | - FEAT-002: replayed as the user-command registry boundary, adapted to preserve |
| 176 | current Hunter behavior. |
| 177 | - FEAT-003: replayed as public architecture and evidence docs for the Hunter |
| 178 | target. |
| 179 | |
| 180 | Validation evidence is included in the PR body. |
| 181 | |
| 182 | Paulo Aboim Pinto |
| 183 | ``` |
| 184 | |
| 185 | ## Validation Results |
| 186 | |
| 187 | Record live results here before opening or updating the PR. |
| 188 | |
| 189 | | Check | Result | |
| 190 | |-------|--------| |
| 191 | | `cargo fmt --all -- --check` | Pass | |
| 192 | | `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo check -p codewhale-tui` | Pass | |
| 193 | | `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui commands::` | Pass: 456 command tests | |
| 194 | | `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui command_palette` | Pass: 18 tests | |
| 195 | | `CARGO_TARGET_DIR=/tmp/codewhale-hunter-target cargo test -p codewhale-tui slash_completion` | Pass: 17 tests | |
| 196 | | `git diff --check` | Pass | |
| 197 |