feat: add three-layer swarm command conflict prevention system

.claude/issue-traces/740/01-issue-body.md

@@ -0,0 +1,101 @@
+## Summary
+
+7 findings from the holistic council review of the Swarm Command Conflict Prevention implementation (3 phases, 14 tasks). These are non-blocking advisory items that should be addressed to close remaining gaps in test coverage, runtime safety, spec accuracy, and quality assurance.
+
+---
+
+### Finding 1: Add FR-014 performance and idempotency tests (HIGH)
+
+**Location:** `src/hooks/cc-command-intercept.ts` / `src/hooks/cc-command-intercept.test.ts`
+
+**Issue:** The spec (FR-014, SC-004) requires automated verification that the runtime hook processes messages in under 5ms (for a 10,000-token message) and is idempotent (applying twice produces identical output to applying once). Neither test exists.
+
+**Acceptance criteria:**
+- [ ] Performance test: generate a ~10,000-token message, pass through `createCcCommandInterceptHook({}).messagesTransform`, assert processing time < 5ms
+- [ ] Idempotency test: apply hook to a bare `/plan` message, save result; apply hook again to the result; assert both outputs are identical
+- [ ] Both tests run as part of `bun test src/hooks/cc-command-intercept.test.ts`
+
+---
+
+### Finding 2: Add runtime protection for `/checkpoint` (MEDIUM)
+
+**Location:** `src/hooks/cc-command-intercept.ts` lines 165-204
+
+**Issue:** `/checkpoint` is classified as **CRITICAL** in the conflict registry but the runtime hook does nothing when it encounters bare `/checkpoint`. It's neither hard-blocked (like `/reset`/`/clear`) nor soft-corrected (like `/plan`).
+
+**Proposed fix:** Add `/checkpoint` to the hard-block list or soft-correct it to `/swarm checkpoint <action>`.
+
+**Acceptance criteria:**
+- [ ] Bare `/checkpoint` in an agent message results in runtime intervention
+- [ ] Existing adversarial tests still pass
+- [ ] `/checkpoint` inside code blocks, URLs, comments, or `/swarm`-namespaced is unaffected
+
+---
+
+### Finding 3: Write task gate evidence for Phase 3 tasks 3.2 and 3.3 (MEDIUM)
+
+**Location:** `.swarm/evidence/`
+
+**Issue:** Task 3.2 (adversarial tests) and Task 3.3 (hook registration) have deliverables on disk but no gate evidence files (`3.2.json`, `3.3.json`) in `.swarm/evidence/`. Phase 3 completion-verify only reports 1 of 3 tasks checked.
+
+**Acceptance criteria:**
+- [ ] `.swarm/evidence/3.2.json` exists with reviewer + test_engineer gate results
+- [ ] `.swarm/evidence/3.3.json` exists with reviewer + test_engineer gate results
+- [ ] `completion-verify` for Phase 3 reports 3/3 tasks
+
+---
+
+### Finding 4: Add prompt content regression tests (MEDIUM)
+
+**Location:** `tests/unit/agents/`
+
+**Issue:** COMMAND NAMESPACE blocks exist in all 4 agent prompts but no automated tests verify they persist. A prompt refactor could silently remove hardening.
+
+**Acceptance criteria:**
+- [ ] Tests verify `## COMMAND NAMESPACE` presence in architect.ts, coder.ts, reviewer.ts, test-engineer.ts
+- [ ] Specific command names flagged: `/plan`, `/reset`, `/checkpoint`, `/clear`, `/compact`
+- [ ] Specific directive language checked: `NEVER`, `PROHIBITED`, `DO NOT INVOKE`
+- [ ] Removing a COMMAND NAMESPACE block causes a test failure
+
+---
+
+### Finding 5: Update FR-012 spec text to match implementation (LOW)
+
+**Location:** `.swarm/spec.md` FR-012
+
+**Issue:** Spec says "throws a structured error" but implementation uses output mutation (replacing message content) — necessary because `composeHandlers` wraps in `safeHook` which catches thrown errors.
+
+**Fix:** Update FR-012 to say "replaces the message content via output mutation with a structured advisory."
+
+---
+
+### Finding 6: Expand reviewer/test-engineer prompt coverage (LOW)
+
+**Location:** `src/agents/reviewer.ts`, `src/agents/test-engineer.ts`
+
+**Issue:** Prompts list 6 commands only. Missing: `/agents`, `/config`, `/export`, `/doctor`, `/history`.
+
+**Fix:** Evaluate whether to expand to include all 9 conflicts or document the scope decision.
+
+---
+
+### Finding 7: Add config-option tests for the hook (LOW)
+
+**Location:** `src/hooks/cc-command-intercept.ts`
+
+**Issue:** All 45 tests use default config. No test exercises `blockDestructive: false`, `intercept: ['CRITICAL']`, or `logIntercepts: false`.
+
+**Acceptance criteria:**
+- [ ] `blockDestructive: false` — `/reset` passes through unblocked
+- [ ] `intercept: ['CRITICAL']` — `/status` (HIGH) is not intercepted
+- [ ] `logIntercepts: false` — logger.warn is NOT called for HIGH commands
+
+---
+
+## Priority
+
+1. **Finding 1** (perf/idempotency tests) — highest priority, spec-requirement gap
+2. **Finding 2** (/checkpoint runtime gap) — CRITICAL classification, no runtime protection
+3. **Finding 4** (prompt regression tests) — protects against silent regression
+4. **Finding 3** (gate evidence) — process completeness
+5. **Findings 5-7** — polish and spec accuracy

.claude/session/swarm-mode.md

@@ -60,3 +60,23 @@ Ignore these thoughts:
 - "I should move on because this is taking too long"
 
 If any of those appear, slow down and return to the workflow.
+
+## Command Namespace
+
+All swarm commands use the /swarm <subcommand> form.
+
+The following bare slash commands share names with swarm subcommands and must never
+be invoked in a swarm session:
+
+| Bare CC Command | Why Prohibited | Swarm Equivalent |
+|---|---|---|
+| `/plan` | Enters CC plan mode — blocks execution | `/swarm plan` |
+| `/reset` | Wipes conversation context | `/swarm reset --confirm` |
+| `/checkpoint` | Reverts conversation history | `/swarm checkpoint <action>` |
+| `/clear` | Wipes conversation context | — |
+| `/compact` | Corrupts task-critical context | — |
+| `/status` | Shows CC version info | `/swarm status` |
+| `/agents` | Manages CC subagent configs | `/swarm agents` |
+| `/config` | Opens CC settings | `/swarm config` |
+| `/export` | Exports conversation text | `/swarm export` |
+| `/memory` | Edits CLAUDE.md | Use swarm knowledge tools |

.claude/skills/swarm-implement/SKILL.md

@@ -24,6 +24,18 @@ Use this execution ladder:
 This is not a slow full-swarm recreation.
 This is a speed-preserving, quality-maximizing workflow.
 
+## Command Namespace
+
+Swarm commands: always /swarm <subcommand> — never bare subcommand names.
+
+CRITICAL — these CC built-ins share names with swarm commands and MUST be avoided:
+  /plan → use /swarm plan (reading) or do not invoke (entering plan mode)
+  /reset → NEVER invoke — wipes conversation context
+  /checkpoint → NEVER invoke bare — use /swarm checkpoint <action>
+
+HIGH — these CC built-ins produce wrong output:
+  /status → use /swarm status (not CC /status)
+
 ## Quality and speed policy
 - Quality and pre-ship defect detection are paramount.
 - Speed still matters.

.claude/skills/swarm/SKILL.md

@@ -15,9 +15,65 @@ Argument handling:
 - If the first word of `$ARGUMENTS` is a **known plugin subcommand** (see list below): do NOT treat it as a swarm task. Instead, tell the user to run it as a slash command directly (e.g., `/swarm close`, `/swarm handoff`). These are OpenCode plugin commands handled by the swarm plugin's command system, not tasks for the swarm workflow. Do NOT try to interpret or execute them yourself.
 - Otherwise: enable swarm mode, then treat `$ARGUMENTS` as the task to execute immediately.
 
-Known plugin subcommands (do NOT interpret these as tasks):
-<!-- Keep in sync with COMMAND_REGISTRY in src/commands/registry.ts -->
-`status`, `plan`, `agents`, `history`, `config`, `evidence`, `handoff`, `archive`, `diagnose`, `diagnosis`, `preflight`, `sync-plan`, `benchmark`, `export`, `reset`, `rollback`, `retrieve`, `clarify`, `analyze`, `specify`, `brainstorm`, `qa-gates`, `dark-matter`, `knowledge`, `curate`, `turbo`, `full-auto`, `write-retro`, `reset-session`, `simulate`, `promote`, `issue`, `pr-review`, `checkpoint`, `close`
+### SWARM-NAMESPACED subcommands — DO NOT confuse with Claude Code built-in commands
+
+These are invoked as `/swarm <subcommand>`, NOT as bare `/subcommand`:
+
+- `/swarm status` — show current swarm status
+- `/swarm plan` — view or manage implementation plan
+- `/swarm agents` — list available swarm agents
+- `/swarm history` — view swarm execution history
+- `/swarm config` — view swarm configuration
+- `/swarm evidence` — view evidence files
+- `/swarm handoff` — hand off to another agent
+- `/swarm archive` — archive swarm sessions
+- `/swarm diagnose` / `/swarm diagnosis` — diagnose swarm issues
+- `/swarm preflight` — run preflight checks
+- `/swarm sync-plan` — sync plan with repository
+- `/swarm benchmark` — run benchmarks
+- `/swarm export` — export swarm data
+- `/swarm reset` — reset swarm state
+- `/swarm rollback` — rollback to previous state
+- `/swarm retrieve` — retrieve swarm data
+- `/swarm clarify` — clarify swarm task
+- `/swarm analyze` — analyze swarm execution
+- `/swarm specify` — specify swarm requirements
+- `/swarm brainstorm` — brainstorm swarm tasks
+- `/swarm qa-gates` — manage QA gates
+- `/swarm dark-matter` — detect hidden couplings
+- `/swarm knowledge` — manage knowledge base
+- `/swarm curate` — curate knowledge
+- `/swarm turbo` — enable turbo mode
+- `/swarm full-auto` — enable full auto mode
+- `/swarm write-retro` — write retrospective
+- `/swarm reset-session` — reset session
+- `/swarm simulate` — simulate swarm execution
+- `/swarm promote` — promote knowledge
+- `/swarm issue` — create issue
+- `/swarm pr-review` — review pull request
+- `/swarm checkpoint` — checkpoint session state
+- `/swarm close` — close swarm session
+
+### CRITICAL NAMING CONFLICTS
+
+These swarm subcommands share exact names with CC built-in commands.
+Invoking the bare form instead of `/swarm <name>` causes irreversible damage:
+
+| Swarm Command | CC Built-in | Damage |
+|---|---|---|
+| `/swarm plan` | CC `/plan` | Enters CC plan mode — blocks execution |
+| `/swarm reset` | CC `/reset` | Wipes entire conversation context |
+| `/swarm checkpoint` | CC `/checkpoint` | Reverts conversation history |
+
+All swarm commands: `/swarm <subcommand>`. Never the bare name.
+
+### COMMAND INVOCATION RULE
+
+All commands in this list are invoked as `/swarm <subcommand>`.
+Never invoke the bare subcommand as a standalone slash command.
+`/plan`, `/status`, `/reset`, `/checkpoint`, `/agents`, `/config`, `/export`, `/doctor`
+are Claude Code built-in commands with completely different behaviors.
+The `/swarm` prefix is mandatory, not optional.
 
 Examples:
 - `/swarm` — enable swarm mode only

.github/workflows/ci.yml

@@ -1,17 +1,16 @@
 name: CI
 
 on:
-  push:
-    branches: ["**"]
   pull_request:
     branches: ["**"]
 
-# Cancel in-progress runs for the same branch when a new push arrives.
-# Groups push and pull_request events for the same branch together so only
-# one run proceeds at a time, preventing double-run dist-check interference.
+# Serialize CI runs for the same branch/PR to prevent double-run dist-check
+# interference. Old runs are NOT cancelled because cancelling leaves stale
+# check statuses that persist on PRs and block merging even after a new
+# successful run completes.
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 permissions:
   contents: read

CHANGELOG.md

@@ -1,18 +1,17 @@
 # Changelog
 
-## [7.3.7](https://github.com/zaxbysauce/opencode-swarm/compare/v7.3.6...v7.3.7) (2026-05-03)
-
-
-### Bug Fixes
-
-* rename release docs from v7.3.6 to v7.3.7; improve deadlock reset assertion ([dd04c18](https://github.com/zaxbysauce/opencode-swarm/commit/dd04c1814b322569e42c3e4d6e40fdfb01b44bf0))
+## [Unreleased]
 
-## [7.3.6](https://github.com/zaxbysauce/opencode-swarm/compare/v7.3.5...v7.3.6) (2026-05-03)
+### Features
 
+* **conflict-registry:** add pure-data module mapping 9 swarm commands to their CC built-in counterparts with severity ratings (CRITICAL/HIGH/MEDIUM); commands with conflicts display a ⚠️ warning in `/swarm help` output
+* **ci-gate:** add `src/commands/conflict-registry.test.ts` CI gate that prevents new CRITICAL conflicts from being merged without explicit acknowledgment in the test allow-list
+* **constants:** add `CLAUDE_CODE_NATIVE_COMMANDS` frozen set (115 CC built-in commands) to `src/config/constants.ts` for runtime intercept hook; includes `freezeSet()` helper that throws on mutation attempts
 
-### Bug Fixes
+### Changed
 
-* **mutation:** bound generateMutants with timeout; fix git apply CRLF failure on Windows ([#739](https://github.com/zaxbysauce/opencode-swarm/issues/739)) ([de535a2](https://github.com/zaxbysauce/opencode-swarm/commit/de535a2ef37bd8d07b45c906ea499e9ddd065b92))
+* **registry:** add optional `clashesWithNativeCcCommand` field to `CommandEntry` type; populated on 9 commands (`plan`, `reset`, `checkpoint`, `status`, `agents`, `config`, `export`, `doctor`, `history`)
+* **index:** `buildHelpText()` now renders a ⚠️ conflict warning line for every command that has `clashesWithNativeCcCommand` set
 
 ## [7.3.5](https://github.com/zaxbysauce/opencode-swarm/compare/v7.3.4...v7.3.5) (2026-05-03)
 

README.md

@@ -229,6 +229,8 @@ All 41 subcommands at a glance:
 
 Use `/swarm help` to see all available commands categorized by function. Use `/swarm help <command>` for detailed usage information on a specific command.
 
+Nine commands display a ⚠️ warning in help output because they share names with Claude Code built-in slash commands (e.g., `/plan`, `/reset`, `/status`). The warning reminds you to always use `/swarm <command>` — the bare CC command does something different and sometimes destructive. See [docs/commands.md#claude-code-command-conflicts](docs/commands.md#claude-code-command-conflicts) for the full conflict registry.
+
 See [docs/commands.md](docs/commands.md) for the full reference (41 commands).
 
 ## Command Aliases

dist/agents/prompt-namespace.test.d.ts

@@ -0,0 +1 @@
+export {};