@paths.design/caws-cli 9.3.1 → 10.0.1

package/dist/gates/todo-detection.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview TODO/FIXME scanning gate
+ * Detects actionable TODO, FIXME, HACK, XXX markers in comments.
+ * Filters out false positives: string literals, regex definitions, test assertions,
+ * and documentation about the TODO system itself.
+ * Context-aware: commit context scans staged diff, cli/edit context scans file content.
+ * @author @darianrosebrook
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const name = 'todo_detection';
+
+const TODO_MARKERS = /\b(TODO|FIXME|HACK|XXX)\b/g;
+
+/**
+ * Comment patterns for languages we scan.
+ * A line is a "comment TODO" if the TODO marker appears after a comment introducer.
+ */
+const COMMENT_TODO = /(?:\/\/|#|\/?\*|\{\/\*)\s*\b(TODO|FIXME|HACK|XXX)\b/;
+
+/**
+ * Patterns that indicate the line is ABOUT the TODO system, not an actual TODO.
+ * These are lines where TODO appears as data, not as intent.
+ */
+const FALSE_POSITIVE_PATTERNS = [
+  /TODO_PATTERN/,                       // regex variable name
+  /TODO\/FIXME/,                        // describing the pattern itself
+  /\btoMatch\b|\btoContain\b|\bexpect\(/,  // test assertions
+  /writeFileSync.*TODO/,                // test fixture data
+  /\bdescribe\(.*TODO|\btest\(.*TODO|\bit\(.*TODO/,  // test names
+  /Pattern.*TODO|regex.*TODO/i,         // documentation about patterns
+  /["'`].*\bTODO\b.*["'`]/,            // string literals containing TODO
+];
+
+/** Directories to skip when scanning files directly */
+const EXCLUDE_DIRS = ['node_modules/', 'dist/', 'dist-bundle/', 'build/', '.next/', 'coverage/', 'vendor/', '__pycache__/'];
+
+/** Files that are part of the TODO detection system itself — skip to avoid self-analysis */
+const SELF_FILES = ['todo-detection.js', 'todo_detection.js', 'todo_analyzer.py', 'todo-analyzer'];
+
+/** Extensions to scan */
+const SOURCE_EXTENSIONS = ['.js', '.ts', '.tsx', '.jsx', '.py', '.rs', '.go', '.java', '.rb', '.cs', '.sh'];
+
+/**
+ * Check if a file should be excluded from scanning.
+ * @param {string} filePath - Relative file path
+ * @returns {boolean}
+ */
+function isExcluded(filePath) {
+  for (const dir of EXCLUDE_DIRS) {
+    if (filePath.startsWith(dir) || filePath.includes('/' + dir)) return true;
+  }
+  // Skip the gate's own implementation files
+  const basename = path.basename(filePath);
+  for (const self of SELF_FILES) {
+    if (basename === self || basename.includes(self)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a line contains a real TODO comment (not a false positive).
+ * Returns the marker name if real, null if false positive.
+ * @param {string} line - Source line
+ * @returns {string|null} The marker found, or null
+ */
+function findRealTodo(line) {
+  const trimmed = line.trim();
+
+  // Must contain a marker at all
+  TODO_MARKERS.lastIndex = 0;
+  if (!TODO_MARKERS.test(trimmed)) return null;
+
+  // Filter out false positives
+  for (const fp of FALSE_POSITIVE_PATTERNS) {
+    if (fp.test(trimmed)) return null;
+  }
+
+  // Must look like a comment containing the marker — not just any line with TODO in it
+  if (!COMMENT_TODO.test(trimmed)) return null;
+
+  // Extract which marker
+  TODO_MARKERS.lastIndex = 0;
+  const match = TODO_MARKERS.exec(trimmed);
+  return match ? match[1] : null;
+}
+
+/**
+ * Scan staged diff for newly-added TODO markers.
+ * Used in commit context — only flags markers being added, not pre-existing ones.
+ */
+function scanStagedDiff(projectRoot) {
+  const messages = [];
+  let totalCount = 0;
+
+  const diff = execSync('git diff --cached -U0', {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let currentFile = null;
+  let lineNum = 0;
+
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ b/')) {
+      currentFile = line.slice(6);
+      continue;
+    }
+    if (line.startsWith('@@')) {
+      const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)/);
+      if (match) {
+        lineNum = parseInt(match[1], 10) - 1;
+      }
+      continue;
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      lineNum++;
+      const content = line.slice(1); // remove the leading +
+      const marker = findRealTodo(content);
+      if (marker) {
+        totalCount++;
+        messages.push(`${currentFile}:${lineNum}: ${marker} found`);
+      }
+    } else if (!line.startsWith('-')) {
+      lineNum++;
+    }
+  }
+
+  return { totalCount, messages };
+}
+
+/**
+ * Scan file contents directly for TODO markers.
+ * Used in cli/edit context — reports all existing markers in the given files.
+ */
+function scanFiles(stagedFiles, projectRoot) {
+  const messages = [];
+  let totalCount = 0;
+
+  const filesToScan = stagedFiles.filter(f =>
+    SOURCE_EXTENSIONS.some(ext => f.endsWith(ext)) && !isExcluded(f)
+  );
+
+  for (const file of filesToScan) {
+    try {
+      const fullPath = path.resolve(projectRoot, file);
+      if (!fs.existsSync(fullPath)) continue;
+
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const marker = findRealTodo(lines[i]);
+        if (marker) {
+          totalCount++;
+          messages.push(`${file}:${i + 1}: ${marker} found`);
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return { totalCount, messages };
+}
+
+/**
+ * Run the TODO detection gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - File paths to check
+ * @param {string} params.projectRoot - Project root
+ * @param {string} [params.context] - Execution context (commit, cli, edit)
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, projectRoot, context }) {
+  try {
+    let result;
+
+    if (context === 'commit') {
+      // Commit context: scan only newly-added lines in staged diff
+      result = scanStagedDiff(projectRoot);
+    } else {
+      // CLI/edit context: scan file contents directly
+      result = scanFiles(stagedFiles, projectRoot);
+    }
+
+    if (result.totalCount > 0) {
+      result.messages.unshift(`Found ${result.totalCount} TODO/FIXME/HACK/XXX marker(s)${context === 'commit' ? ' in staged changes' : ''}`);
+      return { status: 'warn', messages: result.messages };
+    }
+
+    return { status: 'pass', messages: [] };
+  } catch (err) {
+    return {
+      status: 'warn',
+      messages: [`Cannot scan for TODO markers: ${err.message}`],
+    };
+  }
+}
+
+module.exports = { name, run };

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,7 @@ 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');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -60,16 +62,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 +133,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 +184,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 +251,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 +297,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,8 +369,17 @@ 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, stale-merged, and missing entries', false)
+  .option('--force', 'Allow pruning entries owned by other sessions', false)
+  .action((options) => worktreeCommand('repair', options));
+
 // Session command group
 const sessionCmd = program
   .command('session')
@@ -518,6 +503,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');
 
@@ -560,7 +553,7 @@ waiversCmd
   .action((id, options) => waiversCommand('revoke', { ...options, id }));
 
 // 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)')
@@ -596,7 +589,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');
@@ -606,6 +601,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')
@@ -642,6 +639,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')
@@ -718,6 +717,36 @@ 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',
+];
+
 program.exitOverride((err) => {
   // Handle help and version requests gracefully
   if (
@@ -732,34 +761,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}`));
 
@@ -767,9 +769,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(
@@ -814,6 +814,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 {
@@ -837,25 +843,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}`));
 
@@ -863,9 +851,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) {