@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/templates/.caws/schemas/working-spec.schema.json

@@ -1,340 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "CAWS Working Spec",
-  "type": "object",
-  "required": [
-    "id",
-    "title",
-    "risk_tier",
-    "mode",
-    "blast_radius",
-    "operational_rollback_slo",
-    "scope",
-    "invariants",
-    "acceptance",
-    "non_functional",
-    "contracts"
-  ],
-  "not": {
-    "required": [
-      "change_budget"
-    ]
-  },
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+[a-z]*$",
-      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits with an optional lowercase suffix (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01, APC-01a). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-25 alignment)."
-    },
-    "title": {
-      "type": "string",
-      "minLength": 10,
-      "maxLength": 200,
-      "description": "Clear, descriptive title"
-    },
-    "type": {
-      "type": "string",
-      "enum": [
-        "feature",
-        "fix",
-        "refactor",
-        "chore",
-        "doc",
-        "docs"
-      ],
-      "description": "Type of work (informational; `mode` is the enforced gate input)"
-    },
-    "status": {
-      "type": "string",
-      "enum": [
-        "draft",
-        "active",
-        "in_progress",
-        "completed",
-        "closed",
-        "archived"
-      ]
-    },
-    "created_at": {
-      "type": "string"
-    },
-    "updated_at": {
-      "type": "string"
-    },
-    "worktree": {
-      "type": "string",
-      "description": "CAWS worktree name assigned to this spec"
-    },
-    "risk_tier": {
-      "type": [
-        "integer",
-        "string"
-      ],
-      "enum": [
-        1,
-        2,
-        3,
-        "1",
-        "2",
-        "3"
-      ],
-      "description": "Risk level (1=high, 2=medium, 3=low)"
-    },
-    "mode": {
-      "type": "string",
-      "enum": [
-        "feature",
-        "refactor",
-        "fix",
-        "doc",
-        "docs",
-        "chore",
-        "development"
-      ],
-      "description": "Mode of change. `development` is the default used by `caws specs create`; feature/refactor/fix/doc/chore are the classic modes the legacy validator accepted."
-    },
-    "waiver_ids": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^WV-\\d{4}$"
-      },
-      "description": "IDs of active waivers applying to this spec"
-    },
-    "blast_radius": {
-      "type": "object",
-      "required": [
-        "modules",
-        "data_migration"
-      ],
-      "properties": {
-        "modules": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "List of modules/paths the change touches"
-        },
-        "data_migration": {
-          "type": "boolean",
-          "description": "Whether the change requires a data migration"
-        }
-      },
-      "additionalProperties": true
-    },
-    "operational_rollback_slo": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Time target for operational rollback (e.g. '5m', '30m', '1h')"
-    },
-    "scope": {
-      "type": "object",
-      "required": [
-        "in"
-      ],
-      "properties": {
-        "in": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "minItems": 1,
-          "description": "Files/paths allowed to be edited (non-empty)"
-        },
-        "out": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Files/paths explicitly excluded from edits"
-        }
-      },
-      "additionalProperties": true
-    },
-    "invariants": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "minItems": 1,
-      "description": "Properties that must hold across the change (non-empty)"
-    },
-    "acceptance": {
-      "type": "array",
-      "minItems": 1,
-      "description": "Given/When/Then acceptance criteria (non-empty)",
-      "items": {
-        "type": "object",
-        "required": [
-          "id",
-          "given",
-          "when",
-          "then"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "minLength": 1
-          },
-          "given": {
-            "type": "string",
-            "minLength": 1
-          },
-          "when": {
-            "type": "string",
-            "minLength": 1
-          },
-          "then": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "additionalProperties": true
-      }
-    },
-    "non_functional": {
-      "type": "object",
-      "required": [
-        "a11y",
-        "perf",
-        "security"
-      ],
-      "properties": {
-        "a11y": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Accessibility requirements (may be empty array if not applicable)"
-        },
-        "perf": {
-          "type": "object",
-          "description": "Performance requirements (e.g. api_p95_ms, lcp_ms)"
-        },
-        "security": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Security requirements (may be empty array if not applicable)"
-        }
-      },
-      "additionalProperties": true
-    },
-    "contracts": {
-      "type": "array",
-      "description": "API contracts. Empty array is permitted; CAWSFIX-06 will warn (not fail) when mode=feature with empty contracts.",
-      "items": {
-        "type": "object",
-        "required": [
-          "type",
-          "path"
-        ],
-        "properties": {
-          "type": {
-            "type": "string",
-            "enum": [
-              "openapi",
-              "graphql",
-              "proto",
-              "pact",
-              "project_setup"
-            ]
-          },
-          "path": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
-          "version": {
-            "type": "string"
-          }
-        },
-        "additionalProperties": true
-      }
-    },
-    "observability": {
-      "type": "object"
-    },
-    "migrations": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "rollback": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "experimental_mode": {
-      "type": "object",
-      "required": [
-        "enabled",
-        "rationale",
-        "expires_at"
-      ],
-      "properties": {
-        "enabled": {
-          "type": "boolean"
-        },
-        "rationale": {
-          "type": "string"
-        },
-        "expires_at": {
-          "type": "string"
-        }
-      }
-    },
-    "timeboxed_hours": {
-      "type": "integer",
-      "minimum": 1
-    },
-    "human_override": {
-      "type": "object",
-      "required": [
-        "approved_by",
-        "reason"
-      ],
-      "properties": {
-        "approved_by": {
-          "type": "string"
-        },
-        "reason": {
-          "type": "string"
-        },
-        "waived_requirements": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "expiry_date": {
-          "type": "string"
-        }
-      }
-    },
-    "ai_assessment": {
-      "type": "object",
-      "properties": {
-        "confidence_level": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 10
-        },
-        "uncertainty_areas": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "recommended_pairing": {
-          "type": "boolean"
-        }
-      }
-    }
-  },
-  "additionalProperties": true
-}

package/dist/templates/.caws/schemas/worktrees.schema.json

@@ -1,38 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CAWS Worktree Registry",
-  "description": "Registry of git worktrees managed by CAWS for agent scope isolation",
-  "type": "object",
-  "required": ["version", "worktrees"],
-  "properties": {
-    "version": {
-      "type": "integer",
-      "const": 1
-    },
-    "worktrees": {
-      "type": "object",
-      "additionalProperties": {
-        "type": "object",
-        "required": ["name", "path", "branch", "baseBranch", "createdAt", "status"],
-        "properties": {
-          "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
-          "path": { "type": "string" },
-          "branch": { "type": "string" },
-          "baseBranch": { "type": "string" },
-          "scope": { "type": ["string", "null"] },
-          "specId": { "type": ["string", "null"] },
-          "owner": { "type": ["string", "null"], "description": "CLAUDE_SESSION_ID of the creating agent" },
-          "createdAt": { "type": "string", "format": "date-time" },
-          "destroyedAt": { "type": "string", "format": "date-time" },
-          "autoRegistered": { "type": "boolean" },
-          "status": {
-            "type": "string",
-            "enum": ["fresh", "active", "merged", "orphaned", "missing", "stale-merged", "destroyed"]
-          }
-        },
-        "additionalProperties": false
-      }
-    }
-  },
-  "additionalProperties": false
-}

package/dist/templates/.caws/templates/working-spec.template.yml

@@ -1,80 +0,0 @@
-id: '{{FEATURE_ID}}'
-title: '{{FEATURE_TITLE}}'
-# Recommended when the spec belongs to a CAWS worktree:
-# worktree: '{{WORKTREE_NAME}}'
-risk_tier: {{TIER}}
-mode: feature
-blast_radius:
-  modules: []
-  data_migration: false
-operational_rollback_slo: "30m"
-scope:
-  in:
-    - '{{SCOPE_ITEM_1}}'
-    - '{{SCOPE_ITEM_2}}'
-  out:
-    - '{{OUT_OF_SCOPE_ITEM_1}}'
-invariants:
-  - '{{BUSINESS_RULE_1}}'
-  - '{{BUSINESS_RULE_2}}'
-acceptance:
-  - id: A1
-    given: '{{GIVEN_CONDITION}}'
-    when: '{{WHEN_ACTION}}'
-    then: '{{THEN_OUTCOME}}'
-    status: pending # pending | in_progress | completed
-    # Optional: detailed progress tracking
-    # tests:
-    #   written: 0
-    #   passing: 0
-    # coverage: 0.0
-    # last_updated: '2025-10-09T14:30:00Z'
-  - id: A2
-    given: '{{GIVEN_CONDITION_2}}'
-    when: '{{WHEN_ACTION_2}}'
-    then: '{{THEN_OUTCOME_2}}'
-    status: pending # pending | in_progress | completed
-    # Optional: detailed progress tracking
-    # tests:
-    #   written: 0
-    #   passing: 0
-    # coverage: 0.0
-    # last_updated: '2025-10-09T14:30:00Z'
-non_functional:
-  a11y:
-    - '{{ACCESSIBILITY_REQUIREMENT}}'
-  perf:
-    api_p95_ms: {{PERF_BUDGET}}
-    lcp_ms: {{LCP_BUDGET}}
-  security:
-    - '{{SECURITY_REQUIREMENT}}'
-contracts:
-  - type: '{{CONTRACT_TYPE}}'
-    path: '{{CONTRACT_PATH}}'
-observability:
-  logs:
-    - '{{LOG_STATEMENT}}'
-  metrics:
-    - '{{METRIC_NAME}}'
-  traces:
-    - '{{TRACE_SPAN}}'
-migrations:
-  - '{{MIGRATION_DESCRIPTION}}'
-rollback:
-  - '{{ROLLBACK_STRATEGY}}'
-# Optional: Enable for experimental features with reduced requirements
-# experiment_mode: true
-# timeboxed_hours: 24
-
-# Optional: AI confidence assessment
-# ai_assessment:
-#   confidence_level: 8
-#   uncertainty_areas: ["complex business logic", "performance implications"]
-#   recommended_pairing: false
-
-# Optional: Human override for special cases (hotfixes, urgent changes)
-# human_override:
-#   approved_by: "senior-dev-username"
-#   reason: "Urgent production fix - bypassing mutation tests for immediate deployment"
-#   waived_requirements: ["mutation_testing", "manual_review"]
-#   expiry_date: "2025-10-01T00:00:00Z"

package/dist/templates/.caws/tools/README.md

@@ -1,18 +0,0 @@
-# CAWS Tools
-
-This directory contains CAWS-specific tools that aren't available in the CLI.
-
-## scope-guard.js
-
-Checks whether a file is within scope of active working-spec and feature specs. Used by Cursor hooks for scope validation on file attachments.
-
-```bash
-# Check if a file is in scope
-node .caws/tools/scope-guard.js check src/index.js
-
-# Exit code 0 = in scope, 1 = out of scope
-```
-
-**Usage in Cursor Hooks:**
-
-The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.

package/dist/templates/.caws/tools/scope-guard.js

@@ -1,203 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview CAWS Scope Guard (file-level)
- * Checks whether a given file path is within scope of active specs.
- * Used by Cursor hooks for scope validation on file attachments.
- * @author @darianrosebrook
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Convert a glob pattern to a RegExp, handling **, *, ?, [abc], {a,b}
- */
-function globToRegex(pattern) {
-  let i = 0, re = '';
-  while (i < pattern.length) {
-    const c = pattern[i];
-    if (c === '*' && pattern[i + 1] === '*') {
-      re += '.*'; i += 2;
-      if (pattern[i] === '/') i++; // skip trailing slash after **
-    } else if (c === '*') {
-      re += '[^/]*'; i++;
-    } else if (c === '?') {
-      re += '[^/]'; i++;
-    } else if (c === '[') {
-      const end = pattern.indexOf(']', i);
-      if (end > i) { re += pattern.slice(i, end + 1); i = end + 1; }
-      else { re += '\\['; i++; }
-    } else if (c === '{') {
-      const end = pattern.indexOf('}', i);
-      if (end > i) {
-        const alts = pattern.slice(i + 1, end).split(',').map(a => a.trim());
-        re += '(?:' + alts.join('|') + ')'; i = end + 1;
-      } else { re += '\\{'; i++; }
-    } else if ('.+^$|()'.includes(c)) {
-      re += '\\' + c; i++;
-    } else {
-      re += c; i++;
-    }
-  }
-  return new RegExp(re);
-}
-
-const TERMINAL = new Set(['completed', 'closed', 'archived']);
-
-/**
- * Check if a file is within scope of active specs.
- * @param {string} filePath - Relative path from project root
- * @param {string} projectDir - Project root directory
- * @returns {{inScope: boolean, reason: string}}
- */
-function checkFileScope(filePath, projectDir) {
-  // Smart allowlist: root-level files, .caws/, .claude/ always pass
-  if (!filePath.includes('/') || filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) {
-    return { inScope: true, reason: 'allowlisted path' };
-  }
-
-  const specFile = path.join(projectDir, '.caws/working-spec.yaml');
-  const specsDir = path.join(projectDir, '.caws/specs');
-
-  if (!fs.existsSync(specFile) && !fs.existsSync(specsDir)) {
-    return { inScope: true, reason: 'no specs found' };
-  }
-
-  // Load all active specs
-  let yaml;
-  try { yaml = require('js-yaml'); } catch (_) {
-    return { inScope: true, reason: 'js-yaml not available' };
-  }
-
-  // --- Authoritative spec detection ---
-  // If inside a worktree with a mutual spec binding, only check that spec.
-  let authoritativeSpec = null;
-  let mode = 'union';
-
-  const registryPath = path.join(projectDir, '.caws', 'worktrees.json');
-  const worktreesBase = path.join(projectDir, '.caws', 'worktrees');
-  const cwd = process.cwd();
-
-  if (cwd.startsWith(worktreesBase + path.sep)) {
-    const relative = path.relative(worktreesBase, cwd);
-    const worktreeName = relative.split(path.sep)[0];
-
-    if (worktreeName && fs.existsSync(registryPath)) {
-      try {
-        const reg = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-        const entry = reg.worktrees && reg.worktrees[worktreeName];
-
-        if (entry && entry.specId) {
-          const specCandidates = [
-            path.join(specsDir, entry.specId + '.yaml'),
-            path.join(specsDir, entry.specId + '.yml'),
-          ];
-          for (const candidate of specCandidates) {
-            if (fs.existsSync(candidate)) {
-              try {
-                const s = yaml.load(fs.readFileSync(candidate, 'utf8'));
-                if (s && !TERMINAL.has(s.status) && s.worktree === worktreeName) {
-                  authoritativeSpec = { source: path.basename(candidate), spec: s };
-                  mode = 'authoritative';
-                }
-              } catch (_) {}
-              break;
-            }
-          }
-        }
-      } catch (_) {}
-    }
-  }
-
-  // --- Collect specs based on mode ---
-  const specs = [];
-
-  if (authoritativeSpec) {
-    specs.push(authoritativeSpec);
-  } else {
-    if (fs.existsSync(specFile)) {
-      try {
-        const s = yaml.load(fs.readFileSync(specFile, 'utf8'));
-        if (s && !TERMINAL.has(s.status)) {
-          specs.push({ source: 'working-spec', spec: s });
-        }
-      } catch (_) {}
-    }
-
-    if (fs.existsSync(specsDir)) {
-      for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
-        try {
-          const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
-          if (s && !TERMINAL.has(s.status)) {
-            specs.push({ source: f, spec: s });
-          }
-        } catch (_) {}
-      }
-    }
-  }
-
-  if (specs.length === 0) {
-    return { inScope: true, reason: 'no active specs' };
-  }
-
-  // Check scope.out — any match blocks
-  for (const { source, spec } of specs) {
-    for (const pattern of (spec.scope?.out || [])) {
-      if (globToRegex(pattern).test(filePath)) {
-        const modeHint = mode === 'union'
-          ? '. No authoritative spec bound — checking all active specs. Fix: caws worktree bind <spec-id>'
-          : '';
-        return { inScope: false, reason: `out-of-scope in ${source} (pattern: ${pattern})${modeHint}` };
-      }
-    }
-  }
-
-  // scope.in — must match at least one
-  const allIn = specs.flatMap(({ spec }) => spec.scope?.in || []);
-  if (allIn.length > 0) {
-    const found = allIn.some(pattern => globToRegex(pattern).test(filePath));
-    if (!found) {
-      const modeHint = mode === 'union'
-        ? '. No authoritative spec bound — checking all active specs. Fix: caws worktree bind <spec-id>'
-        : '';
-      return { inScope: false, reason: `not in any active spec scope.in${modeHint}` };
-    }
-  }
-
-  return { inScope: true, reason: 'in scope' };
-}
-
-// CLI interface
-if (require.main === module) {
-  const command = process.argv[2];
-  const filePath = process.argv[3];
-
-  if (command === 'check' && filePath) {
-    // Resolve relative to cwd
-    const projectDir = process.cwd();
-    const rel = filePath.startsWith(projectDir)
-      ? filePath.slice(projectDir.length + 1)
-      : filePath;
-
-    const result = checkFileScope(rel, projectDir);
-    if (result.inScope) {
-      console.log(`in_scope: ${result.reason}`);
-      process.exit(0);
-    } else {
-      console.error(`out_of_scope: ${result.reason}`);
-      process.exit(1);
-    }
-  } else {
-    console.log('CAWS Scope Guard');
-    console.log('Usage:');
-    console.log('  node scope-guard.js check <file-path>');
-    console.log('');
-    console.log('Examples:');
-    console.log('  node scope-guard.js check src/index.js');
-    console.log('  node scope-guard.js check packages/cli/lib/main.ts');
-    process.exit(1);
-  }
-}
-
-module.exports = { checkFileScope, globToRegex };