forge-workflow 0.0.1

package/docs/plans/2026-03-02-superpowers-gaps-tasks.md

@@ -0,0 +1,260 @@
+# Task List: superpowers-gaps
+
+**Feature**: superpowers-gaps
+**Design doc**: `docs/plans/2026-03-02-superpowers-gaps-design.md`
+**Beads**: forge-6od
+**Branch**: feat/superpowers-gaps
+**Created**: 2026-03-02
+**Baseline**: 1215 pass, 0 fail
+
+---
+
+## Overview
+
+6 changes, ordered by dependency:
+0a. **Task 0a**: ✅ Entry HARD-GATE in `/plan` — blocks planning if not on master, creates worktree before Phase 1 (DONE: 86eaec8)
+0b. **Task 0b**: ✅ Branch isolation fix in `/plan` Phase 3 — always `git checkout master` before branching (DONE: 9b31bd9)
+1. **Task 1**: DRY gate in `plan.md` Phase 2 (instruction change only — no lib/test change)
+2. **Task 2**: YAGNI filter in `plan.md` Phase 3 + `lib/commands/plan.js` function + test
+3. **Task 3**: Verification HARD-GATE in `dev.md` task completion (instruction change only)
+4. **Task 4**: Rename `/check` → `/validate`: rename files, update lib, update tests, update all references
+
+---
+
+## Task 1: DRY gate in /plan Phase 2
+
+**File(s)**:
+- `.claude/commands/plan.md`
+
+**What to implement**:
+Add an explicit DRY search step to Phase 2's "Codebase exploration" section, immediately before the `HARD-GATE: Phase 2 exit` block. The step must require the agent to use actual search tools (Grep, Glob, Read) — not just "think about it" — to find existing implementations before finalizing the approach. If a match is found, the design doc's approach section must be updated to say "extend existing [file/function]" not "create new".
+
+**TDD steps**:
+1. Write test: `test/commands/plan.phases.test.js` — add test `'should detect DRY violation when existing implementation found'`
+   - Input: mock codebase grep returning a match for a search term
+   - Expected: `detectDRYViolation({ searchTerm: 'validateSlug', matches: [{ file: 'lib/utils.js', line: 42 }] })` returns `{ violation: true, existingFile: 'lib/utils.js', existingLine: 42 }`
+2. Run test: `bun test test/commands/plan.phases.test.js` — confirm it fails (function doesn't exist yet)
+3. Implement: add `detectDRYViolation(params)` to `lib/commands/plan.js` AND add DRY search step to `plan.md` Phase 2 codebase exploration section
+4. Run test: confirm it passes
+5. Commit: `feat: add DRY gate to /plan Phase 2 codebase exploration`
+
+**Expected output**:
+- `plan.md` Phase 2 has new step under "Codebase exploration": "DRY check — before finalizing approach, run grep/glob searches for existing implementations of [key concept from approach]. Document what was found. If match exists: update approach to 'extend [file]', not 'create new'."
+- `lib/commands/plan.js` exports `detectDRYViolation({ searchTerm, matches })` returning `{ violation: bool, existingFile?, existingLine? }`
+- Test passes
+
+---
+
+## Task 2: YAGNI filter in /plan Phase 3 task writing
+
+**File(s)**:
+- `.claude/commands/plan.md`
+- `lib/commands/plan.js`
+- `test/commands/plan.phases.test.js`
+
+**What to implement**:
+Add a YAGNI filter step to Phase 3 Step 5 (task list creation), after the initial task draft but before saving to file. For each task, the agent must confirm it maps to a specific requirement, success criterion, or edge case in the design doc. Tasks with no design doc anchor are flagged. Flagged tasks are presented to the user as "potential scope creep" with the anchor they couldn't find. The user decides: keep (and specify which requirement it serves) or remove.
+
+Special case: if ALL tasks are flagged, return `allFlagged: true` and message "Design doc doesn't cover all tasks — needs amendment."
+
+**TDD steps**:
+1. Write test: `test/commands/plan.phases.test.js` — add 3 tests:
+   - `'should pass YAGNI filter when task maps to design doc requirement'`
+     - Input: `applyYAGNIFilter({ task: 'Add validateSlug function', designDoc: '## Success Criteria\n- validateSlug validates slug format' })`
+     - Expected: `{ flagged: false, anchor: 'Success Criteria: validateSlug validates slug format' }`
+   - `'should flag task with no design doc anchor'`
+     - Input: `applyYAGNIFilter({ task: 'Add dark mode toggle', designDoc: '## Success Criteria\n- validateSlug validates slug format' })`
+     - Expected: `{ flagged: true, reason: 'No matching requirement found in design doc' }`
+   - `'should return allFlagged when all tasks fail YAGNI filter'`
+     - Input: `applyYAGNIFilter({ tasks: ['Task A', 'Task B'], designDoc: '## Purpose\nFoo' })`
+     - Expected: `{ allFlagged: true, message: "Design doc doesn't cover all tasks — needs amendment" }`
+2. Run test: `bun test test/commands/plan.phases.test.js` — confirm all 3 fail
+3. Implement: add `applyYAGNIFilter(params)` to `lib/commands/plan.js` AND add YAGNI filter step to `plan.md` Phase 3 Step 5
+4. Run test: confirm all 3 pass
+5. Commit: `feat: add YAGNI filter to /plan Phase 3 task writing`
+
+**Expected output**:
+- `plan.md` Phase 3 Step 5 has new step after "initial task draft": "YAGNI filter — for each task, find the design doc requirement it serves (success criterion, edge case, constraint). Tasks with no match → flag as 'potential scope creep'. Present flagged tasks to user. User decides: keep (specify requirement) or remove."
+- `lib/commands/plan.js` exports `applyYAGNIFilter({ task|tasks, designDoc })` with correct behavior per tests above
+- All 3 tests pass
+
+---
+
+## Task 3: Verification HARD-GATE in /dev task completion
+
+**File(s)**:
+- `.claude/commands/dev.md`
+
+**What to implement**:
+Upgrade the existing `<HARD-GATE: task completion>` block (currently at line ~178) to require fresh verification evidence before marking a task done. The current gate checks test passage only. The new gate must also require: run the actual implemented function/feature and observe real output. This is the "verification-before-completion" Iron Law from Superpowers: "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE."
+
+The gate must explicitly:
+1. Name what command proves completion
+2. Require running it fresh (not "last run was fine")
+3. Show the actual output
+4. Forbid the phrases: "should pass", "looks good", "seems to work"
+
+This is a `.md` instruction change only — no `lib/` change, no new test. The existing `dev.test.js` tests should continue to pass.
+
+**TDD steps**:
+1. Write test: `test/commands/dev.test.js` — add test `'should require fresh verification evidence in completion gate'`
+   - Search for `HARD-GATE: task completion` in dev.md content
+   - Expected: the gate text includes "fresh" AND "actual output" AND does NOT include any path that allows "should pass" without running
+   - This is a documentation structure test: `const content = fs.readFileSync('.claude/commands/dev.md'); expect(content).toContain('fresh'); expect(content).toContain('actual output');`
+2. Run test: `bun test test/commands/dev.test.js` — confirm it fails (current gate doesn't have this language)
+3. Implement: update the `<HARD-GATE: task completion>` block in `dev.md` with the verification-before-completion language
+4. Run test: confirm it passes
+5. Commit: `feat: add verification-before-completion to /dev task completion gate`
+
+**Expected output**:
+- `dev.md` task completion HARD-GATE includes:
+  - "Run the implemented function/feature and observe actual output (not just tests)"
+  - "Forbidden: 'should pass', 'looks good', 'seems to work' — these are not evidence"
+  - "Required: paste actual command + actual output before marking task done"
+- Test passes
+
+---
+
+## Task 4: Rename /check → /validate + add 4-phase debug mode
+
+This is the largest task. Split into 4 sub-tasks for clarity, but implement as one committed change (keep atomic).
+
+### Task 4a: Rename core files
+
+**File(s)**:
+- `.claude/commands/check.md` → `.claude/commands/validate.md`
+- `lib/commands/check.js` → `lib/commands/validate.js`
+- `test/commands/check.test.js` → `test/commands/validate.test.js`
+
+**What to implement**:
+- Copy check.md to validate.md, update heading and command references inside
+- Copy check.js to validate.js, update function name exports (`executeCheck` → `executeValidate`, etc.) and the `require()` path in validate.test.js
+- Delete original check.md, check.js, check.test.js after copies are correct
+- Verify tests pass: `bun test test/commands/validate.test.js`
+
+**TDD steps**:
+1. Write test: `test/commands/validate.test.js` (copy of check.test.js with updated imports/names)
+   - Key test: `'should run all validations in sequence'` using `executeValidate()` instead of `executeCheck()`
+   - Additional test: `'should export executeValidate function'` — `const { executeValidate } = require('../../lib/commands/validate.js'); expect(typeof executeValidate).toBe('function')`
+2. Run test: `bun test test/commands/validate.test.js` — confirm it fails (validate.js doesn't exist)
+3. Implement: create validate.js (copy+rename from check.js), create validate.md (copy+rename from check.md)
+4. Run test: confirm it passes
+5. Do NOT delete check.js/check.md yet — wait for Task 4d to update all references first
+
+### Task 4b: Add 4-phase debug mode to validate.md
+
+**File(s)**:
+- `.claude/commands/validate.md`
+- `lib/commands/validate.js`
+- `test/commands/validate.test.js`
+
+**What to implement**:
+Add debug mode as a new section in `validate.md` that activates when any validation step fails. The section must implement the 4-phase systematic debug flow:
+- Phase D1: Reproduce — confirm failure is deterministic, exact error output
+- Phase D2: Root-cause trace — trace failure to source (not symptom)
+- Phase D3: Fix — SINGLE minimal fix, ONE change at a time, FAILING TEST FIRST
+- Phase D4: Verify — re-run full validation from beginning, confirm fix works end-to-end
+
+HARD-GATE in debug mode: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST" and "3+ fix attempts = STOP, question architecture."
+
+In `lib/commands/validate.js`, add:
+- `executeDebugMode({ error, fixAttempts })` — returns `{ escalate: bool, phase: 'D1'|'D2'|'D3'|'D4' }`
+- When `fixAttempts >= 3` → returns `{ escalate: true, message: 'STOP: 3+ fixes. Question architecture before Fix #4.' }`
+
+**TDD steps**:
+1. Write test: `test/commands/validate.test.js` — add 3 tests:
+   - `'should enter debug mode on validation failure'`
+     - Input: `executeDebugMode({ error: 'Test failed: expected 42, got 0', fixAttempts: 0 })`
+     - Expected: `{ escalate: false, phase: 'D1' }`
+   - `'should escalate when 3+ fix attempts'`
+     - Input: `executeDebugMode({ error: 'still failing', fixAttempts: 3 })`
+     - Expected: `{ escalate: true, message: ... }`
+   - `'should require fresh verification before claiming fix works'`
+     - Input: `executeDebugMode({ error: 'err', fixAttempts: 1, claim: 'should be fixed now' })`
+     - Expected: `{ valid: false, reason: 'No fresh verification evidence — run validation fresh' }`
+2. Run test: confirm all 3 fail
+3. Implement: add `executeDebugMode()` to `lib/commands/validate.js` AND add 4-phase debug section to `validate.md`
+4. Run test: confirm all 3 pass
+5. Hold commit until Task 4c complete
+
+### Task 4c: Update all /check references in command docs
+
+**File(s)**:
+- `.claude/commands/dev.md`
+- `.claude/commands/plan.md`
+- `.claude/commands/ship.md`
+- `.claude/commands/review.md`
+- `.claude/commands/premerge.md`
+- `.claude/commands/verify.md`
+- `.claude/commands/research.md`
+- `.claude/commands/rollback.md`
+- `.claude/rules/workflow.md`
+- `AGENTS.md`
+
+**What to implement**:
+Replace all `/check` references with `/validate` in the files listed above. Also update:
+- `check.md` → `validate.md` in any file link (`[.claude/commands/check.md]`)
+- `<HARD-GATE: /check exit>` → `<HARD-GATE: /validate exit>`
+- Stage description in workflow table: "Type check, lint, code review, security, tests" → "Validate: type check, lint, tests, security. On failure: 4-phase debug mode."
+
+**TDD steps**:
+1. Write test: `test/commands/validate.test.js` — add test:
+   - `'AGENTS.md should reference /validate not /check'`
+     - `const content = fs.readFileSync('AGENTS.md', 'utf-8'); expect(content).not.toContain('/check'); expect(content).toContain('/validate');`
+2. Run test: confirm it fails (AGENTS.md still has /check)
+3. Implement: batch-replace `/check` → `/validate` across all listed files
+4. Run test: confirm it passes
+5. Hold commit until Task 4d complete
+
+### Task 4d: Update docs + GitHub files, delete old check files
+
+**File(s)**:
+- `docs/WORKFLOW.md`
+- `docs/TOOLCHAIN.md`
+- `docs/VALIDATION.md`
+- `docs/EXAMPLES.md`
+- `docs/README-v1.3.md`
+- `docs/ROADMAP.md`
+- `docs/MANUAL_REVIEW_GUIDE.md`
+- `docs/ENHANCED_ONBOARDING.md`
+- `.github/CONTRIBUTING.md`
+- `.github/pull_request_template.md`
+- `.github/agentic-workflows/behavioral-test.md`
+- Delete: `.claude/commands/check.md`, `lib/commands/check.js`, `test/commands/check.test.js`
+
+**What to implement**:
+- Batch-replace `/check` → `/validate` in all docs/ and .github/ files
+- Delete the original check.md, check.js, check.test.js (now superseded)
+- Update `check.md` links in CONTRIBUTING.md to point to `validate.md`
+
+**TDD steps**:
+1. Write test: `test/commands/validate.test.js` — add test:
+   - `'check.md should no longer exist'`
+     - `const exists = fs.existsSync('.claude/commands/check.md'); expect(exists).toBe(false);`
+2. Run test: confirm it fails (check.md still exists)
+3. Implement: replace in all docs files, then delete check.md, check.js, check.test.js
+4. Run test: confirm it passes
+5. Now run FULL test suite: `bun test` — confirm 1215 pass, 0 fail (minus the removed check.test.js tests now in validate.test.js)
+6. Commit all Task 4a-4d changes: `feat: rename /check to /validate with 4-phase debug mode on failure`
+
+---
+
+## Flagged Tasks (No Design Doc Anchor — Pre-Cleared with User)
+
+None. All tasks above map directly to confirmed requirements in the design doc.
+
+---
+
+## Summary
+
+| Task | Files Changed | Type | Effort |
+|---|---|---|---|
+| Task 1: DRY gate | plan.md, plan.js, plan.phases.test.js | feature | Small |
+| Task 2: YAGNI filter | plan.md, plan.js, plan.phases.test.js | feature | Small |
+| Task 3: Verification gate | dev.md, dev.test.js | feature | Tiny |
+| Task 4a: Core rename | validate.md, validate.js, validate.test.js | refactor | Medium |
+| Task 4b: Debug mode | validate.md, validate.js, validate.test.js | feature | Medium |
+| Task 4c: Command doc refs | 9 command/rule files | refactor | Small |
+| Task 4d: Docs + delete | 8 docs + 3 github + 3 deletes | refactor | Small |
+
+**Total**: 7 sub-tasks, ~4 distinct TDD cycles

package/docs/plans/2026-03-04-agent-command-parity-design.md

@@ -0,0 +1,163 @@
+# Design: Agent Command Parity
+
+- **Slug**: agent-command-parity
+- **Date**: 2026-03-04
+- **Status**: Superseded by 2026-03-15-agent-command-parity-v2-design.md
+
+---
+
+## Purpose
+
+Every major AI coding agent (Claude Code, Cursor, Codex CLI, OpenCode, Cline, Windsurf, Aider, Kilo, Roo, Continue, Copilot) should have the full Forge workflow implemented using that agent's **native mechanism** — whether that's slash commands, workflow files, rules/context injection, or prompt files.
+
+Currently only Claude Code has complete command support. Cursor/Cline/Codex/OpenCode/Windsurf have partial or no implementation. Stage count is inconsistent across files (7 vs 9 stages). The `check → validate` rename exists only in feat/superpowers-gaps (PR 50).
+
+**Critically**: Since Forge is used as a framework across many projects, manually cross-checking every agent after each change is not viable. This feature also ships `forge check-agents` — a CLI command any project can run to automatically verify all agent configs are complete and consistent. This becomes part of every project's `/check` stage.
+
+---
+
+## Success Criteria
+
+1. **Claude Code**: Already complete — verify stays correct after PR 50 merge
+2. **OpenCode**: `.opencode/commands/` — 7 stage command files
+3. **Antigravity**: `.agents/workflows/` — 7 stage workflow files (triggered with `/workflow-name`)
+4. **Cursor**: `.cursor/commands/` — 7 stage command files (beta v1.6+)
+5. **Cline**: `.clinerules/workflows/` — 7 stage workflow files (v3.13+)
+6. **Windsurf**: `.windsurf/workflows/` — 7 stage workflow files
+7. **Kilo Code**: `.kilocode/commands/` — 7 stage command files
+8. **Roo Code**: `.roo/commands/` — 7 stage command files
+9. **Continue**: `.continue/prompts/` — 7 `.prompt` files with `invokable: true`
+10. **GitHub Copilot**: `.github/prompts/` — 7 `.prompt.md` files
+11. **Codex VS Code ext**: `.agents/skills/forge-workflow/SKILL.md` — shared dir with Antigravity; invoked `$forge-workflow` (no project-level `/` commands possible)
+12. **Aider**: ~~dropped~~ — built-in `/commands` conflict with Forge commands, no custom slash command support, degraded UX. Use Claude Code or any other supported agent instead.
+13. **All configs consistent**: Same 7-stage workflow, same command names (post-PR-50 = `/validate` not `/check`)
+14. **Plugin catalog updated**: `lib/agents/*.plugin.json` — all capability flags correct
+15. **`forge check-agents` CLI command**: Verifies all agent configs are complete and consistent; ships as part of Forge CLI.
+
+---
+
+## Out of Scope
+
+- Inventing new workflow stages — the 7-stage workflow is frozen pending PR 50 merge
+- Implementing the workflow logic itself (commands already exist in `.claude/commands/`)
+- Cross-agent testing infrastructure (separate feature)
+- Merging PR 50 (user does that manually)
+
+---
+
+## Dependencies
+
+- **PR 50 must merge first** (`feat/superpowers-gaps`) — it contains `check → validate` rename and other fixes; all agent files in this plan use `/validate` naming
+- This work branches from master **after** PR 50 merges
+
+---
+
+## Approach Selected
+
+**Native mechanism per agent**: Each agent gets the files appropriate to its actual command system. The source of truth for command content is `.claude/commands/*.md` (which will have `validate.md` post-PR-50). All other agent files are adapters of this source.
+
+**Agent priority order** (true slash commands first, then best-effort):
+1. Claude Code — already complete, verify after PR 50 merge
+2. OpenCode — `.opencode/commands/*.md`
+3. Antigravity — `.agents/workflows/*.md` (also has `.agents/skills/` shared with Codex)
+4. Cursor — `.cursor/commands/*.md` (beta v1.6+)
+5. Cline — `.clinerules/workflows/*.md` (v3.13+)
+6. Windsurf — `.windsurf/workflows/*.md`
+7. Kilo Code — `.kilocode/commands/*.md`
+8. Roo Code — `.roo/commands/*.md`
+9. Continue — `.continue/prompts/*.prompt` (with `invokable: true`)
+10. GitHub Copilot — `.github/prompts/*.prompt.md`
+11. Codex (VS Code ext) — `.agents/skills/forge-workflow/SKILL.md` (shared dir with Antigravity; no `/` commands; uses `$skill-name` or implicit)
+12. Aider — **dropped** (built-in command conflicts, no slash command support)
+
+**Build order**:
+1. Research: confirm exact file format for each agent (especially Codex CLI, Windsurf, Kilo, Roo, Continue, Copilot)
+2. Implement priority 2–8 (native command/workflow/prompt files)
+3. Implement priority 9–11 (context-injection agents — update rules/context files)
+4. Update plugin catalog (`lib/agents/*.plugin.json`) to reflect actual capabilities
+5. Update AGENTS.md to be the consistent, authoritative cross-agent reference
+6. Build `forge check-agents` CLI command — validates all agent configs in any project using Forge
+
+---
+
+## Constraints
+
+- **UX parity**: User types `/plan`, `/dev`, `/validate`, `/ship`, `/review`, `/premerge`, `/verify` — same command names in every agent, same resulting behavior. The agent handles it natively or via context, but the UX is identical.
+- **Context-injection agents must be actionable**: For Cursor native/Cline — config files must read as "when you see `/plan`, do X" not "here is documentation about X". Imperative, not descriptive.
+- **AGENTS.md stays small**: It is always-loaded context (Aider, Codex skills, etc.). Keep it as a concise imperative command reference — not a documentation dump. Full step-by-step detail lives only in per-agent command files, loaded on demand.
+- Command content must be consistent across all agents (same steps, same HARD-GATEs)
+- No introducing new workflow logic — just adapting existing `.claude/commands/` content
+- File formats must match each agent's actual spec (confirmed via research, not assumed)
+- Ambiguity policy: Pause and ask user if any agent's format is unexpected
+
+---
+
+## Edge Cases
+
+- **Codex VS Code extension `/commands` in UI = built-in system commands only**: No project-level custom slash commands. Use Skills at `.agents/skills/forge-workflow/SKILL.md` — invoked with `$forge-workflow` or implicitly. The `/` menu shown in UI is not extensible per-project.
+- **Cursor has TWO separate systems**: `.cursor/rules/*.mdc` = persistent context injected every prompt (NOT commands). `.cursor/commands/*.md` = true slash commands (beta v1.6+, triggered on-demand with `/`). We implement both.
+- **Cline has TWO separate systems**: `.clinerules/*.md` = persistent rules. `.clinerules/workflows/*.md` = true slash commands (v3.13+). We implement workflows for commands.
+- **Continue uses `.prompt` extension, not `.md`**: `invokable: true` frontmatter required to enable slash command.
+- **Copilot uses `.prompt.md` double extension**: File must be in `.github/prompts/`.
+- **Some agents don't support hooks**: Windsurf (`.windsurf/hooks.json`) and Copilot (`.github/hooks/*.json`, Preview) support hooks. Codex CLI, Roo, Kilo, Continue do not. Only implement hooks for agents confirmed above.
+- **PR 50 not merged when starting /dev**: Do not start /dev until PR 50 is merged — all files use `/validate`, not `/check`
+- **Plugin.json out of sync**: Multiple plugin files have wrong capability flags — `cursor.plugin.json` says `commands: false` (correct — Cursor uses extension), Codex CLI plugin is missing entirely, hooks flags are all unset.
+
+---
+
+## Ambiguity Policy
+
+If any agent's native command format is discovered to differ from what was researched, **pause and ask the user** before implementing. Document the finding and proposed approach, then wait for approval.
+
+---
+
+## Technical Research
+
+### Agent Command/Workflow File Formats (Confirmed)
+
+| Agent | Command Dir | File Ext | Key Frontmatter | Trigger | Hooks |
+|-------|------------|----------|-----------------|---------|-------|
+| Claude Code | `.claude/commands/` | `.md` | `description:` | `/name` | `.claude/settings.json` |
+| OpenCode | `.opencode/commands/` | `.md` | `description`, `agent`, `model`, `subtask` | `/name` | Plugin JS/TS: 25+ events |
+| **Antigravity** | `.agents/workflows/` | `.md` | `description:` (optional) | `/name` | `.agents/hooks/` (TBD) |
+| Cursor | `.cursor/commands/` | `.md` | None required | `/name` | None |
+| Cline | `.clinerules/workflows/` | `.md` | None required | `/name` | None |
+| Windsurf | `.windsurf/workflows/` | `.md` | None required | `/name` | `.windsurf/hooks.json`: 12 events |
+| Kilo Code | `.kilocode/commands/` | `.md` | `description`, `mode` | `/name` | None |
+| Roo Code | `.roo/commands/` | `.md` | `description`, `argument-hint`, `mode` | `/name` | None |
+| Continue | `.continue/prompts/` | `.prompt` | `name`, `description`, `invokable: true` | `/name` | None |
+| Copilot | `.github/prompts/` | `.prompt.md` | `name`, `description`, `agent`, `model`, `tools` | `/name` | `.github/hooks/*.json`: 8 events |
+| Codex (ext) | `.agents/skills/<name>/` | `SKILL.md` | `name`, `description` | `$name` (implicit) | None shipped |
+| Aider | **dropped** — command conflicts | — | — | — | — |
+
+### OWASP Top 10 Analysis
+
+This feature writes config/instruction files — no user input processing, no auth, no network calls from config files themselves. Risk surface is minimal:
+
+- **A01 Broken Access Control**: N/A — no access control in config files
+- **A02 Cryptographic Failures**: N/A
+- **A03 Injection**: Low risk — hook scripts run shell commands. Mitigate: all hook scripts in `.windsurf/hooks.json` and `.github/hooks/*.json` use hardcoded paths, no user input interpolated.
+- **A05 Security Misconfiguration**: Moderate — agent permission configs (opencode.json, `.codex/config.toml`) must not over-grant. Mitigate: follow existing deny/ask/allow patterns established in current configs.
+- **A08 Software and Data Integrity**: Low — config files are checked into git, integrity protected by version control.
+- **Others (A04, A06, A07, A09, A10)**: Not applicable to static config files.
+
+### TDD Test Scenarios (for `forge check-agents`)
+
+1. **Happy path**: Project with all agent dirs populated → `forge check-agents` exits 0, prints "All agents: OK"
+2. **Missing command file**: Project missing `.opencode/commands/validate.md` → exits non-zero, prints which file is missing for which agent
+3. **Inconsistent stage count**: `.windsurfrules` says 9 stages, plugin says 7 → check flags inconsistency
+4. **Unknown agent format in plugin**: plugin.json references directory that doesn't exist → check warns, doesn't error (agent may not be installed)
+5. **Wrong file extension**: `.continue/prompts/validate.md` instead of `validate.prompt` → check flags extension error
+
+### Sources
+
+- [OpenAI Codex CLI Skills](https://developers.openai.com/codex/skills/)
+- [OpenCode Commands](https://opencode.ai/docs/commands/)
+- [Windsurf Workflows](https://docs.windsurf.com/windsurf/cascade/workflows)
+- [Windsurf Hooks](https://docs.windsurf.com/windsurf/cascade/hooks)
+- [Kilo Code Workflows](https://kilo.ai/docs/customize/workflows)
+- [Roo Code Commands](https://docs.roocode.com/features/slash-commands)
+- [Continue Prompt Files](https://docs.continue.dev/customize/deep-dives/prompts)
+- [GitHub Copilot Prompts](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
+- [GitHub Copilot Hooks](https://code.visualstudio.com/docs/copilot/customization/hooks)
+- [Antigravity Workflows](https://docs.antigravity.dev/workflows) <!-- agent-command-parity research; verify URL when implementing -->

package/docs/plans/2026-03-04-verify-worktree-cleanup-decisions.md

@@ -0,0 +1,7 @@
+# Decisions Log: verify-worktree-cleanup
+
+- **Feature**: verify-worktree-cleanup
+- **Date**: 2026-03-04
+- **Beads**: forge-bmi
+
+_No decisions logged yet._

package/docs/plans/2026-03-04-verify-worktree-cleanup-design.md

@@ -0,0 +1,165 @@
+# Design: Fix /verify to Clean Up Worktree and Branch After Merge
+
+- **Slug**: verify-worktree-cleanup
+- **Date**: 2026-03-04
+- **Status**: Approved
+- **Beads**: forge-bmi
+
+---
+
+## Purpose
+
+`/verify` runs after a PR merges. Currently it checks CI and deployments, but never removes the feature worktree or local branch — leaving stale state in the repo. The example output even shows "Branch: feat/auth-refresh deleted ✓" but no step actually does this.
+
+Result: every merged feature leaves a dangling worktree + local branch forever, requiring manual cleanup.
+
+---
+
+## Success Criteria
+
+1. After `/verify` runs on a healthy merge, the feature worktree is removed (`git worktree remove`)
+2. After `/verify` runs on a healthy merge, the local feature branch is deleted (`git branch -d`)
+3. If the worktree directory doesn't exist (already cleaned up manually), step skips gracefully
+4. If the branch is already deleted, step skips gracefully
+5. Cleanup only happens after CI is confirmed healthy — not before
+6. The HARD-GATE is updated to include cleanup as a required step
+7. All other agents' verify command files are updated identically (if they exist)
+
+---
+
+## Out of Scope
+
+- Deleting the remote branch (GitHub does that automatically on merge with branch auto-delete enabled)
+- Cleanup on unhealthy merges (user may need to inspect the worktree)
+- Creating new worktree cleanup infrastructure — this is just adding `git worktree remove` + `git branch -d` to the existing verify steps
+
+---
+
+## Approach Selected
+
+Add two steps to `/verify` between the existing "Step 5: Report Status" and "Step 7: Close Beads Issue":
+
+**New Step 6: Clean Up Worktree and Branch**
+
+The feature branch name is known from the Beads issue or from `git worktree list`. Steps:
+1. Run `git worktree list` to find the worktree path for the merged branch
+2. `git worktree remove <path>` (if it exists)
+3. `git branch -d <branch>` (if it still exists locally)
+4. Report cleanup in the status output
+
+Cleanup is conditional on healthy CI (Step 3 passed). If CI failed, skip cleanup and note it in the output.
+
+---
+
+## Constraints
+
+- Cleanup is **destructive** — must only run after confirming the merge actually landed (`gh pr list --state merged` confirmed in Step 2)
+- Must be idempotent — if worktree or branch already gone, skip silently
+- `git branch -d` (safe delete) not `git branch -D` (force) — if branch has unmerged commits it should warn rather than silently delete
+- Do not remove worktrees that belong to other in-progress features
+
+---
+
+## Edge Cases
+
+- **Worktree already removed**: `git worktree list` won't show it — skip gracefully
+- **Branch already deleted**: `git branch -d` exits non-zero if branch doesn't exist — catch and skip
+- **Multiple worktrees**: `git worktree list` may show multiple — only remove the one matching the merged branch
+- **No worktree was ever created**: Some workflows skip worktree setup — if no matching worktree found, skip cleanup step entirely
+- **Stale superpowers-gaps worktree**: This fix will clean up the `feat/superpowers-gaps` worktree the next time a verify-like cleanup is run manually (`git worktree remove .worktrees/superpowers-gaps`)
+
+---
+
+## Ambiguity Policy
+
+If the merged branch name cannot be determined (e.g., squash merge loses branch name), skip cleanup and tell the user: "Could not determine feature branch — run `git worktree list` and `git worktree remove <path>` manually."
+
+---
+
+## Technical Research
+
+### How to detect which worktree to remove
+
+```bash
+# List all worktrees with their branches
+git worktree list --porcelain
+# Output includes: worktree <path>, HEAD <sha>, branch refs/heads/<name>
+# Find the entry where branch = merged branch name
+```
+
+### How to get merged branch name
+
+From the PR info retrieved in Step 2:
+```bash
+gh pr view <number> --json headRefName --jq '.headRefName'
+```
+
+### OWASP Analysis
+
+- No user input processed — branch names come from `git` and `gh` CLI output
+- `git worktree remove` and `git branch -d` are local operations only
+- No injection risk — branch names passed as arguments are from controlled sources
+- Risk: **A01 Broken Access Control** — N/A (local git operations)
+- Risk: **A03 Injection** — minimal; branch names from `gh` output, not user-typed. Mitigate: use `--` separator in git commands if needed.
+
+### TDD Test Scenarios
+
+1. **Happy path**: Worktree exists for merged branch → removed, branch deleted, report shows cleanup
+2. **Worktree already gone**: `git worktree list` has no entry for branch → skip silently, no error
+3. **Branch already deleted**: `git branch -d` fails → catch, skip, log "branch already deleted"
+4. **CI failed**: Step 3 detected failing CI → skip cleanup entirely, leave worktree intact
+5. **Multiple worktrees**: Two worktrees exist → only the one matching merged branch is removed
+
+---
+
+## Task List
+
+### Task 1: Update `.claude/commands/verify.md` — add cleanup steps
+
+**File(s)**: `.claude/commands/verify.md`
+
+**What to implement**:
+- Add **Step 6: Clean Up Worktree and Branch** between current Step 5 (Report Status) and Step 7 (Close Beads):
+  1. Get merged branch name: `gh pr view <number> --json headRefName --jq '.headRefName'`
+  2. Find matching worktree: `git worktree list --porcelain | grep <branch>`
+  3. If found: `git worktree remove <path> --force` (force needed because bun install creates node_modules)
+  4. Delete local branch: `git branch -d <branch>` (safe delete, skip if not found)
+  5. Report: "Worktree: removed ✓" / "Branch: deleted ✓" in status output
+- Update example output to show cleanup lines (they're already in the example — just need the actual steps)
+- Update HARD-GATE to add: "Worktree removed (or confirmed already gone)"
+
+**TDD steps**:
+1. Write test: `test/commands/verify.test.js` — check that verify.md contains "worktree remove", "branch -d", and the HARD-GATE mentions worktree cleanup
+2. Run test: `bun test test/commands/verify.test.js` — fails (those strings not in file)
+3. Implement: edit verify.md to add Step 6
+4. Run test: passes
+5. Commit: `fix: add worktree and branch cleanup to /verify stage`
+
+**Expected output**: verify.md has Step 6 with worktree/branch cleanup; test passes.
+
+---
+
+### Task 2: Clean up the stale `superpowers-gaps` worktree now
+
+**File(s)**: none (one-time cleanup)
+
+**What to implement**:
+The `feat/superpowers-gaps` worktree at `.worktrees/superpowers-gaps` is stale — PR 50 merged. Remove it manually as a one-time fix:
+```bash
+git worktree remove .worktrees/superpowers-gaps --force
+git branch -d feat/superpowers-gaps
+```
+
+**TDD steps**:
+1. Run: `git worktree list` — confirm superpowers-gaps appears
+2. Run cleanup: `git worktree remove .worktrees/superpowers-gaps --force && git branch -d feat/superpowers-gaps`
+3. Run: `git worktree list` — confirm it's gone
+4. Commit: `chore: clean up stale superpowers-gaps worktree`
+
+**Expected output**: `git worktree list` shows only master and active feature worktrees.
+
+---
+
+## Ordering
+
+Task 2 can run in parallel with Task 1 — it's a one-time cleanup independent of the command file edit.

package/docs/plans/2026-03-05-forge-uto-decisions.md

@@ -0,0 +1,6 @@
+# Decisions Log: forge-uto
+
+- **Feature**: forge-uto
+- **Date**: 2026-03-05
+
+(No decisions logged yet — populated during /dev)