@paths.design/caws-cli 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,7 @@
     "templates"
   ],
   "scripts": {
-    "build": "mkdir -p dist && cp -r src/* dist/ && npm run typecheck",
+    "build": "mkdir -p dist && cp -r src/* dist/",
     "dev": "mkdir -p dist && cp -r src/* dist/ && node dist/index.js",
     "typecheck": "tsc --emitDeclarationOnly --outDir dist",
     "start": "node dist/index.js",
@@ -51,12 +51,10 @@
     "directory": "packages/caws-cli"
   },
   "dependencies": {
-    "ajv": "^8.12.0",
     "chalk": "4.1.2",
     "commander": "^11.0.0",
     "fs-extra": "^11.0.0",
-    "inquirer": "8.2.7",
-    "js-yaml": "4.1.0"
+    "inquirer": "8.2.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
@@ -68,10 +66,13 @@
     "@types/inquirer": "^8.2.6",
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^20.0.0",
+    "ajv": "8.17.1",
     "esbuild": "0.25.10",
     "eslint": "^9.0.0",
     "jest": "30.1.3",
+    "js-yaml": "4.1.0",
     "lint-staged": "15.5.2",
+    "micromatch": "4.0.8",
     "prettier": "^3.0.0",
     "semantic-release": "25.0.0-beta.6",
     "typescript": "^5.0.0"

package/templates/.cursor/hooks/caws-scope-guard.sh

@@ -13,6 +13,57 @@ FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
 # Check if CAWS is available and we have a working spec
 if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
 
+  # AGENT GUARDRAILS - Prevent policy bypass attempts
+  if [[ "$ACTION" == "edit_file" ]] || [[ "$ACTION" == "create_file" ]]; then
+    if [[ "$FILE_PATH" == ".caws/policy.yaml" ]]; then
+      echo '{
+        "userMessage": "🚫 Policy file editing blocked by agent guardrails",
+        "agentMessage": "Agents cannot edit .caws/policy.yaml - requires human dual control",
+        "block": true,
+        "suggestions": [
+          "Policy changes must be approved by humans with Gatekeeper role",
+          "Create a separate PR for policy changes",
+          "For budget exceptions: caws waivers create --title=\"Budget exception\" --reason=architectural_refactor --gates=budget_limit",
+          "Contact @gatekeepers for policy modifications"
+        ]
+      }'
+      exit 1
+    fi
+
+    if [[ "$FILE_PATH" == "CODEOWNERS" ]]; then
+      echo '{
+        "userMessage": "🚫 CODEOWNERS editing blocked by agent guardrails",
+        "agentMessage": "Agents cannot modify CODEOWNERS - governance changes require approval",
+        "block": true,
+        "suggestions": [
+          "CODEOWNERS changes require governance review",
+          "Contact repository maintainers for ownership changes",
+          "For approval workflows: caws waivers create --reason=governance_change"
+        ]
+      }'
+      exit 1
+    fi
+
+    if [[ "$FILE_PATH" == ".caws/working-spec.yaml" ]]; then
+      # Check if trying to add change_budget
+      FILE_CONTENT=$(echo "$INPUT" | jq -r '.content // ""')
+      if echo "$FILE_CONTENT" | grep -q "change_budget"; then
+        echo '{
+          "userMessage": "🚫 Budget editing blocked by agent guardrails",
+          "agentMessage": "Agents cannot introduce change_budget fields - budgets are derived automatically",
+          "block": true,
+          "suggestions": [
+            "Check current budget status: caws burnup",
+            "For budget exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=budget_limit --expires-at=\"2025-12-31T23:59:59Z\"",
+            "Add waiver_ids to working spec instead: [\"WV-XXXX\"]",
+            "Validate waiver: caws validate .caws/working-spec.yaml"
+          ]
+        }'
+        exit 1
+      fi
+    fi
+  fi
+
   # For file access actions, check scope
   if [[ "$ACTION" == "read_file" ]] || [[ "$ACTION" == "edit_file" ]] || [[ -n "$FILE_PATH" ]]; then
 
@@ -25,9 +76,10 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
         "agentMessage": "Cannot access '"$FILE_PATH"' - outside CAWS defined scope",
         "block": true,
         "suggestions": [
-          "Check CAWS working spec scope definition",
-          "Update scope in .caws/working-spec.yaml if needed",
-          "Create waiver for scope violation: caws waivers create --reason=scope_violation"
+          "Check current scope: caws validate .caws/working-spec.yaml",
+          "Update scope in working spec: edit .caws/working-spec.yaml scope.in array",
+          "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary --description=\"Need access to '"$FILE_PATH"' for implementation\"",
+          "Validate changes: caws validate .caws/working-spec.yaml"
         ]
       }'
       exit 1
@@ -36,8 +88,10 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
         "userMessage": "⚠️ File access outside primary scope",
         "agentMessage": "File '"$FILE_PATH"' is outside primary scope but allowed",
         "suggestions": [
-          "Consider if this file should be in primary scope",
-          "Update .caws/working-spec.yaml scope if needed"
+          "Check if needed in primary scope: edit .caws/working-spec.yaml scope.in",
+          "Consider scope implications: caws agent evaluate",
+          "Document scope decision in working spec invariants",
+          "Validate scope changes: caws validate .caws/working-spec.yaml"
         ]
       }'
     fi
@@ -63,9 +117,11 @@ if command -v caws &> /dev/null && [[ -f ".caws/working-spec.yaml" ]]; then
           "userMessage": "⚠️ Prompt references files outside CAWS scope",
           "agentMessage": "Prompt mentions out-of-scope files: '"$OUT_OF_SCOPE"'",
           "suggestions": [
-            "Focus on files within CAWS defined scope",
-            "Update working spec scope if additional files needed",
-            "Remove out-of-scope file references from prompt"
+            "Check current scope definition: caws validate .caws/working-spec.yaml",
+            "Update working spec scope: edit .caws/working-spec.yaml scope.in array",
+            "For scope exceptions: caws waivers create --title=\"Scope expansion\" --reason=architectural_refactor --gates=scope_boundary",
+            "Refocus prompt on in-scope files or request scope update approval",
+            "Validate scope changes: caws validate .caws/working-spec.yaml"
           ]
         }'
       fi

package/templates/.cursor/hooks/validate-spec.sh

@@ -16,20 +16,30 @@ FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
 
 # Only validate if working-spec.yaml was edited
 if [[ "$FILE_PATH" == *"working-spec.yaml"* ]] || [[ "$FILE_PATH" == *"working-spec.yml"* ]]; then
-  # Run CAWS validation
-  if [ -f "apps/tools/caws/validate.js" ]; then
-    if ! node apps/tools/caws/validate.js --quiet 2>/dev/null; then
-      echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors. Please review and fix before continuing."}' 2>/dev/null
-      exit 0
+  echo "🔍 Validating CAWS working spec..." >&2
+
+  # Check if CAWS CLI is available
+  if command -v caws &> /dev/null; then
+    # Run CAWS validation with suggestions
+    if VALIDATION=$(caws validate "$FILE_PATH" --quiet 2>&1); then
+      echo '{"userMessage":"✅ CAWS spec validation passed","agentMessage":"Working specification is valid and complete."}' 2>/dev/null
+    else
+      # Get suggestions for fixing the spec
+      SUGGESTIONS=$(caws validate "$FILE_PATH" --suggestions 2>/dev/null | head -5 | tr '\n' '; ' | sed 's/; $//' || echo "Run caws validate --suggestions for details")
+
+      echo '{
+        "userMessage": "⚠️ CAWS spec validation failed. Run: caws validate --suggestions",
+        "agentMessage": "The working-spec.yaml file has validation errors. Please review and fix before continuing.",
+        "suggestions": [
+          "Run caws validate --suggestions for detailed error messages",
+          "Check required fields: id, title, risk_tier, mode",
+          "Ensure acceptance criteria are properly defined",
+          "Verify scope boundaries are appropriate"
+        ]
+      }' 2>/dev/null
     fi
   else
-    # Fallback: try caws CLI
-    if command -v caws &> /dev/null; then
-      if ! caws validate --quiet 2>/dev/null; then
-        echo '{"userMessage":"⚠️ CAWS spec validation failed. Run: caws validate --suggestions","agentMessage":"The working-spec.yaml file has validation errors."}' 2>/dev/null
-        exit 0
-      fi
-    fi
+    echo '{"userMessage":"⚠️ CAWS CLI not available for validation","agentMessage":"Install CAWS CLI for automatic spec validation: npm install -g @caws/cli"}' 2>/dev/null
   fi
 fi
 

package/templates/.cursor/rules/{01-claims-verification.mdc → 00-claims-verification.mdc}

@@ -141,4 +141,4 @@ Use this before any production claim:
 - [ ] Deployment docs exist and are tested
 - [ ] Documentation matches code reality
 
-**If ANY box is unchecked, do not claim production readiness.**
+**If ANY box is unchecked, do not claim production readiness.**

package/templates/.cursor/rules/01-working-style.mdc

@@ -0,0 +1,50 @@
+---
+description: Default agent behavior, edit style, and risk limits
+globs:
+alwaysApply: true
+---
+
+# Working Style & Risk Limits
+
+## Intent
+
+Prefer directly applying fixes over explaining. Explanations are secondary unless asked, or when a change is **risky** (see Risk Gate).
+
+## Edit Principles
+
+- **Small, bounded diffs.** Keep edits minimal, cohesive, and reviewable.
+- **Edit existing modules over forking.** Prefer refactor + rename to duplication.
+- **Preserve public behavior** unless the task explicitly requests behavioral change.
+
+## Ask-First Triggers (Risk Gate)
+
+Before editing, _ask with a Targeted Edit Plan_ if any are true:
+
+- Changes cross package boundaries or public APIs.
+- Requires deleting files or renaming public symbols.
+- Introduces a new dependency or build tool.
+- Affects security, persistence, auth, or infra.
+- Touches > 10 files or > 300 LOC.
+
+**Targeted Edit Plan (TEP)** must include:
+
+- Scope (files, symbols), risks, rollback notes.
+- Tests to run/update.
+- Acceptance checks (what passing looks like).
+
+## Diff Hygiene
+
+- Keep each commit focused on one intent.
+- Include brief rationale in the commit subject (≤72 chars).
+- Never bypass pre-commit hooks; `--no-verify` is **forbidden**.
+
+## When to Explain
+
+- On TEP prompts, on rejected edits, or when trade-offs are non-obvious.
+- Keep explanations concise and adjacent to the diff.
+
+## Acceptance (per PR)
+
+- Tests + lints pass locally.
+- No widened public API surface without TEP.
+- No dead code or duplicate modules introduced.

package/templates/.cursor/rules/{02-testing-standards.mdc → 02-quality-gates.mdc}

@@ -36,9 +36,9 @@ alwaysApply: true
 ### Test Structure Requirements
 
 ```typescript
-describe("ComponentName", () => {
-  describe("when condition A", () => {
-    it("should behave correctly", () => {
+describe('ComponentName', () => {
+  describe('when condition A', () => {
+    it('should behave correctly', () => {
       // Given: Setup preconditions
       // When: Execute the action
       // Then: Verify the outcome
@@ -116,11 +116,11 @@ describe("ComponentName", () => {
 
 ```typescript
 // DON'T: Mock the function you're supposed to test
-jest.mock("./businessLogic", () => ({
+jest.mock('./businessLogic', () => ({
   calculateTotal: jest.fn(() => 100),
 }));
 
-test("calculateTotal", () => {
+test('calculateTotal', () => {
   expect(calculateTotal()).toBe(100); // Tests the mock, not the logic
 });
 ```
@@ -129,7 +129,7 @@ test("calculateTotal", () => {
 
 ```typescript
 // DON'T: Test private methods or internal state
-test("internal counter increments", () => {
+test('internal counter increments', () => {
   component.privateCounter = 5; // Accessing private state
   expect(component.privateCounter).toBe(5);
 });
@@ -139,7 +139,7 @@ test("internal counter increments", () => {
 
 ```typescript
 // DON'T: Generic error testing
-test("throws error", () => {
+test('throws error', () => {
   expect(() => riskyOperation()).toThrow(); // Too vague
 });
 ```
@@ -148,8 +148,8 @@ test("throws error", () => {
 
 ```typescript
 // DON'T: Leave test data behind
-test("creates user", async () => {
-  await createUser({ name: "test" });
+test('creates user', async () => {
+  await createUser({ name: 'test' });
   // No cleanup - data persists
 });
 ```
@@ -159,9 +159,9 @@ test("creates user", async () => {
 ### ✅ Proper Error Testing
 
 ```typescript
-test("throws specific error for invalid input", () => {
-  expect(() => validateEmail("invalid")).toThrow(ValidationError);
-  expect(() => validateEmail("invalid")).toThrow("Invalid email format");
+test('throws specific error for invalid input', () => {
+  expect(() => validateEmail('invalid')).toThrow(ValidationError);
+  expect(() => validateEmail('invalid')).toThrow('Invalid email format');
 });
 ```
 
@@ -169,19 +169,19 @@ test("throws specific error for invalid input", () => {
 
 ```typescript
 const realisticUser = {
-  id: "user-123",
-  email: "user@example.com",
-  name: "John Doe",
-  createdAt: new Date("2024-01-01"),
-  preferences: { theme: "dark", notifications: true },
+  id: 'user-123',
+  email: 'user@example.com',
+  name: 'John Doe',
+  createdAt: new Date('2024-01-01'),
+  preferences: { theme: 'dark', notifications: true },
 };
 ```
 
 ### ✅ Proper Async Testing
 
 ```typescript
-test("resolves with correct data", async () => {
-  const result = await fetchUserData("user-123");
+test('resolves with correct data', async () => {
+  const result = await fetchUserData('user-123');
   expect(result).toEqual(expectedUserData);
 });
 ```
@@ -189,7 +189,7 @@ test("resolves with correct data", async () => {
 ### ✅ Database Test Cleanup
 
 ```typescript
-describe("UserService", () => {
+describe('UserService', () => {
   let dbClient;
 
   beforeEach(async () => {
@@ -209,7 +209,7 @@ describe("UserService", () => {
 ### Test Comments for Complex Logic
 
 ```typescript
-test("calculates compound interest with monthly compounding", () => {
+test('calculates compound interest with monthly compounding', () => {
   // Formula: A = P(1 + r/n)^(nt)
   // Where: A = final amount, P = principal, r = rate, n = compounding frequency, t = time
   const principal = 1000;
@@ -217,12 +217,7 @@ test("calculates compound interest with monthly compounding", () => {
   const compoundingFrequency = 12; // monthly
   const timeInYears = 2;
 
-  const result = calculateCompoundInterest(
-    principal,
-    rate,
-    compoundingFrequency,
-    timeInYears
-  );
+  const result = calculateCompoundInterest(principal, rate, compoundingFrequency, timeInYears);
   const expected = 1104.54; // Pre-calculated expected value
 
   expect(result).toBeCloseTo(expected, 2);
@@ -245,7 +240,7 @@ test("calculates compound interest with monthly compounding", () => {
 ### Response Time Assertions
 
 ```typescript
-test("responds within SLA", async () => {
+test('responds within SLA', async () => {
   const startTime = Date.now();
   const result = await expensiveOperation();
   const duration = Date.now() - startTime;
@@ -312,4 +307,64 @@ test("meets color contrast requirements", () => {
     getContrastRatio(styles.color, styles.backgroundColor)
   ).toBeGreaterThan(4.5);
 });
-```
+```
+
+## Execution Discipline
+
+- Run unit tests and lints after any major change; iterate until green.
+- If the project defines an engine, confirm Node version via console before running scripts.
+- `.env` files exist; do **not** attempt to cat protected dotfiles. Use framework tooling or documented env loaders.
+
+## Commits
+
+- `--no-verify` is **not allowed**. If hooks fail, **fix the cause** or split work into smaller audited commits.
+- Commit subjects: **what + why** in one sentence. Bodies for context only when needed.
+
+## TODOs & Placeholders
+
+Tag placeholders explicitly in code:
+
+- `// TODO: ...` (critical, must block if reached)
+- `// PLACEHOLDER: ...` (non-critical placeholder, warn)
+- `// MOCK DATA: ...` (remove before release)
+
+**Critical TODOs**: throw at execution site with clear message.
+
+## Diagrams/Charts
+
+- In Markdown, use **Mermaid** only. Ensure contrast (dark text on light, light on dark backgrounds).
+
+## CAWS Integration
+
+### Quality Gate Commands
+
+```bash
+# 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
+
+# Update progress with test completion
+caws progress update --criterion-id="TEST-001" --status="completed" --tests-passing=25
+```
+
+### Test Analysis
+
+```bash
+# Analyze test patterns and budget prediction
+caws test-analysis assess-budget
+caws test-analysis analyze-patterns
+caws test-analysis find-similar
+```
+
+## Acceptance
+
+- `test`, `lint`, `typecheck` succeed.
+- No TODOs executed at runtime.
+- No style violations flagged by project linters.
+- Coverage thresholds met (80%+ line, 90%+ branch)
+- Mutation testing scores meet targets (70%+ for critical components)
+- All integration tests use real database connections
+- Performance tests meet documented SLAs

package/templates/.cursor/rules/03-naming-and-refactor.mdc

@@ -0,0 +1,33 @@
+---
+description: Canonical naming; forbid enhanced/new/final forks; refactor rules
+globs:
+alwaysApply: true
+---
+
+# Canonical Naming & Refactor Rules
+
+## No Duplicate/Fork Names
+
+Reject or remove modules/files named with these modifiers:
+`enhanced | unified | better | new | next | final | copy | revamp | improved` (case-insensitive).
+
+**Pre-flight check (human-run or agent-run shell):**
+
+```bash
+rg -n --no-ignore -g '!node_modules' '(?i)\b(enhanced|unified|better|new|next|final|copy|revamp|improved)\b'
+rg -n --no-ignore -g '!node_modules' '(?i)(enhanced|unified|new|final|copy).*\.([tj]sx?|mjs|cjs|mts|cts)$'
+```
+
+If hits exist in proposed filenames/symbols: **do not proceed**. Use **purpose-first canonical names** and edit the existing module.
+
+## Refactor Strategy
+
+- **Merge, then delete**: If two files cover one domain, merge into the canonical name, update imports, remove the duplicate.
+- Prefer **Strategy** + feature flags over file forks.
+- Every refactor must include tests proving no behavior change (or updated tests + CHANGELOG if behavior changes).
+
+## Acceptance
+
+- No banned modifiers present in filenames or public symbols.
+- Imports updated; build is green.
+- Duplicates removed from tree.

package/templates/.cursor/rules/04-logging-language-style.mdc

@@ -0,0 +1,23 @@
+---
+description: Logging, language tone, emoji policy
+globs:
+alwaysApply: true
+---
+
+# Logging & Language
+
+## Clarity over chronology
+
+Remove "phase/week" phrasing in docs/logs. State the **specific improvement**:
+
+- ❌ "PHASE 1 optimization"
+- ✅ "Initialize workload analyzer for parallelization"
+
+## Emojis
+
+- Emojis are banned across code, docs, and commits.
+- Exception (debug logs only): ⚠️, ✅, 🚫.
+
+## Commit Tone
+
+Professional, neutral, and specific. Avoid hype or vague framing.

package/templates/.cursor/rules/05-safe-defaults-guards.mdc

@@ -0,0 +1,23 @@
+---
+description: Safe defaults, guard clauses, early returns
+globs:
+alwaysApply: false
+---
+
+# Safe Defaults & Guard Clauses
+
+## Intent
+
+Minimize null/undefined faults and nesting.
+
+## Guidelines (language-agnostic)
+
+- Prefer **guard clauses** at top of function to fail fast.
+- Default parameter objects in signatures.
+- Prefer **short-circuiting** / optional access / null-coalescing where supported.
+- Loop defensively on possibly-empty collections.
+
+## Acceptance
+
+- No deep nesting introduced where guard clauses apply.
+- Inputs validated at boundaries; failures are explicit and early.

package/templates/.cursor/rules/06-typescript-conventions.mdc

@@ -0,0 +1,36 @@
+---
+description: TypeScript/JS conventions (alias imports, const, types source of truth)
+globs:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.mts'
+  - '**/*.cts'
+alwaysApply: false
+---
+
+# TS/JS Conventions
+
+## Variables
+
+- Prefer `const` over `let` where possible.
+
+## Imports
+
+- Use aliased imports from `@/` (mapped to `src`).
+- Replace deep relative paths (`../../x`) with `@/...` when available.
+
+## Types
+
+- Single source of truth at `src/types`.
+- Before creating a new type, check and extend the canonical definition.
+- Avoid duplicate declarations; prefer composition or augmentation.
+
+## Modularity
+
+- As files approach ~1000 LOC, evaluate separation of concerns; extract cohesive units.
+
+## Acceptance
+
+- No unnecessary `let`.
+- No duplicate type declarations.
+- No deep relative paths where alias exists.

package/templates/.cursor/rules/07-process-ops.mdc

@@ -0,0 +1,20 @@
+---
+description: Process discipline for local servers and hung commands
+globs:
+alwaysApply: true
+---
+
+# Process Discipline
+
+## Servers
+
+- Before starting a dev server, check if one is already running on the port; reuse or stop it to avoid duplicates.
+- If multiple processes are attached to the port, list and kill explicitly; document PIDs in the PR note if non-obvious.
+
+## Hung/Canceled Commands
+
+If a command is canceled or stalls:
+
+1. Assume it hung or waited for input.
+2. Re-run with verbose/debug flags.
+3. Surface the prompt/interaction in the PR so reviewers understand the resolution.

package/templates/.cursor/rules/08-solid-and-architecture.mdc

@@ -0,0 +1,16 @@
+---
+description: Architecture invariants (SOLID) and change isolation
+globs:
+alwaysApply: true
+---
+
+# Architecture Invariants
+
+- SRP: Each module/class has one reason to change.
+- OCP: Prefer extension points over editing stable internals.
+- LSP/ISP/DIP: Respect substitution; segregate interfaces; depend on abstractions.
+
+## Change Isolation
+
+- Introduce seams (interfaces/strategies) near integration points.
+- Add tests at seams; assert unchanged public behavior.