anvil-dev-framework 0.1.6

package/docs/specifications/SPEC-ANV-VRW/component-02-stop-gate.md

@@ -0,0 +1,226 @@
+---
+shard_id: SPEC-ANV-VRW/component-02
+parent: SPEC-ANV-VRW
+title: Stop Hook Verification Gate
+status: draft
+linear_issue: ANV-142
+priority: P0
+estimated_hours: 3-4
+dependencies:
+  - component-01-verify
+---
+
+# Component 2: Stop Hook Verification Gate
+
+## Overview
+
+A stop hook that prevents Claude from exiting when verification fails. This ensures the AI cannot prematurely complete tasks with broken code.
+
+> Boris Cherny: "Non-zero exit blocks stopping"
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-SH-100 | Run verification checks before allowing exit | P0 | Checks execute on stop attempt |
+| REQ-SH-101 | Return non-zero exit code to block stopping | P0 | Exit code 1 prevents stop |
+| REQ-SH-102 | Provide clear feedback on what's blocking exit | P0 | User sees specific failure |
+| REQ-SH-103 | Allow override with explicit user command | P1 | `/force-exit` bypasses gate |
+| REQ-SH-104 | Configure which checks are mandatory | P1 | Config controls checks |
+| REQ-SH-105 | Log all gate events for debugging | P2 | Events logged with timestamp |
+
+---
+
+## Behavior Flow
+
+```
+User: Attempts to stop session
+
+Stop Hook:
+1. Check ANVIL_REQUIRE_VERIFICATION env var
+   - If "false" → Allow exit immediately
+
+2. Check ANVIL_FORCE_EXIT env var
+   - If "true" → Log warning, allow exit
+
+3. Run verification checks:
+   - npm test
+   - npm run lint
+   - npm run typecheck
+
+4. If ALL pass:
+   ✅ Verification gate passed
+   exit 0 (allow stop)
+
+5. If ANY fail:
+   ❌ Tests failing - cannot exit
+   Fix failing tests or use /force-exit to bypass
+   exit 1 (block stop)
+```
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Stop Gate Hook
+**File**: `global/hooks/stop_gate.sh`
+**Estimated**: 1.5 hours
+
+- [ ] Check `ANVIL_REQUIRE_VERIFICATION` env var
+- [ ] Check `ANVIL_FORCE_EXIT` override flag
+- [ ] Run test suite verification
+- [ ] Run lint verification
+- [ ] Run typecheck verification
+- [ ] Return appropriate exit code
+- [ ] Provide clear error messages
+
+### Task 2: Create Force Exit Command
+**File**: `global/commands/force-exit.md`
+**Estimated**: 0.5 hours
+
+- [ ] Set `ANVIL_FORCE_EXIT=true` env var
+- [ ] Log override with reason
+- [ ] Trigger actual exit
+- [ ] Document usage and warnings
+
+### Task 3: Update Settings Registration
+**File**: `.claude/settings.json` (hooks section)
+**Estimated**: 0.5 hours
+
+- [ ] Register stop_gate.sh in Stop hooks
+- [ ] Document hook ordering
+- [ ] Test hook registration
+
+### Task 4: Add Gate Logging
+**File**: `global/lib/gate_logger.py`
+**Estimated**: 0.5 hours
+
+- [ ] Create log file at `.claude/logs/stop_gate.log`
+- [ ] Log each gate event with timestamp
+- [ ] Log pass/fail status and reason
+- [ ] Include verification output summary
+
+---
+
+## Hook Implementation
+
+```bash
+#!/bin/bash
+# global/hooks/stop_gate.sh
+# Stop hook that gates on verification
+
+set -e
+
+# Check if verification is required
+REQUIRE_VERIFY="${ANVIL_REQUIRE_VERIFICATION:-true}"
+
+if [[ "$REQUIRE_VERIFY" != "true" ]]; then
+    exit 0  # Allow exit
+fi
+
+# Check for explicit override
+if [[ "$ANVIL_FORCE_EXIT" == "true" ]]; then
+    echo "⚠️ Force exit requested - bypassing verification"
+    exit 0
+fi
+
+echo "🔒 Running verification gate..."
+
+# Run test suite
+if ! npm test --silent 2>/dev/null; then
+    echo "❌ Tests failing - cannot exit"
+    echo "Fix failing tests or use /force-exit to bypass"
+    exit 1  # Block exit
+fi
+
+# Run lint
+if ! npm run lint --silent 2>/dev/null; then
+    echo "❌ Lint errors - cannot exit"
+    echo "Fix lint errors or use /force-exit to bypass"
+    exit 1
+fi
+
+# Run typecheck
+if ! npm run typecheck --silent 2>/dev/null; then
+    echo "❌ Type errors - cannot exit"
+    echo "Fix type errors or use /force-exit to bypass"
+    exit 1
+fi
+
+echo "✅ Verification gate passed"
+exit 0
+```
+
+---
+
+## Settings Configuration
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "type": "command",
+      "command": "bash global/hooks/stop_gate.sh"
+    }]
+  }
+}
+```
+
+---
+
+## `/force-exit` Command
+
+```markdown
+# /force-exit - Bypass Verification Gate
+
+> Force exit even when verification fails.
+
+## Usage
+/force-exit "reason for bypassing"
+
+## Behavior
+1. Sets ANVIL_FORCE_EXIT=true
+2. Logs bypass with reason
+3. Allows stop hook to pass
+
+## Warning
+This bypasses quality gates. Use only when:
+- Known test flakiness
+- Urgent context compaction needed
+- Explicitly instructed by user
+```
+
+---
+
+## Test Cases
+
+| Test Case | Setup | Expected |
+|-----------|-------|----------|
+| All pass | Clean codebase | Exit allowed |
+| Failing tests | 1 test failure | Exit blocked, message shown |
+| Lint errors | ESLint errors | Exit blocked, message shown |
+| Type errors | TSC errors | Exit blocked, message shown |
+| Force exit | `/force-exit` used | Exit allowed with warning |
+| Verification disabled | `ANVIL_REQUIRE_VERIFICATION=false` | Exit allowed immediately |
+
+---
+
+## Error Messages
+
+| Condition | Message |
+|-----------|---------|
+| Tests failing | `❌ Tests failing - cannot exit\nFix failing tests or use /force-exit to bypass` |
+| Lint errors | `❌ Lint errors - cannot exit\nFix lint errors or use /force-exit to bypass` |
+| Type errors | `❌ Type errors - cannot exit\nFix type errors or use /force-exit to bypass` |
+| Force bypass | `⚠️ Force exit requested - bypassing verification` |
+
+---
+
+## Integration Points
+
+- **Trigger**: Claude Code stop event
+- **Input**: Verification results from component-01
+- **Output**: Exit code (0 = allow, 1 = block)
+- **Override**: `/force-exit` command

package/docs/specifications/SPEC-ANV-VRW/component-03-posttooluse.md

@@ -0,0 +1,209 @@
+---
+shard_id: SPEC-ANV-VRW/component-03
+parent: SPEC-ANV-VRW
+title: PostToolUse Formatting Hook
+status: draft
+linear_issue: ANV-143
+priority: P0
+estimated_hours: 2-3
+dependencies: none
+---
+
+# Component 3: PostToolUse Formatting Hook
+
+## Overview
+
+Automatically format code files after every Edit or Write operation. This catches the "last 10%" of formatting issues that Claude often misses.
+
+> Boris Cherny: "PostToolUse hooks for formatting"
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-PTU-100 | Run formatter on files after Edit tool | P0 | Formatter executes on Edit |
+| REQ-PTU-101 | Run formatter on files after Write tool | P0 | Formatter executes on Write |
+| REQ-PTU-102 | Support project-specific formatter (prettier, black, etc.) | P0 | Config selects formatter |
+| REQ-PTU-103 | Execute in <500ms to avoid slowdown | P1 | Timed execution |
+| REQ-PTU-104 | Skip binary files and node_modules | P1 | Path filtering works |
+| REQ-PTU-105 | Log formatting changes for visibility | P2 | Changes logged |
+
+---
+
+## Supported Formatters
+
+| File Type | Primary Formatter | Fallback |
+|-----------|------------------|----------|
+| `.ts`, `.tsx`, `.js`, `.jsx` | prettier | eslint --fix |
+| `.json`, `.md`, `.css`, `.html` | prettier | - |
+| `.py` | black | ruff format |
+| `.go` | gofmt | - |
+| `.sh` | shfmt | - |
+| `.rs` | rustfmt | - |
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create PostToolUse Hook
+**File**: `global/hooks/post_tool_format.sh`
+**Estimated**: 1 hour
+
+- [ ] Extract `CLAUDE_FILE_PATH` from environment
+- [ ] Skip if no file path provided
+- [ ] Skip non-existent files
+- [ ] Skip binary and excluded paths
+- [ ] Detect file type from extension
+- [ ] Run appropriate formatter
+- [ ] Handle formatter not installed gracefully
+
+### Task 2: Configure Formatter Detection
+**Estimated**: 0.5 hours
+
+- [ ] TypeScript/JavaScript: npx prettier
+- [ ] Python: black or ruff
+- [ ] Go: gofmt
+- [ ] Bash: shfmt
+- [ ] Add fallback for missing formatters
+
+### Task 3: Performance Optimization
+**Estimated**: 0.5 hours
+
+- [ ] Measure execution time
+- [ ] Skip if formatter not installed
+- [ ] Use `--silent` flags
+- [ ] Add timeout protection
+
+### Task 4: Register Hook
+**File**: `.claude/settings.json`
+**Estimated**: 0.5 hours
+
+- [ ] Add PostToolUse hook entry
+- [ ] Configure matcher for "Edit|Write"
+- [ ] Test with both Edit and Write operations
+
+---
+
+## Hook Implementation
+
+```bash
+#!/bin/bash
+# global/hooks/post_tool_format.sh
+# PostToolUse hook for auto-formatting
+
+FILE_PATH="$CLAUDE_FILE_PATH"
+
+# Skip if no file path
+if [[ -z "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Skip non-existent files
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Skip binary and excluded paths
+case "$FILE_PATH" in
+    */node_modules/*|*/.git/*|*.png|*.jpg|*.ico|*.woff*|*.ttf|*.eot)
+        exit 0
+        ;;
+esac
+
+# Determine formatter based on file type
+case "$FILE_PATH" in
+    *.ts|*.tsx|*.js|*.jsx|*.json|*.md|*.css|*.html)
+        if command -v npx &> /dev/null; then
+            npx prettier --write "$FILE_PATH" 2>/dev/null || true
+        fi
+        ;;
+    *.py)
+        if command -v black &> /dev/null; then
+            black --quiet "$FILE_PATH" 2>/dev/null || true
+        elif command -v ruff &> /dev/null; then
+            ruff format --quiet "$FILE_PATH" 2>/dev/null || true
+        fi
+        ;;
+    *.go)
+        if command -v gofmt &> /dev/null; then
+            gofmt -w "$FILE_PATH" 2>/dev/null || true
+        fi
+        ;;
+    *.sh)
+        if command -v shfmt &> /dev/null; then
+            shfmt -w "$FILE_PATH" 2>/dev/null || true
+        fi
+        ;;
+    *.rs)
+        if command -v rustfmt &> /dev/null; then
+            rustfmt "$FILE_PATH" 2>/dev/null || true
+        fi
+        ;;
+esac
+
+exit 0
+```
+
+---
+
+## Settings Configuration
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "bash global/hooks/post_tool_format.sh"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Test Cases
+
+| Test Case | Input | Expected |
+|-----------|-------|----------|
+| Edit TS file | Unformatted TypeScript | File formatted with prettier |
+| Write new Python | New .py file | File formatted with black |
+| Edit binary | .png file | Skipped (no formatting) |
+| Edit node_modules | node_modules/*.js | Skipped (excluded path) |
+| Missing formatter | No prettier installed | Graceful skip, no error |
+| Large file | 10k line file | Completes in <500ms |
+
+---
+
+## Performance Considerations
+
+| Concern | Solution |
+|---------|----------|
+| Slow formatting | Use `--quiet` flags |
+| Timeout | Add 500ms timeout wrapper |
+| Missing formatter | Check `command -v` first |
+| Network calls | Use local formatters only |
+
+---
+
+## Excluded Paths
+
+Files in these paths are never formatted:
+- `node_modules/`
+- `.git/`
+- `dist/`, `build/`, `out/`
+- Binary files (images, fonts)
+- Lock files (`package-lock.json`, `yarn.lock`)
+
+---
+
+## Integration Points
+
+- **Trigger**: Edit or Write tool completion
+- **Input**: `CLAUDE_FILE_PATH` environment variable
+- **Output**: Formatted file (in-place)
+- **Independent**: No dependencies on other components