@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/status.js

@@ -11,6 +11,12 @@ const chalk = require('chalk');
 // child_process removed - execSync no longer used directly
 const { safeAsync, outputResult } = require('../error-handler');
 const { parallel } = require('../utils/async-utils');
+const { resolveSpec } = require('../utils/spec-resolver');
+// 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)
@@ -30,6 +36,41 @@ async function loadWorkingSpec(specPath = '.caws/working-spec.yaml') {
   }
 }
 
+/**
+ * Resolve the primary spec for status display when explicitly targeted
+ * or when the resolver can identify a single canonical spec.
+ * Returns null when no spec can be auto-selected.
+ * @param {Object} options
+ * @returns {Promise<Object|null>}
+ */
+async function loadResolvedStatusSpec(options = {}) {
+  try {
+    const resolved = await resolveSpec({
+      specId: options.specId,
+      specFile: options.spec,
+      warnLegacy: false,
+      interactive: false,
+      quiet: Boolean(options.json),
+    });
+    return {
+      ...resolved,
+      selected: true,
+    };
+  } catch (error) {
+    if (
+      error.message === 'Spec ID required when multiple specs exist' &&
+      !options.specId &&
+      !options.spec
+    ) {
+      return null;
+    }
+    if (error.message.includes('No CAWS spec found')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
 /**
  * Load specs from the new multi-spec system
  * @returns {Promise<Array>} Array of spec objects
@@ -317,7 +358,7 @@ function getTimeSince(timestamp) {
  * @param {Object} data - Status data
  */
 function displayStatus(data) {
-  const { spec, hooks, provenance, waivers, gates } = data;
+  const { spec, specSelection, hooks, provenance, waivers, gates } = data;
 
   console.log(chalk.bold.cyan('\nCAWS Project Status'));
   console.log(chalk.cyan('==============================================\n'));
@@ -327,6 +368,9 @@ function displayStatus(data) {
     console.log(chalk.green('Working Spec'));
     console.log(chalk.gray(`   ID: ${spec.id} | Tier: ${spec.risk_tier} | Mode: ${spec.mode}`));
     console.log(chalk.gray(`   Title: ${spec.title}`));
+    if (specSelection?.specType) {
+      console.log(chalk.gray(`   Source: ${specSelection.specType} (${specSelection.specPath})`));
+    }
   } else {
     console.log(chalk.red('Working Spec'));
     console.log(chalk.gray('   No working spec found'));
@@ -335,6 +379,47 @@ function displayStatus(data) {
 
   console.log('');
 
+  // Working State (EVLOG-002: from event log)
+  if (spec && spec.id) {
+    let ws = null;
+    try { ws = loadStateFromEvents(spec.id); } catch { /* non-fatal */ }
+    if (ws && ws.phase !== 'not-started') {
+      const phaseLabels = {
+        'not-started': 'Not Started',
+        'spec-authoring': 'Spec Authoring',
+        'implementation': 'Implementation',
+        'verification': 'Verification',
+        'complete': 'Complete',
+      };
+      console.log(chalk.green('Working State'));
+      console.log(chalk.gray(`   Phase: ${phaseLabels[ws.phase] || ws.phase}`));
+      if (ws.validation) {
+        const vIcon = ws.validation.passed ? chalk.green('pass') : chalk.red('fail');
+        console.log(chalk.gray(`   Validation: ${vIcon}${ws.validation.grade ? ` (Grade ${ws.validation.grade})` : ''}`));
+      }
+      if (ws.evaluation) {
+        console.log(chalk.gray(`   Evaluation: ${ws.evaluation.percentage}% (Grade ${ws.evaluation.grade})`));
+      }
+      if (ws.gates) {
+        const gIcon = ws.gates.passed ? chalk.green('pass') : chalk.red('blocked');
+        const s = ws.gates.summary;
+        console.log(chalk.gray(`   Gates: ${gIcon} (${s.passed} pass, ${s.blocked} blocked, ${s.warned} warned)`));
+      }
+      if (ws.acceptance_criteria) {
+        const ac = ws.acceptance_criteria;
+        console.log(chalk.gray(`   ACs: ${ac.pass}/${ac.total} pass, ${ac.fail} fail, ${ac.unchecked} unchecked`));
+      }
+      if (ws.files_touched && ws.files_touched.length > 0) {
+        console.log(chalk.gray(`   Files touched: ${ws.files_touched.length}`));
+      }
+      if (ws.blockers && ws.blockers.length > 0) {
+        console.log(chalk.red(`   Blockers: ${ws.blockers.length}`));
+        ws.blockers.forEach(b => console.log(chalk.red(`      - ${b.message}`)));
+      }
+      console.log('');
+    }
+  }
+
   // Git Hooks Status
   if (hooks.installed) {
     console.log(chalk.green(`Git Hooks`));
@@ -894,14 +979,23 @@ async function statusCommand(options = {}) {
       const currentMode = await modes.getCurrentMode();
 
       // Load all status data in parallel for better performance
-      const [spec, specs, hooks, provenance, waivers, gates] = await parallel([
-        () => loadWorkingSpec(options.spec || '.caws/working-spec.yaml'),
-        () => loadSpecsFromMultiSpec(),
-        () => checkGitHooks(),
-        () => loadProvenanceChain(),
-        () => loadWaiverStatus(),
-        () => checkQualityGates(),
+      const [resolvedSpec, specs, hooks, provenance, waivers, gates] = await parallel([
+        loadResolvedStatusSpec(options),
+        loadSpecsFromMultiSpec(),
+        checkGitHooks(),
+        loadProvenanceChain(),
+        loadWaiverStatus(),
+        checkQualityGates(),
       ]);
+      const spec = resolvedSpec?.spec || null;
+      const specSelection = resolvedSpec
+        ? {
+            specPath: resolvedSpec.path
+              ? path.relative(process.cwd(), resolvedSpec.path)
+              : null,
+            specType: resolvedSpec.type,
+          }
+        : null;
 
       // Display status (visual mode if requested)
       if (options.visual || options.json) {
@@ -932,6 +1026,8 @@ async function statusCommand(options = {}) {
                   title: spec.title,
                   riskTier: spec.risk_tier,
                   mode: spec.mode,
+                  specType: specSelection?.specType || null,
+                  specPath: specSelection?.specPath || null,
                   acceptanceCriteria: spec.acceptance_criteria?.length || 0,
                   completedCriteria:
                     spec.acceptance_criteria?.filter((c) => c.completed).length || 0,
@@ -960,8 +1056,10 @@ async function statusCommand(options = {}) {
               passed: gates.passed,
               message: gates.message,
             },
+            workingState: spec && spec.id ? (loadStateFromEvents(spec.id) || null) : null,
             overallProgress: calculateOverallProgress({
               spec,
+              specSelection,
               specs,
               hooks,
               provenance,
@@ -971,6 +1069,7 @@ async function statusCommand(options = {}) {
           };
 
           console.log(JSON.stringify(result, null, 2));
+          return result;
         } else {
           // Visual output
           await displayVisualStatus(
@@ -989,6 +1088,7 @@ async function statusCommand(options = {}) {
         // Original text-based output
         displayStatus({
           spec,
+          specSelection,
           hooks,
           provenance,
           waivers,
@@ -996,6 +1096,13 @@ async function statusCommand(options = {}) {
         });
       }
 
+      if (options.json) {
+        return {
+          command: 'status',
+          mode: 'json',
+        };
+      }
+
       const result = outputResult({
         command: 'status',
         mode: options.visual ? 'visual' : options.json ? 'json' : 'text',
@@ -1027,13 +1134,14 @@ async function statusCommand(options = {}) {
       return result;
     },
     'status check',
-    true
+    !options.json
   );
 }
 
 module.exports = {
   statusCommand,
   loadWorkingSpec,
+  loadResolvedStatusSpec,
   checkGitHooks,
   loadProvenanceChain,
   loadWaiverStatus,

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/tutorial.js

@@ -115,9 +115,10 @@ Follow this proven TDD workflow:
 7. **Archive**: Complete and archive finished work
 
 Key commands:
-- \`caws progress update --criterion-id A1 --status completed\`
-- \`caws validate\` - Validate current work
-- \`caws status --visual\` - Check progress
+- \`caws validate --spec-id FEAT-001\` - Validate current work
+- \`caws status --spec-id FEAT-001\` - Check progress
+- \`caws evaluate --spec-id FEAT-001\` - Quality/readiness scoring
+- \`caws burnup --spec-id FEAT-001\` - Budget burn-up report
 - \`caws archive <change-id>\` - Complete work
         `,
         action: 'Try: caws status --visual',
@@ -235,18 +236,18 @@ Let's get you started!
 First, ensure CAWS is properly initialized:
 
 1. Initialize CAWS: \`caws init .\`
-2. Choose your complexity mode: \`caws mode set --interactive\`
+2. Create a feature spec: \`caws specs create FEAT-001 --type feature --title "My Feature"\`
 3. Set up git hooks: \`caws hooks install\`
 4. Initialize provenance: \`caws provenance init\`
 
 For existing projects, use: \`caws scaffold\`
 
-Choose a mode that fits your project:
-- Simple: Small projects, quick prototyping
-- Standard: Most teams and projects
-- Enterprise: Large teams, compliance requirements
+All commands support \`--spec-id\` to target a specific feature spec:
+- \`caws validate --spec-id FEAT-001\`
+- \`caws status --spec-id FEAT-001\`
+- \`caws evaluate --spec-id FEAT-001\`
         `,
-        action: 'Try: caws mode current',
+        action: 'Try: caws specs list',
         verify: 'mode_setup',
       },
       {

package/dist/commands/validate.js

@@ -14,7 +14,14 @@ const {
 } = require('../validation/spec-validation');
 
 // Import spec resolution system
-const { resolveSpec, suggestMigration } = require('../utils/spec-resolver');
+const {
+  resolveSpec,
+  suggestMigration,
+  loadSpecsRegistry,
+} = require('../utils/spec-resolver');
+const { recordValidation } = require('../utils/working-state');
+const { appendEvent } = require('../utils/event-log');
+const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
 
 /**
  * Validate command handler
@@ -75,12 +82,14 @@ async function validateCommand(specFile, options = {}) {
       // Check scope conflicts (if multiple specs exist)
       const { checkMultiSpecStatus } = require('../utils/spec-resolver');
       const multiSpecStatus = await checkMultiSpecStatus();
+      const registry =
+        multiSpecStatus.registry ||
+        await loadSpecsRegistry();
+      const specIds = Object.keys(registry.specs || {});
 
-      if (multiSpecStatus.specCount > 1) {
+      if (specIds.length > 1) {
         const { checkScopeConflicts } = require('../utils/spec-resolver');
-        const conflicts = await checkScopeConflicts(
-          Object.keys(multiSpecStatus.registry?.specs || {})
-        );
+        const conflicts = await checkScopeConflicts(specIds);
 
         if (conflicts.length > 0) {
           const myConflicts = conflicts.filter((c) => c.spec1 === spec.id || c.spec2 === spec.id);
@@ -135,6 +144,60 @@ async function validateCommand(specFile, options = {}) {
 
     const finalResult = enhancedValidation;
 
+    // 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 {
+      const grade = finalResult.complianceScore !== undefined
+        ? getComplianceGrade(finalResult.complianceScore)
+        : null;
+      if (finalResult.valid) {
+        lifecycle.emit(EVENTS.VALIDATION_PASSED, {
+          specId: spec.id, grade, complianceScore: finalResult.complianceScore,
+          timestamp: new Date().toISOString(),
+        });
+      } else {
+        lifecycle.emit(EVENTS.VALIDATION_FAILED, {
+          specId: spec.id, errors: finalResult.errors || [],
+          errorCount: (finalResult.errors || []).length,
+          warningCount: (finalResult.warnings || []).length,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch { /* non-fatal */ }
+
     // Format output based on requested format
     if (options.format === 'json') {
       // Structured JSON output matching CAWSValidationResult
@@ -236,7 +299,8 @@ async function validateCommand(specFile, options = {}) {
     if (error.message === 'Spec ID required when multiple specs exist' && !options.specId) {
       const { checkMultiSpecStatus } = require('../utils/spec-resolver');
       const status = await checkMultiSpecStatus();
-      const specIds = Object.keys(status.registry?.specs || {});
+      const registry = status.registry || await loadSpecsRegistry();
+      const specIds = Object.keys(registry.specs || {});
 
       if (specIds.length === 0) {
         console.error(chalk.red('No specs found in registry'));

package/dist/commands/verify-acs.js

@@ -7,13 +7,12 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { execFileSync } = require('child_process');
 const { findProjectRoot } = require('../utils/detection');
-
-const SPECS_DIR = '.caws/specs';
-const TERMINAL_STATUSES = new Set(['completed', 'closed', 'archived']);
+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.
@@ -318,55 +317,6 @@ function verifySpec(spec, projectRoot, options = {}) {
   };
 }
 
-/**
- * Load all active specs from .caws/specs/
- * @param {string} projectRoot
- * @param {string} [targetSpecId] - If provided, only load this spec
- * @returns {Array<{path: string, spec: Object}>}
- */
-function loadSpecs(projectRoot, targetSpecId) {
-  const specs = [];
-  const specsDir = path.join(projectRoot, SPECS_DIR);
-
-  if (targetSpecId) {
-    const specPath = path.join(specsDir, `${targetSpecId}.yaml`);
-    if (!fs.existsSync(specPath)) {
-      const ymlPath = path.join(specsDir, `${targetSpecId}.yml`);
-      if (!fs.existsSync(ymlPath)) {
-        throw new Error(`Spec '${targetSpecId}' not found at ${specPath}`);
-      }
-      specs.push({ path: ymlPath, spec: yaml.load(fs.readFileSync(ymlPath, 'utf8')) });
-    } else {
-      specs.push({ path: specPath, spec: yaml.load(fs.readFileSync(specPath, 'utf8')) });
-    }
-    return specs;
-  }
-
-  // Also check working-spec.yaml
-  const workingSpec = path.join(projectRoot, '.caws/working-spec.yaml');
-  if (fs.existsSync(workingSpec)) {
-    try {
-      const s = yaml.load(fs.readFileSync(workingSpec, 'utf8'));
-      if (s && !TERMINAL_STATUSES.has(s.status)) {
-        specs.push({ path: workingSpec, spec: s });
-      }
-    } catch (_) { /* ignore unreadable config */ }
-  }
-
-  if (fs.existsSync(specsDir)) {
-    for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
-      try {
-        const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
-        if (s && !TERMINAL_STATUSES.has(s.status)) {
-          specs.push({ path: path.join(specsDir, f), spec: s });
-        }
-      } catch (_) { /* ignore unreadable config */ }
-    }
-  }
-
-  return specs;
-}
-
 /**
  * Main command handler
  */
@@ -379,33 +329,51 @@ async function verifyAcsCommand(options = {}) {
     process.exit(1);
   }
 
-  const specs = loadSpecs(projectRoot, options.specId);
-
-  if (specs.length === 0) {
-    console.log(chalk.yellow('No active specs found.'));
-    return;
-  }
+  const resolved = await resolveSpec({
+    specId: options.specId,
+    warnLegacy: false,
+  });
 
   const allResults = [];
   let totalAcs = 0, totalMechanical = 0, totalPass = 0, totalFail = 0, totalUnchecked = 0;
+  const result = verifySpec(resolved.spec, projectRoot, {
+    run: options.run || false,
+    runner: options.runner,
+  });
+  result.path = resolved.path;
+  result.type = resolved.type;
+  allResults.push(result);
+
+  for (const r of result.results) {
+    totalAcs++;
+    if (r.status === 'PASS') { totalPass++; totalMechanical++; }
+    else if (r.status === 'FAIL') { totalFail++; totalMechanical++; }
+    else { totalUnchecked++; }
+  }
 
-  for (const { spec } of specs) {
-    const acs = extractACs(spec);
-    if (acs.length === 0) continue;
-
-    const result = verifySpec(spec, projectRoot, {
-      run: options.run || false,
-      runner: options.runner,
-    });
-    allResults.push(result);
+  // 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 */ }
+  }
 
-    // Tally
-    for (const r of result.results) {
-      totalAcs++;
-      if (r.status === 'PASS') { totalPass++; totalMechanical++; }
-      else if (r.status === 'FAIL') { totalFail++; totalMechanical++; }
-      else { totalUnchecked++; }
-    }
+  // 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
@@ -421,7 +389,11 @@ async function verifyAcsCommand(options = {}) {
   // Table output
   for (const result of allResults) {
     console.log(chalk.cyan(`\n## ${result.specId} — ${result.title}`));
-    console.log(chalk.gray(`   Test runner: ${result.runner} | Mode: ${options.run ? 'run' : 'collect-only'}`));
+    console.log(
+      chalk.gray(
+        `   Test runner: ${result.runner} | Mode: ${options.run ? 'run' : 'collect-only'} | Spec: ${result.type} -> ${result.path}`
+      )
+    );
     console.log();
 
     const widths = { id: 8, desc: 40, method: 14, status: 10 };