@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/commands/status.js

@@ -11,6 +11,8 @@ 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');
+const { loadState } = require('../utils/working-state');
 
 /**
  * Load working specification (legacy single file approach)
@@ -30,6 +32,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 +354,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 +364,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 +375,47 @@ function displayStatus(data) {
 
   console.log('');
 
+  // Working State
+  if (spec && spec.id) {
+    let ws = null;
+    try { ws = loadState(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 +975,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 +1022,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 +1052,10 @@ async function statusCommand(options = {}) {
               passed: gates.passed,
               message: gates.message,
             },
+            workingState: spec && spec.id ? (loadState(spec.id) || null) : null,
             overallProgress: calculateOverallProgress({
               spec,
+              specSelection,
               specs,
               hooks,
               provenance,
@@ -971,6 +1065,7 @@ async function statusCommand(options = {}) {
           };
 
           console.log(JSON.stringify(result, null, 2));
+          return result;
         } else {
           // Visual output
           await displayVisualStatus(
@@ -989,6 +1084,7 @@ async function statusCommand(options = {}) {
         // Original text-based output
         displayStatus({
           spec,
+          specSelection,
           hooks,
           provenance,
           waivers,
@@ -996,6 +1092,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 +1130,14 @@ async function statusCommand(options = {}) {
       return result;
     },
     'status check',
-    true
+    !options.json
   );
 }
 
 module.exports = {
   statusCommand,
   loadWorkingSpec,
+  loadResolvedStatusSpec,
   checkGitHooks,
   loadProvenanceChain,
   loadWaiverStatus,

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,13 @@ 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 { lifecycle, EVENTS } = require('../utils/lifecycle-events');
 
 /**
  * Validate command handler
@@ -75,12 +81,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 +143,40 @@ 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 */ }
+
+    // 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 +278,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,11 @@
 
 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');
 
 /**
  * Detect the project's test runner from config files.
@@ -318,55 +316,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,35 +328,39 @@ 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;
-
-  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);
-
-    // Tally
-    for (const r of result.results) {
-      totalAcs++;
-      if (r.status === 'PASS') { totalPass++; totalMechanical++; }
-      else if (r.status === 'FAIL') { totalFail++; totalMechanical++; }
-      else { totalUnchecked++; }
-    }
+  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++; }
   }
 
+  // Record to working state
+  try {
+    recordACVerification(resolved.spec.id, {
+      total: totalAcs,
+      pass: totalPass,
+      fail: totalFail,
+      unchecked: totalUnchecked,
+      results: result.results,
+    }, projectRoot);
+  } catch { /* non-fatal */ }
+
   // Output
   if (options.format === 'json') {
     console.log(JSON.stringify({
@@ -421,7 +374,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 };

package/dist/commands/waivers.js

@@ -13,6 +13,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
+const { getAgentSessionId } = require('../utils/agent-session');
 const WaiversManager = require('../waivers-manager');
 const { commandWrapper, Output } = require('../utils/command-wrapper');
 
@@ -24,16 +25,12 @@ const WAIVER_DIR = '.caws/waivers';
  * within the check-*.mjs files.
  */
 const VALID_GATES = [
-  'naming',
-  'code_freeze',
-  'duplication',
-  'duplication_gate',
-  'god_objects',
-  'placeholders',
-  'simplification',
-  'hidden-todo',
-  'documentation',
-  '*',
+  'budget_limit',
+  'spec_completeness',
+  'scope_boundary',
+  'god_object',
+  'todo_detection',
+  '*',  // wildcard — waiver applies to all gates
 ];
 
 /**
@@ -49,7 +46,7 @@ async function waiversCommand(subcommand = 'list', options = {}) {
       const setup = initializeGlobalSetup();
 
       if (setup.hasWorkingSpec) {
-        Output.success(`Detected ${setup.setupType} CAWS setup`, {
+        Output.success(`Detected ${setup.type} CAWS setup`, {
           capabilities: setup.capabilities,
         });
       }
@@ -138,6 +135,24 @@ async function createWaiver(options) {
     process.exit(1);
   }
 
+  // Self-approval prevention: creator cannot be approver
+  // Uses strict equality — the previous .includes() check was an asymmetric
+  // substring match that produced false positives (blocking legitimate approvers
+  // whose name happened to contain the session ID) while missing the reverse
+  // case (approver is a prefix of the session ID).
+  // When CLAUDE_SESSION_ID is unset or empty, we can't identify the creator,
+  // so self-approval prevention is skipped ('' || null → null → falsy guard).
+  const creatorSession = getAgentSessionId(process.cwd());
+  if (creatorSession && options.approvedBy) {
+    if (options.approvedBy === creatorSession) {
+      throw new Error(
+        'Waiver creator cannot be the approver.\n' +
+        'A different agent or human must approve this waiver.\n' +
+        `Creator session: ${creatorSession}`
+      );
+    }
+  }
+
   // Generate waiver ID
   const waiverId = `WV-${Date.now().toString().slice(-4)}`;
   const timestamp = new Date().toISOString();
@@ -155,8 +170,27 @@ async function createWaiver(options) {
     impact_level: options.impactLevel,
     mitigation_plan: options.mitigationPlan,
     status: 'active',
+    created_by_session: creatorSession,
   };
 
+  // Validate waiver against schema before persisting
+  try {
+    const { createValidator, getSchemaPath } = require('../utils/schema-validator');
+    const schemaPath = getSchemaPath('waivers.schema.json', process.cwd());
+    const validate = createValidator(schemaPath);
+    // waivers.schema.json uses patternProperties keyed by waiver ID
+    const waiverDoc = { [waiverId]: waiver };
+    const result = validate(waiverDoc);
+    if (!result.valid) {
+      console.warn(chalk.yellow('Waiver has schema violations:'));
+      result.errors.forEach((err) => {
+        console.warn(chalk.yellow(`  ${err.instancePath}: ${err.message}`));
+      });
+    }
+  } catch (schemaErr) {
+    // Non-fatal — don't block waiver creation on schema issues
+  }
+
   // Save individual waiver file
   const waiverPath = path.join(process.cwd(), WAIVER_DIR, `${waiverId}.yaml`);
   fs.writeFileSync(waiverPath, yaml.dump(waiver, { lineWidth: -1 }));
@@ -198,9 +232,32 @@ async function listWaivers(_options) {
     return;
   }
 
+  // Load a schema validator once for all waiver files (if available)
+  let waiverValidate = null;
+  try {
+    const { createValidator, getSchemaPath } = require('../utils/schema-validator');
+    const schemaPath = getSchemaPath('waivers.schema.json', process.cwd());
+    waiverValidate = createValidator(schemaPath);
+  } catch {
+    // Schema not available — skip validation
+  }
+
   const waivers = waiverFiles.map((file) => {
     const content = fs.readFileSync(path.join(waiversDir, file), 'utf8');
-    return yaml.load(content);
+    const waiver = yaml.load(content);
+
+    // Validate each loaded waiver against schema
+    if (waiverValidate && waiver && waiver.id) {
+      const result = waiverValidate({ [waiver.id]: waiver });
+      if (!result.valid) {
+        console.warn(chalk.yellow(`Schema warning for ${file}:`));
+        result.errors.forEach((err) => {
+          console.warn(chalk.yellow(`  ${err.instancePath}: ${err.message}`));
+        });
+      }
+    }
+
+    return waiver;
   });
 
   // Filter by status