@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/init.js

@@ -8,6 +8,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const inquirer = require('inquirer');
 const chalk = require('chalk');
+const yaml = require('js-yaml');
 
 // Import shared utilities
 const { detectCAWSSetup } = require('../utils/detection');
@@ -27,6 +28,119 @@ const {
   getRecommendedIDEs,
   parseIDESelection,
 } = require('../utils/ide-detection');
+// CAWSFIX-10: share the canonical spec-ID regex with the validator
+const { SPEC_ID_PATTERN } = require('../validation/spec-validation');
+
+function buildInitialFeatureSpec(specContent, fallbackId) {
+  const parsed = yaml.load(specContent);
+  const riskTier =
+    typeof parsed.risk_tier === 'string'
+      ? parseInt(parsed.risk_tier.replace(/^T/i, ''), 10) || 3
+      : parsed.risk_tier || 3;
+  const aiConfidenceRaw = parsed.ai_assessment?.confidence_level;
+  const aiConfidence =
+    typeof aiConfidenceRaw === 'number' && aiConfidenceRaw <= 1
+      ? Math.max(1, Math.min(10, Math.round(aiConfidenceRaw * 10)))
+      : typeof aiConfidenceRaw === 'number'
+        ? Math.max(1, Math.min(10, Math.round(aiConfidenceRaw)))
+        : 8;
+  const normalizedContracts =
+    Array.isArray(parsed.contracts) && parsed.contracts.length > 0
+      ? parsed.contracts.map((contract, index) => ({
+          type: ['openapi', 'graphql', 'proto', 'pact'].includes(contract?.type)
+            ? contract.type
+            : 'openapi',
+          path:
+            contract?.path ||
+            (index === 0 ? 'docs/api/initial-feature.yaml' : `docs/api/contract-${index + 1}.yaml`),
+        }))
+      : riskTier <= 2
+        ? [{ type: 'openapi', path: 'docs/api/initial-feature.yaml' }]
+        : [];
+
+  return {
+    id: parsed.id || fallbackId,
+    title: parsed.title || 'New CAWS Project',
+    risk_tier: riskTier,
+    mode: parsed.mode || 'feature',
+    blast_radius: parsed.blast_radius || { modules: ['src', 'tests'], data_migration: false },
+    operational_rollback_slo: parsed.operational_rollback_slo || '5m',
+    scope: parsed.scope || {
+      in: ['src/', 'tests/'],
+      out: ['node_modules/', 'dist/', 'build/'],
+    },
+    invariants: Array.isArray(parsed.invariants) && parsed.invariants.length > 0
+      ? parsed.invariants
+      : ['System maintains data consistency'],
+    acceptance: Array.isArray(parsed.acceptance) && parsed.acceptance.length > 0
+      ? parsed.acceptance
+      : [
+          {
+            id: 'A1',
+            given: 'Current system state',
+            when: 'the initial project is bootstrapped',
+            then: 'the CAWS project should validate successfully',
+          },
+        ],
+    non_functional: parsed.non_functional || {
+      a11y: ['keyboard'],
+      perf: { api_p95_ms: 250 },
+      security: [],
+    },
+    contracts: normalizedContracts,
+    observability: parsed.observability || { logs: [], metrics: [], traces: [] },
+    migrations: Array.isArray(parsed.migrations) ? parsed.migrations : [],
+    rollback: Array.isArray(parsed.rollback) ? parsed.rollback : [],
+    ai_assessment: {
+      confidence_level: aiConfidence,
+      uncertainty_areas: Array.isArray(parsed.ai_assessment?.uncertainty_areas)
+        ? parsed.ai_assessment.uncertainty_areas
+        : [],
+      recommended_pairing:
+        parsed.ai_assessment?.recommended_pairing !== undefined
+          ? Boolean(parsed.ai_assessment.recommended_pairing)
+          : aiConfidence <= 6,
+    },
+  };
+}
+
+async function writeInitialSpecArtifacts(specContent, fallbackId) {
+  const canonicalSpec = buildInitialFeatureSpec(specContent, fallbackId);
+  const now = new Date().toISOString();
+  const canonicalContent = yaml.dump(canonicalSpec, { indent: 2 });
+  const specsDir = path.join('.caws', 'specs');
+  const featureSpecPath = path.join(specsDir, `${canonicalSpec.id}.yaml`);
+  const workingSpecPath = path.join('.caws', 'working-spec.yaml');
+  const registryPath = path.join(specsDir, 'registry.json');
+
+  await fs.ensureDir(specsDir);
+  await fs.writeFile(featureSpecPath, canonicalContent);
+  await fs.writeFile(workingSpecPath, canonicalContent);
+  await fs.writeJson(
+    registryPath,
+    {
+      version: '1.0.0',
+      specs: {
+        [canonicalSpec.id]: {
+          path: `${canonicalSpec.id}.yaml`,
+          type: 'feature',
+          status: 'active',
+          created_at: now,
+          updated_at: now,
+          owner: null,
+        },
+      },
+      lastUpdated: now,
+    },
+    { spaces: 2 }
+  );
+
+  return {
+    canonicalSpec,
+    featureSpecPath,
+    workingSpecPath,
+  };
+}
 
 /**
  * Initialize a new project with CAWS
@@ -407,11 +521,12 @@ async function initProject(projectName, options) {
             return `PROJ-${randomNum.toString().padStart(3, '0')}`;
           },
           validate: (input) => {
-            if (!input.match(/^[A-Z]+-\d+$/)) {
-              return 'Project ID must be in format PREFIX-NUMBER (e.g., PROJ-001)';
+            // CAWSFIX-10: accept multi-segment IDs like P03-IMPL-01
+            if (!SPEC_ID_PATTERN.test(input)) {
+              return 'Project ID must be in format PREFIX-NUMBER or PREFIX-SEGMENT-NUMBER (e.g., PROJ-001, P03-IMPL-01)';
             }
-            if (input.length > 20) {
-              return 'Project ID must be less than 20 characters';
+            if (input.length > 40) {
+              return 'Project ID must be less than 40 characters';
             }
             return true;
           },
@@ -492,10 +607,12 @@ async function initProject(projectName, options) {
       console.log(chalk.blue('\nGenerating CAWS working spec...'));
       const specContent = generateWorkingSpec(answers);
 
-      // Write working spec
+      // Write canonical feature spec plus legacy compatibility mirror
       await fs.ensureDir('.caws');
-      await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
+      const initialSpec = await writeInitialSpecArtifacts(specContent, answers.projectId);
+      console.log(chalk.green(`Created ${initialSpec.featureSpecPath}`));
       console.log(chalk.green('Created .caws/working-spec.yaml'));
+      console.log(chalk.green('Created .caws/specs/registry.json'));
 
       // Optionally create policy.yaml (optional - defaults work fine)
       const policyPath = path.join('.caws', 'policy.yaml');
@@ -503,7 +620,6 @@ async function initProject(projectName, options) {
         const { PolicyManager } = require('../policy/PolicyManager');
         const policyManager = new PolicyManager();
         const defaultPolicy = policyManager.getDefaultPolicy();
-        const yaml = require('js-yaml');
         const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
         await fs.writeFile(policyPath, policyContent);
         console.log(chalk.green('Created .caws/policy.yaml (optional - defaults work fine)'));
@@ -522,10 +638,20 @@ ${answers.projectDescription}
 ## Risk Tier: ${answers.riskTier === 1 ? 'High (T1)' : answers.riskTier === 2 ? 'Medium (T2)' : 'Low (T3)'}
 
 ## Next Steps
-1. Review and customize \`.caws/working-spec.yaml\`
+1. Review and customize \`.caws/specs/${answers.projectId}.yaml\`
 2. Set up your development environment
 3. Implement features according to the spec
-4. Run \`caws validate\` to check your progress
+4. Run \`caws validate --spec-id ${answers.projectId}\` to check your progress
+
+## Multi-Agent Recommendation
+The initial project spec is also available in \`.caws/specs/${answers.projectId}.yaml\`.
+For multi-agent work, treat feature specs in \`.caws/specs/\` as canonical and use
+\`.caws/working-spec.yaml\` only as a compatibility mirror:
+
+\`\`\`bash
+caws specs create my-feature --type feature --title "My Feature"
+caws validate --spec-id my-feature
+\`\`\`
 
 ## Quality Gates
 - **Coverage**: ${answers.riskTier === 1 ? '90%+' : answers.riskTier === 2 ? '80%+' : '70%+'}
@@ -584,7 +710,7 @@ Happy coding! `;
         projectTitle: path.basename(process.cwd()),
         projectDescription: `A ${detectedType} project managed with CAWS`,
         riskTier: 2,
-        projectId: `PROJ-${Math.floor(Math.random() * 1000) + 1}`,
+        projectId: `PROJ-${String(Math.floor(Math.random() * 1000) + 1).padStart(3, '0')}`,
         useCursorHooks: true,
         generateExamples: false,
         projectMode: 'feature',
@@ -624,8 +750,10 @@ Happy coding! `;
 
       const specContent = generateWorkingSpec(defaultAnswers);
       await fs.ensureDir('.caws');
-      await fs.writeFile(path.join('.caws', 'working-spec.yaml'), specContent);
+      const initialSpec = await writeInitialSpecArtifacts(specContent, defaultAnswers.projectId);
+      console.log(chalk.green(`Created ${initialSpec.featureSpecPath}`));
       console.log(chalk.green('Created .caws/working-spec.yaml'));
+      console.log(chalk.green('Created .caws/specs/registry.json'));
 
       // Optionally create policy.yaml (optional - defaults work fine)
       const policyPath = path.join('.caws', 'policy.yaml');
@@ -633,7 +761,6 @@ Happy coding! `;
         const { PolicyManager } = require('../policy/PolicyManager');
         const policyManager = new PolicyManager();
         const defaultPolicy = policyManager.getDefaultPolicy();
-        const yaml = require('js-yaml');
         const policyContent = yaml.dump(defaultPolicy, { indent: 2 });
         await fs.writeFile(policyPath, policyContent);
         console.log(chalk.green('Created .caws/policy.yaml (optional - defaults work fine)'));
@@ -670,8 +797,10 @@ Happy coding! `;
     // Success message
     console.log(chalk.green('\nCAWS project initialized successfully!'));
     console.log(chalk.blue('\nNext steps:'));
-    console.log('1. Review .caws/working-spec.yaml');
-    console.log('2. Customize the specification for your needs');
+    console.log('1. Review .caws/specs/<spec-id>.yaml');
+    console.log('2. Treat .caws/working-spec.yaml as the compatibility mirror, not the long-term source of truth');
+    console.log('3. If multiple agents will collaborate, create more feature specs with `caws specs create <id>`');
+    console.log('4. Use `--spec-id` on validation/status/diagnose commands for feature work');
 
     // Show contract requirements if Tier 1 or 2
     // Use answers if available (interactive mode), otherwise default to 2
@@ -688,16 +817,18 @@ Happy coding! `;
     }
 
     console.log('\nRecommended Setup Workflow:');
-    console.log('   1. Review .caws/working-spec.yaml');
+    console.log('   1. Review .caws/specs/<spec-id>.yaml');
     console.log('   2. Run: caws scaffold (adds tools and templates)');
-    console.log('   3. Run: caws validate (verify setup)');
-    console.log('   4. Run: caws diagnose (check health)');
-    console.log('   5. Optional: Create .caws/policy.yaml for custom budgets');
+    console.log('   3. For multi-agent work, run: caws specs create <feature-id>');
+    console.log('   4. Run: caws validate --spec-id <spec-id> (verify setup)');
+    console.log('   5. Run: caws diagnose --spec-id <spec-id> (check health)');
+    console.log('   6. Optional: Create .caws/policy.yaml for custom budgets');
     const finalIDEs = answers?.selectedIDEs || [];
     if (finalIDEs.includes('cursor') || finalIDEs.includes('claude') || options.interactive === false) {
-      console.log('   6. Restart your IDE to activate quality gates');
+      console.log('   7. Restart your IDE to activate quality gates');
     }
     console.log('\nQuick start: caws scaffold && caws validate && caws diagnose');
+    console.log('Multi-agent quick start: caws specs create my-feature && caws validate --spec-id my-feature');
   } catch (error) {
     console.error(chalk.red('Error during initialization:'), error.message);
     if (error.stack) {

package/dist/commands/iterate.js

@@ -14,6 +14,11 @@ const { initializeGlobalSetup } = require('../config');
 
 // Import spec resolution system
 const { resolveSpec } = require('../utils/spec-resolver');
+// EVLOG-002 Phase 2 read flip: iterate reads from the event log instead of
+// the state layer. loadStateFromEvents matches loadState's contract exactly
+// (returns null for specs with no events), so the `workingState &&` guard
+// below stays correct without code changes.
+const { loadStateFromEvents } = require('../utils/event-renderer');
 
 /**
  * Iterate command handler
@@ -21,12 +26,12 @@ const { resolveSpec } = require('../utils/spec-resolver');
  * @param {string} specFile - Path to working spec file
  * @param {object} options - Command options
  */
-async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}) {
+async function iterateCommand(specFile, options = {}) {
   try {
     // Resolve spec using priority system
     const resolved = await resolveSpec({
       specId: options.specId,
-      specFile,
+      specFile: specFile || undefined,
       warnLegacy: false,
     });
 
@@ -36,12 +41,19 @@ async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}
     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(', ')}`);
     }
 
     // Parse current state from options
-    const currentState = options.currentState ? JSON.parse(options.currentState) : {};
+    let currentState = {};
+    if (options.currentState) {
+      try {
+        currentState = JSON.parse(options.currentState);
+      } catch {
+        console.error('Invalid JSON in --current-state. Using defaults.');
+      }
+    }
     const stateDescription = currentState.description || 'Starting implementation';
 
     console.log(chalk.blue('\nIterative Development Guidance\n'));
@@ -50,9 +62,48 @@ async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}
     console.log(`ID: ${spec.id} | Tier: ${spec.risk_tier} | Mode: ${spec.mode}`);
     console.log(`Current State: ${stateDescription}\n`);
 
+    // Load working state for evidence-based guidance (EVLOG-002: from event log)
+    let workingState = null;
+    try { workingState = loadStateFromEvents(spec.id); } catch { /* non-fatal */ }
+
     // Analyze progress based on mode
     const guidance = generateGuidance(spec, currentState, options);
 
+    // If working state exists, overlay evidence-based data
+    if (workingState && workingState.phase !== 'not-started') {
+      guidance.phase = formatPhase(workingState.phase);
+
+      // Build evidence-based completed steps
+      const evidence = [];
+      if (workingState.validation && workingState.validation.passed) {
+        evidence.push(`Validation passed (Grade ${workingState.validation.grade || '?'})`);
+      }
+      if (workingState.evaluation) {
+        evidence.push(`Evaluation: ${workingState.evaluation.percentage}% (Grade ${workingState.evaluation.grade})`);
+      }
+      if (workingState.gates && workingState.gates.passed) {
+        evidence.push(`All gates passing (last run: ${workingState.gates.context} context)`);
+      }
+      if (workingState.acceptance_criteria) {
+        const ac = workingState.acceptance_criteria;
+        evidence.push(`AC verification: ${ac.pass}/${ac.total} pass, ${ac.fail} fail, ${ac.unchecked} unchecked`);
+      }
+      if (workingState.files_touched && workingState.files_touched.length > 0) {
+        evidence.push(`${workingState.files_touched.length} file(s) touched`);
+      }
+      if (evidence.length > 0) {
+        guidance.completed = evidence;
+      }
+
+      // Overlay blockers and next actions from state
+      if (workingState.blockers && workingState.blockers.length > 0) {
+        guidance.blockers = workingState.blockers.map(b => b.message);
+      }
+      if (workingState.next_actions && workingState.next_actions.length > 0) {
+        guidance.nextActions = workingState.next_actions;
+      }
+    }
+
     // Display guidance
     console.log(chalk.blue('Current Phase:\n'));
     console.log(`   ${guidance.phase}\n`);
@@ -72,6 +123,18 @@ async function iterateCommand(specFile = '.caws/working-spec.yaml', options = {}
       guidance.blockers.forEach((blocker) => {
         console.log(chalk.red(`   ${blocker}`));
       });
+
+      // Show quality gap summary if sidecars available
+      try {
+        const { diagnoseQualityGaps } = require('../sidecars');
+        if (workingState) {
+          const gapResult = diagnoseQualityGaps(workingState, spec);
+          if (gapResult.data && gapResult.data.gaps && gapResult.data.gaps.length > 0) {
+            console.log(chalk.yellow(`\n   Quality gaps: ${gapResult.data.summary}`));
+            console.log(chalk.yellow('   Run: caws sidecar gaps --spec-id ' + spec.id));
+          }
+        }
+      } catch { /* sidecars not available — non-fatal */ }
     }
 
     console.log(chalk.blue('\nRecommendations:\n'));
@@ -337,4 +400,18 @@ function getQualityGates(riskTier) {
   return gates[riskTier] || gates[2];
 }
 
+/**
+ * Format phase slug into human-readable label
+ */
+function formatPhase(phase) {
+  const labels = {
+    'not-started': 'Not Started',
+    'spec-authoring': 'Spec Authoring',
+    'implementation': 'Implementation',
+    'verification': 'Verification',
+    'complete': 'Complete',
+  };
+  return labels[phase] || phase;
+}
+
 module.exports = { iterateCommand };

package/dist/commands/parallel.js

@@ -128,6 +128,10 @@ function handleStatus() {
     const statusColor =
       agent.status === 'active'
         ? chalk.green
+        : agent.status === 'fresh'
+        ? chalk.cyan
+        : agent.status === 'merged'
+        ? chalk.blue
         : agent.status === 'missing'
         ? chalk.red
         : chalk.yellow;

package/dist/commands/plan.js

@@ -10,7 +10,7 @@ const chalk = require('chalk');
 const { safeAsync, outputResult } = require('../error-handler');
 
 // Import spec resolution system
-const { resolveSpec } = require('../utils/spec-resolver');
+const { resolveSpec, loadSpecsRegistry } = require('../utils/spec-resolver');
 
 /**
  * Plan templates for different spec types
@@ -86,15 +86,11 @@ const PLAN_TEMPLATES = {
  * @returns {Promise<Object|null>} Spec data or null
  */
 async function loadSpecForPlanning(specId) {
-  try {
-    const resolved = await resolveSpec({
-      specId,
-      warnLegacy: false,
-    });
-    return resolved.spec;
-  } catch (error) {
-    return null;
-  }
+  const resolved = await resolveSpec({
+    specId,
+    warnLegacy: false,
+  });
+  return resolved.spec;
 }
 
 /**
@@ -398,21 +394,18 @@ async function planCommand(action, options = {}) {
 
             if (status.specCount === 1) {
               // Use the single spec automatically
-              const registry = await require('../utils/spec-resolver').loadSpecsRegistry();
+              const registry = await loadSpecsRegistry();
               const singleSpecId = Object.keys(registry.specs)[0];
               console.log(chalk.blue(`Auto-detected single spec: ${singleSpecId}`));
 
               const spec = await loadSpecForPlanning(singleSpecId);
-              if (!spec) {
-                throw new Error(`Auto-detected spec '${singleSpecId}' could not be loaded`);
-              }
-
               await generateAndDisplayPlan(spec, singleSpecId, options);
             } else if (status.specCount > 1) {
+              const registry = await loadSpecsRegistry();
               throw new Error(
                 'Multiple specs detected. Please specify which one: caws plan generate --spec-id <id>\n' +
                   'Available specs: ' +
-                  Object.keys(status.registry?.specs || {}).join(', ')
+                  Object.keys(registry.specs || {}).join(', ')
               );
             } else {
               throw new Error('No specs found. Create a spec first: caws specs create <id>');
@@ -420,9 +413,6 @@ async function planCommand(action, options = {}) {
           } else {
             // Load spec for planning
             const spec = await loadSpecForPlanning(specId);
-            if (!spec) {
-              throw new Error(`Spec '${specId}' not found`);
-            }
 
             return await generateAndDisplayPlan(spec, specId, options);
           }

package/dist/commands/provenance.js

@@ -12,6 +12,41 @@ const crypto = require('crypto');
 const yaml = require('js-yaml');
 const { execSync } = require('child_process');
 const { commandWrapper } = require('../utils/command-wrapper');
+const { resolveSpec } = require('../utils/spec-resolver');
+
+async function resolveProvenanceSpec(options = {}) {
+  try {
+    return await resolveSpec({
+      specId: options.specId,
+      specFile: options.specFile,
+      warnLegacy: false,
+    });
+  } catch (error) {
+    const shouldFallbackToLegacy =
+      !options.specId &&
+      !options.specFile &&
+      error.message.includes('schema violations');
+
+    if (!shouldFallbackToLegacy) {
+      throw error;
+    }
+
+    const legacyPath = path.join(process.cwd(), '.caws', 'working-spec.yaml');
+    if (!(await fs.pathExists(legacyPath))) {
+      throw error;
+    }
+
+    const legacyContent = await fs.readFile(legacyPath, 'utf8');
+    const legacySpec = yaml.load(legacyContent);
+
+    return {
+      path: legacyPath,
+      type: 'legacy',
+      spec: legacySpec,
+      degradedValidation: true,
+    };
+  }
+}
 
 /**
  * Get quality gates status from saved report
@@ -90,14 +125,8 @@ async function updateProvenance(options) {
   // Ensure output directory exists
   await fs.ensureDir(output);
 
-  // Load current working spec
-  const specPath = '.caws/working-spec.yaml';
-  if (!(await fs.pathExists(specPath))) {
-    throw new Error('Working spec not found - not in CAWS project');
-  }
-
-  const specContent = await fs.readFile(specPath, 'utf8');
-  const spec = yaml.load(specContent);
+  const resolved = await resolveProvenanceSpec(options);
+  const spec = resolved.spec;
 
   // Load existing provenance chain
   const provenanceChain = await loadProvenanceChain(output);
@@ -116,6 +145,9 @@ async function updateProvenance(options) {
       title: spec.title,
       risk_tier: spec.risk_tier,
       mode: spec.mode,
+      type: resolved.type,
+      path: resolved.path,
+      status: spec.status || null,
       waiver_ids: spec.waiver_ids || [],
     },
     quality_gates: getQualityGatesStatus(),
@@ -148,6 +180,10 @@ async function updateProvenance(options) {
 
   if (!quiet) {
     console.log(`Provenance updated for commit ${commit.substring(0, 8)}`);
+    console.log(`   Spec: ${spec.id} (${resolved.type}) -> ${resolved.path}`);
+    if (resolved.degradedValidation) {
+      console.log('   Note: using legacy spec metadata despite schema validation issues');
+    }
     console.log(`   Chain length: ${provenanceChain.length} entries`);
     console.log(`   Hash: ${newEntry.hash.substring(0, 16)}...`);
   }
@@ -929,17 +965,12 @@ async function initProvenance(options) {
   await fs.ensureDir(output);
   console.log(`Created provenance directory: ${output}`);
 
-  // Load working spec to validate CAWS project
-  const specPath = '.caws/working-spec.yaml';
-  if (!(await fs.pathExists(specPath))) {
-    console.log('');
-    console.log('Not in a CAWS project - missing working spec');
-    console.log('Run "caws init" first to create a CAWS project');
-    process.exit(1);
+  const resolved = await resolveProvenanceSpec(options);
+  console.log(`Found CAWS spec: ${resolved.spec.id} (${resolved.type})`);
+  if (resolved.degradedValidation) {
+    console.log('   Proceeding with legacy spec metadata despite schema validation issues');
   }
 
-  console.log('Found CAWS working spec');
-
   // Initialize empty chain
   const initialChain = [];
   await saveProvenanceChain(initialChain, output);
@@ -947,6 +978,11 @@ async function initProvenance(options) {
 
   // Create environment configuration hints
   const envConfig = {
+    spec: {
+      id: resolved.spec.id,
+      path: resolved.path,
+      type: resolved.type,
+    },
     cursor_tracking_api: cursorApi || process.env.CURSOR_TRACKING_API || 'not_configured',
     cursor_checkpoint_api: process.env.CURSOR_CHECKPOINT_API || 'not_configured',
     cursor_project_id: process.env.CURSOR_PROJECT_ID || 'not_configured',