@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/specs.js

@@ -15,6 +15,37 @@ 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');
+const { appendEvent } = require('../utils/event-log');
+
+/**
+ * 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,
@@ -26,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';
@@ -68,6 +128,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 +344,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...'));
   }
 
@@ -232,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;
@@ -280,27 +457,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 +478,86 @@ 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 */ }
+
+  // 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,
-    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 +579,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 +612,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,15 +777,51 @@ 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);
 
+  // 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;
 }
 
@@ -580,7 +846,77 @@ async function closeSpec(id) {
     return false;
   }
 
-  return await updateSpec(id, { status: 'closed' });
+  // 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;
+  }
+
+  // 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;
 }
 
 /**