@paths.design/caws-cli 10.0.1 → 10.1.0

package/README.md

@@ -110,6 +110,19 @@ caws worktree merge <name>
 
 # 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
 ```
 
 ### Session Management
@@ -186,14 +199,9 @@ 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
 

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,
 };

package/dist/commands/evaluate.js

@@ -12,6 +12,7 @@ const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
 const { resolveSpec } = require('../utils/spec-resolver');
 const { recordEvaluation } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
 
 /**
  * Evaluate command handler
@@ -202,18 +203,31 @@ async function evaluateCommand(specFile, options = {}) {
               ? 'D'
               : 'F';
 
-    // Record to working state
-    try {
-      const checksPassed = results.checks.filter(c => c.status === 'pass').length;
-      recordEvaluation(spec.id, {
-        score: results.score,
-        max_score: results.maxScore,
-        percentage,
-        grade,
-        checks_passed: checksPassed,
-        checks_total: results.checks.length,
-      });
-    } catch { /* non-fatal */ }
+    // Record to working state (Phase 1 dual-write: state layer + event log)
+    const checksPassed = results.checks.filter(c => c.status === 'pass').length;
+    const evaluationPayload = {
+      score: results.score,
+      max_score: results.maxScore,
+      percentage,
+      grade,
+      checks_passed: checksPassed,
+      checks_total: results.checks.length,
+    };
+    // CAWSFIX-02: guard recordEvaluation with `spec && spec.id` check to
+    // prevent the .caws/state/undefined.json bug class. Matches the pattern
+    // gates.js already uses and the appendEvent call below.
+    if (spec && spec.id) {
+      try {
+        recordEvaluation(spec.id, evaluationPayload);
+      } catch { /* non-fatal */ }
+    }
+
+    // EVLOG-001: emit evaluation_completed event alongside state write.
+    if (spec && spec.id) {
+      await appendEvent(
+        { actor: 'cli', event: 'evaluation_completed', spec_id: spec.id, data: evaluationPayload }
+      );
+    }
 
     console.log('\n' + '-'.repeat(60));
     console.log(

package/dist/commands/gates.js

@@ -10,7 +10,13 @@ const { formatText, formatJson, formatEnrichedText } = require('../gates/format'
 const { enrichGateResults } = require('../gates/feedback');
 const { resolveSpec } = require('../utils/spec-resolver');
 const { commandWrapper } = require('../utils/command-wrapper');
-const { recordGates, loadState } = require('../utils/working-state');
+// EVLOG-002 Phase 2 read flip: gates still writes via recordGates (state layer)
+// AND emits a gates_evaluated event (from Phase 1), but the feedback-enrichment
+// READ at line ~116 now goes through the event log renderer instead of loadState.
+// The write path is deliberately unchanged in Phase 2 — only reads flip.
+const { recordGates } = require('../utils/working-state');
+const { loadStateFromEvents } = require('../utils/event-renderer');
+const { appendEvent } = require('../utils/event-log');
 
 /**
  * Run quality gates via the v2 pipeline
@@ -80,18 +86,39 @@ async function gatesCommand(options = {}) {
 
       const report = await evaluateGates({ projectRoot, stagedFiles, spec, context });
 
-      // Record to working state
+      // Record to working state (Phase 1 dual-write: state layer + event log)
       if (spec && spec.id) {
         try { recordGates(spec.id, report, context, projectRoot); } catch { /* non-fatal */ }
+
+        // EVLOG-001: emit gates_evaluated event alongside state write.
+        // Payload shape mirrors the `gates` field produced by recordGates.
+        await appendEvent(
+          {
+            actor: 'cli',
+            event: 'gates_evaluated',
+            spec_id: spec.id,
+            data: {
+              context,
+              passed: report.passed,
+              summary: report.summary || {},
+              gates: (report.gates || []).map((g) => ({
+                name: g.name,
+                status: g.status,
+                mode: g.mode,
+              })),
+            },
+          },
+          { projectRoot }
+        );
       }
 
       if (options.json || options.format === 'json') {
         console.log(formatJson(report));
       } else if (!options.quiet) {
-        // Enrich feedback on failure or --verbose
+        // Enrich feedback on failure or --verbose (EVLOG-002: from event log)
         if (!report.passed || options.verbose) {
           try {
-            const state = spec?.id ? loadState(spec.id, projectRoot) : null;
+            const state = spec?.id ? loadStateFromEvents(spec.id, { projectRoot }) : null;
             const enrichments = enrichGateResults(report, { spec, state, projectRoot });
             if (enrichments.size > 0) {
               console.log(formatEnrichedText(report, enrichments));

package/dist/commands/init.js

@@ -28,6 +28,8 @@ const {
   getRecommendedIDEs,
   parseIDESelection,
 } = require('../utils/ide-detection');
+// CAWSFIX-10: share the canonical spec-ID regex with the validator
+const { SPEC_ID_PATTERN } = require('../validation/spec-validation');
 
 function buildInitialFeatureSpec(specContent, fallbackId) {
   const parsed = yaml.load(specContent);
@@ -519,11 +521,12 @@ async function initProject(projectName, options) {
             return `PROJ-${randomNum.toString().padStart(3, '0')}`;
           },
           validate: (input) => {
-            if (!input.match(/^[A-Z]+-\d+$/)) {
-              return 'Project ID must be in format PREFIX-NUMBER (e.g., PROJ-001)';
+            // CAWSFIX-10: accept multi-segment IDs like P03-IMPL-01
+            if (!SPEC_ID_PATTERN.test(input)) {
+              return 'Project ID must be in format PREFIX-NUMBER or PREFIX-SEGMENT-NUMBER (e.g., PROJ-001, P03-IMPL-01)';
             }
-            if (input.length > 20) {
-              return 'Project ID must be less than 20 characters';
+            if (input.length > 40) {
+              return 'Project ID must be less than 40 characters';
             }
             return true;
           },

package/dist/commands/iterate.js

@@ -14,7 +14,11 @@ const { initializeGlobalSetup } = require('../config');
 
 // Import spec resolution system
 const { resolveSpec } = require('../utils/spec-resolver');
-const { loadState } = require('../utils/working-state');
+// EVLOG-002 Phase 2 read flip: iterate reads from the event log instead of
+// the state layer. loadStateFromEvents matches loadState's contract exactly
+// (returns null for specs with no events), so the `workingState &&` guard
+// below stays correct without code changes.
+const { loadStateFromEvents } = require('../utils/event-renderer');
 
 /**
  * Iterate command handler
@@ -58,9 +62,9 @@ async function iterateCommand(specFile, options = {}) {
     console.log(`ID: ${spec.id} | Tier: ${spec.risk_tier} | Mode: ${spec.mode}`);
     console.log(`Current State: ${stateDescription}\n`);
 
-    // Load working state for evidence-based guidance
+    // Load working state for evidence-based guidance (EVLOG-002: from event log)
     let workingState = null;
-    try { workingState = loadState(spec.id); } catch { /* non-fatal */ }
+    try { workingState = loadStateFromEvents(spec.id); } catch { /* non-fatal */ }
 
     // Analyze progress based on mode
     const guidance = generateGuidance(spec, currentState, options);