@paths.design/caws-cli 9.3.1 → 10.0.1

package/dist/commands/gates.js

@@ -0,0 +1,122 @@
+/**
+ * @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');
+const { recordGates, loadState } = require('../utils/working-state');
+
+/**
+ * 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
+      if (spec && spec.id) {
+        try { recordGates(spec.id, report, context, projectRoot); } catch { /* non-fatal */ }
+      }
+
+      if (options.json || options.format === 'json') {
+        console.log(formatJson(report));
+      } else if (!options.quiet) {
+        // Enrich feedback on failure or --verbose
+        if (!report.passed || options.verbose) {
+          try {
+            const state = spec?.id ? loadState(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 };

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');
@@ -28,6 +29,117 @@ const {
   parseIDESelection,
 } = require('../utils/ide-detection');
 
+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
  */
@@ -492,10 +604,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 +617,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 +635,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 +707,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 +747,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 +758,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 +794,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 +814,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,7 @@ const { initializeGlobalSetup } = require('../config');
 
 // Import spec resolution system
 const { resolveSpec } = require('../utils/spec-resolver');
+const { loadState } = require('../utils/working-state');
 
 /**
  * Iterate command handler
@@ -21,12 +22,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 +37,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 +58,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
+    let workingState = null;
+    try { workingState = loadState(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 +119,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 +396,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',