@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/policy/PolicyManager.js

@@ -8,6 +8,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
+const { createValidator, getSchemaPath } = require('../utils/schema-validator');
 
 /**
  * Policy Manager - Handles policy loading with intelligent caching
@@ -86,6 +87,34 @@ class PolicyManager {
       }
 
       if (policyPath && policyContent) {
+        // Schema validation (warn and fall back to defaults on failure)
+        try {
+          const schemaFilePath = getSchemaPath('policy.schema.json', projectRoot);
+          const validate = createValidator(schemaFilePath);
+          const schemaResult = validate(policyContent);
+          if (!schemaResult.valid) {
+            console.warn('Policy has schema violations:', schemaResult.errors);
+            console.warn('Falling back to default policy');
+            const defaultPolicy = this.getDefaultPolicy();
+            if (this.enableCaching) {
+              this.policyCache.set(projectRoot, {
+                policy: defaultPolicy,
+                cachedAt: Date.now(),
+                ttl: cacheTTL,
+              });
+            }
+            return {
+              ...defaultPolicy,
+              _isDefault: true,
+              _schemaErrors: schemaResult.errors,
+              _cacheHit: false,
+              _loadDuration: Date.now() - startTime,
+            };
+          }
+        } catch (schemaErr) {
+          console.warn('Could not validate policy schema:', schemaErr.message);
+        }
+
         // Validate policy structure
         this.validatePolicy(policyContent);
 
@@ -299,27 +328,30 @@ class PolicyManager {
       gates: {
         budget_limit: {
           enabled: true,
+          mode: 'block',
           description: 'Enforce change budget limits',
         },
         spec_completeness: {
           enabled: true,
+          mode: 'block',
           description: 'Require complete working specifications',
         },
-        contract_compliance: {
-          enabled: true,
-          description: 'Validate API contracts',
-        },
-        coverage_threshold: {
+        scope_boundary: {
           enabled: true,
-          description: 'Maintain test coverage requirements',
+          mode: 'block',
+          description: 'Enforce spec scope boundaries',
         },
-        mutation_threshold: {
+        god_object: {
           enabled: true,
-          description: 'Require mutation testing for T1/T2 changes',
+          mode: 'warn',
+          thresholds: { warning: 1750, critical: 2000 },
+          description: 'Detect oversized source files',
         },
-        security_scan: {
+        todo_detection: {
           enabled: true,
-          description: 'Run security vulnerability scans',
+          mode: 'warn',
+          thresholds: { min_confidence: 0.8 },
+          description: 'Scan for TODO/FIXME/HACK/XXX markers',
         },
       },
     };

package/dist/scaffold/claude-hooks.js

@@ -54,7 +54,7 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
     // Map levels to hook scripts
     const hookMapping = {
       safety: ['block-dangerous.sh', 'scan-secrets.sh', 'worktree-guard.sh', 'worktree-write-guard.sh', 'stop-worktree-check.sh', 'session-caws-status.sh'],
-      quality: ['quality-check.sh', 'validate-spec.sh'],
+      quality: ['quality-check.sh', 'validate-spec.sh', 'doc-frontmatter-check.sh'],
       scope: ['scope-guard.sh', 'naming-check.sh'],
       audit: ['audit.sh', 'session-log.sh'],
       lite: ['block-dangerous.sh', 'scope-guard.sh', 'lite-sprawl-check.sh', 'simplification-guard.sh'],
@@ -81,6 +81,7 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
       'block-dangerous.sh',
       'scope-guard.sh',
       'naming-check.sh',
+      'doc-frontmatter-check.sh',
       'lite-sprawl-check.sh',
       'simplification-guard.sh',
       'worktree-guard.sh',
@@ -90,6 +91,23 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
       'session-log.sh',
     ];
 
+    // Copy supporting scripts (not hooks themselves, but used by hooks)
+    const supportingScripts = [
+      'classify_command.py',
+      'test_classify_command.py',
+      'test_wrapper_smoke.sh',
+    ];
+
+    for (const script of supportingScripts) {
+      const sourcePath = path.join(claudeHooksTemplateDir, script);
+      const destPath = path.join(claudeHooksDir, script);
+
+      if (fs.existsSync(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        await fs.chmod(destPath, 0o755);
+      }
+    }
+
     for (const script of allHookScripts) {
       if (enabledHooks.has(script)) {
         const sourcePath = path.join(claudeHooksTemplateDir, script);
@@ -254,6 +272,11 @@ function generateClaudeSettings(levels, _enabledHooks) {
           command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/validate-spec.sh',
           timeout: 15,
         },
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/doc-frontmatter-check.sh',
+          timeout: 10,
+        },
       ],
     });
   }

package/dist/scaffold/git-hooks.js

@@ -279,7 +279,7 @@ if [ -d ".caws" ]; then
         var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
         var wts = Object.values(reg.worktrees || {});
         var active = wts.filter(function(w) {
-          return w.status === 'active' && w.baseBranch === '$CURRENT_BRANCH';
+          return (w.status === 'active' || w.status === 'fresh' || w.status === 'merged') && w.baseBranch === '$CURRENT_BRANCH';
         });
         console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(','));
       } catch(e) { console.log('0:'); }
@@ -338,7 +338,7 @@ if [ -d ".caws" ]; then
       HAS_ACTIVE_WT=$(node -e "
         try {
           var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
-          var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+          var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
           console.log(active.length > 0 ? 'yes' : 'no');
         } catch(e) { console.log('no'); }
       " 2>/dev/null)
@@ -358,110 +358,42 @@ if [ -d ".caws" ]; then
 fi
 # ===== End Multi-Agent Safety Guard =====
 
-# Fallback chain for quality gates:
-# 1. Try Node.js script (if exists)
-# 2. Try CAWS CLI
-# 3. Try Makefile target
-# 4. Try Python scripts
-# 5. Skip gracefully (warn only)
-
+# Run CAWS quality gates
 QUALITY_GATES_RAN=false
+QUALITY_GATES_WARNED=false
 
-# Option 1: Quality gates package (installed via npm)
-if [ -f "node_modules/@paths.design/quality-gates/run-quality-gates.mjs" ]; then
-  if command -v node >/dev/null 2>&1; then
-    echo "Running quality gates package..."
-    if CI= node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --context=commit; then
-      echo "Quality gates passed"
-      QUALITY_GATES_RAN=true
-    else
-      echo "Quality gates failed - commit blocked"
-      echo "Fix the violations above before committing"
-      exit 1
-    fi
-  fi
-# Option 1b: Quality gates package (monorepo/local copy)
-elif [ -f "node_modules/@caws/quality-gates/run-quality-gates.mjs" ]; then
-  if command -v node >/dev/null 2>&1; then
-    echo "Running quality gates package (local)..."
-    if CI= node node_modules/@caws/quality-gates/run-quality-gates.mjs --context=commit; then
-      echo "Quality gates passed"
-      QUALITY_GATES_RAN=true
-    else
-      echo "Quality gates failed - commit blocked"
-      echo "Fix the violations above before committing"
-      exit 1
-    fi
-  fi
-# Option 2: Legacy Node.js quality gates script (deprecated)
-elif [ -f "scripts/quality-gates/run-quality-gates.js" ]; then
-  if command -v node >/dev/null 2>&1; then
-    echo "Running legacy Node.js quality gates script..."
-    if node scripts/quality-gates/run-quality-gates.js; then
-      echo "Quality gates passed"
-      QUALITY_GATES_RAN=true
-    else
-      echo "Quality gates failed - commit blocked"
-      echo "Fix the violations above before committing"
-      exit 1
-    fi
-  fi
-# Option 3: CAWS CLI validation
-elif command -v caws >/dev/null 2>&1; then
-  # In a worktree, validate only the associated spec to avoid false positives
-  CAWS_VALIDATE_ARGS="--quiet"
-  WORKTREE_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
-  if [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
-    SPEC_ID=$(node -e "
-      try {
-        var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
-        var wt = Object.values(reg.worktrees || {}).find(function(w) {
-          return w.branch === '$WORKTREE_BRANCH';
-        });
-        if (wt && wt.specId) console.log(wt.specId);
-      } catch(e) {}
-    " 2>/dev/null || echo "")
-    if [ -n "$SPEC_ID" ]; then
-      CAWS_VALIDATE_ARGS="--quiet --spec-id $SPEC_ID"
-    fi
-  fi
-  echo "Running CAWS CLI validation..."
-  if caws validate $CAWS_VALIDATE_ARGS 2>/dev/null; then
-    echo "CAWS validation passed"
-    QUALITY_GATES_RAN=true
-  else
-    echo "CAWS validation failed, but allowing commit (non-blocking)"
-    echo "Run 'caws validate' for details"
-    QUALITY_GATES_RAN=true
-  fi
-# Option 3: Makefile target
-elif [ -f "Makefile" ] && grep -q "caws-validate\\|caws-gates" Makefile; then
-  echo "Running Makefile quality gates..."
-  if make caws-validate >/dev/null 2>&1 || make caws-gates >/dev/null 2>&1; then
-    echo "Makefile quality gates passed"
-    QUALITY_GATES_RAN=true
-  else
-    echo "Makefile quality gates failed, but allowing commit (non-blocking)"
-    QUALITY_GATES_RAN=true
-  fi
-# Option 4: Python scripts
-elif [ -f "scripts/simple_gates.py" ] && command -v python3 >/dev/null 2>&1; then
-  echo "Running Python quality gates script..."
-  if python3 scripts/simple_gates.py all --tier 2 --profile backend-api >/dev/null 2>&1; then
-    echo "Python quality gates passed"
+# Resolve spec ID from worktree context if available
+SPEC_ID=""
+WORKTREE_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+if [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  SPEC_ID=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
+      var wt = Object.values(reg.worktrees || {}).find(function(w) {
+        return w.branch === '$WORKTREE_BRANCH';
+      });
+      if (wt && wt.specId) console.log(wt.specId);
+    } catch(e) {}
+  " 2>/dev/null || echo "")
+fi
+
+GATES_ARGS="--context=commit --quiet"
+if [ -n "$SPEC_ID" ]; then
+  GATES_ARGS="$GATES_ARGS --spec-id $SPEC_ID"
+fi
+
+if command -v caws >/dev/null 2>&1; then
+  if caws gates run $GATES_ARGS; then
+    echo "Quality gates passed"
     QUALITY_GATES_RAN=true
   else
-    echo "Python quality gates failed, but allowing commit (non-blocking)"
-    QUALITY_GATES_RAN=true
+    GATE_EXIT=$?
+    echo "Quality gates BLOCKED the commit (exit code $GATE_EXIT)"
+    exit 1
   fi
-# Option 5: Skip gracefully
 else
-  echo "Quality gates not available - skipping"
-  echo "Available options:"
-  echo "   - Install quality gates: npm install --save-dev @paths.design/quality-gates"
-  echo "   - Install CAWS CLI: npm install -g @paths.design/caws-cli"
-  echo "   - Use Python: python3 scripts/simple_gates.py"
-  echo "   - Use Makefile: make caws-gates"
+  echo "CAWS CLI not available — skipping quality gates"
+  echo "Install with: npm install -g @paths.design/caws-cli"
   QUALITY_GATES_RAN=true
 fi
 
@@ -534,7 +466,11 @@ ${todoSuggestion
   fi
 fi
 
-echo "All quality checks passed - proceeding with commit"
+if [ "$QUALITY_GATES_WARNED" = true ]; then
+  echo "Proceeding with commit (some quality checks had warnings)"
+else
+  echo "All quality checks passed - proceeding with commit"
+fi
 exit 0
 `;
 }
@@ -554,6 +490,13 @@ function generatePostCommitHook() {
     exit 0
   fi
 
+  # Skip during merge operations — caws worktree merge triggers a merge
+  # commit, and writing to .caws/provenance/chain.json here would dirty
+  # the tree mid-merge, blocking subsequent operations.
+  if [ -f ".git/MERGE_HEAD" ] || [ -f "$(git rev-parse --git-dir 2>/dev/null)/MERGE_HEAD" ]; then
+    exit 0
+  fi
+
   # Get the current commit hash
   COMMIT_HASH=$(git rev-parse HEAD)
 
@@ -828,7 +771,7 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
     try {
       var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
       var active = Object.values(reg.worktrees || {}).filter(function(w) {
-        return w.status === 'active' && w.baseBranch === '$CURRENT_BRANCH';
+        return (w.status === 'active' || w.status === 'fresh' || w.status === 'merged') && w.baseBranch === '$CURRENT_BRANCH';
       });
       console.log(active.length);
     } catch(e) { console.log('0'); }

package/dist/scaffold/index.js

@@ -728,11 +728,12 @@ async function scaffoldProject(options) {
       } else {
         console.log('2. Run: caws validate (verify setup)');
         console.log('3. Run: caws diagnose (check project health)');
-        console.log('4. Customize .caws/working-spec.yaml for your project');
-        console.log('5. Optional: Create .caws/policy.yaml for tier-specific budgets');
+        console.log('4. Customize .caws/specs/<spec-id>.yaml for your project');
+        console.log('5. Treat .caws/working-spec.yaml as a compatibility mirror');
+        console.log('6. Optional: Create .caws/policy.yaml for tier-specific budgets');
         if (!qualityGatesAdded && !options.minimal) {
           console.log(
-            chalk.gray('6. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
+            chalk.gray('7. Note: Quality gates scripts skipped (git hooks use CAWS CLI by default)')
           );
           console.log(
             chalk.gray(

package/dist/session/session-manager.js

@@ -11,6 +11,8 @@ const fs = require('fs-extra');
 const path = require('path');
 const crypto = require('crypto');
 
+const { mergeFilesTouched } = require('../utils/working-state');
+
 const SESSIONS_DIR = '.caws/sessions';
 const REGISTRY_FILE = '.caws/sessions.json';
 const CAPSULE_SCHEMA_VERSION = 'caws.capsule.v1';
@@ -79,16 +81,62 @@ function getWorkspaceFingerprint(cwd) {
 }
 
 /**
- * Get project name from working spec or directory
+ * Load the best available spec synchronously (feature specs first, then legacy).
+ * @param {string} root - Repository root
+ * @param {string} [specId] - Optional specific spec ID
+ * @returns {object|null} Parsed spec object or null
+ */
+function loadBestSpecSync(root, specId) {
+  const yaml = require('js-yaml');
+
+  // If a specific spec ID is requested, load it directly
+  if (specId) {
+    for (const ext of ['.yaml', '.yml']) {
+      const p = path.join(root, '.caws/specs', `${specId}${ext}`);
+      if (fs.existsSync(p)) {
+        try { return yaml.load(fs.readFileSync(p, 'utf8')); } catch { /* skip */ }
+      }
+    }
+  }
+
+  // Check registry for active feature specs
+  const registryPath = path.join(root, '.caws/specs/registry.json');
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      const specs = registry.specs || {};
+      const activeIds = Object.keys(specs).filter(
+        id => specs[id].status !== 'closed' && specs[id].status !== 'archived'
+      );
+      for (const id of activeIds) {
+        const specEntry = specs[id];
+        const p = path.join(root, '.caws/specs', specEntry.path || `${id}.yaml`);
+        if (fs.existsSync(p)) {
+          try { return yaml.load(fs.readFileSync(p, 'utf8')); } catch { /* skip */ }
+        }
+      }
+    } catch { /* fall through */ }
+  }
+
+  // Legacy fallback
+  const legacyPath = path.join(root, '.caws/working-spec.yaml');
+  if (fs.existsSync(legacyPath)) {
+    try { return yaml.load(fs.readFileSync(legacyPath, 'utf8')); } catch { /* skip */ }
+  }
+
+  return null;
+}
+
+/**
+ * Get project name from best available spec or directory
  * @param {string} root - Repository root
+ * @param {string} [specId] - Optional specific spec ID
  * @returns {string}
  */
-function getProjectName(root) {
+function getProjectName(root, specId) {
   try {
-    const yaml = require('js-yaml');
-    const specPath = path.join(root, '.caws/working-spec.yaml');
-    if (fs.existsSync(specPath)) {
-      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+    const spec = loadBestSpecSync(root, specId);
+    if (spec) {
       return spec.title || spec.id || path.basename(root);
     }
   } catch {
@@ -98,16 +146,15 @@ function getProjectName(root) {
 }
 
 /**
- * Get skein ID from working spec
+ * Get skein ID from best available spec
  * @param {string} root - Repository root
+ * @param {string} [specId] - Optional specific spec ID
  * @returns {string}
  */
-function getSkeinId(root) {
+function getSkeinId(root, specId) {
   try {
-    const yaml = require('js-yaml');
-    const specPath = path.join(root, '.caws/working-spec.yaml');
-    if (fs.existsSync(specPath)) {
-      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+    const spec = loadBestSpecSync(root, specId);
+    if (spec) {
       return spec.id || 'unknown';
     }
   } catch {
@@ -201,8 +248,8 @@ function startSession(options = {}) {
 
   const capsule = {
     schema: CAPSULE_SCHEMA_VERSION,
-    project: getProjectName(root),
-    skein_id: getSkeinId(root),
+    project: getProjectName(root, specId),
+    skein_id: getSkeinId(root, specId),
     session_id: sessionId,
     role,
     spec_id: specId || null,
@@ -318,6 +365,11 @@ function checkpointSession(data = {}) {
   // Write updated capsule
   fs.writeFileSync(capsulePath, JSON.stringify(capsule, null, 2));
 
+  // Bridge to working state (per-spec)
+  if (capsule.spec_id && capsule.work_summary.paths_touched.length > 0) {
+    try { mergeFilesTouched(capsule.spec_id, capsule.work_summary.paths_touched, root); } catch { /* non-fatal */ }
+  }
+
   return capsule;
 }
 
@@ -385,6 +437,11 @@ function endSession(data = {}) {
   // Write finalized capsule
   fs.writeFileSync(capsulePath, JSON.stringify(capsule, null, 2));
 
+  // Bridge to working state (per-spec)
+  if (capsule.spec_id && capsule.work_summary.paths_touched.length > 0) {
+    try { mergeFilesTouched(capsule.spec_id, capsule.work_summary.paths_touched, root); } catch { /* non-fatal */ }
+  }
+
   // Update registry
   registry.sessions[sessionId].status = 'completed';
   registry.sessions[sessionId].ended_at = capsule.ended_at;

package/dist/sidecars/index.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Sidecar Registry
+ * Central registry of all bounded governance sidecars.
+ * @author @darianrosebrook
+ */
+
+const { analyzeSpecDrift } = require('./spec-drift');
+const { diagnoseQualityGaps } = require('./quality-gaps');
+const { draftWaiver } = require('./waiver-draft');
+const { summarizeProvenance } = require('./provenance-summary');
+const { createSidecarOutput, createNoStateOutput, formatSidecarText } = require('./schema');
+
+/**
+ * Registry of available sidecars.
+ * Each entry has a function and a short description for help text.
+ */
+const SIDECARS = {
+  drift: { fn: analyzeSpecDrift, description: 'Analyze spec drift vs implementation evidence' },
+  gaps: { fn: diagnoseQualityGaps, description: 'Diagnose quality gaps preventing phase advancement' },
+  'waiver-draft': { fn: draftWaiver, description: 'Generate pre-filled waiver templates from gate failures' },
+  provenance: { fn: summarizeProvenance, description: 'Summarize work provenance for merge readiness' },
+};
+
+module.exports = {
+  SIDECARS,
+  analyzeSpecDrift,
+  diagnoseQualityGaps,
+  draftWaiver,
+  summarizeProvenance,
+  createSidecarOutput,
+  createNoStateOutput,
+  formatSidecarText,
+};

package/dist/sidecars/listeners.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Sidecar Lifecycle Listeners
+ * Registers lightweight event handlers that print hints to run sidecars
+ * at governance-significant moments. Non-blocking, non-fatal.
+ * @author @darianrosebrook
+ */
+
+const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
+
+/**
+ * Register sidecar hint listeners on the lifecycle emitter.
+ * Call once during CLI startup.
+ */
+function registerSidecarListeners() {
+  // On gate blocked → suggest waiver draft
+  lifecycle.on(EVENTS.GATES_BLOCKED, (payload) => {
+    try {
+      if (process.env.CAWS_QUIET === '1') return;
+      const specFlag = payload.specId ? ` --spec-id ${payload.specId}` : '';
+      const gateFlag = payload.gateName ? ` --gate ${payload.gateName}` : '';
+      console.log(
+        `\n  [Sidecar] Waiver draft available: caws sidecar waiver-draft${specFlag}${gateFlag}`
+      );
+    } catch { /* non-fatal */ }
+  });
+
+  // On phase transition (non-complete) → suggest quality gap analysis
+  lifecycle.on(EVENTS.PHASE_TRANSITION, (payload) => {
+    try {
+      if (process.env.CAWS_QUIET === '1') return;
+      if (payload.newPhase === 'complete') return;
+      const specFlag = payload.specId ? ` --spec-id ${payload.specId}` : '';
+      console.log(
+        `\n  [Sidecar] Phase changed to ${payload.newPhase}. Run: caws sidecar gaps${specFlag}`
+      );
+    } catch { /* non-fatal */ }
+  });
+}
+
+module.exports = { registerSidecarListeners };