claude-code-scanner 1.0.0

package/template/.claude/docs/task-record-schema.md

@@ -0,0 +1,196 @@
+# Task Record Schema
+
+## File: `.claude/tasks/TASK-{id}.md`
+
+### Frontmatter
+```yaml
+---
+id: TASK-{number}
+title: {title}
+type: feature | bugfix | refactor | hotfix | tech-debt | spike
+scope: frontend-only | backend-only | fullstack | infrastructure | cross-cutting
+complexity: small | medium | large
+priority: P0-critical | P1-high | P2-medium | P3-low
+status: {state — see State Machine below}
+branch: {branch name}
+pr: {PR number or "pending"}
+assigned-to: {agent name or "unassigned"}
+depends-on: {TASK-id or "none"}
+created: {ISO timestamp}
+updated: {ISO timestamp}
+---
+```
+
+### Current Status Section
+- Phase, state, progress %, last activity, next action, blocked Y/N
+
+### Loop State Section
+Track all active correspondence loops to survive compaction:
+```markdown
+## Loop State
+
+### Dev-Test Loop (Phase 6)
+- dev-test-loop: iteration N/5
+- coverage-baseline: N%
+- coverage-current: N%
+- fix-agent: @debugger|@api-builder|@frontend|@infra
+- last-failure: [test name] — [error] at [ISO timestamp]
+
+### Review-Rework Loop (Phase 7)
+- review-loop: iteration N/3
+- reviewer-status: APPROVE | REQUEST_CHANGES (N critical, M suggestions)
+- security-status: APPROVE | REQUEST_CHANGES (N findings)
+- open-comments: [count] critical, [count] suggestions
+- addressed-comments: [count] fixed, [count] won't-fix
+
+### CI Fix Loop (Phase 8)
+- ci-fix-loop: iteration N/3
+- last-ci-failure: [check name] — [error] at [ISO timestamp]
+- fix-agent: @debugger|@api-builder|@frontend|@infra|@tester
+
+### QA Bug Loop (Phase 9)
+- qa-bug-loop:
+  - BUG-{id}-1 (P1): iteration N/3 — [OPEN|FIXED|VERIFIED|REOPENED]
+  - BUG-{id}-2 (P3): known-issue
+- total-bugs: N found, M fixed, K verified, J known-issues
+- regression-check-after-each-fix: true
+
+### Sign-off Rejection Loop (Phase 10)
+- signoff-rejection-cycle: N/2
+- qa-signoff: APPROVED|CONDITIONAL|REJECTED|PENDING
+- biz-signoff: APPROVED|REJECTED|PENDING
+- tech-signoff: APPROVED|REJECTED|PENDING
+- last-rejection: [who] — [reason] at [ISO timestamp]
+
+### Deploy Loop (Phase 11)
+- deploy-loop: iteration N/2
+- last-deploy-failure: [error type] — [summary] at [ISO timestamp]
+- rollback-executed: true|false
+```
+
+### Loop Counter Reset Rules
+| Event | Counters That Reset |
+|-------|-------------------|
+| Phase 10 rejects -> Phase 5 | dev-test, review, ci-fix reset to 0 |
+| Phase 10 rejects -> Phase 4 or 3 | ALL loop counters reset to 0 |
+| Deploy fails -> Phase 5 | dev-test, review, ci-fix reset to 0 |
+| Normal phase advance | Counters preserved for reporting |
+| Agent timeout in loop | Counts as +1 to current loop iteration |
+| ON_HOLD -> resume | ALL loop counters preserved (no reset) |
+
+## Task State Machine
+```
+Forward flow:
+BACKLOG -> INTAKE -> ANALYZING -> DESIGNING -> APPROVED -> DEVELOPING
+  -> DEV_TESTING -> REVIEWING -> CI_PENDING -> QA_TESTING
+  -> QA_SIGNOFF -> BIZ_SIGNOFF -> TECH_SIGNOFF
+  -> DEPLOYING -> MONITORING -> CLOSED
+
+Phase-to-state mapping:
+  Phase 1  = INTAKE
+  Phase 2  = ANALYZING
+  Phase 3  = DESIGNING
+  Phase 4  = APPROVED (after user confirms)
+  Phase 5  = DEVELOPING
+  Phase 6  = DEV_TESTING
+  Phase 7  = REVIEWING
+  Phase 8  = CI_PENDING
+  Phase 9  = QA_TESTING
+  Phase 10 = QA_SIGNOFF -> BIZ_SIGNOFF -> TECH_SIGNOFF
+  Phase 11 = DEPLOYING
+  Phase 12 = MONITORING
+  Phase 13 = CLOSED (after final report)
+
+Special states (from ANY active state):
+  -> BLOCKED (waiting on depends-on or manual unblock)
+  -> ON_HOLD (deferred by user/product-owner, resume with /workflow resume)
+  -> CANCELLED (terminal, cleanup executed)
+
+Reverse transitions (rejection routing):
+  QA_SIGNOFF -> DEVELOPING (QA rejects: bugs)
+  BIZ_SIGNOFF -> APPROVED (reqs wrong) or DEVELOPING (UI wrong)
+  TECH_SIGNOFF -> DESIGNING (architecture) or DEVELOPING (perf/tests)
+  DEPLOYING -> DEVELOPING (code bug) or DEPLOYING (config retry)
+
+Circuit breaker -> escalated to user (stays in current state until resolved)
+```
+
+### Timeline Section
+Every event: timestamp, phase, event description, agent/actor, duration
+
+### Handoff Log
+Track every agent-to-agent handoff:
+```markdown
+## Handoff Log
+| Timestamp | From | To | Reason | Artifacts | Status |
+|-----------|------|-----|--------|-----------|--------|
+| 2026-03-26T10:00:00Z | @explorer | @team-lead | impact analysis complete | scan-results.md | complete |
+| 2026-03-26T10:05:00Z | @team-lead | @api-builder | backend dev assigned | TASK-001.md | complete |
+```
+
+### Phase Detail Sections (1-13)
+Each phase records specific outputs:
+- **Phase 1:** type, scope, complexity, branch name, task record created
+- **Phase 2:** files affected, blast radius, test coverage %, security flags, risk level
+- **Phase 3:** approach chosen, alternatives rejected, files to create/modify, breaking changes
+- **Phase 4:** acceptance criteria list with PENDING/VERIFIED/FAILED status
+- **Phase 5:** agents active, files created/modified, lines +/-, tests written, sub-phase status
+- **Phase 6:** unit/integration/e2e results, coverage delta, bugs found/fixed, retry count
+- **Phase 7:** review result, critical issues, suggestions, security review, iteration count
+- **Phase 8:** PR number/URL, CI check results, fix iterations
+- **Phase 9:** scenario results (happy/edge/regression/perf/security/a11y), issues found
+- **Phase 10:** QA/business/tech sign-off status with who/when/conditions
+- **Phase 11:** target env, pre-checks, deploy method, health check, rollback needed
+- **Phase 12:** monitoring duration, error rate, latency impact, issues closed
+
+### Blocker Log
+| Timestamp | Blocker | Severity | Owner | Resolved | Resolution |
+
+### Decision Log
+| Timestamp | Decision | Rationale | Made By | Reversible |
+
+### Risk Register
+| Risk | Likelihood | Impact | Mitigation | Status |
+
+### Execution Report Section
+Per-phase and cumulative execution analytics:
+```markdown
+## Execution Reports
+| Phase | Score | Hallucination | Regression | Tokens | Agents | Handoffs |
+|-------|-------|---------------|------------|--------|--------|----------|
+| 2 | 85/100 | 0 (CLEAN) | 0 (CLEAN) | ~12k | 2 | 3 |
+| 5 | 72/100 | 1 (MINOR) | 0 (CLEAN) | ~45k | 4 | 8 |
+| 6 | 90/100 | 0 (CLEAN) | 0 (CLEAN) | ~18k | 2 | 4 |
+| ... | | | | | | |
+| **TOTAL** | **82/100** | **1** | **0** | **~120k** | **8** | **24** |
+
+### Bottleneck Analysis
+- Slowest phase: Phase 5 (Development) — 45k tokens, 4 agents
+- Most rework: Phase 7 (Review) — 2 iterations
+- Highest context: Phase 5 — peaked at 58%
+
+### Lessons Learned
+- {Actionable insight for next time}
+```
+
+Full execution reports saved to: `.claude/reports/executions/TASK-{id}_phase-{N}_{timestamp}.md`
+Cumulative report saved to: `.claude/reports/executions/TASK-{id}_final.md`
+
+## Bug Record Format
+```
+BUG-{task_id}-{number}
+Severity: P0-P4
+Summary, Steps to Reproduce, Expected/Actual, Evidence
+Assigned: @agent-name
+Status: OPEN -> IN_PROGRESS -> FIXED -> QA_VERIFY -> VERIFIED/REOPENED -> CLOSED
+```
+
+## Directory Structure
+```
+.claude/tasks/TASK-001.md
+.claude/tasks/TASK-001_changes.log
+.claude/reports/daily/{date}.md
+.claude/reports/weekly/{week}.md
+.claude/reports/executions/TASK-001_phase-2_2026-03-26T100000Z.md
+.claude/reports/executions/TASK-001_final.md
+```

package/template/.claude/hooks/drift-detector.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// SessionStart hook: lightweight drift detection on startup
+// Checks for obvious staleness — full sync requires /sync skill
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const claudeDir = path.join(process.cwd(), '.claude');
+const manifestPath = path.join(claudeDir, 'manifest.json');
+
+// Only run if .claude/ exists (environment is set up)
+if (!fs.existsSync(claudeDir)) process.exit(0);
+
+const warnings = [];
+
+// --- 1. Check manifest freshness ---
+let manifest = null;
+let daysSinceSync = Infinity;
+
+if (fs.existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    const lastSync = new Date(manifest.last_sync);
+    daysSinceSync = Math.floor((Date.now() - lastSync.getTime()) / (1000 * 60 * 60 * 24));
+
+    if (daysSinceSync > 14) {
+      warnings.push(`DRIFT: Last sync was ${daysSinceSync} days ago. Run /sync --check`);
+    }
+  } catch (e) {
+    warnings.push('DRIFT: manifest.json is corrupted. Run /sync --fix');
+  }
+} else {
+  // No manifest = never synced — only warn if environment looks established
+  const agentsDir = path.join(claudeDir, 'agents');
+  if (fs.existsSync(agentsDir) && fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length > 0) {
+    warnings.push('DRIFT: No manifest.json found. Run /sync --check to create baseline');
+  }
+}
+
+// --- 2. Quick agent count check ---
+const agentsDir = path.join(claudeDir, 'agents');
+const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+
+if (fs.existsSync(agentsDir) && fs.existsSync(claudeMdPath)) {
+  const agentFiles = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+  const claudeMd = fs.readFileSync(claudeMdPath, 'utf-8');
+
+  // Count @agent mentions in CLAUDE.md (only from the Agent Team table)
+  const agentTableMatch = claudeMd.match(/## Agent Team[\s\S]*?(?=\n## |$)/);
+  const agentSection = agentTableMatch ? agentTableMatch[0] : '';
+  const agentMentions = (agentSection.match(/@[\w-]+/g) || [])
+    .filter(a => a !== '@imports' && a !== '@path');
+  const uniqueMentions = [...new Set(agentMentions)];
+
+  if (agentFiles.length !== uniqueMentions.length) {
+    warnings.push(`DRIFT: ${agentFiles.length} agent files but ${uniqueMentions.length} agents in CLAUDE.md. Run /sync --fix`);
+  }
+}
+
+// --- 3. Quick dependency file change check ---
+const depFiles = ['package.json', 'go.mod', 'Cargo.toml', 'requirements.txt', 'pyproject.toml', 'Gemfile', 'pom.xml'];
+if (manifest && manifest.tech_stack) {
+  for (const depFile of depFiles) {
+    const depPath = path.join(process.cwd(), depFile);
+    if (fs.existsSync(depPath)) {
+      const currentHash = crypto.createHash('sha256')
+        .update(fs.readFileSync(depPath))
+        .digest('hex')
+        .substring(0, 16);
+
+      const manifestEntry = manifest.tech_stack[depFile];
+      if (manifestEntry && manifestEntry.hash && manifestEntry.hash !== currentHash) {
+        warnings.push(`DRIFT: ${depFile} changed since last sync. Run /sync --check`);
+        break; // One dependency warning is enough
+      }
+    }
+  }
+}
+
+// --- 4. Quick hook registration check ---
+const hooksDir = path.join(claudeDir, 'hooks');
+const settingsPath = path.join(claudeDir, 'settings.json');
+
+if (fs.existsSync(hooksDir) && fs.existsSync(settingsPath)) {
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    const hookFiles = fs.readdirSync(hooksDir).filter(f => f.endsWith('.js'));
+    const registeredHooks = new Set();
+
+    for (const [event, matchers] of Object.entries(settings.hooks || {})) {
+      for (const matcher of matchers) {
+        for (const hook of (matcher.hooks || [])) {
+          if (hook.type === 'command' && hook.command) {
+            const match = hook.command.match(/([\w-]+\.js)/);
+            if (match) registeredHooks.add(match[1]);
+          }
+        }
+      }
+    }
+
+    const orphanHooks = hookFiles.filter(f => !registeredHooks.has(f));
+    if (orphanHooks.length > 0) {
+      warnings.push(`DRIFT: ${orphanHooks.length} hook(s) not registered in settings.json: ${orphanHooks.join(', ')}`);
+    }
+
+    for (const registered of registeredHooks) {
+      if (!hookFiles.includes(registered)) {
+        warnings.push(`DRIFT: settings.json references ${registered} but file not found`);
+      }
+    }
+  } catch (e) {
+    // settings.json parse error — protect-files hook will catch this
+  }
+}
+
+// --- 5. Quick skill directory check ---
+const skillsDir = path.join(claudeDir, 'skills');
+if (fs.existsSync(skillsDir)) {
+  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+
+  for (const skill of skillDirs) {
+    const skillMd = path.join(skillsDir, skill, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      warnings.push(`DRIFT: Skill directory ${skill}/ exists but has no SKILL.md`);
+    }
+  }
+}
+
+// --- Output warnings ---
+if (warnings.length > 0) {
+  console.log('');
+  for (const w of warnings) {
+    console.log(w);
+  }
+  if (warnings.length >= 3) {
+    console.log(`\n${warnings.length} drift issues detected. Run: /sync --check (for report) or /sync --fix (to auto-repair)`);
+  }
+}
+
+process.exit(0);

package/template/.claude/hooks/execution-report.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Stop hook: collect execution metadata and prompt for execution report generation
+// Runs on session Stop to capture final execution state
+
+const fs = require('fs');
+const path = require('path');
+
+const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+const reportsDir = path.join(process.cwd(), '.claude', 'reports', 'executions');
+
+// Find active task
+let activeTask = null;
+let activeTaskPath = null;
+
+try {
+// Ensure reports directory exists
+if (!fs.existsSync(reportsDir)) {
+  fs.mkdirSync(reportsDir, { recursive: true });
+}
+
+if (fs.existsSync(tasksDir)) {
+  const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+  for (const tf of taskFiles) {
+    const taskPath = path.join(tasksDir, tf);
+    const content = fs.readFileSync(taskPath, 'utf-8');
+    if (/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING)/.test(content)) {
+      activeTask = content;
+      activeTaskPath = taskPath;
+      break;
+    }
+  }
+}
+
+if (!activeTask) {
+  // No active task — output minimal execution snapshot
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    task: 'none',
+    status: 'no active task found'
+  };
+  console.log(`EXECUTION SNAPSHOT: ${JSON.stringify(snapshot)}`);
+  process.exit(0);
+}
+
+// Extract task metadata
+const idMatch = activeTask.match(/^id:\s*(.+)$/m);
+const titleMatch = activeTask.match(/^title:\s*(.+)$/m);
+const statusMatch = activeTask.match(/^status:\s*(.+)$/m);
+const taskId = idMatch ? idMatch[1].trim() : 'UNKNOWN';
+const taskTitle = titleMatch ? titleMatch[1].trim() : 'UNKNOWN';
+const taskStatus = statusMatch ? statusMatch[1].trim() : 'UNKNOWN';
+
+// Count handoffs from handoff log
+const handoffMatches = activeTask.match(/\| \d{4}-\d{2}-\d{2}T.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|/g);
+const handoffCount = handoffMatches ? handoffMatches.length : 0;
+
+// Count loop iterations
+const devTestLoop = activeTask.match(/dev-test-loop:\s*iteration\s*(\d+)/);
+const reviewLoop = activeTask.match(/review-loop:\s*iteration\s*(\d+)/);
+const qaBugLoop = activeTask.match(/qa-bug-loop:\s*iteration\s*(\d+)/);
+
+// Count agents mentioned in handoff log
+const agentMentions = activeTask.match(/@[\w-]+/g) || [];
+const agentCounts = {};
+for (const agent of agentMentions) {
+  agentCounts[agent] = (agentCounts[agent] || 0) + 1;
+}
+
+// Read changes log
+const changesLogPath = activeTaskPath.replace(/\.md$/, '_changes.log');
+let filesChanged = 0;
+let changesLog = '';
+if (fs.existsSync(changesLogPath)) {
+  changesLog = fs.readFileSync(changesLogPath, 'utf-8');
+  filesChanged = changesLog.split('\n').filter(l => l.trim()).length;
+}
+
+// Build execution snapshot
+const snapshot = {
+  timestamp: new Date().toISOString(),
+  task_id: taskId,
+  title: taskTitle,
+  status: taskStatus,
+  agents_used: Object.keys(agentCounts).length,
+  agent_breakdown: agentCounts,
+  handoffs: handoffCount,
+  loops: {
+    dev_test: devTestLoop ? parseInt(devTestLoop[1]) : 0,
+    review: reviewLoop ? parseInt(reviewLoop[1]) : 0,
+    qa_bug: qaBugLoop ? parseInt(qaBugLoop[1]) : 0
+  },
+  files_changed: filesChanged
+};
+
+// Save execution snapshot
+const snapshotPath = path.join(reportsDir, `${taskId}_snapshot_${Date.now()}.json`);
+fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+
+// Output summary for the Stop prompt hook to consume
+console.log(`\nEXECUTION SNAPSHOT for ${taskId}: ${taskTitle}`);
+console.log(`  Status: ${taskStatus}`);
+console.log(`  Agents used: ${Object.keys(agentCounts).length} (${Object.keys(agentCounts).join(', ')})`);
+console.log(`  Handoffs: ${handoffCount}`);
+console.log(`  Loops: dev-test=${snapshot.loops.dev_test}, review=${snapshot.loops.review}, qa-bug=${snapshot.loops.qa_bug}`);
+console.log(`  Files changed: ${filesChanged}`);
+console.log(`  Snapshot saved: ${snapshotPath}`);
+console.log(`\nRun /execution-report ${taskId} for full analysis with success scoring, hallucination check, and regression impact.`);
+
+} catch (err) {
+  // Non-fatal — don't block session stop
+  console.log(`EXECUTION REPORT HOOK: non-fatal error — ${err.message}`);
+}
+
+process.exit(0);

package/template/.claude/hooks/notify-approval.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Cross-platform OS notification when Claude needs user approval
+const { execSync } = require('child_process');
+
+const MSG = 'Claude Code needs your approval';
+
+function tryExec(cmd) {
+  try { execSync(cmd, { stdio: 'ignore', timeout: 5000 }); return true; } catch { return false; }
+}
+
+function hasCommand(name) {
+  try {
+    const check = process.platform === 'win32' ? `where ${name}` : `command -v ${name}`;
+    execSync(check, { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+if (process.platform === 'darwin') {
+  // macOS
+  tryExec(`osascript -e 'display notification "${MSG}" with title "Claude Code"'`);
+} else if (process.platform === 'win32') {
+  // Windows — non-blocking balloon tip notification
+  tryExec(`powershell.exe -NoProfile -Command "[void][System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); $n=New-Object System.Windows.Forms.NotifyIcon; $n.Icon=[System.Drawing.SystemIcons]::Information; $n.Visible=$true; $n.ShowBalloonTip(3000,'Claude Code','${MSG}',[System.Windows.Forms.ToolTipIcon]::Info); Start-Sleep -Milliseconds 100; $n.Dispose()"`);
+} else {
+  // Linux
+  if (hasCommand('notify-send')) {
+    tryExec(`notify-send "Claude Code" "${MSG}"`);
+  }
+}

package/template/.claude/hooks/post-compact-recovery.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// PostCompact hook: re-inject critical workflow state after context compaction
+// Compaction can lose loop counters, phase state, and active handoffs — this restores them
+
+const fs = require('fs');
+const path = require('path');
+
+const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+if (!fs.existsSync(tasksDir)) process.exit(0);
+
+const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+for (const file of files) {
+  const filePath = path.join(tasksDir, file);
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  // Only process active tasks
+  if (!/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING|QA_SIGNOFF|BIZ_SIGNOFF|TECH_SIGNOFF|DEPLOYING)/.test(content)) {
+    continue;
+  }
+
+  const id = (content.match(/^id:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+  const title = (content.match(/^title:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+  const status = (content.match(/^status:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+  const assignedTo = (content.match(/^assigned-to:\s*(.+)$/m) || [])[1] || 'unassigned';
+
+  console.log('');
+  console.log('=== CONTEXT RECOVERY (post-compaction) ===');
+  console.log(`ACTIVE TASK: ${id} — ${title.trim()}`);
+  console.log(`STATUS: ${status.trim()} | ASSIGNED: ${assignedTo.trim()}`);
+
+  // Extract and re-inject loop state
+  const loopSection = content.match(/## Loop State\n([\s\S]*?)(?=\n##|\n$|$)/);
+  if (loopSection) {
+    console.log('');
+    console.log('LOOP STATE (preserved):');
+    const lines = loopSection[1].trim().split('\n').filter(l => l.trim().startsWith('-'));
+    for (const line of lines) {
+      console.log(`  ${line.trim()}`);
+    }
+  }
+
+  // Extract last handoff
+  const handoffLines = content.match(/\| \d{4}-\d{2}-\d{2}T.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|/g);
+  if (handoffLines && handoffLines.length > 0) {
+    const lastHandoff = handoffLines[handoffLines.length - 1];
+    console.log('');
+    console.log(`LAST HANDOFF: ${lastHandoff.trim()}`);
+  }
+
+  // Extract blockers
+  if (/blocked:\s*Y/i.test(content)) {
+    const blockerMatch = content.match(/BLOCKER:\s*(.+)/i);
+    console.log('');
+    console.log(`BLOCKER: ${blockerMatch ? blockerMatch[1].trim() : 'See task file for details'}`);
+  }
+
+  // Extract open bugs
+  const bugMatches = content.match(/BUG-\S+\s*\(P[0-4]\)/g);
+  if (bugMatches) {
+    console.log('');
+    console.log(`OPEN BUGS: ${bugMatches.join(', ')}`);
+  }
+
+  console.log('');
+  console.log(`Full state: .claude/tasks/${file}`);
+  console.log('=== END RECOVERY ===');
+  break; // Only show the first active task
+}

package/template/.claude/hooks/post-edit-format.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Post-tool hook: auto-format edited files
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Timeout: exit if stdin hangs
+setTimeout(() => process.exit(0), 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file || !fs.existsSync(file)) process.exit(0);
+
+    // Validate file path is within the project directory
+    const resolved = path.resolve(file);
+    if (!resolved.startsWith(process.cwd())) process.exit(0);
+
+    const ext = path.extname(file).toLowerCase();
+    const formatters = {
+      '.ts': ['npx', ['prettier', '--write']],
+      '.tsx': ['npx', ['prettier', '--write']],
+      '.js': ['npx', ['prettier', '--write']],
+      '.jsx': ['npx', ['prettier', '--write']],
+      '.json': ['npx', ['prettier', '--write']],
+      '.css': ['npx', ['prettier', '--write']],
+      '.py': ['black', []],
+      '.go': ['gofmt', ['-w']],
+      '.rs': ['rustfmt', []],
+    };
+
+    const formatter = formatters[ext];
+    if (formatter) {
+      const [cmd, args] = formatter;
+      try { execFileSync(cmd, [...args, resolved], { stdio: 'ignore', timeout: 10000 }); } catch {}
+    }
+  } catch {}
+  process.exit(0);
+});

package/template/.claude/hooks/pre-compact-save.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// PreCompact hook: save critical state BEFORE compaction destroys conversation history
+// Fires at ~95% context — this is our last chance to preserve state
+
+const fs = require('fs');
+const path = require('path');
+
+const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+const reportsDir = path.join(process.cwd(), '.claude', 'reports');
+
+if (!fs.existsSync(tasksDir)) process.exit(0);
+
+const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+let saved = false;
+
+for (const file of files) {
+  const filePath = path.join(tasksDir, file);
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  if (!/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING|QA_SIGNOFF|BIZ_SIGNOFF|TECH_SIGNOFF|DEPLOYING)/.test(content)) {
+    continue;
+  }
+
+  const id = (content.match(/^id:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+  const title = (content.match(/^title:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+  const status = (content.match(/^status:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+
+  // Save pre-compaction state snapshot
+  const snapshotDir = path.join(reportsDir, 'executions');
+  if (!fs.existsSync(snapshotDir)) {
+    fs.mkdirSync(snapshotDir, { recursive: true });
+  }
+
+  const snapshot = {
+    event: 'pre-compaction',
+    timestamp: new Date().toISOString(),
+    task_id: id.trim(),
+    title: title.trim(),
+    status: status.trim(),
+    reason: 'Context approaching 95% — auto-compaction imminent',
+    preserved: {
+      loop_state: extractSection(content, 'Loop State'),
+      last_handoff: extractLastHandoff(content),
+      open_bugs: extractBugs(content),
+      blocked: /blocked:\s*Y/i.test(content)
+    }
+  };
+
+  const snapshotPath = path.join(snapshotDir, `${id.trim()}_precompact_${Date.now()}.json`);
+  fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+
+  // Output critical context for the compaction to preserve
+  console.log('');
+  console.log('WARNING: Context at ~95% — compaction starting.');
+  console.log(`TASK: ${id.trim()} — ${title.trim()} [${status.trim()}]`);
+
+  if (snapshot.preserved.loop_state) {
+    console.log(`LOOPS: ${snapshot.preserved.loop_state}`);
+  }
+  if (snapshot.preserved.open_bugs) {
+    console.log(`BUGS: ${snapshot.preserved.open_bugs}`);
+  }
+
+  console.log('State snapshot saved. PostCompact will re-inject critical state.');
+  console.log('');
+  console.log('COMPACTION GUIDANCE: Focus on preserving the current phase instructions.');
+  console.log('Discard: file contents already read, intermediate exploration results.');
+  console.log('Preserve: task requirements, active phase, loop state, pending decisions.');
+
+  saved = true;
+  break;
+}
+
+if (!saved) {
+  console.log('Context compaction starting. No active task to preserve.');
+}
+
+function extractSection(content, header) {
+  const match = content.match(new RegExp(`## ${header}\\n([\\s\\S]*?)(?=\\n##|$)`));
+  if (!match) return null;
+  return match[1].trim().split('\n').filter(l => l.trim().startsWith('-')).map(l => l.trim()).join('; ');
+}
+
+function extractLastHandoff(content) {
+  const lines = content.match(/\| \d{4}-\d{2}-\d{2}T.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|/g);
+  return lines ? lines[lines.length - 1].trim() : null;
+}
+
+function extractBugs(content) {
+  const bugs = content.match(/BUG-\S+\s*\(P[0-4]\)/g);
+  return bugs ? bugs.join(', ') : null;
+}
+
+process.exit(0);