@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/index.js

@@ -8,14 +8,16 @@
  */
 
 const { Command } = require('commander');
-// eslint-disable-next-line no-unused-vars
-const fs = require('fs-extra');
-// eslint-disable-next-line no-unused-vars
-const path = require('path');
-// eslint-disable-next-line no-unused-vars
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 
+if (
+  process.argv.includes('--json') ||
+  process.argv.includes('--quiet') ||
+  process.argv.includes('-q')
+) {
+  process.env.CAWS_QUIET = '1';
+}
+
 // Import configuration and utilities
 const {
   CLI_VERSION,
@@ -42,8 +44,7 @@ const { iterateCommand } = require('./commands/iterate');
 const { waiversCommand } = require('./commands/waivers');
 const { workflowCommand } = require('./commands/workflow');
 const { qualityMonitorCommand } = require('./commands/quality-monitor');
-const { qualityGatesCommand } = require('./commands/quality-gates');
-const { troubleshootCommand } = require('./commands/troubleshoot');
+const { gatesCommand } = require('./commands/gates');
 const { archiveCommand } = require('./commands/archive');
 const { specsCommand } = require('./commands/specs');
 const { modeCommand } = require('./commands/mode');
@@ -53,6 +54,8 @@ const { worktreeCommand } = require('./commands/worktree');
 const { sessionCommand } = require('./commands/session');
 const { parallelCommand } = require('./commands/parallel');
 const { verifyAcsCommand } = require('./commands/verify-acs');
+const { sidecarCommand } = require('./commands/sidecar');
+const { scopeCommand } = require('./commands/scope');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -60,16 +63,8 @@ const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
 // Import git hooks functionality
 const { scaffoldGitHooks, removeGitHooks, checkGitHooksStatus } = require('./scaffold/git-hooks');
 
-// Import validation functionality
-// eslint-disable-next-line no-unused-vars
-const { validateWorkingSpecWithSuggestions } = require('./validation/spec-validation');
-
 // Import finalization utilities
 const {
-  // eslint-disable-next-line no-unused-vars
-  finalizeProject,
-  // eslint-disable-next-line no-unused-vars
-  continueToSuccess,
   setFinalizationDependencies,
 } = require('./utils/finalization');
 
@@ -139,84 +134,40 @@ program
   .option('--format <format>', 'Output format (text, json)', 'text')
   .action(validateCommand);
 
-// Quality Gates command
+// Gates command group (v2 pipeline)
+const gatesCmd = program
+  .command('gates')
+  .description('Run quality gate checks');
+
+gatesCmd
+  .command('run')
+  .description('Run quality gates against staged files or a specific file')
+  .option('--context <context>', 'Execution context (cli, commit, edit)', 'cli')
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--file <path>', 'Single file to check (for edit context)')
+  .option('--json', 'Output as JSON', false)
+  .option('--quiet', 'Minimal output', false)
+  .action((options) => gatesCommand(options));
+
+// Quality Gates command (legacy alias — delegates to gates command)
 program
   .command('quality-gates')
-  .description('Run comprehensive quality gates (naming, duplication, god objects, documentation)')
+  .description('Run quality gates (alias for "caws gates run")')
   .option('--ci', 'CI mode - exit with error code if violations found', false)
   .option('--json', 'Output machine-readable JSON to stdout', false)
-  .option(
-    '--gates <gates>',
-    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,hidden-todo,documentation,placeholders)',
-    ''
-  )
-  .option('--fix', 'Attempt automatic fixes (experimental)', false)
-  .option('--context <context>', 'Execution context: commit (staged files), push (all tracked files), or ci (all tracked files)', 'commit')
+  .option('--context <context>', 'Execution context: commit, push, ci', 'commit')
   .option('--all-files', 'Check all tracked files (equivalent to --context=ci)', false)
-  .option('--help', 'Show detailed help and usage examples', false)
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--quiet', 'Minimal output', false)
   .action(async (options) => {
-    // Handle --help flag
-    if (options.help) {
-      console.log(`
-CAWS Quality Gates - Enterprise Code Quality Enforcement
-
-USAGE:
-  caws quality-gates [options]
-
-DESCRIPTION:
-  Runs comprehensive quality gates to maintain code quality standards.
-  Supports selective gate execution, JSON output, and CI/CD integration.
-
-OPTIONS:
-  --ci              CI mode - exit with error code if violations found
-  --json            Output machine-readable JSON to stdout
-  --gates=<gates>   Run only specific gates (comma-separated)
-  --fix             Attempt automatic fixes (experimental)
-  --context=<ctx>   Execution context: commit (staged files), push (all tracked), ci (all tracked)
-  --all-files       Check all tracked files (shortcut for --context=ci)
-  --help            Show this help message
-
-VALID GATES:
-  naming           Check naming conventions and banned modifiers
-  code_freeze      Enforce code freeze compliance
-  duplication      Detect functional duplication
-  god_objects      Prevent oversized files
-  hidden-todo      Detect hidden incomplete implementations
-  documentation    Check documentation quality
-  placeholders     Placeholder governance (explicit degradations)
-
-EXAMPLES:
-  # Run all gates in development mode
-  caws quality-gates
-
-  # Run only specific gates
-  caws quality-gates --gates=naming,duplication
-
-  # CI mode with JSON output
-  caws quality-gates --ci --json
-
-  # Check all files in repository (not just staged)
-  caws quality-gates --all-files
-
-  # Use specific context
-  caws quality-gates --context=ci
-
-  # Show detailed help
-  caws quality-gates --help
-
-OUTPUT:
-  - Console: Human-readable results with enforcement levels
-  - JSON: Machine-readable structured data (--json flag)
-  - Artifacts: docs-status/quality-gates-report.json
-  - GitHub Actions: Automatic step summaries when GITHUB_STEP_SUMMARY is set
-
-For more information, see: packages/quality-gates/README.md
-`);
-      process.exit(0);
-    }
-
-    // Call the actual quality gates runner
-    await qualityGatesCommand(options);
+    // Map legacy options to new gates command options
+    const gateOpts = {
+      context: options.allFiles ? 'ci' : (options.context || 'cli'),
+      specId: options.specId,
+      json: options.json,
+      quiet: options.quiet,
+    };
+    await gatesCommand(gateOpts);
   });
 
 // Status command
@@ -234,6 +185,7 @@ program
   .command('archive <change-id>')
   .description('Archive completed change')
   .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-s, --spec <path>', 'Path to spec file (explicit override)')
   .option('-f, --force', 'Force archive even if criteria not met', false)
   .option('--dry-run', 'Preview archive without performing it', false)
   .action(archiveCommand);
@@ -300,6 +252,38 @@ specsCmd
   .description('Show available spec types')
   .action(() => specsCommand('types', {}));
 
+// Sidecar command group
+const sidecarCmd = program.command('sidecar').description('Advisory analysis tools (drift, gaps, waivers, provenance)');
+
+sidecarCmd
+  .command('drift')
+  .description('Analyze spec drift vs implementation evidence')
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--json', 'Output as JSON', false)
+  .action((options) => sidecarCommand('drift', options));
+
+sidecarCmd
+  .command('gaps')
+  .description('Diagnose quality gaps preventing phase advancement')
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--json', 'Output as JSON', false)
+  .action((options) => sidecarCommand('gaps', options));
+
+sidecarCmd
+  .command('waiver-draft')
+  .description('Generate pre-filled waiver templates from gate failures')
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--gate <gate>', 'Specific gate to draft waiver for')
+  .option('--json', 'Output as JSON', false)
+  .action((options) => sidecarCommand('waiver-draft', options));
+
+sidecarCmd
+  .command('provenance')
+  .description('Summarize work provenance for merge readiness')
+  .option('--spec-id <id>', 'Target spec ID')
+  .option('--json', 'Output as JSON', false)
+  .action((options) => sidecarCommand('provenance', options));
+
 // Mode command group
 const modeCmd = program.command('mode').description('Manage CAWS complexity tiers');
 
@@ -314,13 +298,6 @@ modeCmd
   .description('Set CAWS complexity tier')
   .action((mode) => modeCommand('set', { mode }));
 
-modeCmd
-  .command('set')
-  .description('Set CAWS complexity tier (interactive)')
-  .option('-i, --interactive', 'Interactive mode selection', false)
-  .option('-m, --mode <mode>', 'Specific mode to set')
-  .action((options) => modeCommand('set', options));
-
 modeCmd
   .command('compare')
   .description('Compare all available tiers')
@@ -393,15 +370,33 @@ worktreeCmd
   .command('prune')
   .description('Clean up stale worktree entries')
   .option('--max-age <days>', 'Remove entries older than N days', '30')
+  .option('--force', 'Allow pruning entries owned by other sessions', false)
   .action((options) => worktreeCommand('prune', options));
 
 worktreeCmd
   .command('repair')
   .description('Reconcile registry with git and filesystem state')
   .option('--dry-run', 'Report only, do not persist changes', false)
-  .option('--prune', 'Remove destroyed and stale-merged entries', false)
+  .option('--prune', 'Remove destroyed, stale-merged, and missing entries', false)
+  .option('--force', 'Allow pruning entries owned by other sessions', false)
   .action((options) => worktreeCommand('repair', options));
 
+worktreeCmd
+  .command('bind <spec-id>')
+  .description('Bind a spec to this worktree (fixes mutual reference)')
+  .option('--name <name>', 'Worktree name (auto-detected from cwd if omitted)')
+  .action((specId, options) => worktreeCommand('bind', { specId, ...options }));
+
+// Scope command group
+const scopeCmd = program
+  .command('scope')
+  .description('Inspect and manage scope boundaries');
+
+scopeCmd
+  .command('show')
+  .description('Show effective scope for the current context')
+  .action(() => scopeCommand('show'));
+
 // Session command group
 const sessionCmd = program
   .command('session')
@@ -525,6 +520,14 @@ program
   .option('-v, --verbose', 'Show detailed error information', false)
   .action(iterateCommand);
 
+// Burnup command
+program
+  .command('burnup [spec-file]')
+  .description('Generate budget burn-up report for scope visibility')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-v, --verbose', 'Show detailed error information', false)
+  .action(burnupCommand);
+
 // Waivers command group
 const waiversCmd = program.command('waivers').description('Manage CAWS quality gate waivers');
 
@@ -566,8 +569,17 @@ waiversCmd
   .option('-v, --verbose', 'Show detailed error information', false)
   .action((id, options) => waiversCommand('revoke', { ...options, id }));
 
+waiversCmd
+  .command('prune')
+  .description('Prune expired waivers (dry-run by default; use --apply to persist)')
+  .option('--expired', 'Prune active waivers whose expires_at is in the past')
+  .option('--apply', 'Actually transition status (default: dry run)')
+  .option('--json', 'Emit machine-readable JSON output')
+  .option('-v, --verbose', 'Show detailed error information', false)
+  .action((options) => waiversCommand('prune', options));
+
 // Workflow command group
-const workflowCmd = program
+program
   .command('workflow <type>')
   .description('Get workflow-specific guidance')
   .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
@@ -603,7 +615,9 @@ program
   .command('test-analysis <subcommand> [options...]')
   .description('Statistical analysis for budget prediction')
   .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
-  .action(testAnalysisCommand);
+  .action((subcommand, optionArgs, command) => {
+    testAnalysisCommand(subcommand, optionArgs, command.opts());
+  });
 
 // Provenance command group
 const provenanceCmd = program.command('provenance').description('Manage CAWS provenance tracking');
@@ -613,6 +627,8 @@ provenanceCmd
   .command('update')
   .description('Add new commit to provenance chain')
   .requiredOption('-c, --commit <hash>', 'Git commit hash')
+  .option('--spec-id <id>', 'Feature-specific spec ID')
+  .option('-s, --spec <path>', 'Path to spec file (explicit override)')
   .option('-m, --message <msg>', 'Commit message')
   .option('-a, --author <info>', 'Author information')
   .option('-q, --quiet', 'Suppress output')
@@ -649,6 +665,8 @@ provenanceCmd
 provenanceCmd
   .command('init')
   .description('Initialize provenance tracking for the project')
+  .option('--spec-id <id>', 'Feature-specific spec ID')
+  .option('-s, --spec <path>', 'Path to spec file (explicit override)')
   .option('-o, --output <path>', 'Output path for provenance files', '.caws/provenance')
   .option('--cursor-api <url>', 'Cursor tracking API endpoint')
   .option('--cursor-key <key>', 'Cursor API key')
@@ -725,6 +743,37 @@ program.configureHelp({
   showError: () => {}, // Suppress default error display
 });
 
+const VALID_COMMANDS = [
+  'init',
+  'validate',
+  'scaffold',
+  'status',
+  'archive',
+  'specs',
+  'sidecar',
+  'mode',
+  'tutorial',
+  'plan',
+  'templates',
+  'diagnose',
+  'evaluate',
+  'iterate',
+  'waivers',
+  'workflow',
+  'quality-monitor',
+  'quality-gates',
+  'gates',
+  'provenance',
+  'hooks',
+  'burnup',
+  'tool',
+  'worktree',
+  'session',
+  'parallel',
+  'verify-acs',
+  'scope',
+];
+
 program.exitOverride((err) => {
   // Handle help and version requests gracefully
   if (
@@ -739,34 +788,7 @@ program.exitOverride((err) => {
 
   // Check for unknown command
   if (err.code === 'commander.unknownCommand') {
-    const validCommands = [
-      'init',
-      'validate',
-      'scaffold',
-      'status',
-      'archive',
-      'specs',
-      'mode',
-      'tutorial',
-      'plan',
-      'templates',
-      'diagnose',
-      'evaluate',
-      'iterate',
-      'waivers',
-      'workflow',
-      'quality-monitor',
-      'troubleshoot',
-      'provenance',
-      'hooks',
-      'burnup',
-      'tool',
-      'worktree',
-      'session',
-      'parallel',
-      'verify-acs',
-    ];
-    const similar = findSimilarCommand(commandName, validCommands);
+    const similar = findSimilarCommand(commandName, VALID_COMMANDS);
 
     console.error(chalk.red(`\nUnknown command: ${commandName}`));
 
@@ -774,9 +796,7 @@ program.exitOverride((err) => {
       console.error(chalk.yellow(`\nDid you mean: caws ${similar}?`));
     }
 
-    console.error(
-      chalk.yellow('Available commands: init, validate, scaffold, provenance, hooks')
-    );
+    console.error(chalk.yellow('Run: caws --help for the full command list'));
     console.error(chalk.yellow('Try: caws --help for full command list'));
     console.error(
       chalk.blue(
@@ -821,6 +841,12 @@ program.exitOverride((err) => {
   process.exit(1);
 });
 
+// Register sidecar lifecycle listeners (non-fatal hints)
+try {
+  const { registerSidecarListeners } = require('./sidecars/listeners');
+  registerSidecarListeners();
+} catch { /* sidecars module not available — non-fatal */ }
+
 // Parse and run
 if (require.main === module) {
   try {
@@ -844,25 +870,7 @@ if (require.main === module) {
 
     // Check for unknown command
     if (error.code === 'commander.unknownCommand') {
-      const validCommands = [
-        'init',
-        'validate',
-        'scaffold',
-        'status',
-        'archive',
-        'specs',
-        'mode',
-        'tutorial',
-        'plan',
-        'provenance',
-        'hooks',
-        'burnup',
-        'tool',
-        'worktree',
-        'session',
-        'parallel',
-      ];
-      const similar = findSimilarCommand(commandName, validCommands);
+      const similar = findSimilarCommand(commandName, VALID_COMMANDS);
 
       console.error(chalk.red(`\nUnknown command: ${commandName}`));
 
@@ -870,9 +878,7 @@ if (require.main === module) {
         console.error(chalk.yellow(`\nDid you mean: caws ${similar}?`));
       }
 
-      console.error(
-        chalk.yellow('Available commands: init, validate, scaffold, provenance, hooks, parallel')
-      );
+      console.error(chalk.yellow('Run: caws --help for the full command list'));
       console.error(chalk.yellow('Try: caws --help for full command list'));
       console.error(
         chalk.blue(

package/dist/parallel/parallel-manager.js

@@ -192,7 +192,7 @@ function getParallelStatus() {
     let commitCount = 0;
     let dirty = false;
 
-    if (wt && wt.status === 'active') {
+    if (wt && (wt.status === 'active' || wt.status === 'fresh' || wt.status === 'merged')) {
       try {
         const log = execFileSync(
           'git',
@@ -250,7 +250,7 @@ function detectFileConflicts(baseBranch, agentStatuses) {
   const filesByAgent = {};
 
   for (const agent of agentStatuses) {
-    if (agent.status !== 'active') continue;
+    if (agent.status !== 'active' && agent.status !== 'fresh' && agent.status !== 'merged') continue;
     try {
       const diff = execFileSync(
         'git',
@@ -302,7 +302,7 @@ function mergeParallel(options = {}) {
       const wt = worktrees.find((w) => w.name === a.name);
       return wt ? { ...a, ...wt } : null;
     })
-    .filter((a) => a && a.status === 'active');
+    .filter((a) => a && (a.status === 'active' || a.status === 'fresh' || a.status === 'merged'));
 
   // Check for dirty worktrees
   for (const agent of activeAgents) {

package/dist/policy/PolicyManager.js

@@ -8,6 +8,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
+const { createValidator, getSchemaPath } = require('../utils/schema-validator');
 
 /**
  * Policy Manager - Handles policy loading with intelligent caching
@@ -86,6 +87,34 @@ class PolicyManager {
       }
 
       if (policyPath && policyContent) {
+        // Schema validation (warn and fall back to defaults on failure)
+        try {
+          const schemaFilePath = getSchemaPath('policy.schema.json', projectRoot);
+          const validate = createValidator(schemaFilePath);
+          const schemaResult = validate(policyContent);
+          if (!schemaResult.valid) {
+            console.warn('Policy has schema violations:', schemaResult.errors);
+            console.warn('Falling back to default policy');
+            const defaultPolicy = this.getDefaultPolicy();
+            if (this.enableCaching) {
+              this.policyCache.set(projectRoot, {
+                policy: defaultPolicy,
+                cachedAt: Date.now(),
+                ttl: cacheTTL,
+              });
+            }
+            return {
+              ...defaultPolicy,
+              _isDefault: true,
+              _schemaErrors: schemaResult.errors,
+              _cacheHit: false,
+              _loadDuration: Date.now() - startTime,
+            };
+          }
+        } catch (schemaErr) {
+          console.warn('Could not validate policy schema:', schemaErr.message);
+        }
+
         // Validate policy structure
         this.validatePolicy(policyContent);
 
@@ -241,15 +270,17 @@ class PolicyManager {
       throw new Error('Policy missing risk_tiers configuration');
     }
 
-    // Validate all tiers have required fields
-    for (const tier of [1, 2, 3]) {
-      const budget = policy.risk_tiers[tier];
-      if (!budget) {
-        throw new Error(`Policy missing risk tier ${tier} configuration`);
+    const tierKeys = Object.keys(policy.risk_tiers);
+    if (tierKeys.length === 0) {
+      throw new Error('Policy risk_tiers must define at least one risk tier (1, 2, or 3)');
+    }
+    for (const key of tierKeys) {
+      if (!/^[1-3]$/.test(key)) {
+        throw new Error(`Policy risk_tiers has unknown tier '${key}' (expected 1, 2, or 3)`);
       }
-
+      const budget = policy.risk_tiers[key];
       if (typeof budget.max_files !== 'number' || typeof budget.max_loc !== 'number') {
-        throw new Error(`Risk tier ${tier} missing or invalid budget limits`);
+        throw new Error(`Risk tier ${key} missing or invalid budget limits`);
       }
     }
 
@@ -299,27 +330,30 @@ class PolicyManager {
       gates: {
         budget_limit: {
           enabled: true,
+          mode: 'block',
           description: 'Enforce change budget limits',
         },
         spec_completeness: {
           enabled: true,
+          mode: 'block',
           description: 'Require complete working specifications',
         },
-        contract_compliance: {
-          enabled: true,
-          description: 'Validate API contracts',
-        },
-        coverage_threshold: {
+        scope_boundary: {
           enabled: true,
-          description: 'Maintain test coverage requirements',
+          mode: 'block',
+          description: 'Enforce spec scope boundaries',
         },
-        mutation_threshold: {
+        god_object: {
           enabled: true,
-          description: 'Require mutation testing for T1/T2 changes',
+          mode: 'warn',
+          thresholds: { warning: 1750, critical: 2000 },
+          description: 'Detect oversized source files',
         },
-        security_scan: {
+        todo_detection: {
           enabled: true,
-          description: 'Run security vulnerability scans',
+          mode: 'warn',
+          thresholds: { min_confidence: 0.8 },
+          description: 'Scan for TODO/FIXME/HACK/XXX markers',
         },
       },
     };

package/dist/scaffold/claude-hooks.js

@@ -54,7 +54,7 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
     // Map levels to hook scripts
     const hookMapping = {
       safety: ['block-dangerous.sh', 'scan-secrets.sh', 'worktree-guard.sh', 'worktree-write-guard.sh', 'stop-worktree-check.sh', 'session-caws-status.sh'],
-      quality: ['quality-check.sh', 'validate-spec.sh'],
+      quality: ['quality-check.sh', 'validate-spec.sh', 'doc-frontmatter-check.sh'],
       scope: ['scope-guard.sh', 'naming-check.sh'],
       audit: ['audit.sh', 'session-log.sh'],
       lite: ['block-dangerous.sh', 'scope-guard.sh', 'lite-sprawl-check.sh', 'simplification-guard.sh'],
@@ -81,6 +81,7 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
       'block-dangerous.sh',
       'scope-guard.sh',
       'naming-check.sh',
+      'doc-frontmatter-check.sh',
       'lite-sprawl-check.sh',
       'simplification-guard.sh',
       'worktree-guard.sh',
@@ -90,6 +91,23 @@ async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 's
       'session-log.sh',
     ];
 
+    // Copy supporting scripts (not hooks themselves, but used by hooks)
+    const supportingScripts = [
+      'classify_command.py',
+      'test_classify_command.py',
+      'test_wrapper_smoke.sh',
+    ];
+
+    for (const script of supportingScripts) {
+      const sourcePath = path.join(claudeHooksTemplateDir, script);
+      const destPath = path.join(claudeHooksDir, script);
+
+      if (fs.existsSync(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        await fs.chmod(destPath, 0o755);
+      }
+    }
+
     for (const script of allHookScripts) {
       if (enabledHooks.has(script)) {
         const sourcePath = path.join(claudeHooksTemplateDir, script);
@@ -254,6 +272,11 @@ function generateClaudeSettings(levels, _enabledHooks) {
           command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/validate-spec.sh',
           timeout: 15,
         },
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/doc-frontmatter-check.sh',
+          timeout: 10,
+        },
       ],
     });
   }