@oxgeneral/orch 1.0.7 → 1.0.8

package/skills/library/document-release.md

@@ -0,0 +1,365 @@
+---
+name: document-release
+version: 1.0.0
+description: |
+  Post-ship documentation update. Reads all project docs, cross-references the
+  diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
+  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
+  asked to "update the docs", "sync documentation", or "post-ship docs".
+  Proactively suggest after a PR is merged or code is shipped.
+---
+
+## Step 0: Detect base branch
+
+Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
+
+1. Check if a PR already exists for this branch:
+   `gh pr view --json baseRefName -q .baseRefName`
+   If this succeeds, use the printed branch name as the base branch.
+
+2. If no PR exists (command fails), detect the repo's default branch:
+   `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
+
+3. If both commands fail, fall back to `main`.
+
+Print the detected base branch name. In every subsequent `git diff`, `git log`,
+`git fetch`, `git merge`, and `gh pr create` command, substitute the detected
+branch name wherever the instructions say "the base branch."
+
+---
+
+# Document Release: Post-Ship Documentation Update
+
+You are running the `/document-release` workflow. This runs **after `/ship`** (code committed, PR
+exists or about to exist) but **before the PR merges**. Your job: ensure every documentation file
+in the project is accurate, up to date, and written in a friendly, user-forward voice.
+
+You are mostly automated. Make obvious factual updates directly. Stop and ask only for risky or
+subjective decisions.
+
+**Only stop for:**
+- Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites)
+- VERSION bump decision (if not already bumped)
+- New TODOS items to add
+- Cross-doc contradictions that are narrative (not factual)
+
+**Never stop for:**
+- Factual corrections clearly from the diff
+- Adding items to tables/lists
+- Updating paths, counts, version numbers
+- Fixing stale cross-references
+- CHANGELOG voice polish (minor wording adjustments)
+- Marking TODOS complete
+- Cross-doc factual inconsistencies (e.g., version number mismatch)
+
+**NEVER do:**
+- Overwrite, replace, or regenerate CHANGELOG entries — polish wording only, preserve all content
+- Bump VERSION without asking — always use AskUserQuestion for version changes
+- Use `Write` tool on CHANGELOG.md — always use `Edit` with exact `old_string` matches
+
+---
+
+## Step 1: Pre-flight & Diff Analysis
+
+1. Check the current branch. If on the base branch, **abort**: "You're on the base branch. Run from a feature branch."
+
+2. Gather context about what changed:
+
+```bash
+git diff <base>...HEAD --stat
+```
+
+```bash
+git log <base>..HEAD --oneline
+```
+
+```bash
+git diff <base>...HEAD --name-only
+```
+
+3. Discover all documentation files in the repo:
+
+```bash
+find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.orch/*" -not -path "./.context/*" | sort
+```
+
+4. Classify the changes into categories relevant to documentation:
+   - **New features** — new files, new commands, new skills, new capabilities
+   - **Changed behavior** — modified services, updated APIs, config changes
+   - **Removed functionality** — deleted files, removed commands
+   - **Infrastructure** — build system, test infrastructure, CI
+
+5. Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
+
+---
+
+## Step 2: Per-File Documentation Audit
+
+Read each documentation file and cross-reference it against the diff. Use these generic heuristics
+(adapt to whatever project you're in — these are generic, not project-specific):
+
+**README.md:**
+- Does it describe all features and capabilities visible in the diff?
+- Are install/setup instructions consistent with the changes?
+- Are examples, demos, and usage descriptions still valid?
+- Are troubleshooting steps still accurate?
+
+**ARCHITECTURE.md:**
+- Do ASCII diagrams and component descriptions match the current code?
+- Are design decisions and "why" explanations still accurate?
+- Be conservative — only update things clearly contradicted by the diff. Architecture docs
+  describe things unlikely to change frequently.
+
+**CONTRIBUTING.md — New contributor smoke test:**
+- Walk through the setup instructions as if you are a brand new contributor.
+- Are the listed commands accurate? Would each step succeed?
+- Do test tier descriptions match the current test infrastructure?
+- Are workflow descriptions (dev setup, contributor mode, etc.) current?
+- Flag anything that would fail or confuse a first-time contributor.
+
+**CLAUDE.md / project instructions:**
+- Does the project structure section match the actual file tree?
+- Are listed commands and scripts accurate?
+- Do build/test instructions match what's in package.json (or equivalent)?
+
+**Any other .md files:**
+- Read the file, determine its purpose and audience.
+- Cross-reference against the diff to check if it contradicts anything the file says.
+
+For each file, classify needed updates as:
+
+- **Auto-update** — Factual corrections clearly warranted by the diff: adding an item to a
+  table, updating a file path, fixing a count, updating a project structure tree.
+- **Ask user** — Narrative changes, section removal, security model changes, large rewrites
+  (more than ~10 lines in one section), ambiguous relevance, adding entirely new sections.
+
+---
+
+## Step 3: Apply Auto-Updates
+
+Make all clear, factual updates directly using the Edit tool.
+
+For each file modified, output a one-line summary describing **what specifically changed** — not
+just "Updated README.md" but "README.md: added /new-skill to skills table, updated skill count
+from 9 to 10."
+
+**Never auto-update:**
+- README introduction or project positioning
+- ARCHITECTURE philosophy or design rationale
+- Security model descriptions
+- Do not remove entire sections from any document
+
+---
+
+## Step 4: Ask About Risky/Questionable Changes
+
+For each risky or questionable update identified in Step 2, use AskUserQuestion with:
+- Context: project name, branch, which doc file, what we're reviewing
+- The specific documentation decision
+- `RECOMMENDATION: Choose [X] because [one-line reason]`
+- Options including C) Skip — leave as-is
+
+Apply approved changes immediately after each answer.
+
+---
+
+## Step 5: CHANGELOG Voice Polish
+
+**CRITICAL — NEVER CLOBBER CHANGELOG ENTRIES.**
+
+This step polishes voice. It does NOT rewrite, replace, or regenerate CHANGELOG content.
+
+A real incident occurred where an agent replaced existing CHANGELOG entries when it should have
+preserved them. This skill must NEVER do that.
+
+**Rules:**
+1. Read the entire CHANGELOG.md first. Understand what is already there.
+2. Only modify wording within existing entries. Never delete, reorder, or replace entries.
+3. Never regenerate a CHANGELOG entry from scratch. The entry was written by `/ship` from the
+   actual diff and commit history. It is the source of truth. You are polishing prose, not
+   rewriting history.
+4. If an entry looks wrong or incomplete, use AskUserQuestion — do NOT silently fix it.
+5. Use Edit tool with exact `old_string` matches — never use Write to overwrite CHANGELOG.md.
+
+**If CHANGELOG was not modified in this branch:** skip this step.
+
+**If CHANGELOG was modified in this branch**, review the entry for voice:
+
+- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not,
+  rewrite the wording (not the content).
+- Lead with what the user can now **do** — not implementation details.
+- "You can now..." not "Refactored the..."
+- Flag and rewrite any entry that reads like a commit message.
+- Internal/contributor changes belong in a separate "### For contributors" subsection.
+- Auto-fix minor voice adjustments. Use AskUserQuestion if a rewrite would alter meaning.
+
+---
+
+## Step 6: Cross-Doc Consistency & Discoverability Check
+
+After auditing each file individually, do a cross-doc consistency pass:
+
+1. Does the README's feature/capability list match what CLAUDE.md (or project instructions) describes?
+2. Does ARCHITECTURE's component list match CONTRIBUTING's project structure description?
+3. Does CHANGELOG's latest version match the VERSION file?
+4. **Discoverability:** Is every documentation file reachable from README.md or CLAUDE.md? If
+   ARCHITECTURE.md exists but neither README nor CLAUDE.md links to it, flag it. Every doc
+   should be discoverable from one of the two entry-point files.
+5. Flag any contradictions between documents. Auto-fix clear factual inconsistencies (e.g., a
+   version mismatch). Use AskUserQuestion for narrative contradictions.
+
+---
+
+## Step 7: TODOS.md Cleanup
+
+This is a second pass that complements `/ship`'s Step 5.5. Read `review/TODOS-format.md` (if
+available) for the canonical TODO item format.
+
+If TODOS.md does not exist, skip this step.
+
+1. **Completed items not yet marked:** Cross-reference the diff against open TODO items. If a
+   TODO is clearly completed by the changes in this branch, move it to the Completed section
+   with `**Completed:** vX.Y.Z.W (YYYY-MM-DD)`. Be conservative — only mark items with clear
+   evidence in the diff.
+
+2. **Items needing description updates:** If a TODO references files or components that were
+   significantly changed, its description may be stale. Use AskUserQuestion to confirm whether
+   the TODO should be updated, completed, or left as-is.
+
+3. **New deferred work:** Check the diff for `TODO`, `FIXME`, `HACK`, and `XXX` comments. For
+   each one that represents meaningful deferred work (not a trivial inline note), use
+   AskUserQuestion to ask whether it should be captured in TODOS.md.
+
+---
+
+## Step 8: VERSION Bump Question
+
+**CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.**
+
+1. **If VERSION does not exist:** Skip silently.
+
+2. Check if VERSION was already modified on this branch:
+
+```bash
+git diff <base>...HEAD -- VERSION
+```
+
+3. **If VERSION was NOT bumped:** Use AskUserQuestion:
+   - RECOMMENDATION: Choose C (Skip) because docs-only changes rarely warrant a version bump
+   - A) Bump PATCH (X.Y.Z+1) — if doc changes ship alongside code changes
+   - B) Bump MINOR (X.Y+1.0) — if this is a significant standalone release
+   - C) Skip — no version bump needed
+
+4. **If VERSION was already bumped:** Do NOT skip silently. Instead, check whether the bump
+   still covers the full scope of changes on this branch:
+
+   a. Read the CHANGELOG entry for the current VERSION. What features does it describe?
+   b. Read the full diff (`git diff <base>...HEAD --stat` and `git diff <base>...HEAD --name-only`).
+      Are there significant changes (new features, new skills, new commands, major refactors)
+      that are NOT mentioned in the CHANGELOG entry for the current version?
+   c. **If the CHANGELOG entry covers everything:** Skip — output "VERSION: Already bumped to
+      vX.Y.Z, covers all changes."
+   d. **If there are significant uncovered changes:** Use AskUserQuestion explaining what the
+      current version covers vs what's new, and ask:
+      - RECOMMENDATION: Choose A because the new changes warrant their own version
+      - A) Bump to next patch (X.Y.Z+1) — give the new changes their own version
+      - B) Keep current version — add new changes to the existing CHANGELOG entry
+      - C) Skip — leave version as-is, handle later
+
+   The key insight: a VERSION bump set for "feature A" should not silently absorb "feature B"
+   if feature B is substantial enough to deserve its own version entry.
+
+---
+
+## Step 9: Commit & Output
+
+**Empty check first:** Run `git status` (never use `-uall`). If no documentation files were
+modified by any previous step, output "All documentation is up to date." and exit without
+committing.
+
+**Commit:**
+
+1. Stage modified documentation files by name (never `git add -A` or `git add .`).
+2. Create a single commit:
+
+```bash
+git commit -m "$(cat <<'EOF'
+docs: update project documentation for vX.Y.Z.W
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+```
+
+3. Push to the current branch:
+
+```bash
+git push
+```
+
+**PR body update (idempotent, race-safe):**
+
+1. Read the existing PR body into a PID-unique tempfile:
+
+```bash
+gh pr view --json body -q .body > /tmp/orch-pr-body-$$.md
+```
+
+2. If the tempfile already contains a `## Documentation` section, replace that section with the
+   updated content. If it does not contain one, append a `## Documentation` section at the end.
+
+3. The Documentation section should include a **doc diff preview** — for each file modified,
+   describe what specifically changed (e.g., "README.md: added /document-release to skills
+   table, updated skill count from 9 to 10").
+
+4. Write the updated body back:
+
+```bash
+gh pr edit --body-file /tmp/orch-pr-body-$$.md
+```
+
+5. Clean up the tempfile:
+
+```bash
+rm -f /tmp/orch-pr-body-$$.md
+```
+
+6. If `gh pr view` fails (no PR exists): skip with message "No PR found — skipping body update."
+7. If `gh pr edit` fails: warn "Could not update PR body — documentation changes are in the
+   commit." and continue.
+
+**Structured doc health summary (final output):**
+
+Output a scannable summary showing every documentation file's status:
+
+```
+Documentation health:
+  README.md       [status] ([details])
+  ARCHITECTURE.md [status] ([details])
+  CONTRIBUTING.md [status] ([details])
+  CHANGELOG.md    [status] ([details])
+  TODOS.md        [status] ([details])
+  VERSION         [status] ([details])
+```
+
+Where status is one of:
+- Updated — with description of what changed
+- Current — no changes needed
+- Voice polished — wording adjusted
+- Not bumped — user chose to skip
+- Already bumped — version was set by /ship
+- Skipped — file does not exist
+
+---
+
+## Important Rules
+
+- **Read before editing.** Always read the full content of a file before modifying it.
+- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries.
+- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes.
+- **Be explicit about what changed.** Every edit gets a one-line summary.
+- **Generic heuristics, not project-specific.** The audit checks work on any repo.
+- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
+- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
+  who hasn't seen the code.
+

package/skills/library/freeze.md

@@ -0,0 +1,60 @@
+---
+name: freeze
+version: 0.1.0
+description: |
+  Restrict file edits to a specific directory for the session. Blocks Edit and
+  Write outside the allowed path. Use when debugging to prevent accidentally
+  "fixing" unrelated code, or when you want to scope changes to one module.
+  Use when asked to "freeze", "restrict edits", "only edit this folder",
+  or "lock down edits".
+---
+
+# /freeze — Restrict Edits to a Directory
+
+Lock file edits to a specific directory. Any Edit or Write operation targeting
+a file outside the allowed path will be **blocked** (not just warned).
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Which directory should I restrict edits to? Files outside this path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.orch}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user: "Edits are now restricted to `<path>/`. Any Edit or Write
+outside this directory will be blocked. To change the boundary, run `/freeze`
+again. To remove it, run `/unfreeze` or end the session."
+
+## How it works
+
+The hook reads `file_path` from the Edit/Write tool input JSON, then checks
+whether the path starts with the freeze directory. If not, it returns
+`permissionDecision: "deny"` to block the operation.
+
+The freeze boundary persists for the session via the state file. The hook
+script reads it on every Edit/Write invocation.
+
+## Notes
+
+- The trailing `/` on the freeze directory prevents `/src` from matching `/src-old`
+- Freeze applies to Edit and Write tools only — Read, Bash, Glob, Grep are unaffected
+- This prevents accidental edits, not a security boundary — Bash commands like `sed` can still modify files outside the boundary
+- To deactivate, run `/unfreeze` or end the conversation
+

package/skills/library/guard.md

@@ -0,0 +1,55 @@
+---
+name: guard
+version: 0.1.0
+description: |
+  Full safety mode: destructive command warnings + directory-scoped edits.
+  Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with
+  /freeze (blocks edits outside a specified directory). Use for maximum safety
+  when touching prod or debugging live systems. Use when asked to "guard mode",
+  "full safety", "lock it down", or "maximum safety".
+---
+
+# /guard — Full Safety Mode
+
+Activates both destructive command warnings and directory-scoped edit restrictions.
+This is the combination of `/careful` + `/freeze` in a single command.
+
+**Dependency note:** This skill references hook scripts from the sibling `/careful`
+and `/freeze` skill directories. Both must be installed (they are installed together
+by the setup script).
+
+## Setup
+
+Ask the user which directory to restrict edits to. Use AskUserQuestion:
+
+- Question: "Guard mode: which directory should edits be restricted to? Destructive command warnings are always on. Files outside the chosen path will be blocked from editing."
+- Text input (not multiple choice) — the user types a path.
+
+Once the user provides a directory path:
+
+1. Resolve it to an absolute path:
+```bash
+FREEZE_DIR=$(cd "<user-provided-path>" 2>/dev/null && pwd)
+echo "$FREEZE_DIR"
+```
+
+2. Ensure trailing slash and save to the freeze state file:
+```bash
+FREEZE_DIR="${FREEZE_DIR%/}/"
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.orch}"
+mkdir -p "$STATE_DIR"
+echo "$FREEZE_DIR" > "$STATE_DIR/freeze-dir.txt"
+echo "Freeze boundary set: $FREEZE_DIR"
+```
+
+Tell the user:
+- "**Guard mode active.** Two protections are now running:"
+- "1. **Destructive command warnings** — rm -rf, DROP TABLE, force-push, etc. will warn before executing (you can override)"
+- "2. **Edit boundary** — file edits restricted to `<path>/`. Edits outside this directory are blocked."
+- "To remove the edit boundary, run `/unfreeze`. To deactivate everything, end the session."
+
+## What's protected
+
+See `/careful` for the full list of destructive command patterns and safe exceptions.
+See `/freeze` for how edit boundary enforcement works.
+

package/skills/library/investigate.md

@@ -0,0 +1,171 @@
+---
+name: investigate
+version: 1.0.0
+description: |
+  Systematic debugging with root cause investigation. Four phases: investigate,
+  analyze, hypothesize, implement. Iron Law: no fixes without root cause.
+  Use when asked to "debug this", "fix this bug", "why is this broken",
+  "investigate this error", or "root cause analysis".
+  Proactively suggest when the user reports errors, unexpected behavior, or
+  is troubleshooting why something stopped working.
+---
+
+## Iron Law
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it.
+
+---
+
+## Phase 1: Root Cause Investigation
+
+Gather context before forming any hypothesis.
+
+1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time via AskUserQuestion.
+
+2. **Read the code:** Trace the code path from the symptom back to potential causes. Use Grep to find all references, Read to understand the logic.
+
+3. **Check recent changes:**
+   ```bash
+   git log --oneline -20 -- <affected-files>
+   ```
+   Was this working before? What changed? A regression means the root cause is in the diff.
+
+4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.
+
+Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why.
+
+---
+
+## Scope Lock
+
+After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep.
+
+```bash
+[ -x "${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE"
+```
+
+**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file:
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.orch}"
+mkdir -p "$STATE_DIR"
+echo "<detected-directory>/" > "$STATE_DIR/freeze-dir.txt"
+echo "Debug scope locked to: <detected-directory>/"
+```
+
+Substitute `<detected-directory>` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `<dir>/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction."
+
+If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why.
+
+**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted.
+
+---
+
+## Phase 2: Pattern Analysis
+
+Check if this bug matches a known pattern:
+
+| Pattern | Signature | Where to look |
+|---------|-----------|---------------|
+| Race condition | Intermittent, timing-dependent | Concurrent access to shared state |
+| Nil/null propagation | NoMethodError, TypeError | Missing guards on optional values |
+| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks |
+| Integration failure | Timeout, unexpected response | External API calls, service boundaries |
+| Configuration drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state |
+| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache, Turbo |
+
+Also check:
+- `TODOS.md` for related known issues
+- `git log` for prior fixes in the same area — **recurring bugs in the same files are an architectural smell**, not a coincidence
+
+**External pattern search:** If the bug doesn't match a known pattern above, WebSearch for:
+- "{framework} {generic error type}" — **sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.
+- "{library} {component} known issues"
+
+If WebSearch is unavailable, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3.
+
+---
+
+## Phase 3: Hypothesis Testing
+
+Before writing ANY fix, verify your hypothesis.
+
+1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?
+
+2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If WebSearch is unavailable, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess.
+
+3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion:
+   ```
+   3 hypotheses tested, none match. This may be an architectural issue
+   rather than a simple bug.
+
+   A) Continue investigating — I have a new hypothesis: [describe]
+   B) Escalate for human review — this needs someone who knows the system
+   C) Add logging and wait — instrument the area and catch it next time
+   ```
+
+**Red flags** — if you see any of these, slow down:
+- "Quick fix for now" — there is no "for now." Fix it right or escalate.
+- Proposing a fix before tracing data flow — you're guessing.
+- Each fix reveals a new problem elsewhere — wrong layer, not wrong code.
+
+---
+
+## Phase 4: Implementation
+
+Once root cause is confirmed:
+
+1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem.
+
+2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code.
+
+3. **Write a regression test** that:
+   - **Fails** without the fix (proves the test is meaningful)
+   - **Passes** with the fix (proves the fix works)
+
+4. **Run the full test suite.** Paste the output. No regressions allowed.
+
+5. **If the fix touches >5 files:** Use AskUserQuestion to flag the blast radius:
+   ```
+   This fix touches N files. That's a large blast radius for a bug fix.
+   A) Proceed — the root cause genuinely spans these files
+   B) Split — fix the critical path now, defer the rest
+   C) Rethink — maybe there's a more targeted approach
+   ```
+
+---
+
+## Phase 5: Verification & Report
+
+**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional.
+
+Run the test suite and paste the output.
+
+Output a structured debug report:
+```
+DEBUG REPORT
+════════════════════════════════════════
+Symptom:         [what the user observed]
+Root cause:      [what was actually wrong]
+Fix:             [what was changed, with file:line references]
+Evidence:        [test output, reproduction attempt showing fix works]
+Regression test: [file:line of the new test]
+Related:         [TODOS.md items, prior bugs in same area, architectural notes]
+Status:          DONE | DONE_WITH_CONCERNS | BLOCKED
+════════════════════════════════════════
+```
+
+---
+
+## Important Rules
+
+- **3+ failed fix attempts → STOP and question the architecture.** Wrong architecture, not failed hypothesis.
+- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it.
+- **Never say "this should fix it."** Verify and prove it. Run the tests.
+- **If fix touches >5 files → AskUserQuestion** about blast radius before proceeding.
+- **Completion status:**
+  - DONE — root cause found, fix applied, regression test written, all tests pass
+  - DONE_WITH_CONCERNS — fixed but cannot fully verify (e.g., intermittent bug, requires staging)
+  - BLOCKED — root cause unclear after investigation, escalated