@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/archive.js

@@ -10,6 +10,7 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { execSync } = require('child_process');
 const { safeAsync, outputResult } = require('../error-handler');
+const { findProjectRoot } = require('../utils/detection');
 
 // Import spec resolution system
 const { resolveSpec } = require('../utils/spec-resolver');
@@ -20,7 +21,8 @@ const { resolveSpec } = require('../utils/spec-resolver');
  * @returns {Promise<Object|null>} Change data or null
  */
 async function loadChange(changeId) {
-  const changesDir = '.caws/changes';
+  const projectRoot = findProjectRoot();
+  const changesDir = path.join(projectRoot, '.caws/changes');
   const changePath = path.join(changesDir, changeId);
 
   if (!(await fs.pathExists(changePath))) {
@@ -44,10 +46,11 @@ async function loadChange(changeId) {
       path: changePath,
       metadata,
       workingSpec,
+      workingSpecPath: (await fs.pathExists(workingSpecPath)) ? workingSpecPath : null,
       exists: true,
     };
   } catch (error) {
-    return null;
+    throw new Error(`Failed to load change '${changeId}': ${error.message}`);
   }
 }
 
@@ -57,18 +60,24 @@ async function loadChange(changeId) {
  * @returns {Promise<Object>} Validation result
  */
 async function validateAcceptanceCriteria(workingSpec) {
-  if (!workingSpec || !workingSpec.acceptance_criteria) {
+  const criteria = Array.isArray(workingSpec?.acceptance_criteria)
+    ? workingSpec.acceptance_criteria
+    : Array.isArray(workingSpec?.acceptance)
+      ? workingSpec.acceptance
+      : [];
+
+  if (!workingSpec || criteria.length === 0) {
     return {
       valid: false,
       message: 'No acceptance criteria found in working spec',
     };
   }
 
-  const criteria = workingSpec.acceptance_criteria;
+  const hasCompletionTracking = criteria.some((criterion) => criterion.completed !== undefined);
   const incomplete = [];
 
   for (const criterion of criteria) {
-    if (!criterion.completed) {
+    if (criterion.completed === false) {
       incomplete.push(criterion.id || 'unknown');
     }
   }
@@ -80,6 +89,13 @@ async function validateAcceptanceCriteria(workingSpec) {
     };
   }
 
+  if (!hasCompletionTracking) {
+    return {
+      valid: true,
+      message: `Acceptance criteria present (${criteria.length}); no explicit completion flags found`,
+    };
+  }
+
   return {
     valid: true,
     message: `All ${criteria.length} acceptance criteria completed`,
@@ -212,8 +228,8 @@ async function validateQualityGates(_changeId) {
  * @param {Object} change - Change data
  * @returns {Promise<string>} Summary text
  */
-async function generateChangeSummary(change) {
-  const { workingSpec, metadata } = change;
+async function generateChangeSummary(change, workingSpec) {
+  const { metadata } = change;
 
   let summary = `# Change Summary: ${change.id}\n\n`;
 
@@ -267,7 +283,7 @@ async function archiveChange(change) {
  * @param {Object} change - Change data
  * @returns {Promise<void>}
  */
-async function updateProvenance(change) {
+async function updateProvenance(change, specSelection) {
   const provenanceDir = '.caws/provenance';
   const chainPath = path.join(provenanceDir, 'chain.json');
 
@@ -284,8 +300,11 @@ async function updateProvenance(change) {
       action: 'change_completed',
       change_id: change.id,
       metadata: {
-        title: change.workingSpec?.title,
-        risk_tier: change.workingSpec?.risk_tier,
+        title: specSelection?.spec?.title || change.workingSpec?.title,
+        risk_tier: specSelection?.spec?.risk_tier || change.workingSpec?.risk_tier,
+        spec_id: specSelection?.spec?.id || change.workingSpec?.id || null,
+        spec_path: specSelection?.path || change.workingSpecPath || null,
+        spec_type: specSelection?.type || (change.workingSpecPath ? 'change-snapshot' : null),
         files_changed: change.metadata?.files_changed || 0,
         lines_added: change.metadata?.lines_added || 0,
         lines_removed: change.metadata?.lines_removed || 0,
@@ -309,10 +328,20 @@ async function updateProvenance(change) {
  * @param {Object} validation - Validation result
  * @param {Object} qualityGates - Quality gates result
  */
-function displayArchiveResults(change, validation, qualityGates) {
+function displayArchiveResults(change, validation, qualityGates, specSelection) {
   console.log(chalk.bold.cyan(`\nArchiving Change: ${change.id}`));
   console.log(chalk.cyan('==============================================\n'));
 
+  if (specSelection?.spec) {
+    console.log(chalk.blue('Spec Context:'));
+    console.log(
+      chalk.gray(
+        `   ${specSelection.spec.id || 'unknown'} (${specSelection.type}) -> ${specSelection.path}`
+      )
+    );
+    console.log('');
+  }
+
   // Validation status
   if (validation.valid) {
     console.log(chalk.green('Acceptance Criteria'));
@@ -363,22 +392,27 @@ async function archiveCommand(changeId, options = {}) {
       }
 
       // Resolve spec using priority system
-      let workingSpec = change.workingSpec;
-      if (!workingSpec && options.specId) {
-        // If change doesn't have a working spec but spec-id is provided, load it
-        try {
-          const resolved = await resolveSpec({
-            specId: options.specId,
-            warnLegacy: false,
-          });
-          workingSpec = resolved.spec;
-        } catch (error) {
-          console.log(
-            chalk.yellow(`Could not load spec '${options.specId}': ${error.message}`)
-          );
-        }
+      let specSelection = null;
+      if (options.specId || options.specFile) {
+        specSelection = await resolveSpec({
+          specId: options.specId,
+          specFile: options.specFile,
+          warnLegacy: false,
+        });
+      } else if (change.workingSpec) {
+        specSelection = {
+          path: change.workingSpecPath || path.join(change.path, 'working-spec.yaml'),
+          type: 'change-snapshot',
+          spec: change.workingSpec,
+        };
+      } else {
+        specSelection = await resolveSpec({
+          warnLegacy: false,
+        });
       }
 
+      const workingSpec = specSelection.spec;
+
       // Validate acceptance criteria
       const validation = await validateAcceptanceCriteria(workingSpec);
 
@@ -386,7 +420,7 @@ async function archiveCommand(changeId, options = {}) {
       const qualityGates = await validateQualityGates(changeId);
 
       // Display results
-      displayArchiveResults(change, validation, qualityGates);
+      displayArchiveResults(change, validation, qualityGates, specSelection);
 
       // Check if we should proceed with archival
       if (!validation.valid) {
@@ -423,7 +457,7 @@ async function archiveCommand(changeId, options = {}) {
       change.metadata.archived = true;
 
       // Generate and save summary
-      const summary = await generateChangeSummary(change);
+      const summary = await generateChangeSummary(change, workingSpec);
       const summaryPath = path.join(change.path, 'archive-summary.md');
       await fs.writeFile(summaryPath, summary);
 
@@ -431,7 +465,7 @@ async function archiveCommand(changeId, options = {}) {
       await archiveChange(change);
 
       // Update provenance
-      await updateProvenance(change);
+      await updateProvenance(change, specSelection);
 
       console.log(chalk.green(`\nSuccessfully archived change: ${changeId}`));
 
@@ -439,6 +473,11 @@ async function archiveCommand(changeId, options = {}) {
         command: 'archive',
         change: changeId,
         archived: true,
+        specSelection: {
+          id: workingSpec?.id || null,
+          path: specSelection?.path || null,
+          type: specSelection?.type || null,
+        },
         validation: validation.valid,
         qualityGates: qualityGates.valid,
         summary: summary,

package/dist/commands/burnup.js

@@ -11,6 +11,7 @@ const chalk = require('chalk');
 const { execSync } = require('child_process');
 
 const { deriveBudget, generateBurnupReport } = require('../budget-derivation');
+const { resolveSpec } = require('../utils/spec-resolver');
 
 /**
  * Get actual git change statistics from the repository
@@ -86,24 +87,32 @@ function getGitChangeStats(specDir) {
 
 /**
  * Burn-up command handler
- * @param {string} specFile - Path to spec file
+ * @param {string} specFile - Path to spec file (positional, optional)
+ * @param {object} options - Command options including --spec-id
  */
-async function burnupCommand(specFile) {
+async function burnupCommand(specFile, options = {}) {
   try {
-    let specPath = specFile || path.join('.caws', 'working-spec.yaml');
-
-    if (!fs.existsSync(specPath)) {
-      console.error(chalk.red(`Spec file not found: ${specPath}`));
-      process.exit(1);
+    let specPath;
+    let spec;
+
+    // Resolve spec: explicit file > --spec-id > resolver default
+    if (specFile) {
+      specPath = specFile;
+      if (!fs.existsSync(specPath)) {
+        console.error(chalk.red(`Spec file not found: ${specPath}`));
+        process.exit(1);
+      }
+      spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+    } else {
+      const resolved = await resolveSpec({ specId: options.specId });
+      specPath = resolved.path;
+      spec = resolved.spec;
     }
 
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
-
     console.log(chalk.cyan('Generating CAWS budget burn-up report...'));
 
     // Derive budget
-    const derivedBudget = deriveBudget(spec, path.dirname(specPath));
+    const derivedBudget = await deriveBudget(spec, path.dirname(specPath));
 
     // Get actual git change statistics
     const gitStats = getGitChangeStats(path.dirname(specPath));

package/dist/commands/diagnose.js

@@ -6,8 +6,8 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
+const { resolveSpec } = require('../utils/spec-resolver');
 
 // Import utilities
 const { checkTypeScriptTestConfig } = require('../utils/typescript-detector');
@@ -17,29 +17,23 @@ const { configureJestForTypeScript } = require('../generators/jest-config-genera
  * Health check: Working spec validity
  * @returns {Promise<Object>} Check result
  */
-async function checkWorkingSpec() {
-  const specPath = '.caws/working-spec.yaml';
-
-  if (!(await fs.pathExists(specPath))) {
-    return {
-      passed: false,
-      severity: 'high',
-      message: 'Working spec not found',
-      fix: 'Initialize CAWS: caws init .',
-      autoFixable: false,
-    };
-  }
-
+async function checkWorkingSpec(options = {}) {
   try {
-    const content = await fs.readFile(specPath, 'utf8');
-    const spec = yaml.load(content);
+    const resolved = await resolveSpec({
+      specId: options.specId,
+      specFile: options.spec,
+      warnLegacy: false,
+      interactive: false,
+    });
+    const spec = resolved.spec;
+    const specPath = path.relative(process.cwd(), resolved.path);
 
     // Basic validation
     if (!spec.id || !spec.title || !spec.risk_tier) {
       return {
         passed: false,
         severity: 'high',
-        message: 'Working spec missing required fields',
+        message: `Spec missing required fields (${specPath})`,
         fix: 'Run: caws validate for details',
         autoFixable: false,
       };
@@ -47,13 +41,31 @@ async function checkWorkingSpec() {
 
     return {
       passed: true,
-      message: 'Working spec is valid',
+      message: `Spec is valid (${specPath})`,
     };
   } catch (error) {
+    if (error.message === 'Spec ID required when multiple specs exist' && !options.specId) {
+      return {
+        passed: false,
+        severity: 'high',
+        message: 'Multiple specs detected, but no --spec-id was provided',
+        fix: 'Run: caws diagnose --spec-id <id>',
+        autoFixable: false,
+      };
+    }
+    if (error.message.includes('No CAWS spec found')) {
+      return {
+        passed: false,
+        severity: 'high',
+        message: 'No CAWS spec found',
+        fix: 'Initialize CAWS: caws init . or create a feature spec with caws specs create <id>',
+        autoFixable: false,
+      };
+    }
     return {
       passed: false,
       severity: 'high',
-      message: `Working spec has errors: ${error.message}`,
+      message: `Spec has errors: ${error.message}`,
       fix: 'Run: caws validate for details',
       autoFixable: false,
     };
@@ -285,9 +297,9 @@ async function checkCAWSTools() {
  * Run all health checks
  * @returns {Promise<Object>} Diagnosis results
  */
-async function runDiagnosis() {
+async function runDiagnosis(options = {}) {
   const checks = [
-    { name: 'Working spec validity', fn: checkWorkingSpec },
+    { name: 'Working spec validity', fn: () => checkWorkingSpec(options) },
     { name: 'Git repository', fn: checkGitSetup },
     { name: 'Git hooks', fn: checkGitHooks },
     { name: 'TypeScript configuration', fn: checkTypeScriptConfig },
@@ -447,7 +459,7 @@ async function applyAutoFixes(results) {
 async function diagnoseCommand(options = {}) {
   try {
     // Run all health checks
-    const results = await runDiagnosis();
+    const results = await runDiagnosis(options);
 
     // Display results
     displayResults(results);

package/dist/commands/evaluate.js

@@ -7,11 +7,12 @@
  * @author @darianrosebrook
  */
 
-const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
+const { resolveSpec } = require('../utils/spec-resolver');
+const { recordEvaluation } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
 
 /**
  * Evaluate command handler
@@ -19,30 +20,29 @@ const { initializeGlobalSetup } = require('../config');
  * @param {string} specFile - Path to working spec file
  * @param {object} options - Command options
  */
-async function evaluateCommand(specFile = '.caws/working-spec.yaml', options = {}) {
+async function evaluateCommand(specFile, options = {}) {
   try {
     console.log('Detecting CAWS setup...');
     const setup = initializeGlobalSetup();
 
     if (setup.hasWorkingSpec) {
-      console.log(`Detected ${setup.setupType} CAWS setup`);
+      console.log(`Detected ${setup.type} CAWS setup`);
       console.log(`   Capabilities: ${setup.capabilities.join(', ')}`);
     }
 
-    // Load working spec
-    const specPath = path.isAbsolute(specFile) ? specFile : path.join(process.cwd(), specFile);
-
-    if (!fs.existsSync(specPath)) {
-      console.error(chalk.red(`\nWorking spec not found: ${specFile}`));
-      console.error(chalk.yellow('Run: caws init to create a working spec'));
-      process.exit(1);
-    }
-
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
+    const resolved = await resolveSpec({
+      specId: options.specId,
+      specFile: specFile || undefined,
+      warnLegacy: false,
+      interactive: false,
+    });
+    const specPath = resolved.path;
+    const spec = resolved.spec;
 
     console.log(chalk.blue('\nEvaluating CAWS Quality Standards\n'));
     console.log('-'.repeat(60));
+    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
+    console.log(chalk.gray(`Type: ${resolved.type}`));
 
     // Evaluation results
     const results = {
@@ -203,6 +203,32 @@ async function evaluateCommand(specFile = '.caws/working-spec.yaml', options = {
               ? 'D'
               : 'F';
 
+    // Record to working state (Phase 1 dual-write: state layer + event log)
+    const checksPassed = results.checks.filter(c => c.status === 'pass').length;
+    const evaluationPayload = {
+      score: results.score,
+      max_score: results.maxScore,
+      percentage,
+      grade,
+      checks_passed: checksPassed,
+      checks_total: results.checks.length,
+    };
+    // CAWSFIX-02: guard recordEvaluation with `spec && 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 (spec && spec.id) {
+      try {
+        recordEvaluation(spec.id, evaluationPayload);
+      } catch { /* non-fatal */ }
+    }
+
+    // EVLOG-001: emit evaluation_completed event alongside state write.
+    if (spec && spec.id) {
+      await appendEvent(
+        { actor: 'cli', event: 'evaluation_completed', spec_id: spec.id, data: evaluationPayload }
+      );
+    }
+
     console.log('\n' + '-'.repeat(60));
     console.log(
       chalk.bold(

package/dist/commands/gates.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Unified quality gates CLI command
+ * Delegates to the v2 gate pipeline (src/gates/pipeline.js) for evaluation
+ * and formatting (src/gates/format.js) for output.
+ * @author @darianrosebrook
+ */
+
+const { evaluateGates } = require('../gates/pipeline');
+const { formatText, formatJson, formatEnrichedText } = require('../gates/format');
+const { enrichGateResults } = require('../gates/feedback');
+const { resolveSpec } = require('../utils/spec-resolver');
+const { commandWrapper } = require('../utils/command-wrapper');
+// EVLOG-002 Phase 2 read flip: gates still writes via recordGates (state layer)
+// AND emits a gates_evaluated event (from Phase 1), but the feedback-enrichment
+// READ at line ~116 now goes through the event log renderer instead of loadState.
+// The write path is deliberately unchanged in Phase 2 — only reads flip.
+const { recordGates } = require('../utils/working-state');
+const { loadStateFromEvents } = require('../utils/event-renderer');
+const { appendEvent } = require('../utils/event-log');
+
+/**
+ * Run quality gates via the v2 pipeline
+ * @param {Object} options - Command options
+ * @param {string} [options.context] - Execution context (cli, commit, edit)
+ * @param {string} [options.specId] - Target spec ID
+ * @param {string} [options.specFile] - Explicit spec file path
+ * @param {string} [options.file] - Single file to check (for edit context)
+ * @param {boolean} [options.json] - Output as JSON
+ * @param {string} [options.format] - Output format (text, json)
+ * @param {boolean} [options.quiet] - Minimal output
+ */
+async function gatesCommand(options = {}) {
+  return commandWrapper(
+    async () => {
+      const projectRoot = process.cwd();
+      const context = options.context || 'cli';
+
+      // Resolve spec (working-spec or feature spec)
+      let spec = null;
+      try {
+        const resolved = await resolveSpec({
+          specId: options.specId,
+          specFile: options.specFile,
+          warnLegacy: false,
+          interactive: false,
+        });
+        spec = resolved.spec;
+      } catch {
+        // No spec available — gates that need it will handle gracefully
+      }
+
+      // Get file list based on context
+      let stagedFiles = [];
+      const { execSync } = require('child_process');
+      if (context === 'commit') {
+        try {
+          stagedFiles = execSync('git diff --cached --name-only', {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+          })
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+        } catch {
+          /* no staged files */
+        }
+      } else if (options.file) {
+        stagedFiles = [options.file];
+      } else if (context === 'cli') {
+        // For CLI context, use all tracked files so gates can provide meaningful analysis
+        try {
+          stagedFiles = execSync('git ls-files', {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            maxBuffer: 10 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          })
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+        } catch {
+          /* not a git repo or git unavailable */
+        }
+      }
+
+      const report = await evaluateGates({ projectRoot, stagedFiles, spec, context });
+
+      // Record to working state (Phase 1 dual-write: state layer + event log)
+      if (spec && spec.id) {
+        try { recordGates(spec.id, report, context, projectRoot); } catch { /* non-fatal */ }
+
+        // EVLOG-001: emit gates_evaluated event alongside state write.
+        // Payload shape mirrors the `gates` field produced by recordGates.
+        await appendEvent(
+          {
+            actor: 'cli',
+            event: 'gates_evaluated',
+            spec_id: spec.id,
+            data: {
+              context,
+              passed: report.passed,
+              summary: report.summary || {},
+              gates: (report.gates || []).map((g) => ({
+                name: g.name,
+                status: g.status,
+                mode: g.mode,
+              })),
+            },
+          },
+          { projectRoot }
+        );
+      }
+
+      if (options.json || options.format === 'json') {
+        console.log(formatJson(report));
+      } else if (!options.quiet) {
+        // Enrich feedback on failure or --verbose (EVLOG-002: from event log)
+        if (!report.passed || options.verbose) {
+          try {
+            const state = spec?.id ? loadStateFromEvents(spec.id, { projectRoot }) : null;
+            const enrichments = enrichGateResults(report, { spec, state, projectRoot });
+            if (enrichments.size > 0) {
+              console.log(formatEnrichedText(report, enrichments));
+            } else {
+              console.log(formatText(report));
+            }
+          } catch {
+            console.log(formatText(report));
+          }
+        } else {
+          console.log(formatText(report));
+        }
+      }
+
+      // Exit with appropriate code
+      if (!report.passed) {
+        process.exit(1);
+      }
+    },
+    {
+      commandName: 'gates',
+      context: { options },
+      exitOnError: true,
+    }
+  );
+}
+
+module.exports = { gatesCommand };