@paths.design/caws-cli 9.3.2 → 10.1.0

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,9 @@ const fs = require('fs-extra');
 const path = require('path');
 const crypto = require('crypto');
 
+const { mergeFilesTouched } = require('../utils/working-state');
+const { appendEventSync } = require('../utils/event-log');
+
 const SESSIONS_DIR = '.caws/sessions';
 const REGISTRY_FILE = '.caws/sessions.json';
 const CAPSULE_SCHEMA_VERSION = 'caws.capsule.v1';
@@ -79,16 +82,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 +147,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 +249,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,
@@ -250,6 +298,22 @@ function startSession(options = {}) {
   };
   saveRegistry(root, registry);
 
+  // EVLOG-001: emit session_started event via the sync append path.
+  // spec_id is optional for this event type; we include it only when
+  // the session is bound to a spec.
+  const sessionStartedEvent = {
+    actor: 'session',
+    event: 'session_started',
+    data: {
+      session_id: sessionId,
+      role,
+      branch: capsule.base_state.branch,
+      head_rev: capsule.base_state.head_rev,
+    },
+  };
+  if (specId) sessionStartedEvent.spec_id = specId;
+  appendEventSync(sessionStartedEvent, { projectRoot: root, session_id: sessionId });
+
   return capsule;
 }
 
@@ -318,6 +382,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,11 +454,33 @@ 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;
   saveRegistry(root, registry);
 
+  // EVLOG-001: emit session_ended event with final files_touched list.
+  // The renderer uses this to merge file touches into the spec view.
+  const sessionEndedEvent = {
+    actor: 'session',
+    event: 'session_ended',
+    data: {
+      session_id: sessionId,
+      files_touched: capsule.work_summary.paths_touched || [],
+      outcome: capsule.known_issues.some((i) => i.type === 'error') ? 'error' : 'success',
+    },
+  };
+  if (capsule.spec_id) {
+    sessionEndedEvent.spec_id = capsule.spec_id;
+    sessionEndedEvent.data.spec_id = capsule.spec_id;
+  }
+  appendEventSync(sessionEndedEvent, { projectRoot: root, session_id: sessionId });
+
   return capsule;
 }
 

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