@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/waivers.js

@@ -13,6 +13,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { initializeGlobalSetup } = require('../config');
+const { getAgentSessionId } = require('../utils/agent-session');
 const WaiversManager = require('../waivers-manager');
 const { commandWrapper, Output } = require('../utils/command-wrapper');
 
@@ -24,16 +25,12 @@ const WAIVER_DIR = '.caws/waivers';
  * within the check-*.mjs files.
  */
 const VALID_GATES = [
-  'naming',
-  'code_freeze',
-  'duplication',
-  'duplication_gate',
-  'god_objects',
-  'placeholders',
-  'simplification',
-  'hidden-todo',
-  'documentation',
-  '*',
+  'budget_limit',
+  'spec_completeness',
+  'scope_boundary',
+  'god_object',
+  'todo_detection',
+  '*',  // wildcard — waiver applies to all gates
 ];
 
 /**
@@ -49,7 +46,7 @@ async function waiversCommand(subcommand = 'list', options = {}) {
       const setup = initializeGlobalSetup();
 
       if (setup.hasWorkingSpec) {
-        Output.success(`Detected ${setup.setupType} CAWS setup`, {
+        Output.success(`Detected ${setup.type} CAWS setup`, {
           capabilities: setup.capabilities,
         });
       }
@@ -69,10 +66,12 @@ async function waiversCommand(subcommand = 'list', options = {}) {
           return await showWaiver(options.id, options);
         case 'revoke':
           return await revokeWaiver(options.id, options);
+        case 'prune':
+          return await pruneWaivers(options);
         default:
           throw new Error(
             `Unknown waiver subcommand: ${subcommand}.\n` +
-            'Available subcommands: create, list, show, revoke'
+            'Available subcommands: create, list, show, revoke, prune'
           );
       }
     },
@@ -138,6 +137,24 @@ async function createWaiver(options) {
     process.exit(1);
   }
 
+  // Self-approval prevention: creator cannot be approver
+  // Uses strict equality — the previous .includes() check was an asymmetric
+  // substring match that produced false positives (blocking legitimate approvers
+  // whose name happened to contain the session ID) while missing the reverse
+  // case (approver is a prefix of the session ID).
+  // When CLAUDE_SESSION_ID is unset or empty, we can't identify the creator,
+  // so self-approval prevention is skipped ('' || null → null → falsy guard).
+  const creatorSession = getAgentSessionId(process.cwd());
+  if (creatorSession && options.approvedBy) {
+    if (options.approvedBy === creatorSession) {
+      throw new Error(
+        'Waiver creator cannot be the approver.\n' +
+        'A different agent or human must approve this waiver.\n' +
+        `Creator session: ${creatorSession}`
+      );
+    }
+  }
+
   // Generate waiver ID
   const waiverId = `WV-${Date.now().toString().slice(-4)}`;
   const timestamp = new Date().toISOString();
@@ -155,8 +172,26 @@ async function createWaiver(options) {
     impact_level: options.impactLevel,
     mitigation_plan: options.mitigationPlan,
     status: 'active',
+    created_by_session: creatorSession,
   };
 
+  // Validate waiver against schema before persisting
+  try {
+    const { createValidator, getSchemaPath } = require('../utils/schema-validator');
+    const schemaPath = getSchemaPath('waivers.schema.json', process.cwd());
+    const validate = createValidator(schemaPath);
+    // waivers.schema.json validates a single waiver document directly (CAWSFIX-17)
+    const result = validate(waiver);
+    if (!result.valid) {
+      console.warn(chalk.yellow('Waiver has schema violations:'));
+      result.errors.forEach((err) => {
+        console.warn(chalk.yellow(`  ${err.instancePath}: ${err.message}`));
+      });
+    }
+  } catch (schemaErr) {
+    // Non-fatal — don't block waiver creation on schema issues
+  }
+
   // Save individual waiver file
   const waiverPath = path.join(process.cwd(), WAIVER_DIR, `${waiverId}.yaml`);
   fs.writeFileSync(waiverPath, yaml.dump(waiver, { lineWidth: -1 }));
@@ -198,9 +233,32 @@ async function listWaivers(_options) {
     return;
   }
 
+  // Load a schema validator once for all waiver files (if available)
+  let waiverValidate = null;
+  try {
+    const { createValidator, getSchemaPath } = require('../utils/schema-validator');
+    const schemaPath = getSchemaPath('waivers.schema.json', process.cwd());
+    waiverValidate = createValidator(schemaPath);
+  } catch {
+    // Schema not available — skip validation
+  }
+
   const waivers = waiverFiles.map((file) => {
     const content = fs.readFileSync(path.join(waiversDir, file), 'utf8');
-    return yaml.load(content);
+    const waiver = yaml.load(content);
+
+    // Validate each loaded waiver against schema
+    if (waiverValidate && waiver && waiver.id) {
+      const result = waiverValidate(waiver);
+      if (!result.valid) {
+        console.warn(chalk.yellow(`Schema warning for ${file}:`));
+        result.errors.forEach((err) => {
+          console.warn(chalk.yellow(`  ${err.instancePath}: ${err.message}`));
+        });
+      }
+    }
+
+    return waiver;
   });
 
   // Filter by status
@@ -348,6 +406,147 @@ async function revokeWaiver(waiverId, options) {
   console.log(`   Reason: ${waiver.revocation_reason}\n`);
 }
 
+/**
+ * Prune expired waivers.
+ *
+ * Behavior per CAWSFIX-04 AC3-A6:
+ *   --expired            : dry run — list prunable waivers, no disk changes,
+ *                          no events emitted. Exit 0.
+ *   --expired --apply    : transition each prunable waiver from
+ *                          `status: active` to `status: expired` in place
+ *                          (file is updated, NOT deleted, to preserve the
+ *                          audit trail) and append a `waiver_pruned` event
+ *                          to the event log for each.
+ *
+ * A waiver is "prunable" iff `status === 'active'` AND `expires_at < now`.
+ * Waivers already `expired` or `revoked` are untouched (A4). Non-expired
+ * active waivers are untouched (A5). Empty registries exit 0 with a
+ * friendly message (A6).
+ *
+ * @param {object} options
+ * @param {boolean} [options.expired] — currently the only prune criterion
+ * @param {boolean} [options.apply] — if false, dry-run (default)
+ * @param {boolean} [options.json] — machine-readable output
+ */
+async function pruneWaivers(options = {}) {
+  if (!options.expired) {
+    console.error(chalk.red('\n`caws waivers prune` requires --expired\n'));
+    console.log(chalk.yellow('Usage: caws waivers prune --expired [--apply]\n'));
+    process.exit(1);
+  }
+
+  const waiversManager = new WaiversManager();
+
+  // Fast path: no waivers directory or no waiver files at all.
+  const allWaivers = waiversManager.enumerateWaiverFiles();
+  if (allWaivers.length === 0) {
+    const msg = 'No active waivers to check.';
+    if (options.json) {
+      console.log(JSON.stringify({ status: 'ok', pruned: [], message: msg }));
+    } else {
+      console.log(chalk.yellow(`\n${msg}\n`));
+    }
+    return { pruned: [], applied: false };
+  }
+
+  const candidates = waiversManager.findExpiredWaivers();
+
+  // No prunable waivers — report and return.
+  if (candidates.length === 0) {
+    const msg = 'No expired waivers to prune.';
+    if (options.json) {
+      console.log(JSON.stringify({ status: 'ok', pruned: [], message: msg }));
+    } else {
+      console.log(chalk.green(`\n${msg}\n`));
+    }
+    return { pruned: [], applied: false };
+  }
+
+  const apply = Boolean(options.apply);
+
+  if (!apply) {
+    // Dry run — report only, no disk changes, no events.
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          status: 'dry_run',
+          applied: false,
+          pruned: candidates.map((c) => ({ id: c.id, expires_at: c.expires_at })),
+        })
+      );
+    } else {
+      console.log(chalk.yellow(`\nDry run — ${candidates.length} waiver(s) would be pruned:\n`));
+      candidates.forEach((c) => {
+        console.log(`  ${chalk.bold(c.id)}  expired at ${c.expires_at}`);
+      });
+      console.log(chalk.dim('\nRe-run with --apply to transition status to expired.\n'));
+    }
+    return { pruned: candidates, applied: false };
+  }
+
+  // Apply path — transition each file and emit events.
+  const { appendEvent } = require('../utils/event-log');
+  const pruned = [];
+  const failures = [];
+
+  for (const c of candidates) {
+    try {
+      const updated = waiversManager.markWaiverExpired(c.path);
+
+      // Emit waiver_pruned event. spec_id is optional for this event
+      // (waivers may or may not be tied to a spec). Using the waiver's
+      // applies_to field when available, otherwise omitting.
+      const spec_id =
+        updated && typeof updated.applies_to === 'string' && updated.applies_to.trim() !== ''
+          ? updated.applies_to
+          : undefined;
+
+      await appendEvent({
+        actor: 'cli',
+        event: 'waiver_pruned',
+        spec_id,
+        data: {
+          waiver_id: c.id,
+          expires_at: c.expires_at,
+          previous_status: 'active',
+          new_status: 'expired',
+        },
+      });
+
+      pruned.push({ id: c.id, expires_at: c.expires_at });
+    } catch (err) {
+      failures.push({ id: c.id, error: err.message });
+    }
+  }
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        status: failures.length === 0 ? 'ok' : 'partial',
+        applied: true,
+        pruned,
+        failures,
+      })
+    );
+  } else {
+    console.log(
+      chalk.green(`\nPruned ${pruned.length} expired waiver(s):\n`)
+    );
+    pruned.forEach((p) => {
+      console.log(`  ${chalk.bold(p.id)}  (was expired at ${p.expires_at})`);
+    });
+    if (failures.length > 0) {
+      console.log(chalk.red(`\n${failures.length} failure(s):\n`));
+      failures.forEach((f) => {
+        console.log(`  ${chalk.bold(f.id)}: ${f.error}`);
+      });
+    }
+    console.log();
+  }
+
+  return { pruned, applied: true, failures };
+}
+
 /**
  * Add waiver to active waivers file for quality gates integration
  */

package/dist/commands/worktree.js

@@ -12,7 +12,12 @@ const {
   mergeWorktree,
   pruneWorktrees,
   repairWorktrees,
+  loadRegistry,
+  saveRegistry,
+  getRepoRoot,
+  findFeatureSpecPath,
 } = require('../worktree/worktree-manager');
+const { getAgentSessionId } = require('../utils/agent-session');
 
 /**
  * Handle worktree subcommands
@@ -34,9 +39,11 @@ async function worktreeCommand(subcommand, options = {}) {
         return handlePrune(options);
       case 'repair':
         return handleRepair(options);
+      case 'bind':
+        return handleBind(options);
       default:
         console.error(chalk.red(`Unknown worktree subcommand: ${subcommand}`));
-        console.log(chalk.blue('Available: create, list, destroy, merge, prune, repair'));
+        console.log(chalk.blue('Available: create, list, destroy, merge, prune, repair, bind'));
         process.exit(1);
     }
   } catch (error) {
@@ -76,27 +83,47 @@ function handleList() {
   }
 
   const maxNameLen = Math.max(18, ...entries.map((e) => e.name.length + 2));
-  const totalWidth = maxNameLen + 12 + 20 + 16 + 10;
+  const maxBranchLen = Math.max(20, ...entries.map((e) => (e.branch || '').length + 2));
+  const totalWidth = maxNameLen + 14 + maxBranchLen + 16 + 16;
   console.log(chalk.bold.cyan('CAWS Worktrees'));
   console.log(chalk.cyan('='.repeat(totalWidth)));
   console.log(
     chalk.bold(
       'Name'.padEnd(maxNameLen) +
-        'Status'.padEnd(12) +
-        'Branch'.padEnd(20) +
+        'Status'.padEnd(14) +
+        'Branch'.padEnd(maxBranchLen) +
         'Last Commit'.padEnd(16) +
-        'Owner'
+        'Session'
     )
   );
   console.log(chalk.gray('-'.repeat(totalWidth)));
 
+  // Show current session for comparison
+  const currentSession = getAgentSessionId(process.cwd());
+  if (currentSession) {
+    const shortCurrent = currentSession.length > 8 ? '...' + currentSession.slice(-8) : currentSession;
+    console.log(chalk.gray(`You: ${shortCurrent}`));
+    console.log(chalk.gray('-'.repeat(totalWidth)));
+  }
+
   for (const entry of entries) {
-    const statusColor =
-      entry.status === 'active'
-        ? chalk.green
-        : entry.status === 'destroyed'
-          ? chalk.gray
-          : chalk.yellow;
+    const statusColors = {
+      active: chalk.green,
+      fresh: chalk.cyan,
+      merged: chalk.blue,
+      destroyed: chalk.gray,
+      missing: chalk.red,
+      'stale-merged': chalk.yellow,
+      orphaned: chalk.yellow,
+      unregistered: chalk.yellow,
+    };
+    const statusColor = statusColors[entry.status] || chalk.white;
+
+    // Build status string with dirty indicator
+    let statusStr = entry.status;
+    if (entry.dirty && (entry.status === 'active' || entry.status === 'fresh')) {
+      statusStr += '*';
+    }
 
     // Format last commit age
     let commitAge = chalk.gray('-');
@@ -104,29 +131,29 @@ function handleList() {
       commitAge = chalk.white(entry.lastCommit.age);
     }
 
-    // Format owner — show truncated session ID or '-'
+    // Format owner — show truncated session ID, highlight if it's the current session
     let ownerStr = chalk.gray('-');
     if (entry.owner) {
-      // Show last 8 chars of session ID for readability
       const short = entry.owner.length > 8 ? '...' + entry.owner.slice(-8) : entry.owner;
-      ownerStr = chalk.gray(short);
-    }
-
-    // Status suffix for merged branches
-    let statusStr = entry.status;
-    if (entry.merged && entry.status === 'active') {
-      statusStr = 'merged';
+      if (currentSession && entry.owner === currentSession) {
+        ownerStr = chalk.green(short + ' (you)');
+      } else {
+        ownerStr = chalk.yellow(short);
+      }
     }
 
     console.log(
       entry.name.padEnd(maxNameLen) +
-        statusColor(statusStr.padEnd(12)) +
-        (entry.branch || '').padEnd(20) +
+        statusColor(statusStr.padEnd(14)) +
+        (entry.branch || '').padEnd(maxBranchLen) +
         commitAge.padEnd(16 + 10) + // +10 for chalk color codes
         ownerStr
     );
   }
 
+  // Legend
+  console.log('');
+  console.log(chalk.gray('Status: fresh = no commits yet, active = has commits/changes, active* = dirty files'));
   console.log('');
 }
 
@@ -204,9 +231,10 @@ function handleMerge(options) {
 
 function handlePrune(options) {
   const maxAge = options.maxAge !== undefined ? parseInt(options.maxAge, 10) : 30;
+  const force = options.force || false;
 
   console.log(chalk.cyan(`Pruning worktrees (max age: ${maxAge} days)`));
-  const result = pruneWorktrees({ maxAgeDays: maxAge });
+  const result = pruneWorktrees({ maxAgeDays: maxAge, force });
 
   // Handle both old return format (array) and new format (object with pruned/skipped)
   const pruned = Array.isArray(result) ? result : result.pruned;
@@ -234,6 +262,7 @@ function handlePrune(options) {
 function handleRepair(options) {
   const dryRun = options.dryRun || false;
   const shouldPrune = options.prune || false;
+  const force = options.force || false;
 
   if (dryRun) {
     console.log(chalk.cyan('Repair dry-run (no changes will be persisted)'));
@@ -241,7 +270,7 @@ function handleRepair(options) {
     console.log(chalk.cyan('Repairing worktree registry'));
   }
 
-  const result = repairWorktrees({ prune: shouldPrune, dryRun });
+  const result = repairWorktrees({ prune: shouldPrune, dryRun, force });
 
   if (result.repaired.length === 0 && result.pruned.length === 0 && result.skipped.length === 0) {
     console.log(chalk.green('Registry is consistent. Nothing to repair.'));
@@ -251,10 +280,11 @@ function handleRepair(options) {
   if (result.repaired.length > 0) {
     console.log(chalk.green('\nRepaired ' + result.repaired.length + ' entry/entries:'));
     for (const r of result.repaired) {
+      const ownerTag = r.owner ? chalk.yellow(` [owner: ${r.owner}]`) : '';
       if (r.action === 'registered') {
         console.log(chalk.gray('   + ' + r.name + ' (auto-registered from git)'));
       } else {
-        console.log(chalk.gray('   ~ ' + r.name + ' (' + r.from + ' -> ' + r.to + ')'));
+        console.log(chalk.gray('   ~ ' + r.name + ' (' + r.from + ' -> ' + r.to + ')') + ownerTag);
       }
     }
   }
@@ -262,7 +292,8 @@ function handleRepair(options) {
   if (result.pruned.length > 0) {
     console.log(chalk.green('\nPruned ' + result.pruned.length + ' stale entry/entries:'));
     for (const p of result.pruned) {
-      console.log(chalk.gray('   - ' + p.name + ' (' + p.status + ')'));
+      const ownerTag = p.owner ? chalk.yellow(` [owner: ${p.owner}]`) : '';
+      console.log(chalk.gray('   - ' + p.name + ' (' + p.status + ')') + ownerTag);
     }
   }
 
@@ -278,4 +309,78 @@ function handleRepair(options) {
   }
 }
 
+function handleBind(options) {
+  const path = require('path');
+  const fs = require('fs-extra');
+  const yaml = require('js-yaml');
+  const { specId, name } = options;
+
+  if (!specId) {
+    console.error(chalk.red('Spec ID is required'));
+    console.log(chalk.blue('Usage: caws worktree bind <spec-id> [--name <worktree-name>]'));
+    process.exit(1);
+  }
+
+  // Determine worktree name: from option, or detect from cwd
+  let worktreeName = name;
+  if (!worktreeName) {
+    const root = getRepoRoot();
+    const cwd = process.cwd();
+    const worktreesBase = path.join(root, '.caws', 'worktrees');
+
+    if (cwd.startsWith(worktreesBase + path.sep)) {
+      const relative = path.relative(worktreesBase, cwd);
+      worktreeName = relative.split(path.sep)[0];
+    }
+  }
+
+  if (!worktreeName) {
+    console.error(chalk.red('Could not determine worktree name.'));
+    console.log(chalk.blue('Either run this from inside a worktree, or pass --name <worktree-name>'));
+    process.exit(1);
+  }
+
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  // Find the worktree entry in the registry
+  if (!registry.worktrees || !registry.worktrees[worktreeName]) {
+    console.error(chalk.red(`Worktree '${worktreeName}' not found in registry.`));
+    console.log(chalk.blue('Run: caws worktree list  to see available worktrees'));
+    process.exit(1);
+  }
+
+  // Load the spec file
+  const specPath = findFeatureSpecPath(root, specId);
+  if (!specPath) {
+    console.error(chalk.red(`Spec '${specId}' not found in .caws/specs/`));
+    console.log(chalk.blue('Run: caws specs list  to see available specs'));
+    process.exit(1);
+  }
+
+  const specContent = fs.readFileSync(specPath, 'utf8');
+  const specData = yaml.load(specContent);
+
+  // Warn if spec already bound to a different worktree
+  if (specData.worktree && specData.worktree !== worktreeName) {
+    console.log(chalk.yellow(`Warning: Spec '${specId}' is currently bound to worktree '${specData.worktree}'.`));
+    console.log(chalk.yellow(`Rebinding to '${worktreeName}'.`));
+  }
+
+  // Update registry side: set specId on the worktree entry
+  registry.worktrees[worktreeName].specId = specId;
+  saveRegistry(root, registry);
+
+  // Update spec side: set worktree field
+  specData.worktree = worktreeName;
+  const updatedYaml = yaml.dump(specData, { lineWidth: 120, noRefs: true });
+  fs.writeFileSync(specPath, updatedYaml, 'utf8');
+
+  console.log(chalk.green(`Binding established`));
+  console.log(chalk.gray(`   Worktree: ${worktreeName} -> spec: ${specId}`));
+  console.log(chalk.gray(`   Spec: ${specId} -> worktree: ${worktreeName}`));
+  console.log(chalk.gray(`   Registry: ${path.join(root, '.caws', 'worktrees.json')}`));
+  console.log(chalk.gray(`   Spec file: ${specPath}`));
+}
+
 module.exports = { worktreeCommand };

package/dist/error-handler.js

@@ -7,9 +7,7 @@
 const chalk = require('chalk');
 const {
   ERROR_CATEGORIES,
-  ERROR_CODES,
   getErrorCategory,
-  getCategorySuggestions,
 } = require('./utils/error-categories');
 
 /**
@@ -73,7 +71,7 @@ async function safeAsync(operation, context = '', includeTiming = false) {
   try {
     const result = await operation();
 
-    if (includeTiming && timer) {
+    if (includeTiming && timer && !isJsonOutput() && process.env.CAWS_QUIET !== '1') {
       const duration = timer.formatDuration();
       console.log(chalk.gray(`   (completed in ${duration})`));
     }
@@ -110,7 +108,7 @@ function safeSync(operation, context = '', includeTiming = false) {
   try {
     const result = operation();
 
-    if (includeTiming && timer) {
+    if (includeTiming && timer && !isJsonOutput() && process.env.CAWS_QUIET !== '1') {
       const duration = timer.formatDuration();
       console.log(chalk.gray(`   (completed in ${duration})`));
     }
@@ -182,15 +180,6 @@ const COMMAND_SUGGESTIONS = {
       suggestions.push(`Did you mean: caws ${similar}?`);
     }
 
-    // Context-aware suggestions based on command type
-    const commandCategories = {
-      setup: ['init', 'scaffold', 'templates'],
-      validation: ['validate', 'status', 'diagnose'],
-      analysis: ['evaluate', 'iterate', 'test-analysis'],
-      compliance: ['waivers', 'workflow', 'quality-monitor'],
-      history: ['provenance', 'hooks'],
-    };
-
     // Suggest category based on what user might be trying to do
     if (command.includes('setup') || command.includes('start') || command.includes('create')) {
       suggestions.push('For project setup: caws init');