@paths.design/caws-cli 9.3.2 → 10.0.1

package/README.md

@@ -12,8 +12,8 @@ The CAWS CLI serves as the central control point for:
 - **Quality Validation**: Run comprehensive validation against working specifications
 - **Agent Integration**: Programmatic APIs for AI agents to evaluate and guide development
 - **Waiver Management**: Fast-lane escape hatches with full audit trails
-- **CI/CD Optimization**: Pipeline generation and optimization tools
-- **Experimental Features**: Dry-run capabilities for experimental functionality
+- **Quality Gates**: v2 pipeline with configurable gate modules
+- **Session Management**: Track and manage agent work sessions
 
 ## Installation
 
@@ -86,40 +86,69 @@ caws waivers list
 caws waivers revoke WV-0001
 ```
 
-### CI/CD Optimization
+### Quality Gates
 
 ```bash
-# Analyze project for CI/CD optimizations
-caws cicd analyze
+# Run quality gates v2 pipeline
+caws gates run
 
-# Generate optimized GitHub Actions workflow
-caws cicd generate github --output .github/workflows/caws-gates.yml
+# Run legacy quality gates
+caws quality-gates
+```
+
+### Worktree Management
+
+```bash
+# Create an isolated worktree for parallel agent work
+caws worktree create <name>
+
+# List active worktrees
+caws worktree list
 
-# Smart test selection based on changes
-caws cicd test-selection --from-commit HEAD~1
+# Merge a completed worktree back to base
+caws worktree merge <name>
+
+# Destroy a worktree
+caws worktree destroy <name>
 ```
 
-### Experimental Features
+### Session Management
 
 ```bash
-# Dry-run validation without side effects
-caws experimental --dry-run validate .caws/working-spec.yaml
+# Start a tracked session
+caws session start
+
+# Create a session checkpoint
+caws session checkpoint
 
-# Experimental quality gates
-caws experimental quality-gates .caws/working-spec.yaml --parallel-execution
+# End a session
+caws session end
+
+# List past sessions
+caws session list
 ```
 
-### Tool Management
+### Spec Management
 
 ```bash
-# List available CAWS tools
-caws tools list
+# List all specs (project + feature)
+caws specs list
+
+# Create a feature spec
+caws specs create FEAT-001 --type feature --title "description"
+
+# Show a spec
+caws specs show FEAT-001
+
+# Check for scope conflicts between specs
+caws specs conflicts
+```
 
-# Execute specific tool
-caws tools run validate
+### Tool Management
 
-# Manage tool configurations
-caws tools --help
+```bash
+# Run the CAWS tool interface
+caws tool
 ```
 
 ## Architecture
@@ -131,7 +160,7 @@ caws-cli/
 ├── src/
 │   ├── index.js           # Main CLI entry point
 │   ├── waivers-manager.js # Waiver system implementation
-│   ├── cicd-optimizer.js  # CI/CD optimization logic
+│   ├── quality-gates/     # v2 gate modules
 │   └── tool-loader.js     # Dynamic tool loading system
 ├── templates/             # Project templates
 └── dist/                  # Compiled output
@@ -142,7 +171,7 @@ caws-cli/
 - **Command Parser**: Commander.js-based CLI with subcommands
 - **Tool System**: Dynamic loading of quality gate tools
 - **Waiver Manager**: Fast-lane escape hatch management
-- **CI/CD Optimizer**: Pipeline analysis and generation
+- **Quality Gates v2**: Modular gate pipeline with configurable modules
 - **Agent Interface**: JSON APIs for programmatic agent integration
 
 ## Integration with CAWS Ecosystem
@@ -168,14 +197,16 @@ caws-cli/
 
 ### Quality Gates Integration
 
-The CLI automatically executes quality gates defined in the template:
+The v2 quality gates pipeline (`caws gates run`) executes modular gate checks:
 
-1. **Spec Validation**: Validates working specifications against schema
+1. **Spec Validation**: Validates working specifications against schema (mode, blast_radius, rollback SLO)
 2. **Security Scanning**: Runs security checks and secret detection
-3. **Code Quality**: Executes linting, type checking, and formatting
-4. **Test Execution**: Runs unit, integration, and contract tests
+3. **Scope Enforcement**: Verifies changes stay within spec-defined boundaries
+4. **Test & Coverage**: Runs tests and validates coverage thresholds per risk tier
 5. **Performance Checks**: Validates performance budgets and metrics
 
+Gates can be configured per-spec with `mode` (block/warn/skip) and custom `thresholds` in policy.yaml.
+
 ### Agent Workflow Integration
 
 The CLI provides structured APIs for agents:

package/dist/commands/archive.js

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

package/dist/commands/burnup.js

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

package/dist/commands/diagnose.js

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

package/dist/commands/evaluate.js

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