@paths.design/caws-cli 9.3.2 → 10.1.0

package/README.md

@@ -12,8 +12,8 @@ The CAWS CLI serves as the central control point for:
 - **Quality Validation**: Run comprehensive validation against working specifications
 - **Agent Integration**: Programmatic APIs for AI agents to evaluate and guide development
 - **Waiver Management**: Fast-lane escape hatches with full audit trails
-- **CI/CD Optimization**: Pipeline generation and optimization tools
-- **Experimental Features**: Dry-run capabilities for experimental functionality
+- **Quality Gates**: v2 pipeline with configurable gate modules
+- **Session Management**: Track and manage agent work sessions
 
 ## Installation
 
@@ -86,40 +86,82 @@ caws waivers list
 caws waivers revoke WV-0001
 ```
 
-### CI/CD Optimization
+### Quality Gates
 
 ```bash
-# Analyze project for CI/CD optimizations
-caws cicd analyze
+# Run quality gates v2 pipeline
+caws gates run
 
-# Generate optimized GitHub Actions workflow
-caws cicd generate github --output .github/workflows/caws-gates.yml
+# Run legacy quality gates
+caws quality-gates
+```
+
+### Worktree Management
+
+```bash
+# Create an isolated worktree for parallel agent work
+caws worktree create <name>
+
+# List active worktrees
+caws worktree list
+
+# Merge a completed worktree back to base
+caws worktree merge <name>
 
-# Smart test selection based on changes
-caws cicd test-selection --from-commit HEAD~1
+# Destroy a worktree
+caws worktree destroy <name>
+
+# Bind a spec to a worktree (fixes authoritative scope mode)
+caws worktree bind <spec-id>
+
+# Repair registry inconsistencies
+caws worktree repair
+```
+
+### Scope Management
+
+```bash
+# Inspect effective scope boundaries, mode, and binding health
+caws scope show
 ```
 
-### Experimental Features
+### Session Management
 
 ```bash
-# Dry-run validation without side effects
-caws experimental --dry-run validate .caws/working-spec.yaml
+# Start a tracked session
+caws session start
 
-# Experimental quality gates
-caws experimental quality-gates .caws/working-spec.yaml --parallel-execution
+# Create a session checkpoint
+caws session checkpoint
+
+# End a session
+caws session end
+
+# List past sessions
+caws session list
 ```
 
-### Tool Management
+### Spec Management
 
 ```bash
-# List available CAWS tools
-caws tools list
+# List all specs (project + feature)
+caws specs list
+
+# Create a feature spec
+caws specs create FEAT-001 --type feature --title "description"
 
-# Execute specific tool
-caws tools run validate
+# Show a spec
+caws specs show FEAT-001
 
-# Manage tool configurations
-caws tools --help
+# Check for scope conflicts between specs
+caws specs conflicts
+```
+
+### Tool Management
+
+```bash
+# Run the CAWS tool interface
+caws tool
 ```
 
 ## Architecture
@@ -131,7 +173,7 @@ caws-cli/
 ├── src/
 │   ├── index.js           # Main CLI entry point
 │   ├── waivers-manager.js # Waiver system implementation
-│   ├── cicd-optimizer.js  # CI/CD optimization logic
+│   ├── quality-gates/     # v2 gate modules
 │   └── tool-loader.js     # Dynamic tool loading system
 ├── templates/             # Project templates
 └── dist/                  # Compiled output
@@ -142,7 +184,7 @@ caws-cli/
 - **Command Parser**: Commander.js-based CLI with subcommands
 - **Tool System**: Dynamic loading of quality gate tools
 - **Waiver Manager**: Fast-lane escape hatch management
-- **CI/CD Optimizer**: Pipeline analysis and generation
+- **Quality Gates v2**: Modular gate pipeline with configurable modules
 - **Agent Interface**: JSON APIs for programmatic agent integration
 
 ## Integration with CAWS Ecosystem
@@ -157,25 +199,22 @@ caws-cli/
         │                       │
         └───────────────────────┘
                 │
-        ┌─────────────────┐
-        │ caws-mcp-server │
-        │ (Agent Bridge)  │
-        └─────────────────┘
 ```
 
 - **caws-template**: Provides the tools and configurations that CLI manages
-- **caws-mcp-server**: Exposes CLI functionality to AI agents via MCP protocol
 
 ### Quality Gates Integration
 
-The CLI automatically executes quality gates defined in the template:
+The v2 quality gates pipeline (`caws gates run`) executes modular gate checks:
 
-1. **Spec Validation**: Validates working specifications against schema
+1. **Spec Validation**: Validates working specifications against schema (mode, blast_radius, rollback SLO)
 2. **Security Scanning**: Runs security checks and secret detection
-3. **Code Quality**: Executes linting, type checking, and formatting
-4. **Test Execution**: Runs unit, integration, and contract tests
+3. **Scope Enforcement**: Verifies changes stay within spec-defined boundaries
+4. **Test & Coverage**: Runs tests and validates coverage thresholds per risk tier
 5. **Performance Checks**: Validates performance budgets and metrics
 
+Gates can be configured per-spec with `mode` (block/warn/skip) and custom `thresholds` in policy.yaml.
+
 ### Agent Workflow Integration
 
 The CLI provides structured APIs for agents:

package/dist/budget-derivation.js

@@ -156,6 +156,168 @@ function getDefaultPolicy() {
   };
 }
 
+/**
+ * Load policy.yaml synchronously for contexts that can't go async.
+ * Falls back to the bundled default policy when the file is absent or invalid.
+ * NOTE: bypasses PolicyManager's TTL cache by design — callers that need
+ * caching should use the async `deriveBudget` path.
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Policy object (validated, with _isDefault flag if fallback used)
+ */
+function loadPolicySync(projectRoot) {
+  const policyPath = path.join(projectRoot, '.caws', 'policy.yaml');
+  if (!fs.existsSync(policyPath)) {
+    return { ...getDefaultPolicy(), _isDefault: true };
+  }
+
+  let policyContent;
+  try {
+    policyContent = yaml.load(fs.readFileSync(policyPath, 'utf-8'));
+  } catch (error) {
+    console.warn(`Could not parse policy.yaml (${error.message}); using defaults`);
+    return { ...getDefaultPolicy(), _isDefault: true };
+  }
+
+  if (!policyContent || typeof policyContent !== 'object') {
+    return { ...getDefaultPolicy(), _isDefault: true };
+  }
+
+  try {
+    validatePolicy(policyContent);
+  } catch (error) {
+    // Policy file exists but is structurally invalid — surface as warning and
+    // fall back to defaults so validation can continue. The PolicyManager
+    // async path uses console.warn for the same shape.
+    console.warn(`Policy has structure violations (${error.message}); using defaults`);
+    return { ...getDefaultPolicy(), _isDefault: true };
+  }
+
+  return policyContent;
+}
+
+/**
+ * Normalize spec.risk_tier to a canonical lookup key.
+ * Accepts numeric tier (2), numeric-string ("2"), or "T2"/"t2" forms.
+ * Returns the numeric tier (2) when the input is recognizable, otherwise
+ * returns the original value so downstream "missing tier" logic can report it.
+ * @param {*} riskTier - spec.risk_tier
+ * @returns {number|*} numeric tier or original value
+ */
+function normalizeRiskTier(riskTier) {
+  if (typeof riskTier === 'number') {
+    return riskTier;
+  }
+  if (typeof riskTier === 'string') {
+    const match = riskTier.match(/^T?(\d)$/i);
+    if (match) {
+      return parseInt(match[1], 10);
+    }
+  }
+  return riskTier;
+}
+
+/**
+ * Look up a tier in policy.risk_tiers, tolerant of numeric vs string keys.
+ * policy.yaml serializes tier keys as strings ("1", "2", "3") while specs
+ * may use numeric risk_tier. Check both representations.
+ * @param {Object} policy - Policy object with risk_tiers map
+ * @param {number|string} tier - Normalized tier key
+ * @returns {Object|undefined} Tier budget config or undefined if missing
+ */
+function lookupTierBudget(policy, tier) {
+  if (!policy || !policy.risk_tiers) {
+    return undefined;
+  }
+  return policy.risk_tiers[tier] ?? policy.risk_tiers[String(tier)];
+}
+
+/**
+ * Build a derived-budget result from a spec, policy, and optional project root.
+ * Shared by both `deriveBudget` (async) and `deriveBudgetSync`. Pure function
+ * over already-loaded policy — no I/O.
+ *
+ * Baseline resolution order (per CAWSFIX-07 A1/A2):
+ *   1. If spec.change_budget has numeric max_files and max_loc, use it.
+ *      Legacy specs still in the tree may carry change_budget; CAWSFIX-03
+ *      forbade it in the schema but not the runtime, so we honor it when
+ *      present.
+ *   2. Otherwise, fall back to policy.risk_tiers[spec.risk_tier].
+ *
+ * Throws a named-tier error (A3) if the tier isn't present in policy and no
+ * spec-level change_budget is available.
+ *
+ * @param {Object} spec - Working spec
+ * @param {Object} policy - Loaded policy object
+ * @param {string} projectRoot - Project root (for waiver loading)
+ * @returns {Object} { baseline, effective, waivers_applied, derived_at }
+ */
+function applyBudgetDerivation(spec, policy, projectRoot) {
+  const riskTier = normalizeRiskTier(spec.risk_tier);
+  const tierBudget = lookupTierBudget(policy, riskTier);
+  const specBudget = spec && spec.change_budget;
+  const hasSpecBudget =
+    specBudget &&
+    typeof specBudget.max_files === 'number' &&
+    typeof specBudget.max_loc === 'number';
+
+  let baseline;
+  if (hasSpecBudget) {
+    baseline = {
+      max_files: specBudget.max_files,
+      max_loc: specBudget.max_loc,
+    };
+  } else if (tierBudget) {
+    baseline = {
+      max_files: tierBudget.max_files,
+      max_loc: tierBudget.max_loc,
+    };
+  } else {
+    const available = policy && policy.risk_tiers ? Object.keys(policy.risk_tiers).join(', ') : 'none';
+    throw new Error(
+      `Risk tier ${spec.risk_tier} not defined in policy.yaml\n` +
+        `Policy only defines tiers: ${available}\n` +
+        `Valid tiers are: 1 (critical), 2 (standard), 3 (low-risk)` +
+        (typeof spec.risk_tier === 'string'
+          ? `\nHint: use numeric risk_tier (e.g., 2) instead of "${spec.risk_tier}"`
+          : '')
+    );
+  }
+
+  let effectiveBudget = { ...baseline };
+
+  if (spec.waiver_ids && Array.isArray(spec.waiver_ids)) {
+    for (const waiverId of spec.waiver_ids) {
+      const waiver = loadWaiver(waiverId, projectRoot);
+      if (waiver && waiver.status === 'active' && isWaiverValid(waiver)) {
+        if (!waiver.gates || !waiver.gates.includes('budget_limit')) {
+          console.warn(
+            `\nWaiver ${waiverId} does not cover 'budget_limit' gate\n` +
+              `   Current gates: [${waiver.gates ? waiver.gates.join(', ') : 'none'}]\n` +
+              `   Add 'budget_limit' to gates array to apply to budget violations\n`
+          );
+          continue;
+        }
+
+        if (waiver.delta) {
+          if (waiver.delta.max_files) {
+            effectiveBudget.max_files += waiver.delta.max_files;
+          }
+          if (waiver.delta.max_loc) {
+            effectiveBudget.max_loc += waiver.delta.max_loc;
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    baseline,
+    effective: effectiveBudget,
+    waivers_applied: spec.waiver_ids || [],
+    derived_at: new Date().toISOString(),
+  };
+}
+
 /**
  * Derive budget for a working spec based on policy and waivers
  * Enhanced to use PolicyManager for caching
@@ -204,70 +366,32 @@ async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
       }
     }
 
-    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
-    let riskTier = spec.risk_tier;
-    if (typeof riskTier === 'string') {
-      const match = riskTier.match(/^T?(\d)$/i);
-      if (match) {
-        riskTier = parseInt(match[1], 10);
-      }
-    }
-
-    // Check if risk tier exists in policy
-    if (!policy.risk_tiers[riskTier]) {
-      throw new Error(
-        `Risk tier ${spec.risk_tier} not defined in policy.yaml\n` +
-          `Policy only defines tiers: ${Object.keys(policy.risk_tiers).join(', ')}\n` +
-          `Valid tiers are: 1 (critical), 2 (standard), 3 (low-risk)` +
-          (typeof spec.risk_tier === 'string'
-            ? `\nHint: use numeric risk_tier (e.g., 2) instead of "${spec.risk_tier}"`
-            : '')
-      );
-    }
-
-    const tierBudget = policy.risk_tiers[riskTier];
-    const baseline = {
-      max_files: tierBudget.max_files,
-      max_loc: tierBudget.max_loc,
-    };
-
-    // Start with baseline budget
-    let effectiveBudget = { ...baseline };
-
-    // Apply waivers if any
-    if (spec.waiver_ids && Array.isArray(spec.waiver_ids)) {
-      for (const waiverId of spec.waiver_ids) {
-        const waiver = loadWaiver(waiverId, projectRoot);
-        if (waiver && waiver.status === 'active' && isWaiverValid(waiver)) {
-          // Validate waiver covers budget_limit gate
-          if (!waiver.gates || !waiver.gates.includes('budget_limit')) {
-            console.warn(
-              `\nWaiver ${waiverId} does not cover 'budget_limit' gate\n` +
-                `   Current gates: [${waiver.gates ? waiver.gates.join(', ') : 'none'}]\n` +
-                `   Add 'budget_limit' to gates array to apply to budget violations\n`
-            );
-            continue;
-          }
-
-          // Apply additive deltas
-          if (waiver.delta) {
-            if (waiver.delta.max_files) {
-              effectiveBudget.max_files += waiver.delta.max_files;
-            }
-            if (waiver.delta.max_loc) {
-              effectiveBudget.max_loc += waiver.delta.max_loc;
-            }
-          }
-        }
-      }
-    }
+    return applyBudgetDerivation(spec, policy, projectRoot);
+  } catch (error) {
+    throw new Error(`Budget derivation failed: ${error.message}`);
+  }
+}
 
-    return {
-      baseline,
-      effective: effectiveBudget,
-      waivers_applied: spec.waiver_ids || [],
-      derived_at: new Date().toISOString(),
-    };
+/**
+ * Synchronous version of deriveBudget for callers that cannot go async.
+ * Uses `loadPolicySync` (no PolicyManager caching) and otherwise shares
+ * the same derivation semantics as the async variant.
+ *
+ * Added for CAWSFIX-07: the legacy synchronous call site in
+ * `validation/spec-validation.js` was passing the un-awaited Promise from
+ * `deriveBudget` into `checkBudgetCompliance`, which then read
+ * `derivedBudget.effective.max_files` on an undefined `.effective` —
+ * producing the "Cannot read properties of undefined (reading 'max_files')"
+ * warning on every schema-compliant spec.
+ *
+ * @param {Object} spec - Working spec object
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Derived budget with baseline and effective limits
+ */
+function deriveBudgetSync(spec, projectRoot = process.cwd()) {
+  try {
+    const policy = loadPolicySync(projectRoot);
+    return applyBudgetDerivation(spec, policy, projectRoot);
   } catch (error) {
     throw new Error(`Budget derivation failed: ${error.message}`);
   }
@@ -278,15 +402,25 @@ async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
  * @param {Object} waiver - Waiver document to validate
  * @throws {Error} If waiver structure is invalid
  */
-function validateWaiverStructure(waiver) {
-  const requiredFields = ['id', 'title', 'reason', 'status', 'gates', 'expires_at', 'approvers'];
+const WAIVER_REQUIRED_FIELDS = [
+  'id',
+  'applies_to',
+  'gates',
+  'delta',
+  'reason_code',
+  'expires_at',
+  'risk_owner',
+  'approvers',
+  'status',
+];
 
+function validateWaiverStructure(waiver) {
   // Check all required fields present
-  for (const field of requiredFields) {
+  for (const field of WAIVER_REQUIRED_FIELDS) {
     if (!(field in waiver)) {
       throw new Error(
         `Waiver missing required field: ${field}\n` +
-          `Required fields: ${requiredFields.join(', ')}\n` +
+          `Required fields: ${WAIVER_REQUIRED_FIELDS.join(', ')}\n` +
           `Fix the waiver file at .caws/waivers/${waiver.id || 'unknown'}.yaml`
       );
     }
@@ -302,8 +436,8 @@ function validateWaiverStructure(waiver) {
     );
   }
 
-  // Validate status
-  const validStatuses = ['active', 'expired', 'revoked'];
+  // Validate status (proposed is valid per schema but not applied by derivation)
+  const validStatuses = ['proposed', 'active', 'expired', 'revoked'];
   if (!validStatuses.includes(waiver.status)) {
     throw new Error(
       `Invalid waiver status: ${waiver.status}\n` +
@@ -322,15 +456,25 @@ function validateWaiverStructure(waiver) {
     );
   }
 
-  // Validate approvers is array
+  // Validate approvers is array of {handle, approved_at?} objects
   if (!Array.isArray(waiver.approvers) || waiver.approvers.length === 0) {
     throw new Error(
       `Invalid waiver approvers: ${JSON.stringify(waiver.approvers)}\n` +
-        'approvers must be a non-empty array of approver names/emails\n' +
-        'Example: approvers: ["tech-lead@company.com"]\n' +
+        'approvers must be a non-empty array of objects with a `handle` field\n' +
+        'Example: approvers: [{ handle: "tech-lead", approved_at: "2025-01-01T00:00:00Z" }]\n' +
         `Fix the approvers field in .caws/waivers/${waiver.id}.yaml`
     );
   }
+  for (const approver of waiver.approvers) {
+    if (typeof approver !== 'object' || approver === null || typeof approver.handle !== 'string') {
+      throw new Error(
+        `Invalid waiver approver entry: ${JSON.stringify(approver)}\n` +
+          'Each approver must be an object with a required `handle` field (string).\n' +
+          'Expected shape: { handle: "github-or-email", approved_at: "ISO-8601" }\n' +
+          `Fix the approvers field in .caws/waivers/${waiver.id}.yaml`
+      );
+    }
+  }
 
   // Validate expires_at is valid date string
   const expiryDate = new Date(waiver.expires_at);
@@ -451,8 +595,9 @@ function isWaiverValid(waiver, policy = null) {
       }
     }
 
-    // Check required fields
-    if (!waiver.id || !waiver.title || !waiver.gates) {
+    // Shallow sanity check. Full schema conformance is enforced by
+    // validateWaiverStructure at load time (see loadWaiver).
+    if (!waiver.id || !waiver.gates) {
       console.warn(`Waiver ${waiver.id || 'unknown'} missing required fields`);
       return false;
     }
@@ -592,6 +737,7 @@ function generateBurnupReport(derivedBudget, currentStats) {
 
 module.exports = {
   deriveBudget,
+  deriveBudgetSync,
   loadWaiver,
   isWaiverValid,
   checkBudgetCompliance,
@@ -601,4 +747,5 @@ module.exports = {
   validatePolicy,
   getDefaultPolicy,
   validateWaiverStructure,
+  WAIVER_REQUIRED_FIELDS,
 };