@paths.design/caws-cli 9.3.2 → 10.0.1

package/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/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/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/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/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/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/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/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/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/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/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/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/templates/CLAUDE.md

@@ -23,27 +23,56 @@ 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"
+
+# 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
+- **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.
 
@@ -89,11 +118,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/templates/{AGENTS.md → agents.md}

@@ -9,27 +9,35 @@ 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
+```
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
@@ -44,7 +52,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 +102,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/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
 

package/templates/scripts/new_feature.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Create a new CAWS feature spec + optional worktree
+#
+# Usage:
+#   scripts/new_feature.sh FEAT-001 "Feature description"
+#   scripts/new_feature.sh FEAT-001 "Feature description" --worktree
+#
+# This script:
+#   1. Creates a feature spec in .caws/specs/<ID>.yaml
+#   2. Optionally creates a git worktree for isolated development
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "usage: scripts/new_feature.sh <SPEC-ID> <title> [--worktree]" >&2
+  echo "  example: scripts/new_feature.sh FEAT-001 'Add user authentication'" >&2
+  exit 1
+fi
+
+SPEC_ID="$1"
+TITLE="$2"
+USE_WORKTREE="${3:-}"
+
+# Validate spec ID format (PREFIX-NUMBER, e.g., FEAT-001, AUTH-042)
+if ! echo "$SPEC_ID" | grep -qE '^[A-Z]+-[0-9]+$'; then
+  echo "error: spec ID must be in format PREFIX-NUMBER (e.g., FEAT-001, AUTH-042)" >&2
+  exit 1
+fi
+
+SPEC_FILE=".caws/specs/${SPEC_ID}.yaml"
+
+# Check if spec already exists
+if [ -f "$SPEC_FILE" ]; then
+  echo "error: spec $SPEC_ID already exists at $SPEC_FILE" >&2
+  exit 1
+fi
+
+# Create spec directory if needed
+mkdir -p .caws/specs
+
+# Generate spec scaffold
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+cat > "$SPEC_FILE" << EOF
+id: ${SPEC_ID}
+type: feature
+title: "${TITLE}"
+status: draft
+risk_tier: 2
+mode: development
+created_at: "${TIMESTAMP}"
+updated_at: "${TIMESTAMP}"
+blast_radius:
+  modules: []
+  data_migration: false
+operational_rollback_slo: 5m
+scope:
+  in: []
+  out:
+    - docs/reference/v1/
+    - .caws/
+threats: []
+invariants: []
+acceptance: []
+acceptance_criteria: []
+milestones: []
+EOF
+
+echo "Created feature spec: $SPEC_FILE"
+
+# Optionally create worktree
+if [ "$USE_WORKTREE" = "--worktree" ]; then
+  BRANCH_NAME="feat/${SPEC_ID,,}"  # lowercase
+  WORKTREE_DIR=".caws/worktrees/${SPEC_ID,,}"
+
+  git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
+  echo "Created worktree: $WORKTREE_DIR (branch: $BRANCH_NAME)"
+  echo ""
+  echo "To start working:"
+  echo "  cd $WORKTREE_DIR"
+fi