@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/templates/.cursor/hooks.json

@@ -5,6 +5,9 @@
       {
         "command": "./.cursor/hooks/block-dangerous.sh"
       },
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      },
       {
         "command": "./.cursor/hooks/audit.sh"
       }
@@ -15,6 +18,9 @@
       },
       {
         "command": "./.cursor/hooks/caws-scope-guard.sh"
+      },
+      {
+        "command": "./.cursor/hooks/session-log.sh"
       }
     ],
     "afterFileEdit": [
@@ -30,6 +36,9 @@
       {
         "command": "./.cursor/hooks/caws-quality-check.sh"
       },
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      },
       {
         "command": "./.cursor/hooks/audit.sh"
       }
@@ -38,11 +47,27 @@
       {
         "command": "./.cursor/hooks/caws-scope-guard.sh"
       },
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      },
       {
         "command": "./.cursor/hooks/audit.sh"
       }
     ],
+    "afterAgentResponse": [
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      }
+    ],
+    "afterAgentThought": [
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      }
+    ],
     "stop": [
+      {
+        "command": "./.cursor/hooks/session-log.sh"
+      },
       {
         "command": "./.cursor/hooks/audit.sh"
       }

package/dist/templates/.cursor/rules/02-quality-gates.mdc

@@ -342,12 +342,10 @@ Tag placeholders explicitly in code:
 # Run comprehensive test suite
 caws quality-gates --test-coverage --mutation-testing
 
-# Check test quality metrics
-caws metrics track --metric="test_coverage" --value=85
-caws metrics track --metric="mutation_score" --value=70
+# Metrics are tracked automatically via working state
 
-# Update progress with test completion
-caws progress update --criterion-id="TEST-001" --status="completed" --tests-passing=25
+# Verify acceptance criteria for test completion
+caws verify-acs --spec-id <id>
 ```
 
 ### Test Analysis

package/dist/templates/.cursor/rules/10-documentation-quality-standards.mdc

@@ -337,11 +337,10 @@ caws validate --check-documentation-quality
 # Generate documentation quality report
 caws docs quality-report --include-marketing-check --include-status-verification
 
-# Track documentation quality metrics
-caws metrics track --metric="documentation_quality_score" --value=95
+# Metrics are tracked automatically via working state
 
-# Update progress with documentation quality
-caws progress update --criterion-id="DOCS-001" --status="completed"
+# Verify acceptance criteria for documentation quality
+caws verify-acs --spec-id <id>
 ```
 
 ## Continuous Improvement
@@ -377,14 +376,10 @@ caws progress update --criterion-id="DOCS-001" --status="completed"
 ### CAWS Integration Points
 
 ```bash
-# Track documentation quality trends
-caws metrics trends --metric="documentation_quality_score" --period="30d"
+# Metrics are tracked automatically via working state
 
-# Export documentation quality metrics
-caws metrics export --format=json --include-documentation-quality
-
-# Archive documentation with quality verification
-caws archive DOCS-001 --verify-documentation-quality
+# Archive documentation
+caws archive DOCS-001
 ```
 
 This rule ensures documentation maintains engineering-grade quality and prevents the accumulation of problematic content that requires manual cleanup, fully integrated with CAWS workflow and quality gates.

package/dist/templates/.cursor/rules/11-scope-management-waivers.mdc

@@ -246,7 +246,7 @@ check-change-budget() {
 # GitHub Actions example
 - name: Check Scope Compliance
   run: |
-    if ! caws validate --scope-check; then
+    if ! caws gates run; then
       echo "❌ Scope violation detected"
       exit 1
     fi
@@ -317,11 +317,8 @@ risk_tier: 'T2' # T1, T2, or T3
 ### CAWS Commands
 
 ```bash
-# Validate scope compliance
-caws validate --scope-check
-
-# Check change budget
-caws validate --budget-check
+# Run quality gates (includes scope and budget checks)
+caws gates run
 
 # Create emergency waiver
 caws waivers create \
@@ -343,14 +340,14 @@ caws waivers status --waiver-id="AUTH-FIX-001"
 ### Quality Gate Integration
 
 ```bash
-# Run quality gates with tier-specific requirements
-caws quality-gates --tier=T2
+# Run quality gates (tier is determined from spec)
+caws gates run
 
-# Check if waiver is required
-caws quality-gates --check-waiver-required
+# List active waivers
+caws waivers list
 
-# Apply waiver to quality gates
-caws quality-gates --apply-waiver=AUTH-FIX-001
+# Create a waiver for quality gates
+caws waivers create
 ```
 
 ## Continuous Improvement
@@ -372,14 +369,13 @@ caws quality-gates --apply-waiver=AUTH-FIX-001
 ### CAWS Integration Points
 
 ```bash
-# Track scope compliance in CAWS metrics
-caws metrics track --metric="scope_violations" --value=0
+# Metrics are tracked automatically via working state
 
-# Update progress with scope compliance
-caws progress update --criterion-id="SCOPE-001" --status="completed"
+# Verify acceptance criteria for scope compliance
+caws verify-acs --spec-id <id>
 
-# Archive changes with scope compliance verification
-caws archive FEAT-001 --verify-scope-compliance
+# Archive changes
+caws archive FEAT-001
 ```
 
 This rule ensures proper scope management while providing structured escape hatches for critical situations that require immediate attention, fully integrated with CAWS workflow and quality gates.

package/dist/templates/.cursor/rules/12-implementation-completeness.mdc

@@ -484,11 +484,11 @@ def calculate_completeness_score(analysis_results):
 ### CAWS Quality Monitoring
 
 ```bash
-# Use CAWS quality monitoring
-caws quality-monitor --action=code_edited --files="$(git diff --name-only)"
+# Run quality gates after code changes
+caws gates run
 
-# Track TODO resolution progress
-caws progress-update --criterion-id="TODO-001" --status="completed" --tests-passing=1
+# Verify acceptance criteria for TODO resolution
+caws verify-acs --spec-id <id>
 ```
 
 ### Continuous Improvement

package/dist/templates/.cursor/rules/13-language-agnostic-standards.mdc

@@ -485,24 +485,14 @@ caws quality-gates --check-universal-standards
 ### Metrics Tracking
 
 ```bash
-# Track complexity metrics
-caws metrics track --metric="cyclomatic_complexity" --value=8
-
-# Track maintainability metrics
-caws metrics track --metric="function_size" --value=25
-
-# Track architectural compliance
-caws metrics track --metric="dependency_injection" --value=1
+# Metrics are tracked automatically via working state
 ```
 
 ### Progress Tracking
 
 ```bash
-# Update progress with complexity compliance
-caws progress update --criterion-id="COMPLEXITY-001" --status="completed"
-
-# Track architectural pattern implementation
-caws progress update --criterion-id="ARCHITECTURE-001" --status="in_progress"
+# Verify acceptance criteria for complexity compliance
+caws verify-acs --spec-id <id>
 ```
 
 ## Enforcement Mechanisms

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

@@ -30,9 +30,9 @@ 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`
+1. **Before implementation**: `caws iterate --current-state "describe what you're about to do"`
+2. **During implementation**: `caws evaluate --quiet`
+3. **Before commit**: `caws validate && caws evaluate`
 
 ## Quality Gates by Risk Tier
 
@@ -65,8 +65,8 @@ Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`,
 
 ### Feature Development
 1. Validate working spec: `caws validate`
-2. Get implementation guidance: `caws agent iterate`
-3. Implement with quality checks: `caws agent evaluate --quiet`
+2. Get implementation guidance: `caws iterate`
+3. Implement with quality checks: `caws evaluate --quiet`
 4. Run full validation: `caws validate && npm test`
 
 ### Bug Fixes

package/dist/templates/.idea/runConfigurations/CAWS_Evaluate.xml

@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="CAWS: Evaluate Quality" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="agent evaluate .caws/working-spec.yaml">
+  <configuration default="false" name="CAWS: Evaluate Quality" type="NodeJSConfigurationType" factoryName="Node.js" path-to-js-file="$PROJECT_DIR$/packages/caws-cli/dist/index.js" working-dir="$PROJECT_DIR$" application-parameters="evaluate">
     <method v="2" />
   </configuration>
 </component>

package/dist/templates/.junie/guidelines.md

@@ -15,8 +15,8 @@ Before making changes, read `.caws/working-spec.yaml`. It defines:
 
 ```bash
 caws validate                    # Validate the working spec
-caws agent iterate               # Get implementation guidance
-caws agent evaluate              # Evaluate quality compliance
+caws iterate               # Get implementation guidance
+caws evaluate              # Evaluate quality compliance
 caws waivers create --reason ... # Create waiver for justified exceptions
 ```
 

package/dist/templates/.vscode/settings.json

@@ -22,12 +22,14 @@
   // Exclude CAWS-generated files from search and navigation
   "files.exclude": {
     ".caws/cache/": true,
+    ".caws/state/": true,
     ".caws/waivers/review-*.md": true
   },
 
   // Search excludes for CAWS artifacts
   "search.exclude": {
     ".caws/cache/**": true,
+    ".caws/state/**": true,
     "packages/*/dist/**": true,
     "packages/*/node_modules/**": true
   },
@@ -57,7 +59,7 @@
         "label": "CAWS: Evaluate Quality",
         "type": "shell",
         "command": "caws",
-        "args": ["agent", "evaluate", ".caws/working-spec.yaml"],
+        "args": ["evaluate"],
         "group": "test",
         "presentation": {
           "echo": true,

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

@@ -29,8 +29,8 @@ Always check `.caws/working-spec.yaml` before making changes. It defines:
 
 ```bash
 caws validate                    # Validate working spec
-caws agent iterate               # Get implementation guidance
-caws agent evaluate              # Evaluate quality compliance
+caws iterate               # Get implementation guidance
+caws evaluate              # Evaluate quality compliance
 caws waivers create --reason ... # Create waiver for justified exceptions
 ```
 

package/dist/templates/.windsurf/workflows/caws-guided-development.md

@@ -20,7 +20,7 @@ caws init feature-name --interactive
 ### 2. Plan Implementation Strategy
 ```
 # Get CAWS guidance for implementation approach
-caws agent iterate --current-state "Planning phase complete, need implementation strategy"
+caws iterate --current-state "Planning phase complete, need implementation strategy"
 
 # CAWS will suggest:
 # - Implementation steps
@@ -35,7 +35,7 @@ caws agent iterate --current-state "Planning phase complete, need implementation
 # Real-time feedback via CAWS tools
 
 # Regular quality checks
-caws agent evaluate --quiet
+caws evaluate --quiet
 ```
 
 ### 4. Quality Assurance Integration
@@ -63,7 +63,7 @@ npm run test:contract
 ### 6. Final Quality Review
 ```
 # Complete CAWS evaluation
-caws agent evaluate
+caws evaluate
 
 # Generate provenance report
 caws provenance generate

package/dist/templates/CLAUDE.md

@@ -23,30 +23,93 @@ caws validate
 
 ## CAWS Workflow
 
-Before writing code, check the working spec:
+Before writing code, check the canonical spec for the current feature:
 
 ```bash
-# Validate the working spec
-caws validate
+# Create a feature spec for isolated work
+caws specs create FEAT-001 --type feature --title "description"
+
+# If you're in a CAWS worktree, the created spec should record it:
+# worktree: <worktree-name>
+
+# Validate the feature spec
+caws validate --spec-id FEAT-001
+
+# Run quality gates v2 pipeline
+caws gates run
 
 # Get iteration guidance
-caws agent iterate --current-state "describe what you're about to do"
+caws iterate --current-state "describe what you're about to do"
 
 # After implementation, evaluate quality
-caws agent evaluate
+caws evaluate
+
+# Verify acceptance criteria have evidence
+caws verify-acs --spec-id FEAT-001
+
+# Check budget burn-up
+caws burnup --spec-id FEAT-001
+
+# Check status for the same feature
+caws status --spec-id FEAT-001
+```
+
+### Advisory Sidecars
+
+Sidecar commands are diagnostic analysis tools. They don't enforce anything -- they help you understand what's happening and what to do next.
+
+```bash
+caws sidecar drift       # Compare spec intent vs current implementation
+caws sidecar gaps        # Diagnose quality gaps blocking gate passage
+caws sidecar waiver-draft  # Generate pre-filled waiver template for a failing gate
+caws sidecar provenance  # Summarize work history for merge readiness review
 ```
 
 ### Working Spec
 
-The project spec lives at `.caws/working-spec.yaml`. Feature specs live at `.caws/specs/<ID>.yaml`. It defines:
+Canonical feature specs live at `.caws/specs/<ID>.yaml` (create with `caws specs create <id> --type feature --title "description"`). `.caws/working-spec.yaml` is a compatibility mirror for older tooling and legacy single-spec flows. The active spec defines:
 
 - **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
+- **Mode**: The type of change (`feature`, `refactor`, `fix`, `doc`, `chore`) -- required
+- **Worktree**: The owning CAWS worktree name for this spec (`worktree`) -- recommended for all isolated work
+- **Blast radius**: Which modules are affected (`blast_radius.modules`) -- required
+- **Operational rollback SLO**: Time target for rollback (e.g. `"30m"`) -- required
 - **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 (see note below)
-- **Acceptance criteria**: What "done" means — IDs must match `^A\d+$` (e.g. `A1`, `A12`)
+- **Acceptance criteria**: What "done" means -- IDs must match `^A\d+$` (e.g. `A1`, `A12`)
 
 Always stay within scope boundaries and change budgets.
 
+Recommended operating rule: one active feature spec, one active worktree. If a task has a worktree, record that ownership in the spec YAML with `worktree: <name>`.
+
+### Scope and Worktree Binding
+
+The scope guard enforces file edit boundaries based on your spec's `scope.in` and `scope.out` patterns. **How it enforces depends on whether your worktree is bound to a spec:**
+
+- **Authoritative mode** (worktree bound to a spec): Only your spec's scope patterns are checked. Other agents' specs cannot block your edits. This is the correct state.
+- **Union mode** (no binding): The guard checks ALL active specs. Any `scope.out` from any spec can block you, even unrelated ones. This is the common source of "why is spec X blocking me?" confusion.
+
+**The mutual binding** requires both sides:
+1. The worktree registry (`.caws/worktrees.json`) must have `specId` pointing to your spec
+2. Your spec (`.caws/specs/<id>.yaml`) must have `worktree: <name>` pointing to your worktree
+
+If either side is missing, the guard falls back to union mode.
+
+**Quick commands:**
+```bash
+# See your effective scope and binding health
+caws scope show
+
+# Fix a broken binding
+caws worktree bind <spec-id>
+```
+
+**Recovery checklist** (when the scope guard blocks you unexpectedly):
+1. Run `caws scope show` — check if you're in authoritative or union mode
+2. If union mode: bind your spec with `caws worktree bind <spec-id>`
+3. If authoritative but still blocked: the file is genuinely outside your spec's scope. Update your spec's `scope.in` if the file should be in scope, or request a waiver
+4. Do NOT modify another spec's `scope.out` to unblock yourself — that defeats the isolation
+
 > **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
 > derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
 > spec is not used by `caws validate` for enforcement.
@@ -89,11 +152,17 @@ Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`,
 
 ```
 .caws/
-  working-spec.yaml   # Project spec (risk tier, scope, acceptance criteria)
+  working-spec.yaml   # Compatibility mirror for legacy commands
+  specs/              # Canonical feature specs
   policy.yaml         # Quality policy overrides (optional)
   waivers.yml         # Active waivers
+  state/              # Runtime working state (auto-managed)
 ```
 
+> **Working state**: `.caws/state/<spec-id>.json` tracks runtime progress -- current phase,
+> validation/evaluation results, gate history, and files touched. This is maintained
+> automatically by CAWS commands. Agents don't need to manage it directly.
+
 ## Hooks
 
 This project has Claude Code hooks configured in `.claude/settings.json`:

package/dist/templates/agents.md

@@ -9,27 +9,56 @@ 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
+caws validate            # Validate the current CAWS spec
 ```
 
 ## Project Structure
 
 ```
 .caws/
-  working-spec.yaml      # Project spec (risk tier, scope, acceptance criteria)
+  working-spec.yaml      # Compatibility mirror for legacy paths
+  specs/                 # Canonical feature specs
   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
+1. **Read the canonical spec**: Use `.caws/specs/<spec-id>.yaml` when feature specs exist
+2. **Validate**: Run `caws validate --spec-id <spec-id>` for feature work
+3. **Plan**: Run `caws 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
+5. **Verify**: Run `caws evaluate` to check quality compliance
 6. **Commit**: Use conventional commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`)
 
+For a new feature in a multi-agent project:
+
+```bash
+caws specs create my-feature --type feature --title "My Feature"
+caws validate --spec-id my-feature
+```
+
+## Scope and Worktree Binding
+
+The scope guard enforces `scope.in` and `scope.out` from your spec. How it enforces depends on binding:
+
+- **Authoritative mode** (worktree bound to a spec): Only your spec's scope is checked. Other agents' specs cannot block you.
+- **Union mode** (no binding): ALL active specs are checked. Any `scope.out` from any spec can block you.
+
+```bash
+# See your effective scope and binding health
+caws scope show
+
+# Fix a broken binding
+caws worktree bind <spec-id>
+```
+
+**Recovery** (when blocked unexpectedly):
+1. Run `caws scope show` to check mode and binding health
+2. If union mode: `caws worktree bind <spec-id>`
+3. If authoritative but blocked: update your spec's `scope.in`
+4. Do NOT edit another spec's `scope.out` to unblock yourself
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
@@ -44,7 +73,7 @@ caws validate            # Validate CAWS working spec
 
 ## Quality Gates
 
-Requirements are tiered based on the `risk_tier` in the working spec:
+Requirements are tiered based on the `risk_tier` in the active spec:
 
 | Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
 |------|---------------|----------------|----------------|
@@ -94,11 +123,23 @@ Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`,
 
 ## Pre-Submit Checklist
 
-- [ ] Working spec exists and validates (`caws validate`)
+- [ ] Canonical spec exists and validates (`caws validate --spec-id <spec-id>` when applicable)
 - [ ] 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
+- [ ] Change budget not exceeded (`caws burnup --spec-id <spec-id>` shows budget consumption)
+- [ ] Acceptance criteria proven (`caws verify-acs --spec-id <spec-id>` checks evidence exists)
 - [ ] Conventional commit message
+
+### Optional: Self-Diagnosis with Sidecars
+
+If a gate blocks you, use sidecar commands to understand why before retrying:
+
+```bash
+caws sidecar gaps          # What's missing? Which gates are failing and why?
+caws sidecar drift         # Has implementation drifted from the spec intent?
+caws sidecar waiver-draft  # Generate a pre-filled waiver if the gap is acceptable
+caws sidecar provenance    # Summarize work history for merge readiness
+```

package/dist/templates/docs/README.md

@@ -14,12 +14,13 @@ This project is built with the **Coding Agent Workflow System (CAWS)** - an engi
 
 ### 1. Project Setup
 The project is already scaffolded with CAWS. Review and customize:
-- `.caws/working-spec.yaml` - Project specification and requirements
-- `.caws/policy/tier-policy.json` - Risk tier definitions
+- `.caws/specs/<spec-id>.yaml` - Canonical feature specification and requirements
+- `.caws/working-spec.yaml` - Compatibility mirror for legacy paths
+- `.caws/policy.yaml` - Risk tier definitions
 - `.github/workflows/caws.yml` - CI/CD quality gates
 
 ### 2. Development Workflow
-1. **Plan**: Update working spec with requirements and scope
+1. **Plan**: Update the active feature spec with requirements and scope
 2. **Implement**: Follow agent conduct rules and mode constraints
 3. **Verify**: Run tests and quality gates locally
 4. **Document**: Update documentation and generate provenance
@@ -111,7 +112,7 @@ The project includes automated quality gates:
 
 ### Common Issues
 1. **Trust Score Low**: Check test coverage and quality gates
-2. **Scope Violations**: Ensure changes align with working spec
+2. **Scope Violations**: Ensure changes align with the active spec
 3. **Budget Exceeded**: Review change size and complexity
 4. **Flaky Tests**: Use property testing and proper mocking
 
@@ -124,14 +125,14 @@ The project includes automated quality gates:
 ## Contributing
 
 ### Development Process
-1. Update working specification
+1. Update the active feature specification
 2. Create comprehensive tests
 3. Implement with quality gates
 4. Generate provenance artifacts
 5. Document changes thoroughly
 
 ### Code Review
-- Review against working specification
+- Review against the active feature spec
 - Check trust score and quality gates
 - Validate observability and rollback
 - Ensure documentation completeness
@@ -139,7 +140,7 @@ The project includes automated quality gates:
 ## Resources
 
 - **[CAWS Framework](agents.md)**: Complete system documentation
-- **[Working Specification](.caws/working-spec.yaml)**: Project requirements
+- **[Canonical Specs](.caws/specs/)**: Project requirements
 - **[Quality Gates](.github/workflows/caws.yml)**: CI/CD pipeline
 - **[Tools](apps/tools/caws/)**: Development utilities