codecruise 0.1.0

package/config/hooks/README.md

@@ -0,0 +1,632 @@
+# codecruise Hooks
+
+Hooks enable **verified, secure, and autonomous execution** with real enforcement.
+
+## P0 Enforcement Hooks (Critical)
+
+These hooks provide **deterministic enforcement** — not suggestions, actual gates:
+
+| Hook | Type | Enforcement |
+|------|------|-------------|
+| `verify-todo-completion.sh` | Stop | **Blocks completion** until quality gates pass |
+| `enforce-tdd.sh` | PreToolUse | **Blocks implementation** until tests exist |
+| `verify-criteria.sh` | Stop (Agent) | **Semantic verification** of TODO criteria |
+
+## Available Hooks
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `verify-todo-completion.sh` | Stop | **P0** Gate: Verify lint/typecheck/tests pass |
+| `enforce-tdd.sh` | PreToolUse | **P0** Gate: Require tests before implementation |
+| `verify-criteria.sh` | Stop (Agent) | **P0** Semantic: Verify TODO criteria met |
+| `enforce-state-machine.sh` | PreToolUse | **P1** Gate: Prevent invalid state transitions |
+| `collect-metrics.sh` | PostToolUse | **P2** Metrics: Track success/retry/intervention rates |
+| `load-context-skills.sh` | SessionStart | **P2** Context: Auto-load relevant skills for TODO |
+| `capture-verification.sh` | PostToolUse | Capture quality command output for scorecards |
+| `format.sh` | PostToolUse | Auto-format files after write/edit |
+| `protect-files.sh` | PreToolUse | Block edits to critical files |
+| `anti-rationalize.sh` | Stop | Prevent premature "done" declarations |
+| `enforce-file-scope.sh` | PreToolUse | Parallel execution safety (worktrees) |
+| `notify.sh` | PostToolUse | Send external notifications |
+
+## Enforcement Configuration
+
+Configure enforcement at multiple levels (highest to lowest priority):
+
+```
+Command flag     → /run --enforce=off     (this run only)
+    ↓
+Project config   → .claude/settings.json  (this project)
+    ↓
+User config      → ~/.claude/settings.json (all projects)
+    ↓
+Default          → strict
+```
+
+### Enforcement Modes
+
+| Mode | Behavior |
+|------|----------|
+| `strict` (default) | Block operations, Claude must fix |
+| `ask` | Show user prompt, allow override |
+| `off` | Disable enforcement entirely |
+
+### 1. Command Flags (Highest Priority)
+
+```bash
+/run phase-01 --enforce=off        # Hotfix mode
+/run phase-01 --enforce=ask        # Ask instead of block
+/run phase-01 --no-tdd             # Skip TDD only
+/run phase-01 --no-quality-gates   # Skip quality gates only
+```
+
+### 2. Project Settings (.claude/settings.json)
+
+```json
+{
+  "codecruise": {
+    "enforce": "strict",
+    "enforce_tdd": "strict",
+    "enforce_quality": "strict",
+    "enforce_criteria": "strict"
+  }
+}
+```
+
+This project uses strict TDD but asks for quality gates:
+```json
+{
+  "codecruise": {
+    "enforce": "strict",
+    "enforce_quality": "ask"
+  }
+}
+```
+
+### 3. User Settings (~/.claude/settings.json)
+
+Same format. Sets your personal defaults across all projects.
+
+```json
+{
+  "codecruise": {
+    "enforce": "ask"
+  }
+}
+```
+
+### In Practice
+
+**Strict mode (default):**
+```
+❌ TDD violation: Write tests first before implementing.
+   Expected test file: src/auth/login.test.ts
+   [Operation blocked - Claude must create test first]
+```
+
+**Ask mode:**
+```
+⚠️ TDD: No test file found. Expected: src/auth/login.test.ts
+   Allow implementation anyway? [y/N]
+   [User can override and continue]
+```
+
+**Off mode:**
+```
+[No enforcement, operation proceeds]
+```
+
+### When to Use Each Mode
+
+| Scenario | Recommended Mode |
+|----------|------------------|
+| Normal development | `strict` |
+| Prototyping/exploration | `ask` |
+| Hotfix/emergency | `off` |
+| CI/automated runs | `strict` |
+| Learning the system | `ask` |
+| Existing codebase (no tests) | `ask` or `off` for TDD |
+
+---
+
+## Quick Setup
+
+Copy the example settings to your project:
+
+```bash
+cp ~/.claude/hooks/settings.example.json .claude/settings.json
+```
+
+Or merge with existing settings.
+
+## P0 Enforcement (Critical Gates)
+
+### 1. TDD Enforcement (enforce-tdd.sh)
+
+**Blocks writes to implementation files unless tests exist first.**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/enforce-tdd.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**What it enforces:**
+- Cannot write to `src/auth/login.ts` unless `src/auth/login.test.ts` exists
+- Test file patterns: `.test.ts`, `.spec.ts`, `__tests__/`, etc.
+- Skips config files (json, yaml, md, etc.)
+
+**Error message:**
+```
+TDD violation: Write tests first before implementing.
+Expected test file: src/auth/login.test.ts
+Create the test file with failing tests (RED), then implement (GREEN).
+```
+
+### 2. Quality Gate Verification (verify-todo-completion.sh)
+
+**Blocks TODO completion until all quality gates pass.**
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/verify-todo-completion.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**What it enforces:**
+- Lint must pass (exit code 0)
+- TypeScript must pass (exit code 0)
+- Tests must pass (exit code 0, 0 failed)
+
+**Error message:**
+```
+Quality gates failed: lint typecheck tests(2 failed).
+Fix issues before completing TODO todo-1.2a-005.
+Run 'pnpm quality' or check .codecruise/verification/ for details.
+```
+
+### 3. Semantic Criteria Verification (Agent Hook)
+
+**Uses Claude to verify TODO acceptance criteria are actually met.**
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "agent",
+            "prompt": "Verify TODO completion. Run ~/.claude/hooks/verify-criteria.sh to get current TODO criteria. Then check the codebase: 1) All criteria in the TODO are implemented, 2) All tests listed exist and would pass, 3) Files match the specification. Return {\"ok\": true} if complete, or {\"ok\": false, \"reason\": \"specific missing items\"}. Be strict - partial completion is NOT complete.",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**What it enforces:**
+- Reads TODO from `roadmap/` with criteria list
+- Spawns agent to verify each criterion against codebase
+- Blocks if any criterion not implemented
+
+**Error example:**
+```json
+{
+  "ok": false,
+  "reason": "Missing: User model does not have 'updatedAt' field as specified in criteria"
+}
+```
+
+## P1 State Machine Enforcement
+
+### 4. State Machine Enforcement (enforce-state-machine.sh)
+
+**Prevents invalid TODO state transitions.**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/enforce-state-machine.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Valid transitions:**
+```
+pending → in_progress
+in_progress → done, blocked, failed
+blocked → in_progress
+failed → in_progress, skipped
+done → (terminal)
+skipped → (terminal)
+```
+
+**What it prevents:**
+- `pending → done` (must go through in_progress)
+- `done → anything` (terminal state)
+- `pending → skipped` (must attempt first)
+
+## P2 Metrics & Context
+
+### 5. Metrics Collection (collect-metrics.sh)
+
+**Tracks success rates, retry rates, and activity.**
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/collect-metrics.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Metrics collected:**
+- Test pass/fail events
+- Lint pass/fail events
+- Commits made
+- Files written (code vs tests)
+
+**Output:** `.codecruise/metrics/summary.json`
+```json
+{
+  "tests": { "passes": 42, "fails": 3, "success_rate": "93.33%" },
+  "lint": { "passes": 45, "fails": 0, "success_rate": "100%" },
+  "activity": { "commits": 12, "tests_written": 15, "code_written": 28 }
+}
+```
+
+### 6. Context-Aware Skill Loading (load-context-skills.sh)
+
+**Auto-loads relevant skills based on TODO files.**
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/load-context-skills.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Skill triggers:**
+| File Pattern | Skill Loaded |
+|--------------|--------------|
+| `*.ts`, `*.tsx` | TypeScript |
+| `/components/`, `/app/` | Frontend |
+| `/api/`, `/routes/` | Backend |
+| `prisma`, `/models/` | Database |
+| `*.test.*`, `*.spec.*` | Testing |
+
+Skills are loaded into Claude's context at session start, reducing the need to re-explain patterns.
+
+## Hook Configurations
+
+### 1. Verification Capture (Essential)
+
+Captures real output from quality commands for accurate scorecards.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool": ["Bash"],
+          "bash_command_regex": "^(pnpm|npm|yarn) (run )?(quality|verify|check|test|lint)"
+        },
+        "command": ".codecruise/hooks/capture-verification.sh",
+        "timeout": 120000
+      }
+    ]
+  }
+}
+```
+
+### 2. Auto-Format (Recommended)
+
+Automatically formats files after edits. "Handles the last 10% before CI" — Boris Cherny
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool": ["Write", "Edit"]
+        },
+        "command": "~/.claude/hooks/format.sh"
+      }
+    ]
+  }
+}
+```
+
+Requires: `prettier`, `black`, `gofmt` (based on file type)
+
+### 3. Protected Files (Recommended)
+
+Blocks modification of critical files like secrets and state.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": {
+          "tool": ["Write", "Edit"]
+        },
+        "command": "~/.claude/hooks/protect-files.sh"
+      }
+    ]
+  }
+}
+```
+
+Protected by default:
+- `.env*` (secrets)
+- `progress.yaml` (state - use commands instead)
+- `roadmap/` (TODOs - use commands instead)
+- `*.lock` (lock files)
+- `.git/`, `.ssh/`, `.aws/` (sensitive directories)
+
+### 4. Anti-Rationalization (Autonomous Mode)
+
+Prevents Claude from declaring victory with incomplete work. From Trail of Bits research.
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "~/.claude/hooks/anti-rationalize.sh"
+      }
+    ]
+  }
+}
+```
+
+Blocks responses containing:
+- "pre-existing"
+- "out of scope"
+- "leave for follow-up"
+- "too many issues"
+- "will address later"
+
+### 5. File Scope Enforcement (Parallel Execution)
+
+Blocks edits outside owned file scope. Essential for worktree-based parallel work.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": {
+          "tool": ["Write", "Edit"]
+        },
+        "command": "~/.claude/hooks/enforce-file-scope.sh"
+      }
+    ]
+  }
+}
+```
+
+Create `.claude/file_scope.txt` in each worktree:
+```
+src/auth/**/*
+tests/auth/**/*
+```
+
+### 6. Notifications (Autonomous Mode)
+
+Send notifications on important events.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool": ["Bash"],
+          "bash_command_regex": "pilot-notify"
+        },
+        "command": "~/.claude/hooks/notify.sh"
+      }
+    ]
+  }
+}
+```
+
+Configure via environment:
+```bash
+export PILOT_NOTIFY_CHANNEL=slack
+export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+```
+
+### 7. Pre-Compact (Context Preservation)
+
+Saves session context before compaction. Ensures "why" decisions survive context compression.
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "command": "~/.claude/hooks/pre-compact.sh"
+      }
+    ]
+  }
+}
+```
+
+Saves to `quality_reports/session_logs/`.
+
+## Output Files
+
+### Verification Output
+
+```
+.codecruise/verification/
+├── timestamp.txt      # When verification ran
+├── lint.txt           # Lint output
+├── lint-exit.txt      # Lint exit code
+├── typecheck.txt      # TypeScript output
+├── typecheck-exit.txt # TypeScript exit code
+├── test.txt           # Test output
+├── test-exit.txt      # Test exit code
+└── summary.json       # Parsed summary for scorecard
+```
+
+### Session Logs
+
+```
+quality_reports/session_logs/
+├── 2026-02-19_auth-implementation.md
+├── 2026-02-20_payment-flow.md
+└── ...
+```
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `PILOT_NOTIFY_CHANNEL` | Notification channel: `slack`, `webhook` | none |
+| `SLACK_WEBHOOK_URL` | Slack incoming webhook URL | none |
+| `PILOT_WEBHOOK_URL` | Generic webhook URL | none |
+| `PILOT_PROTECTED_FILES` | Additional protected file patterns | none |
+
+## Manual Execution
+
+Test hooks directly:
+
+```bash
+# Test verification capture
+.codecruise/hooks/capture-verification.sh
+
+# Test format hook (provide file path via stdin)
+echo '{"tool_input": {"file_path": "src/test.ts"}}' | ~/.claude/hooks/format.sh
+
+# Test notification
+echo '{"event": "blocker", "message": "Redis not running"}' | ~/.claude/hooks/notify.sh
+```
+
+## Creating Custom Hooks
+
+Hooks receive JSON input via stdin and can output JSON to affect behavior.
+
+### PreToolUse Hook
+
+Can block tool execution:
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+
+# Return this to block:
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Reason for blocking"
+  }
+}
+EOF
+exit 0
+
+# Return nothing or exit 0 to allow
+```
+
+### Stop Hook
+
+Can block session exit:
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+RESPONSE=$(echo "$INPUT" | jq -r '.response // empty')
+
+# Return this to block exit:
+cat <<EOF
+{
+  "decision": "block",
+  "reason": "Why the session should not end"
+}
+EOF
+exit 0
+```
+
+## Troubleshooting
+
+**Hook not executing:**
+- Check file permissions: `chmod +x hook.sh`
+- Verify matcher patterns match your commands
+- Check timeout settings (default 30s may be too short)
+
+**JSON parsing errors:**
+- Ensure `jq` is installed
+- Validate JSON output with `jq .`
+
+**Protected files blocking legitimate edits:**
+- Modify `protect-files.sh` to adjust patterns
+- Or use dedicated commands (`/found`, `/run`) instead of direct edits