@paths.design/caws-cli 10.0.1 → 10.1.0

package/dist/commands/scope.js

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview CAWS Scope CLI Command
+ * Inspects and displays effective scope boundaries for the current context
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const {
+  getRepoRoot,
+  loadRegistry,
+  findFeatureSpecPath,
+  WORKTREES_DIR,
+} = require('../worktree/worktree-manager');
+
+/**
+ * Handle scope subcommands
+ * @param {string} subcommand - Subcommand name
+ * @param {Object} options - Command options
+ */
+async function scopeCommand(subcommand, options = {}) {
+  try {
+    switch (subcommand) {
+      case 'show':
+        return handleShow(options);
+      default:
+        console.error(chalk.red(`Unknown scope subcommand: ${subcommand}`));
+        console.log(chalk.blue('Available: show'));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Detect if current working directory is inside a worktree
+ * @param {string} root - Repository root
+ * @returns {{ inWorktree: boolean, worktreeName: string|null }}
+ */
+function detectWorktreeContext(root) {
+  const cwd = process.cwd();
+  const worktreesBase = path.join(root, WORKTREES_DIR);
+
+  if (!cwd.startsWith(worktreesBase + path.sep) && cwd !== worktreesBase) {
+    return { inWorktree: false, worktreeName: null };
+  }
+
+  // Extract worktree name: first path segment after the worktrees dir
+  const relative = path.relative(worktreesBase, cwd);
+  const worktreeName = relative.split(path.sep)[0];
+
+  if (!worktreeName) {
+    return { inWorktree: false, worktreeName: null };
+  }
+
+  return { inWorktree: true, worktreeName };
+}
+
+/**
+ * Load a spec file and return its parsed contents
+ * @param {string} specPath - Absolute path to spec YAML
+ * @returns {Object|null}
+ */
+function loadSpec(specPath) {
+  try {
+    if (!fs.existsSync(specPath)) return null;
+    const content = fs.readFileSync(specPath, 'utf8');
+    return yaml.load(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find all active spec files in .caws/specs/
+ * @param {string} root - Repository root
+ * @returns {Array<{ id: string, path: string, data: Object }>}
+ */
+function findAllActiveSpecs(root) {
+  const specsDir = path.join(root, '.caws', 'specs');
+  if (!fs.existsSync(specsDir)) return [];
+
+  const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  const specs = [];
+
+  for (const file of files) {
+    const specPath = path.join(specsDir, file);
+    const data = loadSpec(specPath);
+    if (!data) continue;
+
+    // Skip closed/archived specs
+    const status = (data.status || '').toLowerCase();
+    if (status === 'closed' || status === 'archived') continue;
+
+    const id = path.basename(file, path.extname(file));
+    specs.push({ id, path: specPath, data });
+  }
+
+  return specs;
+}
+
+/**
+ * Print scope patterns for a spec
+ * @param {Object} data - Parsed spec YAML
+ * @param {string} indent - Indentation prefix
+ */
+function printScopePatterns(data, indent = '   ') {
+  const scope = data.scope || {};
+  const scopeIn = scope.in || scope.include || [];
+  const scopeOut = scope.out || scope.exclude || [];
+
+  if (scopeIn.length > 0) {
+    console.log(chalk.green(`${indent}scope.in:`));
+    for (const pattern of scopeIn) {
+      console.log(chalk.gray(`${indent}  - ${pattern}`));
+    }
+  } else {
+    console.log(chalk.yellow(`${indent}scope.in: (none defined)`));
+  }
+
+  if (scopeOut.length > 0) {
+    console.log(chalk.red(`${indent}scope.out:`));
+    for (const pattern of scopeOut) {
+      console.log(chalk.gray(`${indent}  - ${pattern}`));
+    }
+  } else {
+    console.log(chalk.gray(`${indent}scope.out: (none)`));
+  }
+}
+
+/**
+ * Handle the 'show' subcommand
+ * @param {Object} options - Command options
+ */
+function handleShow(_options) {
+  const root = getRepoRoot();
+  const { inWorktree, worktreeName } = detectWorktreeContext(root);
+
+  console.log(chalk.bold.cyan('CAWS Scope Inspector'));
+  console.log(chalk.cyan('='.repeat(50)));
+  console.log('');
+
+  if (inWorktree) {
+    return handleAuthoritativeMode(root, worktreeName);
+  } else {
+    return handleUnionMode(root);
+  }
+}
+
+/**
+ * Handle authoritative mode: agent is inside a worktree with a bound spec
+ * @param {string} root - Repository root
+ * @param {string} worktreeName - Name of the worktree
+ */
+function handleAuthoritativeMode(root, worktreeName) {
+  console.log(chalk.white(`Worktree: ${chalk.bold(worktreeName)}`));
+
+  const registry = loadRegistry(root);
+  const entry = registry.worktrees ? registry.worktrees[worktreeName] : null;
+
+  if (!entry) {
+    console.log(chalk.red(`Worktree '${worktreeName}' not found in registry.`));
+    console.log(chalk.yellow('The scope guard is operating in union mode (all active specs).'));
+    return handleUnionMode(root);
+  }
+
+  const specId = entry.specId;
+
+  if (!specId) {
+    console.log(chalk.yellow('Mode: union (no spec bound to this worktree)'));
+    console.log('');
+    console.log(chalk.yellow('This worktree has no spec binding. The scope guard checks'));
+    console.log(chalk.yellow('against the union of all active specs.'));
+    console.log('');
+    console.log(chalk.blue('To bind a spec: caws worktree bind <spec-id>'));
+    console.log('');
+    return handleUnionMode(root);
+  }
+
+  // Load the spec
+  const specPath = findFeatureSpecPath(root, specId);
+  if (!specPath) {
+    console.log(chalk.red(`Bound spec '${specId}' not found on disk.`));
+    console.log(chalk.yellow('Fix: recreate the spec or rebind with a valid spec ID.'));
+    console.log(chalk.blue(`  caws worktree bind <valid-spec-id>`));
+    return;
+  }
+
+  const specData = loadSpec(specPath);
+  if (!specData) {
+    console.log(chalk.red(`Failed to parse spec file: ${specPath}`));
+    return;
+  }
+
+  console.log(chalk.green(`Mode: authoritative (single bound spec)`));
+  console.log(chalk.white(`Spec: ${chalk.bold(specId)}`));
+  if (specData.title) {
+    console.log(chalk.gray(`Title: ${specData.title}`));
+  }
+  console.log('');
+
+  // Print scope patterns
+  printScopePatterns(specData);
+  console.log('');
+
+  // Check binding health: mutual reference
+  const specWorktreeRef = specData.worktree || null;
+  const registrySpecRef = specId;
+
+  if (specWorktreeRef !== worktreeName) {
+    console.log(chalk.yellow('Binding health: BROKEN'));
+    console.log(chalk.yellow(`  Registry points to spec '${registrySpecRef}'`));
+    console.log(chalk.yellow(`  Spec 'worktree' field: ${specWorktreeRef || '(missing)'} (expected: ${worktreeName})`));
+    console.log('');
+    console.log(chalk.blue(`Fix: caws worktree bind ${specId}`));
+  } else {
+    console.log(chalk.green('Binding health: OK'));
+    console.log(chalk.gray(`  Registry -> spec: ${registrySpecRef}`));
+    console.log(chalk.gray(`  Spec -> worktree: ${specWorktreeRef}`));
+  }
+}
+
+/**
+ * Handle union mode: no worktree or no spec binding
+ * @param {string} root - Repository root
+ */
+function handleUnionMode(root) {
+  const specs = findAllActiveSpecs(root);
+
+  if (specs.length === 0) {
+    console.log(chalk.gray('Mode: union (no active specs found)'));
+    console.log('');
+    console.log(chalk.gray('No active feature specs in .caws/specs/.'));
+    console.log(chalk.gray('The scope guard has no patterns to enforce.'));
+    console.log('');
+    console.log(chalk.blue('Create a spec: caws specs create <id> --title "description"'));
+    return;
+  }
+
+  console.log(chalk.white('Mode: union (checking all active specs)'));
+  console.log(chalk.gray(`Active specs: ${specs.length}`));
+  console.log('');
+
+  for (const spec of specs) {
+    const statusLabel = spec.data.status || 'draft';
+    console.log(chalk.white(`  ${chalk.bold(spec.id)} [${statusLabel}]`));
+    if (spec.data.title) {
+      console.log(chalk.gray(`  Title: ${spec.data.title}`));
+    }
+    printScopePatterns(spec.data, '    ');
+
+    // Check if this spec has a worktree binding
+    if (spec.data.worktree) {
+      console.log(chalk.gray(`    worktree: ${spec.data.worktree}`));
+    }
+    console.log('');
+  }
+}
+
+module.exports = { scopeCommand };

package/dist/commands/sidecar.js

@@ -7,7 +7,10 @@
 
 const chalk = require('chalk');
 const { resolveSpec } = require('../utils/spec-resolver');
-const { loadState } = require('../utils/working-state');
+// EVLOG-002 Phase 2 read flip: sidecars read state from the event log via the
+// pure renderer. loadStateFromEvents matches loadState's null contract exactly,
+// so the existing "state may be null — sidecars handle that" behavior stays.
+const { loadStateFromEvents } = require('../utils/event-renderer');
 const { commandWrapper } = require('../utils/command-wrapper');
 const { SIDECARS, formatSidecarText } = require('../sidecars');
 
@@ -45,8 +48,8 @@ async function sidecarCommand(subcommand, options = {}) {
         process.exit(1);
       }
 
-      // Load working state (may be null — sidecars handle that)
-      const state = loadState(spec.id);
+      // Load working state (may be null — sidecars handle that; EVLOG-002: from event log)
+      const state = loadStateFromEvents(spec.id);
 
       // Build sidecar-specific options
       const sidecarOptions = {};

package/dist/commands/specs.js

@@ -18,6 +18,7 @@ const { findProjectRoot } = require('../utils/detection');
 const { loadRegistry: loadWorktreeRegistry, getRepoRoot } = require('../worktree/worktree-manager');
 const { getAgentSessionId } = require('../utils/agent-session');
 const { initializeState, saveState, deleteState } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
 
 /**
  * Check if a spec is referenced by any active worktree.
@@ -56,6 +57,35 @@ function getSpecsDir() {
 function getSpecsRegistry() {
   return path.join(findProjectRoot(), '.caws', 'specs', 'registry.json');
 }
+
+function detectCurrentWorktreeName() {
+  const cwd = process.cwd().replace(/\\/g, '/');
+  const worktreeMatch = cwd.match(/\/\.caws\/worktrees\/([^/]+)(?:\/|$)/);
+  if (worktreeMatch) {
+    return worktreeMatch[1];
+  }
+
+  try {
+    const root = getRepoRoot();
+    const branch = require('child_process')
+      .execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: 'pipe',
+      })
+      .trim();
+    const registry = loadWorktreeRegistry(root);
+    for (const [name, entry] of Object.entries(registry.worktrees || {})) {
+      if (entry.branch === branch && entry.status !== 'destroyed' && entry.status !== 'merged') {
+        return name;
+      }
+    }
+  } catch {
+    // Best-effort only; specs can still be created outside a worktree.
+  }
+
+  return null;
+}
 // Legacy constants kept for backward compatibility in tests
 const SPECS_DIR = '.caws/specs';
 const SPECS_REGISTRY = '.caws/specs/registry.json';
@@ -374,6 +404,11 @@ async function createSpec(id, options = {}) {
     contracts: [],
   };
 
+  const detectedWorktree = detectCurrentWorktreeName();
+  if (detectedWorktree) {
+    defaultSpec.worktree = detectedWorktree;
+  }
+
   // Merge template, but preserve required structure
   // Map template.criteria to acceptance if present
   const templateAcceptance = template?.criteria || template?.acceptance;
@@ -456,6 +491,63 @@ async function createSpec(id, options = {}) {
     saveState(id, initialState, findProjectRoot());
   } catch { /* non-fatal */ }
 
+  // CAWSFIX-06: warn when a feature spec is created without contracts.
+  // Contract-first development is a CAWS value proposition; empty `contracts`
+  // on a feature-type spec is discouraged but not fatal. Emit a non-fatal
+  // warning to stderr so agents and humans notice and can update the spec.
+  //
+  // Note: the spec's acceptance text uses "mode=feature" colloquially, but in
+  // CAWS the discriminator is the `type` field (feature/fix/refactor/chore),
+  // not the `mode` field (development/pilot/etc.). We key off `type` to match
+  // the --type CLI flag and the schema.
+  const specType = parsedSpec.type || type;
+  const specContracts = Array.isArray(parsedSpec.contracts) ? parsedSpec.contracts : [];
+  if (specType === 'feature' && specContracts.length === 0) {
+    console.warn(
+      chalk.yellow(
+        `⚠  Spec ${id} has mode=feature but no contracts. ` +
+          `mode=feature without contracts is discouraged — ` +
+          `run 'caws specs update ${id}' to add a contract reference.`
+      )
+    );
+  }
+
+  // EVLOG-001: emit spec_created event alongside state write.
+  //
+  // Spec-lifecycle events (spec_created / spec_closed / spec_deleted) are
+  // **informational redundancy** with the spec file + registry, which are
+  // the true sources of truth for spec identity. In contrast, the
+  // validation/evaluation/gates/verify_acs events are the ONLY record of
+  // those verification runs and losing them is real data loss.
+  //
+  // So we deliberately wrap spec-lifecycle emits in try/catch: a
+  // filesystem error here (test mocks, readonly fs, etc.) must not crash
+  // the spec create/close/delete flow, because the spec file itself is
+  // already persisted by the time we get here. This is a principled
+  // divergence from the strict contract for the observation events —
+  // see docs/internal/EVENTS_LOG_MIGRATION.md §4.5 and EVLOG-001 spec.
+  try {
+    await appendEvent(
+      {
+        actor: 'cli',
+        event: 'spec_created',
+        spec_id: id,
+        data: {
+          id,
+          type: parsedSpec.type || type,
+          title: parsedSpec.title || title,
+          risk_tier: parsedSpec.risk_tier || numericRiskTier,
+          mode: parsedSpec.mode || mode,
+        },
+      },
+      { projectRoot: findProjectRoot() }
+    );
+  } catch (err) {
+    // Surface on stderr but don't propagate — the spec is already created.
+     
+    console.error(`event-log: failed to record spec_created for ${id}: ${err.message}`);
+  }
+
   return {
     id,
     path: fileName,
@@ -717,6 +809,19 @@ async function deleteSpec(id) {
   delete registry.specs[id];
   await saveSpecsRegistry(registry);
 
+  // EVLOG-001: emit spec_deleted event in best-effort mode. See the
+  // createSpec commentary for why spec-lifecycle events diverge from
+  // the strict fail-loud contract used by the observation events.
+  try {
+    await appendEvent(
+      { actor: 'cli', event: 'spec_deleted', spec_id: id, data: { id } },
+      { projectRoot: findProjectRoot() }
+    );
+  } catch (err) {
+     
+    console.error(`event-log: failed to record spec_deleted for ${id}: ${err.message}`);
+  }
+
   return true;
 }
 
@@ -769,7 +874,49 @@ async function closeSpec(id) {
     return false;
   }
 
-  return await updateSpec(id, { status: 'closed' });
+  // CAWSFIX-15: status-only flip uses targeted line-replace so the diff
+  // stays a single line. Full `updateSpec` reserializes the whole YAML,
+  // reordering fields and injecting `*ref_0` anchors for the
+  // acceptance/acceptance_criteria alias — ~20 lines of noise for what
+  // should be a one-word change.
+  const specPath = path.join(getSpecsDir(), registry.specs[id].path);
+  const original = await fs.readFile(specPath, 'utf8');
+  const nowIso = new Date().toISOString();
+  let patched = original.replace(/^status:\s*\S+\s*$/m, 'status: closed');
+  patched = patched.replace(/^updated_at:.*$/m, `updated_at: '${nowIso}'`);
+  let ok = false;
+  if (patched !== original) {
+    await fs.writeFile(specPath, patched);
+    registry.specs[id] = {
+      ...registry.specs[id],
+      status: 'closed',
+      updated_at: nowIso,
+    };
+    await saveSpecsRegistry(registry);
+    ok = true;
+  }
+
+  // EVLOG-001: emit spec_closed event after the status update succeeds.
+  // Records the prior status so the renderer can reconstruct the lifecycle.
+  // Best-effort mode — see createSpec commentary.
+  if (ok) {
+    try {
+      await appendEvent(
+        {
+          actor: 'cli',
+          event: 'spec_closed',
+          spec_id: id,
+          data: { id, prior_status: currentStatus },
+        },
+        { projectRoot: findProjectRoot() }
+      );
+    } catch (err) {
+       
+      console.error(`event-log: failed to record spec_closed for ${id}: ${err.message}`);
+    }
+  }
+
+  return ok;
 }
 
 /**

package/dist/commands/status.js

@@ -12,7 +12,11 @@ const chalk = require('chalk');
 const { safeAsync, outputResult } = require('../error-handler');
 const { parallel } = require('../utils/async-utils');
 const { resolveSpec } = require('../utils/spec-resolver');
-const { loadState } = require('../utils/working-state');
+// EVLOG-002 Phase 2 read flip: status reads working state from the event log
+// via the pure renderer. loadStateFromEvents matches loadState's null contract
+// exactly, so the `ws && ws.phase !== 'not-started'` guard and the
+// `loadState(id) || null` coalesce below stay semantically correct.
+const { loadStateFromEvents } = require('../utils/event-renderer');
 
 /**
  * Load working specification (legacy single file approach)
@@ -375,10 +379,10 @@ function displayStatus(data) {
 
   console.log('');
 
-  // Working State
+  // Working State (EVLOG-002: from event log)
   if (spec && spec.id) {
     let ws = null;
-    try { ws = loadState(spec.id); } catch { /* non-fatal */ }
+    try { ws = loadStateFromEvents(spec.id); } catch { /* non-fatal */ }
     if (ws && ws.phase !== 'not-started') {
       const phaseLabels = {
         'not-started': 'Not Started',
@@ -1052,7 +1056,7 @@ async function statusCommand(options = {}) {
               passed: gates.passed,
               message: gates.message,
             },
-            workingState: spec && spec.id ? (loadState(spec.id) || null) : null,
+            workingState: spec && spec.id ? (loadStateFromEvents(spec.id) || null) : null,
             overallProgress: calculateOverallProgress({
               spec,
               specSelection,

package/dist/commands/templates.js

@@ -53,14 +53,6 @@ const BUILTIN_TEMPLATES = {
     features: ['React', 'TypeScript', 'Storybook', 'Jest', 'Publishing'],
     path: 'templates/react/component-library',
   },
-  'vscode-extension': {
-    name: 'VS Code Extension',
-    description: 'VS Code extension with TypeScript',
-    category: 'Extension',
-    tier: 2,
-    features: ['TypeScript', 'VS Code API', 'Jest', 'Publishing'],
-    path: 'templates/vscode-extension',
-  },
 };
 
 /**

package/dist/commands/validate.js

@@ -20,6 +20,7 @@ const {
   loadSpecsRegistry,
 } = require('../utils/spec-resolver');
 const { recordValidation } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
 const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
 
 /**
@@ -143,19 +144,39 @@ async function validateCommand(specFile, options = {}) {
 
     const finalResult = enhancedValidation;
 
-    // Record to working state
-    try {
-      const grade = finalResult.complianceScore !== undefined
-        ? getComplianceGrade(finalResult.complianceScore)
-        : null;
-      recordValidation(spec.id, {
-        passed: finalResult.valid,
-        compliance_score: finalResult.complianceScore ?? null,
-        grade,
-        error_count: (finalResult.errors || []).length,
-        warning_count: (finalResult.warnings || []).length,
-      });
-    } catch { /* non-fatal */ }
+    // Record to working state (Phase 1 dual-write: state layer + event log)
+    const validationGrade = finalResult.complianceScore !== undefined
+      ? getComplianceGrade(finalResult.complianceScore)
+      : null;
+    const validationPayload = {
+      passed: finalResult.valid,
+      compliance_score: finalResult.complianceScore ?? null,
+      grade: validationGrade,
+      error_count: (finalResult.errors || []).length,
+      warning_count: (finalResult.warnings || []).length,
+    };
+    // CAWSFIX-02: guard recordValidation with the same `spec && spec.id`
+    // check that gates.js already uses and that the appendEvent call below
+    // enforces. Without this, legacy working-specs without an id silently
+    // wrote `.caws/state/undefined.json` — now blocked by the state-layer
+    // fence, but guarding here keeps the intent explicit.
+    if (spec && spec.id) {
+      try {
+        recordValidation(spec.id, validationPayload);
+      } catch { /* non-fatal */ }
+    }
+
+    // EVLOG-001: emit event log entry alongside state write. Only if
+    // spec.id is present — the fence in appendEvent would throw otherwise,
+    // which is intentional for the undefined.json bug class but wrong for
+    // legitimate legacy specs without an id field. Errors here are NOT
+    // swallowed: a failure to append an event is a real defect we want to
+    // surface, not a silent data-loss event.
+    if (spec && spec.id) {
+      await appendEvent(
+        { actor: 'cli', event: 'validation_completed', spec_id: spec.id, data: validationPayload }
+      );
+    }
 
     // Emit lifecycle event
     try {

package/dist/commands/verify-acs.js

@@ -12,6 +12,7 @@ const { execFileSync } = require('child_process');
 const { findProjectRoot } = require('../utils/detection');
 const { resolveSpec } = require('../utils/spec-resolver');
 const { recordACVerification } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
 
 /**
  * Detect the project's test runner from config files.
@@ -350,16 +351,30 @@ async function verifyAcsCommand(options = {}) {
     else { totalUnchecked++; }
   }
 
-  // Record to working state
-  try {
-    recordACVerification(resolved.spec.id, {
-      total: totalAcs,
-      pass: totalPass,
-      fail: totalFail,
-      unchecked: totalUnchecked,
-      results: result.results,
-    }, projectRoot);
-  } catch { /* non-fatal */ }
+  // Record to working state (Phase 1 dual-write: state layer + event log)
+  const acPayload = {
+    total: totalAcs,
+    pass: totalPass,
+    fail: totalFail,
+    unchecked: totalUnchecked,
+    results: result.results,
+  };
+  // CAWSFIX-02: guard recordACVerification with `resolved.spec && resolved.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 (resolved.spec && resolved.spec.id) {
+    try {
+      recordACVerification(resolved.spec.id, acPayload, projectRoot);
+    } catch { /* non-fatal */ }
+  }
+
+  // EVLOG-001: emit verify_acs_completed event alongside state write.
+  if (resolved.spec && resolved.spec.id) {
+    await appendEvent(
+      { actor: 'cli', event: 'verify_acs_completed', spec_id: resolved.spec.id, data: acPayload },
+      { projectRoot }
+    );
+  }
 
   // Output
   if (options.format === 'json') {