@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/commands/quality-monitor.js

@@ -8,9 +8,8 @@
  */
 
 const chalk = require('chalk');
-const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
+const { resolveSpec } = require('../utils/spec-resolver');
 
 /**
  * Analyze quality impact of an action
@@ -79,52 +78,58 @@ function analyzeQualityImpact(action, files = [], context = {}) {
       analysis.recommendations = ['Run CAWS evaluation to assess impact'];
   }
 
-  // Load working spec to check risk tier
-  try {
-    const specPath = path.join(process.cwd(), '.caws/working-spec.yaml');
-    if (fs.existsSync(specPath)) {
-      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
-      const projectTier = spec.risk_tier;
-
-      analysis.project_tier = projectTier;
-
-      // Add context-specific recommendations for high-risk projects
-      if (projectTier <= 2) {
-        analysis.recommendations.unshift(
-          'High-risk project (Tier ' + projectTier + '): Run comprehensive validation'
-        );
-        if (analysis.risk_level === 'low') {
-          analysis.risk_level = 'medium';
-        } else if (analysis.risk_level === 'medium') {
-          analysis.risk_level = 'high';
-        }
-      }
+  // Add context-based recommendations
+  if (context.project_tier) {
+    analysis.project_tier = context.project_tier;
+  }
 
-      // Add tier-specific quality gates
-      if (projectTier === 1) {
-        analysis.quality_gates = [
-          'Branch coverage ≥ 90%',
-          'Mutation score ≥ 70%',
-          'All contract tests passing',
-          'Manual code review required',
-        ];
-      } else if (projectTier === 2) {
-        analysis.quality_gates = [
-          'Branch coverage ≥ 80%',
-          'Mutation score ≥ 50%',
-          'Contract tests passing (if applicable)',
-        ];
-      } else {
-        analysis.quality_gates = ['Branch coverage ≥ 70%', 'Mutation score ≥ 30%'];
-      }
+  return analysis;
+}
+
+/**
+ * Enrich analysis with project tier and resolved spec metadata.
+ * @param {Object} analysis
+ * @param {Object|null} resolvedSpec
+ * @returns {Object}
+ */
+function applySpecContext(analysis, resolvedSpec) {
+  if (!resolvedSpec?.spec) {
+    return analysis;
+  }
+
+  const projectTier = resolvedSpec.spec.risk_tier;
+  analysis.project_tier = projectTier;
+  analysis.spec_id = resolvedSpec.spec.id || null;
+  analysis.spec_path = resolvedSpec.path
+    ? path.relative(process.cwd(), resolvedSpec.path)
+    : null;
+
+  if (projectTier <= 2) {
+    analysis.recommendations.unshift(
+      'High-risk project (Tier ' + projectTier + '): Run comprehensive validation'
+    );
+    if (analysis.risk_level === 'low') {
+      analysis.risk_level = 'medium';
+    } else if (analysis.risk_level === 'medium') {
+      analysis.risk_level = 'high';
     }
-  } catch (error) {
-    // Ignore if we can't load spec
   }
 
-  // Add context-based recommendations
-  if (context.project_tier) {
-    analysis.project_tier = context.project_tier;
+  if (projectTier === 1) {
+    analysis.quality_gates = [
+      'Branch coverage ≥ 90%',
+      'Mutation score ≥ 70%',
+      'All contract tests passing',
+      'Manual code review required',
+    ];
+  } else if (projectTier === 2) {
+    analysis.quality_gates = [
+      'Branch coverage ≥ 80%',
+      'Mutation score ≥ 50%',
+      'Contract tests passing (if applicable)',
+    ];
+  } else {
+    analysis.quality_gates = ['Branch coverage ≥ 70%', 'Mutation score ≥ 30%'];
   }
 
   return analysis;
@@ -170,7 +175,18 @@ async function qualityMonitorCommand(action, options = {}) {
     }
 
     // Analyze quality impact
-    const analysis = analyzeQualityImpact(action, files, context);
+    let analysis = analyzeQualityImpact(action, files, context);
+
+    try {
+      const resolved = await resolveSpec({
+        specId: options.specId,
+        warnLegacy: false,
+        interactive: false,
+      });
+      analysis = applySpecContext(analysis, resolved);
+    } catch {
+      // Best-effort enrichment only
+    }
 
     // Display results
     console.log(chalk.bold('\nCAWS Quality Monitor\n'));
@@ -219,6 +235,9 @@ async function qualityMonitorCommand(action, options = {}) {
     // Project tier
     if (analysis.project_tier) {
       console.log(chalk.bold(`\nProject Tier: ${analysis.project_tier}`));
+      if (analysis.spec_id) {
+        console.log(chalk.gray(`Spec: ${analysis.spec_id}${analysis.spec_path ? ` (${analysis.spec_path})` : ''}`));
+      }
     }
 
     // Quality gates

package/dist/commands/sidecar.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview CAWS Sidecar Command
+ * CLI interface for bounded governance sidecars — advisory analysis modules
+ * that consume working state and produce structured recommendations.
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const { resolveSpec } = require('../utils/spec-resolver');
+const { loadState } = require('../utils/working-state');
+const { commandWrapper } = require('../utils/command-wrapper');
+const { SIDECARS, formatSidecarText } = require('../sidecars');
+
+/**
+ * Run a sidecar analysis.
+ * @param {string} subcommand - Sidecar name (drift, gaps, waiver-draft, provenance)
+ * @param {Object} options - Command options
+ * @param {string} [options.specId] - Target spec ID
+ * @param {boolean} [options.json] - Output as JSON
+ * @param {string} [options.gate] - Gate name filter (waiver-draft only)
+ */
+async function sidecarCommand(subcommand, options = {}) {
+  return commandWrapper(
+    async () => {
+      const sidecar = SIDECARS[subcommand];
+      if (!sidecar) {
+        const available = Object.keys(SIDECARS).join(', ');
+        console.error(chalk.red(`Unknown sidecar: ${subcommand}`));
+        console.error(chalk.yellow(`Available: ${available}`));
+        process.exit(1);
+      }
+
+      // Resolve spec
+      let spec = null;
+      try {
+        const resolved = await resolveSpec({
+          specId: options.specId,
+          warnLegacy: false,
+          quiet: Boolean(options.json),
+        });
+        spec = resolved.spec;
+      } catch (err) {
+        console.error(chalk.red(`Could not resolve spec: ${err.message}`));
+        console.error(chalk.yellow('Use --spec-id <id> to target a specific spec.'));
+        process.exit(1);
+      }
+
+      // Load working state (may be null — sidecars handle that)
+      const state = loadState(spec.id);
+
+      // Build sidecar-specific options
+      const sidecarOptions = {};
+      if (options.gate) sidecarOptions.gateName = options.gate;
+
+      // Run sidecar
+      const result = sidecar.fn(state, spec, sidecarOptions);
+
+      // Output
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatSidecarText(result));
+      }
+
+      return result;
+    },
+    { commandName: `sidecar ${subcommand}` }
+  );
+}
+
+module.exports = { sidecarCommand };

package/dist/commands/specs.js

@@ -15,6 +15,36 @@ const { SPEC_TYPES } = require('../constants/spec-types');
 // Import suggestFeatureBreakdown from spec-resolver
 const { suggestFeatureBreakdown } = require('../utils/spec-resolver');
 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');
+
+/**
+ * Check if a spec is referenced by any active worktree.
+ * Returns the list of worktree names that reference it, or empty array.
+ * @param {string} specId - Spec identifier to check
+ * @returns {string[]} Names of worktrees referencing this spec
+ */
+function getWorktreesReferencingSpec(specId) {
+  try {
+    const root = getRepoRoot();
+    const registry = loadWorktreeRegistry(root);
+    const matches = [];
+    for (const [name, entry] of Object.entries(registry.worktrees || {})) {
+      if (
+        entry.specId === specId &&
+        entry.status !== 'destroyed' &&
+        entry.status !== 'merged'
+      ) {
+        matches.push(name);
+      }
+    }
+    return matches;
+  } catch {
+    // If worktree registry can't be loaded (e.g., no .caws dir), no conflict
+    return [];
+  }
+}
 
 /**
  * Specs directory structure — anchored to the CAWS project root,
@@ -68,6 +98,98 @@ async function saveSpecsRegistry(registry) {
   await fs.writeFile(registryPath, JSON.stringify(registry, null, 2));
 }
 
+/**
+ * Read and validate a spec YAML file that was just written.
+ * This catches malformed YAML and duplicate keys before registry sync.
+ * @param {string} filePath - Absolute path to the spec file
+ * @returns {Promise<Object>} Parsed spec object
+ */
+async function validateAndReadSpecFile(filePath) {
+  const writtenContent = await fs.readFile(filePath, 'utf8');
+  const parsed = yaml.load(writtenContent);
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Failed to parse written spec file - invalid YAML structure');
+  }
+
+  const { validateWorkingSpec } = require('../validation/spec-validation');
+  const validation = validateWorkingSpec(parsed);
+
+  if (!validation.valid) {
+    const errorMessages = validation.errors
+      .map((e) => `${e.instancePath}: ${e.message}`)
+      .join('; ');
+    throw new Error(`Spec validation failed: ${errorMessages}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Build the registry entry from the parsed spec content instead of caller assumptions.
+ * @param {Object} spec - Parsed spec object
+ * @param {string} fileName - Registry path for the spec
+ * @param {string|null} owner - Session owner for the registry entry
+ * @returns {Object} Registry entry
+ */
+function buildRegistryEntryFromSpec(spec, fileName, owner = null) {
+  return {
+    path: fileName,
+    type: spec.type || 'feature',
+    status: spec.status || 'draft',
+    created_at: spec.created_at || new Date().toISOString(),
+    updated_at: spec.updated_at || new Date().toISOString(),
+    owner,
+  };
+}
+
+/**
+ * Backfill legacy sparse specs so write-time validation can succeed when
+ * update/merge flows touch older files created before the stricter schema.
+ * @param {Object} spec - Spec content to normalize
+ * @returns {Object} Normalized spec content
+ */
+function normalizeSpecForValidation(spec = {}) {
+  const normalizedRiskTier =
+    typeof spec.risk_tier === 'string'
+      ? parseInt(spec.risk_tier.replace(/^T/i, ''), 10) || 3
+      : spec.risk_tier || 3;
+
+  const acceptanceVal = Array.isArray(spec.acceptance)
+    ? spec.acceptance
+    : Array.isArray(spec.acceptance_criteria)
+      ? spec.acceptance_criteria
+      : [];
+
+  const defaults = {
+    type: 'feature',
+    status: 'draft',
+    risk_tier: normalizedRiskTier,
+    mode: 'standard',
+    blast_radius: { modules: [], data_migration: false },
+    operational_rollback_slo: '5m',
+    scope: { in: ['src/', 'tests/'], out: ['node_modules/', 'dist/', 'build/'] },
+    invariants: ['System maintains data consistency'],
+    acceptance: [],
+    acceptance_criteria: [],
+    non_functional: { a11y: [], perf: {}, security: [] },
+    contracts: [],
+  };
+
+  return {
+    ...defaults,
+    ...spec,
+    risk_tier: normalizedRiskTier,
+    blast_radius: { ...defaults.blast_radius, ...(spec.blast_radius || {}) },
+    scope: { ...defaults.scope, ...(spec.scope || {}) },
+    non_functional: { ...defaults.non_functional, ...(spec.non_functional || {}) },
+    acceptance: acceptanceVal,
+    acceptance_criteria: Array.isArray(spec.acceptance_criteria)
+      ? spec.acceptance_criteria
+      : acceptanceVal,
+  };
+}
+
 /**
  * List all spec files in the specs directory
  * @returns {Promise<Array>} Array of spec file info
@@ -192,8 +314,28 @@ async function createSpec(id, options = {}) {
     }
   }
 
-  // If we got here via override choice, proceed with creation
+  // If we got here via override choice, check ownership and worktree associations
   if (specExists && (force || answer === 'override')) {
+    // Check session ownership — only the creator session can override
+    const registry = await loadSpecsRegistry();
+    const existingEntry = registry.specs[id];
+    const currentSession = getAgentSessionId(findProjectRoot());
+    if (existingEntry?.owner && currentSession && existingEntry.owner !== currentSession) {
+      throw new Error(
+        `Cannot override spec '${id}': owned by another session (${existingEntry.owner}). ` +
+          `Only the creator session can override a spec. Create a new spec with a different ID instead.`
+      );
+    }
+
+    // Check for active worktree associations
+    const referencingWorktrees = getWorktreesReferencingSpec(id);
+    if (referencingWorktrees.length > 0) {
+      const names = referencingWorktrees.join(', ');
+      throw new Error(
+        `Cannot override spec '${id}': active worktree(s) [${names}] reference it. ` +
+          `Destroy the worktree(s) first with 'caws worktree destroy <name>', or create a new spec with a different ID.`
+      );
+    }
     console.log(chalk.yellow('Overriding existing spec...'));
   }
 
@@ -280,27 +422,9 @@ async function createSpec(id, options = {}) {
   await fs.writeFile(filePath, yamlContent);
 
   // Validate written file (YAML syntax and structure)
+  let parsedSpec;
   try {
-    const writtenContent = await fs.readFile(filePath, 'utf8');
-    const parsed = yaml.load(writtenContent);
-
-    // Validate YAML syntax was preserved
-    if (!parsed || typeof parsed !== 'object') {
-      await fs.remove(filePath);
-      throw new Error('Failed to parse written spec file - invalid YAML structure');
-    }
-
-    // Validate spec structure using CAWS validation
-    const { validateWorkingSpec } = require('../validation/spec-validation');
-    const validation = validateWorkingSpec(parsed);
-
-    if (!validation.valid) {
-      await fs.remove(filePath);
-      const errorMessages = validation.errors
-        .map((e) => `${e.instancePath}: ${e.message}`)
-        .join('; ');
-      throw new Error(`Spec validation failed: ${errorMessages}`);
-    }
+    parsedSpec = await validateAndReadSpecFile(filePath);
   } catch (error) {
     // Clean up invalid file if it exists
     if (await fs.pathExists(filePath)) {
@@ -319,25 +443,29 @@ async function createSpec(id, options = {}) {
 
   // Update registry
   const registry = await loadSpecsRegistry();
-  registry.specs[id] = {
-    path: fileName,
-    type,
-    status: 'draft',
-    created_at: specContent.created_at,
-    updated_at: specContent.updated_at,
-  };
+  registry.specs[id] = buildRegistryEntryFromSpec(
+    parsedSpec,
+    fileName,
+    getAgentSessionId(findProjectRoot())
+  );
   await saveSpecsRegistry(registry);
 
+  // Initialize working state for new spec
+  try {
+    const initialState = initializeState(id);
+    saveState(id, initialState, findProjectRoot());
+  } catch { /* non-fatal */ }
+
   return {
     id,
     path: fileName,
-    type,
-    title,
-    status: 'draft',
-    risk_tier: numericRiskTier,
-    mode,
-    created_at: specContent.created_at,
-    updated_at: specContent.updated_at,
+    type: parsedSpec.type || type,
+    title: parsedSpec.title || title,
+    status: parsedSpec.status || 'draft',
+    risk_tier: parsedSpec.risk_tier || numericRiskTier,
+    mode: parsedSpec.mode || mode,
+    created_at: parsedSpec.created_at || specContent.created_at,
+    updated_at: parsedSpec.updated_at || specContent.updated_at,
   };
 }
 
@@ -359,7 +487,7 @@ async function loadSpec(id) {
     const content = await fs.readFile(specPath, 'utf8');
     return yaml.load(content);
   } catch (error) {
-    return null;
+    throw new Error(`Failed to load spec '${id}' from ${specPath}: ${error.message}`);
   }
 }
 
@@ -392,18 +520,28 @@ async function updateSpec(id, updates = {}) {
     ...updates,
     updated_at: new Date().toISOString(),
   };
+  const normalizedSpec = normalizeSpecForValidation(updatedSpec);
 
-  // Update registry
+  // Write back to file
   const registry = await loadSpecsRegistry();
-  registry.specs[id].updated_at = updatedSpec.updated_at;
-  if (updates.status) {
-    registry.specs[id].status = updates.status;
+  const specPath = path.join(getSpecsDir(), registry.specs[id].path);
+  const previousContent = await fs.readFile(specPath, 'utf8');
+  await fs.writeFile(specPath, yaml.dump(normalizedSpec, { indent: 2 }));
+
+  let parsedSpec;
+  try {
+    parsedSpec = await validateAndReadSpecFile(specPath);
+  } catch (error) {
+    await fs.writeFile(specPath, previousContent);
+    throw new Error(`Failed to update spec '${id}': ${error.message}`);
   }
-  await saveSpecsRegistry(registry);
 
-  // Write back to file
-  const specPath = path.join(getSpecsDir(), registry.specs[id].path);
-  await fs.writeFile(specPath, yaml.dump(updatedSpec, { indent: 2 }));
+  registry.specs[id] = buildRegistryEntryFromSpec(
+    parsedSpec,
+    registry.specs[id].path,
+    registry.specs[id].owner || null
+  );
+  await saveSpecsRegistry(registry);
 
   return true;
 }
@@ -547,11 +685,34 @@ async function deleteSpec(id) {
     return false;
   }
 
+  // Block deletion if owned by another session
+  const currentSession = getAgentSessionId(findProjectRoot());
+  const existingEntry = registry.specs[id];
+  if (existingEntry?.owner && currentSession && existingEntry.owner !== currentSession) {
+    throw new Error(
+      `Cannot delete spec '${id}': owned by another session (${existingEntry.owner}). ` +
+        `Only the creator session can delete a spec.`
+    );
+  }
+
+  // Block deletion if active worktrees reference this spec
+  const referencingWorktrees = getWorktreesReferencingSpec(id);
+  if (referencingWorktrees.length > 0) {
+    const names = referencingWorktrees.join(', ');
+    throw new Error(
+      `Cannot delete spec '${id}': active worktree(s) [${names}] reference it. ` +
+        `Destroy the worktree(s) first with 'caws worktree destroy <name>'.`
+    );
+  }
+
   const specPath = path.join(getSpecsDir(), registry.specs[id].path);
 
   // Remove file
   await fs.remove(specPath);
 
+  // Clean up working state
+  try { deleteState(id, findProjectRoot()); } catch { /* non-fatal */ }
+
   // Update registry
   delete registry.specs[id];
   await saveSpecsRegistry(registry);
@@ -580,6 +741,34 @@ async function closeSpec(id) {
     return false;
   }
 
+  // Block closure if owned by another session
+  const registry = await loadSpecsRegistry();
+  const existingEntry = registry.specs[id];
+  const currentSession = getAgentSessionId(findProjectRoot());
+  if (existingEntry?.owner && currentSession && existingEntry.owner !== currentSession) {
+    console.error(
+      chalk.red(
+        `Cannot close spec '${id}': owned by another session (${existingEntry.owner}). ` +
+          `Only the creator session can close a spec.`
+      )
+    );
+    return false;
+  }
+
+  // Block closure if active worktrees reference this spec (closing removes scope enforcement)
+  const referencingWorktrees = getWorktreesReferencingSpec(id);
+  if (referencingWorktrees.length > 0) {
+    const names = referencingWorktrees.join(', ');
+    console.error(
+      chalk.red(
+        `Cannot close spec '${id}': active worktree(s) [${names}] reference it. ` +
+          `Closing would remove scope enforcement while work is in progress. ` +
+          `Destroy the worktree(s) first with 'caws worktree destroy <name>'.`
+      )
+    );
+    return false;
+  }
+
   return await updateSpec(id, { status: 'closed' });
 }