claude-code-pilot 2.0.0 → 3.0.0

package/{gsd/get-shit-done → src/pilot}/workflows/execute-plan.md

@@ -6,16 +6,21 @@ Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
 Read STATE.md before any operation to load project context.
 Read config.json for planning behavior settings.
 
-@~/.claude/get-shit-done/references/git-integration.md
+@~/.claude/pilot/references/git-integration.md
 </required_reading>
 
+<available_agent_types>
+Valid CCP subagent types (use exact names — do not fall back to 'general-purpose'):
+- ccp-executor — Executes plan tasks, commits, creates SUMMARY.md
+</available_agent_types>
+
 <process>
 
 <step name="init_context" priority="first">
 Load execution context (paths only to minimize orchestrator context):
 
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
+INIT=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" init execute-phase "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -35,7 +40,7 @@ Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix
 
 ```bash
 PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
-# config settings can be fetched via gsd-tools config-get if needed
+# config settings can be fetched via ccp-tools config-get if needed
 ```
 
 <if mode="yolo">
@@ -67,7 +72,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → spawn Task(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
+**Pattern A:** init_agent_tracking → spawn Task(subagent_type="ccp-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
@@ -100,7 +105,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 
 1. Parse segment map: checkpoint locations and types
 2. Per segment:
-   - Subagent route: spawn gsd-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
+   - Subagent route: spawn ccp-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
@@ -125,7 +130,7 @@ This IS the execution instructions. Follow exactly. If plan references CONTEXT.m
 
 <step name="previous_phase_check">
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phases list --type summaries --raw
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" phases list --type summaries --raw
 # Extract the second-to-last summary from the JSON result
 ```
 If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness" blockers: AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
@@ -135,9 +140,12 @@ If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness
 Deviations are normal — handle via rules below.
 
 1. Read @context files from prompt
-2. Per task:
+2. **MCP tools:** If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch for code navigation), prefer them over Grep/Glob when available. Fall back to Grep/Glob if MCP tools are not accessible.
+3. Per task:
+   - **MANDATORY read_first gate:** If the task has a `<read_first>` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task.
    - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
    - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation.
+   - **MANDATORY acceptance_criteria check:** After completing each task, if it has `<acceptance_criteria>`, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later".
 3. Run `<verification>` checks
 4. Confirm `<success_criteria>` met
 5. Document deviations in Summary
@@ -223,9 +231,28 @@ For `type: tdd` plans — RED-GREEN-REFACTOR:
 
 Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pass → debug, iterate. REFACTOR breaks → undo.
 
-See `~/.claude/get-shit-done/references/tdd.md` for structure.
+See `~/.claude/pilot/references/tdd.md` for structure.
 </tdd_plan_execution>
 
+<precommit_failure_handling>
+## Pre-commit Hook Failure Handling
+
+Your commits may trigger pre-commit hooks. Auto-fix hooks handle themselves transparently — files get fixed and re-staged automatically.
+
+**If running as a parallel executor agent (spawned by execute-phase):**
+Use `--no-verify` on all commits. Pre-commit hooks cause build lock contention when multiple agents commit simultaneously (e.g., cargo lock fights in Rust projects). The orchestrator validates once after all agents complete.
+
+**If running as the sole executor (sequential mode):**
+If a commit is BLOCKED by a hook:
+
+1. The `git commit` command fails with hook error output
+2. Read the error — it tells you exactly which hook and what failed
+3. Fix the issue (type error, lint violation, secret leak, etc.)
+4. `git add` the fixed files
+5. Retry the commit
+6. Budget 1-2 retry cycles per commit
+</precommit_failure_handling>
+
 <task_commit>
 ## Task Commit Protocol
 
@@ -260,6 +287,15 @@ TASK_COMMIT=$(git rev-parse --short HEAD)
 TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 ```
 
+**6. Check for untracked generated files:**
+```bash
+git status --short | grep '^??'
+```
+If new untracked files appeared after running scripts or tools, decide for each:
+- **Commit it** — if it's a source file, config, or intentional artifact
+- **Add to .gitignore** — if it's a generated/runtime output (build artifacts, `.env` files, cache files, compiled output)
+- Do NOT leave generated files untracked
+
 </task_commit>
 
 <step name="checkpoint_protocol">
@@ -275,7 +311,7 @@ Display: `CHECKPOINT: [Type]` box → Progress {X}/{Y} → Task name → type-sp
 
 After response: verify if specified. Pass → continue. Fail → inform, wait. WAIT for user — do NOT hallucinate completion.
 
-See ~/.claude/get-shit-done/references/checkpoints.md for details.
+See ~/.claude/pilot/references/checkpoints.md for details.
 </step>
 
 <step name="checkpoint_return_for_orchestrator">
@@ -287,7 +323,22 @@ Orchestrator parses → presents to user → spawns fresh continuation with your
 </step>
 
 <step name="verification_failure_gate">
-If verification fails: STOP. Present: "Verification failed for Task [X]: [name]. Expected: [criteria]. Actual: [result]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered".
+If verification fails:
+
+**Check if node repair is enabled** (default: on):
+```bash
+NODE_REPAIR=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" config-get workflow.node_repair 2>/dev/null || echo "true")
+```
+
+If `NODE_REPAIR` is `true`: invoke `@~/.claude/pilot/workflows/node-repair.md` with:
+- FAILED_TASK: task number, name, done-criteria
+- ERROR: expected vs actual result
+- PLAN_CONTEXT: adjacent task names + phase goal
+- REPAIR_BUDGET: `workflow.node_repair_budget` from config (default: 2)
+
+Node repair will attempt RETRY, DECOMPOSE, or PRUNE autonomously. Only reaches this gate again if repair budget is exhausted (ESCALATE).
+
+If `NODE_REPAIR` is `false` OR repair returns ESCALATE: STOP. Present: "Verification failed for Task [X]: [name]. Expected: [criteria]. Actual: [result]. Repair attempted: [summary of what was tried]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered".
 </step>
 
 <step name="record_completion_time">
@@ -313,11 +364,11 @@ fi
 grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
 ```
 
-If user_setup exists: create `{phase}-USER-SETUP.md` using template `~/.claude/get-shit-done/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
+If user_setup exists: create `{phase}-USER-SETUP.md` using template `~/.claude/pilot/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
 </step>
 
 <step name="create_summary">
-Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `~/.claude/get-shit-done/templates/summary.md`.
+Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `~/.claude/pilot/templates/summary.md`.
 
 **Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
 
@@ -327,21 +378,21 @@ One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "
 
 Include: duration, start/end times, task count, file count.
 
-Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for transition".
+Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step".
 </step>
 
 <step name="update_current_position">
-Update STATE.md using gsd-tools:
+Update STATE.md using ccp-tools:
 
 ```bash
 # Advance plan counter (handles last-plan edge case)
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state advance-plan
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state advance-plan
 
 # Recalculate progress bar from disk state
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state update-progress
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state update-progress
 
 # Record execution metrics
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state record-metric \
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state record-metric \
   --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
   --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
 ```
@@ -353,19 +404,19 @@ From SUMMARY: Extract decisions and add to STATE.md:
 ```bash
 # Add each decision from SUMMARY key-decisions
 # Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state add-decision \
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state add-decision \
   --phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
 
 # Add blockers if any found
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
 ```
 </step>
 
 <step name="update_session_continuity">
-Update session info using gsd-tools:
+Update session info using ccp-tools:
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state record-session \
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" state record-session \
   --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
   --resume-file "None"
 ```
@@ -379,7 +430,7 @@ If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interacti
 
 <step name="update_roadmap">
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE}"
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" roadmap update-plan-progress "${PHASE}"
 ```
 Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
 </step>
@@ -388,7 +439,7 @@ Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct co
 Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" requirements mark-complete ${REQ_IDS}
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" requirements mark-complete ${REQ_IDS}
 ```
 
 Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
@@ -398,7 +449,7 @@ Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-
 Task code already committed per-task. Commit plan metadata:
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 </step>
 
@@ -413,7 +464,7 @@ git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "" --files .planning/codebase/*.md --amend
 ```
 </step>
 
@@ -427,9 +478,9 @@ ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
-| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/gsd:plan-phase {Z+1}` + `/gsd:verify-work {Z}` + `/gsd:discuss-phase {Z+1}` |
-| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/gsd:complete-milestone` + `/gsd:verify-work` + `/gsd:add-phase` |
+| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/ccp:execute-phase {phase}` + `/ccp:verify-work`. STOP here. |
+| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/ccp:plan-phase {Z+1}` + `/ccp:verify-work {Z}` + `/ccp:discuss-phase {Z+1}` |
+| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/ccp:complete-milestone` + `/ccp:verify-work` + `/ccp:add-phase` |
 
 All routes: `/clear` first for fresh context.
 </step>

package/src/pilot/workflows/fast.md

@@ -0,0 +1,105 @@
+<purpose>
+Execute a trivial task inline without subagent overhead. No PLAN.md, no Task spawning,
+no research, no plan checking. Just: understand → do → commit → log.
+
+For tasks like: fix a typo, update a config value, add a missing import, rename a
+variable, commit uncommitted work, add a .gitignore entry, bump a version number.
+
+Use /ccp:quick for anything that needs multi-step planning or research.
+</purpose>
+
+<process>
+
+<step name="parse_task">
+Parse `$ARGUMENTS` for the task description.
+
+If empty, ask:
+```
+What's the quick fix? (one sentence)
+```
+
+Store as `$TASK`.
+</step>
+
+<step name="scope_check">
+**Before doing anything, verify this is actually trivial.**
+
+A task is trivial if it can be completed in:
+- ≤ 3 file edits
+- ≤ 1 minute of work
+- No new dependencies or architecture changes
+- No research needed
+
+If the task seems non-trivial (multi-file refactor, new feature, needs research),
+say:
+
+```
+This looks like it needs planning. Use /ccp:quick instead:
+  /ccp:quick "{task description}"
+```
+
+And stop.
+</step>
+
+<step name="execute_inline">
+Do the work directly:
+
+1. Read the relevant file(s)
+2. Make the change(s)
+3. Verify the change works (run existing tests if applicable, or do a quick sanity check)
+
+**No PLAN.md.** Just do it.
+</step>
+
+<step name="commit">
+Commit the change atomically:
+
+```bash
+git add -A
+git commit -m "fix: {concise description of what changed}"
+```
+
+Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate.
+</step>
+
+<step name="log_to_state">
+If `.planning/STATE.md` exists, append to the "Quick Tasks Completed" table.
+If the table doesn't exist, skip this step silently.
+
+```bash
+# Check if STATE.md has quick tasks table
+if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then
+  # Append entry — workflow handles the format
+  echo "| $(date +%Y-%m-%d) | fast | $TASK | ✅ |" >> .planning/STATE.md
+fi
+```
+</step>
+
+<step name="done">
+Report completion:
+
+```
+✅ Done: {what was changed}
+   Commit: {short hash}
+   Files: {list of changed files}
+```
+
+No next-step suggestions. No workflow routing. Just done.
+</step>
+
+</process>
+
+<guardrails>
+- NEVER spawn a Task/subagent — this runs inline
+- NEVER create PLAN.md or SUMMARY.md files
+- NEVER run research or plan-checking
+- If the task takes more than 3 file edits, STOP and redirect to /ccp:quick
+- If you're unsure how to implement it, STOP and redirect to /ccp:quick
+</guardrails>
+
+<success_criteria>
+- [ ] Task completed in current context (no subagents)
+- [ ] Atomic git commit with conventional message
+- [ ] STATE.md updated if it exists
+- [ ] Total operation under 2 minutes wall time
+</success_criteria>

package/src/pilot/workflows/forensics.md

@@ -0,0 +1,265 @@
+# Forensics Workflow
+
+Post-mortem investigation for failed or stuck CCP workflows. Analyzes git history,
+`.planning/` artifacts, and file system state to detect anomalies and generate a
+structured diagnostic report.
+
+**Principle:** This is a read-only investigation. Do not modify project files.
+Only write the forensic report.
+
+---
+
+## Step 1: Get Problem Description
+
+```bash
+PROBLEM="$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty, ask the user:
+> "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3',
+> 'execute-phase failed silently', 'costs seem unusually high'."
+
+Record the problem description for the report.
+
+## Step 2: Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt to what exists.
+
+### 2a. Git History
+
+```bash
+# Recent commits (last 30)
+git log --oneline -30
+
+# Commits with timestamps for gap analysis
+git log --format="%H %ai %s" -30
+
+# Files changed in recent commits (detect repeated edits)
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+
+# Uncommitted work
+git status --short
+git diff --stat
+```
+
+Record:
+- Commit timeline (dates, messages, frequency)
+- Most-edited files (potential stuck-loop indicator)
+- Uncommitted changes (potential crash/interruption indicator)
+
+### 2b. Planning State
+
+Read these files if they exist:
+- `.planning/STATE.md` — current milestone, phase, progress, blockers, last session
+- `.planning/ROADMAP.md` — phase list with status
+- `.planning/config.json` — workflow configuration
+
+Extract:
+- Current phase and its status
+- Last recorded session stop point
+- Any blockers or flags
+
+### 2c. Phase Artifacts
+
+For each phase directory in `.planning/phases/*/`:
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, check which artifacts exist:
+- `{padded}-PLAN.md` or `{padded}-PLAN-*.md` (execution plans)
+- `{padded}-SUMMARY.md` (completion summary)
+- `{padded}-VERIFICATION.md` (quality verification)
+- `{padded}-CONTEXT.md` (design decisions)
+- `{padded}-RESEARCH.md` (pre-planning research)
+
+Track: which phases have complete artifact sets vs gaps.
+
+### 2d. Session Reports
+
+Read `.planning/reports/SESSION_REPORT.md` if it exists — extract last session outcomes,
+work completed, token estimates.
+
+### 2e. Git Worktree State
+
+```bash
+git worktree list
+```
+
+Check for orphaned worktrees (from crashed agents).
+
+## Step 3: Detect Anomalies
+
+Evaluate the gathered evidence against these anomaly patterns:
+
+### Stuck Loop Detection
+
+**Signal:** Same file appears in 3+ consecutive commits within a short time window.
+
+```bash
+# Look for files committed repeatedly in sequence
+git log --name-only --format="---COMMIT---" -20
+```
+
+Parse commit boundaries. If any file appears in 3+ consecutive commits, flag as:
+- **Confidence HIGH** if the commit messages are similar (e.g., "fix:", "fix:", "fix:" on same file)
+- **Confidence MEDIUM** if the file appears frequently but commit messages vary
+
+### Missing Artifact Detection
+
+**Signal:** Phase appears complete (has commits, is past in roadmap) but lacks expected artifacts.
+
+For each phase that should be complete:
+- PLAN.md missing → planning step was skipped
+- SUMMARY.md missing → phase was not properly closed
+- VERIFICATION.md missing → quality check was skipped
+
+### Abandoned Work Detection
+
+**Signal:** Large gap between last commit and current time, with STATE.md showing mid-execution.
+
+```bash
+# Time since last commit
+git log -1 --format="%ai"
+```
+
+If STATE.md shows an active phase but the last commit is >2 hours old and there are
+uncommitted changes, flag as potential abandonment or crash.
+
+### Crash/Interruption Detection
+
+**Signal:** Uncommitted changes + STATE.md shows mid-execution + orphaned worktrees.
+
+Combine:
+- `git status` shows modified/staged files
+- STATE.md has an active execution entry
+- `git worktree list` shows worktrees beyond the main one
+
+### Scope Drift Detection
+
+**Signal:** Recent commits touch files outside the current phase's expected scope.
+
+Read the current phase PLAN.md to determine expected file paths. Compare against
+files actually modified in recent commits. Flag any files that are clearly outside
+the phase's domain.
+
+### Test Regression Detection
+
+**Signal:** Commit messages containing "fix test", "revert", or re-commits of test files.
+
+```bash
+git log --oneline -20 | grep -iE "fix test|revert|broken|regression|fail"
+```
+
+## Step 4: Generate Report
+
+Create the forensics directory if needed:
+```bash
+mkdir -p .planning/forensics
+```
+
+Write to `.planning/forensics/report-$(date +%Y%m%d-%H%M%S).md`:
+
+```markdown
+# Forensic Report
+
+**Generated:** {ISO timestamp}
+**Problem:** {user's description}
+
+---
+
+## Evidence Summary
+
+### Git Activity
+- **Last commit:** {date} — "{message}"
+- **Commits (last 30):** {count}
+- **Time span:** {earliest} → {latest}
+- **Uncommitted changes:** {yes/no — list if yes}
+- **Active worktrees:** {count — list if >1}
+
+### Planning State
+- **Current milestone:** {version or "none"}
+- **Current phase:** {number — name — status}
+- **Last session:** {stopped_at from STATE.md}
+- **Blockers:** {any flags from STATE.md}
+
+### Artifact Completeness
+| Phase | PLAN | CONTEXT | RESEARCH | SUMMARY | VERIFICATION |
+|-------|------|---------|----------|---------|-------------|
+{for each phase: name | ✅/❌ per artifact}
+
+## Anomalies Detected
+
+### {Anomaly Type} — {Confidence: HIGH/MEDIUM/LOW}
+**Evidence:** {specific commits, files, or state data}
+**Interpretation:** {what this likely means}
+
+{repeat for each anomaly found}
+
+## Root Cause Hypothesis
+
+Based on the evidence above, the most likely explanation is:
+
+{1-3 sentence hypothesis grounded in the anomalies}
+
+## Recommended Actions
+
+1. {Specific, actionable remediation step}
+2. {Another step if applicable}
+3. {Recovery command if applicable — e.g., `/ccp:resume-work`, `/ccp:execute-phase N`}
+
+---
+
+*Report generated by `/ccp:forensics`. All paths redacted for portability.*
+```
+
+**Redaction rules:**
+- Replace absolute paths with relative paths (strip `$HOME` prefix)
+- Remove any API keys, tokens, or credentials found in git diff output
+- Truncate large diffs to first 50 lines
+
+## Step 5: Present Report
+
+Display the full forensic report inline.
+
+## Step 6: Offer Interactive Investigation
+
+> "Report saved to `.planning/forensics/report-{timestamp}.md`.
+>
+> I can dig deeper into any finding. Want me to:
+> - Trace a specific anomaly to its root cause?
+> - Read specific files referenced in the evidence?
+> - Check if a similar issue has been reported before?"
+
+If the user asks follow-up questions, answer from the evidence already gathered.
+Read additional files only if specifically needed.
+
+## Step 7: Offer Issue Creation
+
+If actionable anomalies were found (HIGH or MEDIUM confidence):
+
+> "Want me to create a GitHub issue for this? I'll format the findings and redact paths."
+
+If confirmed:
+```bash
+# Check if "bug" label exists before using it
+BUG_LABEL=$(gh label list --search "bug" --json name -q '.[0].name' 2>/dev/null)
+LABEL_FLAG=""
+if [ -n "$BUG_LABEL" ]; then
+  LABEL_FLAG="--label bug"
+fi
+
+gh issue create \
+  --title "bug: {concise description from anomaly}" \
+  $LABEL_FLAG \
+  --body "{formatted findings from report}"
+```
+
+## Step 8: Update STATE.md
+
+```bash
+ccp-tools.cjs state record-session \
+  --stopped-at "Forensic investigation complete" \
+  --resume-file ".planning/forensics/report-{timestamp}.md"
+```