@paths.design/caws-cli 8.1.0 → 8.2.0

package/templates/.claude/hooks/scope-guard.sh

@@ -23,14 +23,101 @@ fi
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 SPEC_FILE="$PROJECT_DIR/.caws/working-spec.yaml"
+SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
 
-# Check if spec file exists
-if [[ ! -f "$SPEC_FILE" ]]; then
+# Check if spec file or scope.json exists
+if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]]; then
   exit 0
 fi
 
-# Get relative path from project root
-REL_PATH=$(realpath --relative-to="$PROJECT_DIR" "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+# Get relative path from project root (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Lite mode: check scope.json if no working-spec.yaml
+if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
+  if command -v node >/dev/null 2>&1; then
+    LITE_CHECK=$(node -e "
+      const fs = require('fs');
+      const path = require('path');
+      try {
+        const scope = JSON.parse(fs.readFileSync('$SCOPE_FILE', 'utf8'));
+        const filePath = '$REL_PATH';
+        const dirs = scope.allowedDirectories || [];
+        const banned = scope.bannedPatterns || {};
+
+        // Check banned file patterns
+        const basename = path.basename(filePath);
+        const bannedFiles = banned.files || [];
+        for (const pattern of bannedFiles) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(basename)) {
+            console.log('banned:' + pattern);
+            process.exit(0);
+          }
+        }
+
+        // Check banned doc patterns
+        const bannedDocs = banned.docs || [];
+        for (const pattern of bannedDocs) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(basename)) {
+            console.log('banned:' + pattern);
+            process.exit(0);
+          }
+        }
+
+        // Check allowed directories
+        if (dirs.length > 0) {
+          const normalized = filePath.replace(/\\\\\\\\/g, '/');
+          let found = false;
+          for (const dir of dirs) {
+            const d = dir.replace(/\\/$/, '');
+            if (normalized.startsWith(d + '/') || normalized === d) { found = true; break; }
+          }
+          // Allow root-level files and .caws/ directory
+          if (!normalized.includes('/') || normalized.startsWith('.caws/')) found = true;
+          if (!found) {
+            console.log('not_allowed');
+            process.exit(0);
+          }
+        }
+        console.log('allowed');
+      } catch (error) {
+        console.log('error:' + error.message);
+      }
+    " 2>&1)
+
+    if [[ "$LITE_CHECK" == banned:* ]]; then
+      PATTERN="${LITE_CHECK#banned:}"
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PreToolUse",
+          "permissionDecision": "ask",
+          "permissionDecisionReason": "This file ('"$REL_PATH"') matches a banned pattern ('"$PATTERN"') in .caws/scope.json. Creating files with this pattern is blocked to prevent file sprawl."
+        }
+      }'
+      exit 0
+    fi
+
+    if [[ "$LITE_CHECK" == "not_allowed" ]]; then
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PreToolUse",
+          "permissionDecision": "ask",
+          "permissionDecisionReason": "This file ('"$REL_PATH"') is outside the allowed directories in .caws/scope.json. Please confirm this edit is intentional."
+        }
+      }'
+      exit 0
+    fi
+
+    # File is allowed - exit normally
+    exit 0
+  fi
+fi
 
 # Use Node.js to parse YAML and check scope
 if command -v node >/dev/null 2>&1; then
@@ -44,7 +131,7 @@ if command -v node >/dev/null 2>&1; then
       const filePath = '$REL_PATH';
 
       // Check if file is explicitly out of scope
-      const outOfScope = spec.scope?.out_of_scope || [];
+      const outOfScope = spec.scope?.out || [];
       for (const pattern of outOfScope) {
         // Simple glob-like matching
         const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
@@ -55,7 +142,7 @@ if command -v node >/dev/null 2>&1; then
       }
 
       // Check if file is in scope (if scope is explicitly defined)
-      const inScope = spec.scope?.files || spec.scope?.directories || [];
+      const inScope = spec.scope?.in || [];
       if (inScope.length > 0) {
         let found = false;
         for (const pattern of inScope) {

package/templates/.claude/hooks/simplification-guard.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# CAWS Simplification Guard Hook
+# Detects when files are being stubbed out (large deletions + stub content)
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Edit operations (modifications to existing files)
+if [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Get relative path (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Only check code files
+case "$REL_PATH" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs|*.py|*.rs|*.go|*.java|*.kt|*.swift|*.rb|*.php|*.c|*.cpp|*.h)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Check if the file exists in git (skip new files)
+if ! git show "HEAD:$REL_PATH" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Compare staged version with HEAD
+if command -v node >/dev/null 2>&1; then
+  SIMP_CHECK=$(node -e "
+    const { execFileSync } = require('child_process');
+    try {
+      const headContent = execFileSync('git', ['show', 'HEAD:$REL_PATH'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const currentContent = require('fs').readFileSync('$FILE_PATH', 'utf8');
+
+      const countLOC = (c) => c.split('\\n').filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('#')).length;
+      const headLOC = countLOC(headContent);
+      const currentLOC = countLOC(currentContent);
+
+      if (headLOC < 10) { console.log('ok'); process.exit(0); }
+
+      const decrease = (headLOC - currentLOC) / headLOC;
+
+      // Check for stub patterns in new content
+      const stubPatterns = [/^\\s*pass\\s*$/m, /^\\s*\\.\\.\\.\\s*$/m, /raise\\s+NotImplementedError/,
+        /throw\\s+new\\s+Error.*not implemented/i, /\\/\\/\\s*TODO\\s*$/m, /#\\s*TODO\\s*$/m];
+      const hasStubs = stubPatterns.some(p => p.test(currentContent));
+
+      if (decrease >= 0.3 && hasStubs) {
+        console.log('simplified:' + Math.round(decrease * 100) + ':' + headLOC + ':' + currentLOC);
+      } else {
+        console.log('ok');
+      }
+    } catch (error) {
+      console.log('ok');
+    }
+  " 2>&1)
+
+  if [[ "$SIMP_CHECK" == simplified:* ]]; then
+    IFS=':' read -r _ PERCENT OLD_LOC NEW_LOC <<< "$SIMP_CHECK"
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "WARNING: This edit would reduce '"$REL_PATH"' by '"$PERCENT"'% ('"$OLD_LOC"' → '"$NEW_LOC"' LOC) and introduces stub patterns (pass, TODO, NotImplementedError). This looks like a simplification — implementations should be modified, not replaced with stubs. Please confirm this is intentional."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# Allow the edit
+exit 0

package/templates/.cursor/README.md

@@ -156,9 +156,6 @@ ls -la .cursor/hooks/
 # Install CAWS CLI
 npm install -g @caws/cli
 
-# Or use bundled version (VS Code extension)
-code --install-extension caws.caws-vscode-extension
-
 # Verify PATH
 which caws
 ```

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,82 @@
+# CAWS Integration Instructions for GitHub Copilot
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured AI-assisted development.
+
+## CAWS Project Detection
+
+Check if current project uses CAWS:
+- Look for `.caws/working-spec.yaml` file
+- Check for `caws` commands in package.json scripts
+- Verify CAWS CLI availability: `caws --version`
+
+## Working Specifications
+
+Working specs define project requirements and constraints:
+
+```yaml
+id: PROJ-001
+title: "Feature implementation"
+risk_tier: 2  # 1=Critical, 2=Standard, 3=Low risk
+mode: feature  # feature|refactor|fix|chore
+change_budget:
+  max_files: 25
+  max_loc: 1000
+scope:
+  in: ["src/", "tests/"]
+  out: ["node_modules/", "dist/"]
+```
+
+Always validate working specs: `caws validate`
+
+## Quality Workflow
+
+1. **Before implementation**: `caws agent iterate --current-state "describe what you're about to do"`
+2. **During implementation**: `caws agent evaluate --quiet`
+3. **Before commit**: `caws validate && caws agent evaluate`
+
+## Quality Gates by Risk Tier
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+## Key Rules
+
+1. Stay within `scope.in` boundaries -- do not edit files in `scope.out`
+2. Respect `change_budget.max_files` and `change_budget.max_loc` limits
+3. No shadow files -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*` copies
+4. Write tests before implementation when possible
+5. Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+
+## Waivers
+
+If you need to bypass a quality gate, create a waiver:
+
+```bash
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
+
+## Common Patterns
+
+### Feature Development
+1. Validate working spec: `caws validate`
+2. Get implementation guidance: `caws agent iterate`
+3. Implement with quality checks: `caws agent evaluate --quiet`
+4. Run full validation: `caws validate && npm test`
+
+### Bug Fixes
+1. Assess risk tier and impact
+2. Write failing test that reproduces the bug
+3. Implement minimal fix
+4. Run quality validation: `caws validate`
+
+## Troubleshooting
+
+- **Working spec invalid**: Run `caws validate --suggestions`
+- **Scope violations**: Update `.caws/working-spec.yaml` scope or create waiver
+- **Quality gate failures**: Address root cause rather than creating waivers

package/templates/.junie/guidelines.md

@@ -0,0 +1,73 @@
+# Junie Guidelines - CAWS Project
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured development.
+
+## Working Spec
+
+Before making changes, read `.caws/working-spec.yaml`. It defines:
+
+- **Risk tier**: Quality requirements (T1: 90%+ coverage, T2: 80%+, T3: 70%+)
+- **Scope**: `scope.in` lists files you may edit, `scope.out` is off-limits
+- **Change budget**: Maximum files and lines of code per change
+- **Acceptance criteria**: What "done" means for this task
+
+## CAWS Commands
+
+```bash
+caws validate                    # Validate the working spec
+caws agent iterate               # Get implementation guidance
+caws agent evaluate              # Evaluate quality compliance
+caws waivers create --reason ... # Create waiver for justified exceptions
+```
+
+## Key Rules
+
+1. **Stay in scope** -- only edit files listed in `scope.in`
+2. **Respect change budgets** -- stay within `max_files` and `max_loc`
+3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. **Tests first** -- write failing tests before implementation
+5. **Deterministic code** -- inject time, random, and UUID generators for testability
+6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. **Conventional commits** -- use `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` prefixes
+
+## Quality Gates
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+## Code Style
+
+- Prefer `const` over `let`
+- Use guard clauses and early returns over deep nesting
+- Single responsibility: one reason to change per module
+- Depend on abstractions, not concretions
+- Extension points over editing internals (open/closed principle)
+- Max cyclomatic complexity per function: 10
+- Max cognitive complexity: 15
+- Max nesting depth: 4
+- Max function length: 50 lines
+- Max file length: 1000 lines
+- Max parameters: 5
+- No emojis in production code or logs
+- Check if a server/process is already running before starting another
+
+### Naming
+
+Forbidden file name modifiers: enhanced, unified, better, new, next, final, copy, revamp, improved. Prefer in-place edits with a merge-then-delete strategy for refactors.
+
+## Build & Test
+
+```bash
+npm install          # Install dependencies
+npm test             # Run tests
+npm run lint         # Lint code
+npm run typecheck    # Type check (if TypeScript)
+caws validate        # Validate CAWS spec
+```

package/templates/.vscode/launch.json

@@ -1,33 +1,6 @@
 {
   "version": "0.2.0",
   "configurations": [
-    {
-      "name": "Run CAWS Extension",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension"],
-      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
-    },
-    {
-      "name": "Run CAWS Extension (Host Workspace)",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension", "${workspaceFolder}"],
-      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
-    },
-    {
-      "name": "Debug CAWS Extension",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/packages/caws-vscode-extension/out/extension.js",
-      "args": ["--inspect=6009"],
-      "env": {
-        "CAWS_DEBUG": "true"
-      },
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:compile"
-    },
     {
       "name": "Debug MCP Server",
       "type": "node",

package/templates/.windsurf/rules/caws-quality-standards.md

@@ -0,0 +1,54 @@
+# CAWS Quality Standards
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured development.
+
+## Working Spec
+
+Always check `.caws/working-spec.yaml` before making changes. It defines:
+
+- **Risk tier**: T1 (critical, 90%+ coverage), T2 (standard, 80%+), T3 (low risk, 70%+)
+- **Scope boundaries**: `scope.in` (allowed files), `scope.out` (off-limits)
+- **Change budget**: `max_files` and `max_loc` limits per change
+- **Acceptance criteria**: Definition of done
+
+## Key Rules
+
+1. Stay within scope boundaries defined in the working spec
+2. Respect change budgets -- split large changes into smaller PRs
+3. No shadow files: never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. Write tests before implementation when possible
+5. Deterministic code -- inject time, random, and UUID generators for testability
+6. No fake implementations -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. Prove claims -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. No marketing language in docs -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. Ask first for risky changes -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+11. Run `caws validate` before committing
+
+## Quality Commands
+
+```bash
+caws validate                    # Validate working spec
+caws agent iterate               # Get implementation guidance
+caws agent evaluate              # Evaluate quality compliance
+caws waivers create --reason ... # Create waiver for justified exceptions
+```
+
+## Code Style
+
+- Prefer `const` over `let`
+- Use guard clauses and early returns over deep nesting
+- Single responsibility: one reason to change per module
+- Depend on abstractions, not concretions
+- Extension points over editing internals (open/closed principle)
+- Max cyclomatic complexity per function: 10
+- Max nesting depth: 4
+- Max function length: 50 lines
+- Max file length: 1000 lines
+- Max parameters: 5
+- No emojis in production code or logs
+- Check if a server/process is already running before starting another
+
+## Naming
+
+Forbidden file name modifiers: enhanced, unified, better, new, next, final, copy, revamp, improved. Use in-place edits with merge-then-delete strategy for refactors.

package/templates/AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md
+
+This project uses [CAWS](https://github.com/paths-design/caws) (Coding Agent Working Standard) for quality-assured AI-assisted development.
+
+## Build & Test
+
+```bash
+npm install              # Install dependencies
+npm test                 # Run tests
+npm run lint             # Lint code
+npm run typecheck        # Type check (if TypeScript)
+caws validate            # Validate CAWS working spec
+```
+
+## Project Structure
+
+```
+.caws/
+  working-spec.yaml      # Project spec (risk tier, scope, acceptance criteria)
+  policy.yaml            # Quality policy overrides (optional)
+  waivers.yml            # Active waivers (optional)
+```
+
+## CAWS Workflow
+
+1. **Read the working spec**: Check `.caws/working-spec.yaml` for scope, risk tier, and acceptance criteria
+2. **Validate**: Run `caws validate` to ensure the spec is valid
+3. **Plan**: Run `caws agent iterate` for implementation guidance
+4. **Implement**: Write tests first, then implementation. Stay within scope boundaries.
+5. **Verify**: Run `caws agent evaluate` to check quality compliance
+6. **Commit**: Use conventional commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`)
+
+## Key Rules
+
+1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
+2. **Respect change budgets** -- stay within `max_files` and `max_loc` limits
+3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. **Tests first** -- write failing tests before implementation
+5. **Deterministic code** -- inject time, random, and UUID generators for testability
+6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence (test results, coverage reports), not assertions.
+8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade" in documentation and comments
+9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion before implementation
+
+## Quality Gates
+
+Requirements are tiered based on the `risk_tier` in the working spec:
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+## Code Style
+
+- Prefer `const` over `let`
+- Use guard clauses and early returns over deep nesting
+- Single responsibility: one reason to change per module
+- Depend on abstractions, not concretions
+- Extension points over editing internals (open/closed principle)
+- Max cyclomatic complexity per function: 10
+- Max nesting depth: 4
+- Max function length: 50 lines
+- Max file length: 1000 lines
+- Max parameters: 5
+- No emojis in production code or logs
+- Check if a server/process is already running before starting another
+
+### Naming
+
+Forbidden file name modifiers: `enhanced`, `unified`, `better`, `new`, `next`, `final`, `copy`, `revamp`, `improved`. Use in-place edits with merge-then-delete strategy for refactors.
+
+## Modes
+
+| Mode | Contracts | New Files | Key Artifacts |
+|------|-----------|-----------|---------------|
+| **feature** | Required first | Allowed in scope.in | Migration plan, feature flag, perf budget |
+| **refactor** | Must not change | Discouraged | Codemod script + semantic diff |
+| **fix** | Unchanged | Discouraged | Red test -> green; root cause note |
+| **doc** | N/A | Docs only | Updated README/usage snippets |
+| **chore** | N/A | Build/tools only | Version updates, dependency changes |
+
+## Waivers
+
+If you need to bypass a quality gate, create a waiver with justification:
+
+```bash
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
+
+## Pre-Submit Checklist
+
+- [ ] Working spec exists and validates (`caws validate`)
+- [ ] All tests pass (`npm test`)
+- [ ] Coverage meets tier requirements
+- [ ] Lints pass (`npm run lint`)
+- [ ] Types check (`npm run typecheck`)
+- [ ] No scope violations
+- [ ] Change budget not exceeded
+- [ ] Conventional commit message

package/templates/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured AI-assisted development.
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Type check (if TypeScript)
+npm run typecheck
+
+# Run all quality gates
+caws validate
+```
+
+## CAWS Workflow
+
+Before writing code, check the working spec:
+
+```bash
+# Validate the working spec
+caws validate
+
+# Get iteration guidance
+caws agent iterate --current-state "describe what you're about to do"
+
+# After implementation, evaluate quality
+caws agent evaluate
+```
+
+### Working Spec
+
+The project spec lives at `.caws/working-spec.yaml`. It defines:
+
+- **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
+- **Scope**: Which files you can edit (`scope.in`) and which are off-limits (`scope.out`)
+- **Change budget**: Max files and lines of code per change
+- **Acceptance criteria**: What "done" means
+
+Always stay within scope boundaries and change budgets.
+
+### Quality Gates
+
+Quality requirements are tiered:
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+### Key Rules
+
+1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
+2. **Respect change budgets** -- stay within `max_files` and `max_loc` limits
+3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. **Tests first** -- write failing tests before implementation
+5. **Deterministic code** -- inject time, random, and UUID generators for testability
+6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. **Conventional commits** -- use `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` prefixes
+
+### Waivers
+
+If you need to bypass a quality gate, create a waiver with justification:
+
+```bash
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
+
+## Project Structure
+
+```
+.caws/
+  working-spec.yaml   # Project spec (risk tier, scope, acceptance criteria)
+  policy.yaml         # Quality policy overrides (optional)
+  waivers.yml         # Active waivers
+```
+
+## Hooks
+
+This project has Claude Code hooks configured in `.claude/settings.json`:
+
+- **PreToolUse**: Blocks dangerous commands, scans for secrets, enforces scope
+- **PostToolUse**: Runs quality checks, validates spec, checks naming conventions
+- **Session**: Audit logging for provenance tracking
+
+See `.claude/README.md` for hook details.