@paths.design/caws-cli 10.2.0 → 11.1.0

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

@@ -1,82 +0,0 @@
-# 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 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
-
-| 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 iterate`
-3. Implement with quality checks: `caws 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/.idea/runConfigurations/CAWS_Evaluate.xml

@@ -1,5 +0,0 @@
-<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="evaluate">
-    <method v="2" />
-  </configuration>
-</component>

package/templates/.idea/runConfigurations/CAWS_Validate.xml

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

package/templates/.junie/guidelines.md

@@ -1,73 +0,0 @@
-# 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 iterate               # Get implementation guidance
-caws 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,17 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Debug CAWS CLI",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/packages/caws-cli/src/index.js",
-      "args": ["validate", ".caws/working-spec.yaml"],
-      "env": {
-        "NODE_ENV": "development",
-        "CAWS_DEBUG": "true"
-      },
-      "console": "integratedTerminal"
-    }
-  ]
-}

package/templates/.vscode/settings.json

@@ -1,95 +0,0 @@
-{
-  // CAWS VS Code Extension Settings
-  "caws.cli.path": "caws",
-  "caws.autoValidate": true,
-  "caws.showQualityStatus": true,
-  "caws.experimentalMode": false,
-
-  // General IDE settings that work well with CAWS
-  "editor.formatOnSave": true,
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit",
-    "source.organizeImports": "explicit"
-  },
-
-  // File associations for CAWS files
-  "files.associations": {
-    ".caws/working-spec.yaml": "yaml",
-    ".caws/waivers/*.yaml": "yaml",
-    "apps/tools/caws/*.js": "javascript"
-  },
-
-  // 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
-  },
-
-  // CAWS-aware task definitions
-  "tasks": {
-    "version": "2.0.0",
-    "tasks": [
-      {
-        "label": "CAWS: Validate",
-        "type": "shell",
-        "command": "caws",
-        "args": ["validate"],
-        "group": {
-          "kind": "build",
-          "isDefault": true
-        },
-        "presentation": {
-          "echo": true,
-          "reveal": "always",
-          "focus": false,
-          "panel": "shared"
-        },
-        "problemMatcher": []
-      },
-      {
-        "label": "CAWS: Evaluate Quality",
-        "type": "shell",
-        "command": "caws",
-        "args": ["evaluate"],
-        "group": "test",
-        "presentation": {
-          "echo": true,
-          "reveal": "always",
-          "focus": false,
-          "panel": "shared"
-        }
-      },
-      {
-        "label": "CAWS: Create Waiver",
-        "type": "shell",
-        "command": "caws",
-        "args": ["waivers", "create"],
-        "group": "build"
-      }
-    ]
-  },
-
-  // Recommended extensions for CAWS development
-  "recommendations": [
-    "ms-vscode.vscode-json",
-    "redhat.vscode-yaml",
-    "ms-vscode.vscode-typescript-next",
-    "esbenp.prettier-vscode",
-    "dbaeumer.vscode-eslint"
-  ],
-
-  // Workspace-specific settings
-  "yaml.schemas": {
-    "./.caws/schema/working-spec.schema.json": ".caws/working-spec.yaml",
-    "./.caws/schema/waiver.schema.json": ".caws/waivers/*.yaml"
-  }
-}

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

@@ -1,54 +0,0 @@
-# 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 iterate               # Get implementation guidance
-caws 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/.windsurf/workflows/caws-guided-development.md

@@ -1,92 +0,0 @@
-# /caws-guided-development
-
-## CAWS-Guided Feature Development Workflow
-
-**Purpose**: Guide agents through feature development with CAWS quality assurance
-
-**Tags**: development, quality, caws, feature
-
----
-
-### 1. Initialize CAWS Working Spec
-```
-# Create comprehensive working specification
-caws init feature-name --interactive
-
-# Define acceptance criteria, scope, and risk assessment
-# Working spec: .caws/working-spec.yaml
-```
-
-### 2. Plan Implementation Strategy
-```
-# Get CAWS guidance for implementation approach
-caws iterate --current-state "Planning phase complete, need implementation strategy"
-
-# CAWS will suggest:
-# - Implementation steps
-# - Quality gates to consider
-# - Risk mitigation strategies
-# - Testing approach
-```
-
-### 3. Implement Core Functionality
-```
-# Start coding with CAWS quality monitoring
-# Real-time feedback via CAWS tools
-
-# Regular quality checks
-caws evaluate --quiet
-```
-
-### 4. Quality Assurance Integration
-```
-# Run comprehensive quality gates
-caws validate
-
-# Address any failing gates
-# Create waivers if justified
-caws waivers create --reason emergency_hotfix --gates coverage_threshold
-```
-
-### 5. Testing & Validation
-```
-# Unit tests
-npm run test:unit
-
-# Integration tests
-npm run test:integration
-
-# Contract tests
-npm run test:contract
-```
-
-### 6. Final Quality Review
-```
-# Complete CAWS evaluation
-caws evaluate
-
-# Generate provenance report
-caws provenance generate
-
-# Ready for integration
-```
-
----
-
-**Quality Gates**:
-- ✅ Working spec validation
-- ✅ Code quality standards
-- ✅ Test coverage requirements
-- ✅ Security scanning
-- ✅ Performance budgets
-
-**Success Criteria**:
-- All CAWS quality gates pass
-- Acceptance criteria met
-- No critical security issues
-- Performance requirements satisfied
-
-**Call Other Workflows**:
-- `/caws-testing-workflow` - Comprehensive testing
-- `/caws-security-review` - Security validation
-- `/caws-deployment-checklist` - Deployment preparation

package/templates/CLAUDE.md

@@ -1,196 +0,0 @@
-# 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 canonical spec for the current feature:
-
-```bash
-# 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 iterate --current-state "describe what you're about to do"
-
-# After implementation, evaluate quality
-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
-
-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`)
-
-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>
-
-# Inspect the agent registry — who is currently working what
-caws agents list
-
-# Inspect a specific worktree's claim (read-only by default)
-caws worktree claim <name>
-```
-
-**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
-
-### Agent Claims & Multi-Agent Coordination
-
-Each session gets registered in `.caws/agents.json` automatically (via the session-log hook and on every CAWS lifecycle CLI invocation). Worktree session ownership is tracked in `.caws/worktrees.json:owner` as a session id.
-
-`caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without explicit `--takeover`. The refusal prints a structured warning naming the claimer as `<sessionId>:<platform>`, the heartbeat age, and any matching `tmp/<sessionId>/` session-log path so you can read context before deciding.
-
-**Decision-gating uses session-id equality only.** TTL pruning of `agents.json` is registry hygiene; it does NOT authorize takeover. A stale heartbeat doesn't mean the prior session is dead — it may be paused.
-
-`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so handoffs are traceable in `worktrees.json`, not just in agent memory.
-
-### Spec lifecycle: archive
-
-Use `caws specs archive <id>` to move a closed spec to the canonical `.caws/specs/.archive/` directory. The directory is filesystem-authoritative — `caws specs list` reports any file under `.archive/` as `status: archived` regardless of the YAML literal. This means manually-moved legacy specs (no registry entry) are correctly classified.
-
-If you try to `caws specs create <id>` for an id that already exists in `.archive/`, the command refuses without `--force`. With `--force`, the archived YAML is removed and a fresh draft is created — useful for resurrecting an old id with new intent.
-
-> **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.
-
-### 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   # 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`:
-
-- **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.