@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/commands/worktree.js

@@ -13,6 +13,7 @@ const {
   pruneWorktrees,
   repairWorktrees,
 } = require('../worktree/worktree-manager');
+const { getAgentSessionId } = require('../utils/agent-session');
 
 /**
  * Handle worktree subcommands
@@ -76,27 +77,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 +125,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 +225,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 +256,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 +264,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 +274,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 +286,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);
     }
   }
 

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');

package/dist/gates/budget-limit.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Budget enforcement gate
+ * Checks changes against tier budget limits from policy.
+ * Context-aware: commit context counts staged changes, cli context skips (budget is per-change, not per-repo).
+ * @author @darianrosebrook
+ */
+
+const { deriveBudget, checkBudgetCompliance } = require('../budget-derivation');
+const { execSync } = require('child_process');
+
+const name = 'budget_limit';
+
+/**
+ * Count staged files and lines of code from git diff
+ * @param {string[]} stagedFiles - List of staged file paths
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Stats with files_changed and lines_changed
+ */
+function getStagedStats(stagedFiles, projectRoot) {
+  const filesChanged = stagedFiles.length;
+  let linesChanged = 0;
+
+  try {
+    const numstat = execSync('git diff --cached --numstat', {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    for (const line of numstat.trim().split('\n').filter(Boolean)) {
+      const [added, removed] = line.split('\t');
+      const addedNum = added === '-' ? 0 : parseInt(added, 10) || 0;
+      const removedNum = removed === '-' ? 0 : parseInt(removed, 10) || 0;
+      linesChanged += addedNum + removedNum;
+    }
+  } catch (err) {
+    // Fail-closed: if git fails, we cannot verify budget compliance
+    return {
+      files_changed: filesChanged,
+      lines_changed: -1,
+      error: `Cannot count staged line changes: ${err.message}`,
+    };
+  }
+
+  return { files_changed: filesChanged, lines_changed: linesChanged };
+}
+
+/**
+ * Run the budget limit gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - Staged file paths
+ * @param {Object} params.spec - Working spec
+ * @param {Object} params.policy - Policy configuration
+ * @param {string} params.projectRoot - Project root
+ * @param {number} params.riskTier - Risk tier number
+ * @param {string} [params.context] - Execution context (commit, cli, edit)
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, spec, _policy, projectRoot, riskTier, context }) {
+  const messages = [];
+
+  // Budget limits apply to changes, not to the entire repo.
+  // In cli context with all tracked files, budget check is meaningless.
+  if (context === 'cli') {
+    return { status: 'pass', messages: ['Budget check skipped in CLI context (budget applies to changes, not full repo)'] };
+  }
+
+  // Build a minimal spec for deriveBudget
+  const specForBudget = {
+    risk_tier: riskTier,
+    waiver_ids: spec?.waiver_ids || [],
+  };
+
+  try {
+    const budget = await deriveBudget(specForBudget, projectRoot, { useCache: true });
+    const stats = getStagedStats(stagedFiles, projectRoot);
+
+    // Fail-closed: if git stats errored, report it
+    if (stats.error) {
+      messages.push(stats.error);
+      return { status: 'fail', messages };
+    }
+
+    const compliance = checkBudgetCompliance(budget, stats);
+
+    if (!compliance.compliant) {
+      for (const violation of compliance.violations) {
+        messages.push(violation.message);
+      }
+      return { status: 'fail', messages };
+    }
+
+    // Emit budget:pressure if usage > 80% but still compliant
+    try {
+      const filePercent = budget.max_files > 0 ? stats.files_changed / budget.max_files : 0;
+      const locPercent = budget.max_loc > 0 ? stats.lines_changed / budget.max_loc : 0;
+      if (filePercent > 0.8 || locPercent > 0.8) {
+        const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
+        lifecycle.emit(EVENTS.BUDGET_PRESSURE, {
+          specId: spec?.id || null,
+          filesUsed: stats.files_changed,
+          filesLimit: budget.max_files,
+          locUsed: stats.lines_changed,
+          locLimit: budget.max_loc,
+          percentUsed: Math.round(Math.max(filePercent, locPercent) * 100),
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch { /* non-fatal */ }
+
+    return { status: 'pass', messages };
+  } catch (err) {
+    return { status: 'fail', messages: [`Budget check error: ${err.message}`] };
+  }
+}
+
+module.exports = { name, run };

package/dist/gates/feedback.js

@@ -0,0 +1,260 @@
+/**
+ * @fileoverview Gate Feedback Enrichment
+ *
+ * Post-processes raw gate results into enriched feedback with:
+ * - why: human-readable explanation of the failure
+ * - category: scope | policy | quality | architectural
+ * - recurrence: how many times this gate has failed recently
+ * - nextStep: the smallest safe action to resolve
+ * - remediation: a CLI command to fix or waive
+ *
+ * This module sits between the gate pipeline output and the formatter.
+ *
+ * @author @darianrosebrook
+ */
+
+// ---------------------------------------------------------------------------
+// Gate → category mapping
+// ---------------------------------------------------------------------------
+
+const GATE_CATEGORIES = {
+  scope_boundary: 'scope',
+  budget_limit: 'policy',
+  god_object: 'architectural',
+  todo_detection: 'quality',
+  spec_completeness: 'quality',
+};
+
+// ---------------------------------------------------------------------------
+// Per-gate enrichment
+// ---------------------------------------------------------------------------
+
+/**
+ * Enrich a scope_boundary failure.
+ * Messages follow: "Out of scope (excluded): FILE" or "Out of scope (not in allowed paths): FILE"
+ */
+function enrichScopeBoundary(gate, spec) {
+  const scopeIn = spec?.scope?.in || [];
+  const files = gate.messages
+    .filter(m => m.startsWith('Out of scope'))
+    .map(m => m.replace(/^Out of scope \([^)]+\): /, ''));
+
+  if (files.length === 0) return null;
+
+  const why = files.length === 1
+    ? `${files[0]} is outside scope.in patterns [${scopeIn.join(', ')}]`
+    : `${files.length} files are outside scope.in patterns [${scopeIn.join(', ')}]`;
+
+  return {
+    why,
+    nextStep: files.length === 1
+      ? `Add the file's directory to scope.in, or move the change to a separate spec`
+      : `Expand scope.in to cover these paths, or split into a separate spec`,
+    remediation: 'caws waivers create --gates scope_boundary',
+  };
+}
+
+/**
+ * Enrich a budget_limit failure.
+ * Messages follow: violation messages from checkBudgetCompliance.
+ */
+function enrichBudgetLimit(gate) {
+  const why = gate.messages.length > 0
+    ? gate.messages[0]
+    : 'Change exceeds the budget limits for this risk tier';
+
+  return {
+    why,
+    nextStep: 'Split this change into smaller commits, or request a waiver',
+    remediation: 'caws waivers create --gates budget_limit',
+  };
+}
+
+/**
+ * Enrich a god_object failure.
+ * Messages follow: "CRITICAL: FILE has N lines (threshold: T)"
+ */
+function enrichGodObject(gate) {
+  const criticals = gate.messages.filter(m => m.startsWith('CRITICAL'));
+  const file = criticals.length > 0
+    ? criticals[0].replace(/^CRITICAL[^:]*: /, '').replace(/ has \d+.*/, '')
+    : null;
+
+  const why = criticals.length > 0
+    ? criticals[0]
+    : gate.messages[0] || 'File exceeds line-count threshold';
+
+  return {
+    why,
+    nextStep: file
+      ? `Extract helper modules from ${file} to reduce its size`
+      : 'Extract helper modules to reduce file size',
+    remediation: 'caws waivers create --gates god_object',
+  };
+}
+
+/**
+ * Enrich a todo_detection failure.
+ * Messages follow: "FILE:LINE: MARKER found"
+ */
+function enrichTodoDetection(gate) {
+  const markers = gate.messages.filter(m => m.includes(' found'));
+  const why = markers.length > 0
+    ? `${markers.length} TODO/FIXME marker(s) detected in staged changes`
+    : 'Actionable markers detected';
+
+  return {
+    why,
+    nextStep: 'Resolve the TODO/FIXME items before committing, or convert to tracked issues',
+    remediation: 'caws waivers create --gates todo_detection',
+  };
+}
+
+/**
+ * Enrich a spec_completeness failure.
+ */
+function enrichSpecCompleteness(gate) {
+  return {
+    why: gate.messages[0] || 'Working spec does not pass schema validation',
+    nextStep: 'Run: caws validate for detailed errors and suggestions',
+    remediation: null,
+  };
+}
+
+/**
+ * Generic fallback enrichment.
+ */
+function enrichGeneric(gate) {
+  return {
+    why: gate.messages[0] || `Gate "${gate.name}" failed`,
+    nextStep: `Investigate the gate failure and resolve the issue`,
+    remediation: `caws waivers create --gates ${gate.name}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Enrichment dispatch
+// ---------------------------------------------------------------------------
+
+const ENRICHERS = {
+  scope_boundary: enrichScopeBoundary,
+  budget_limit: enrichBudgetLimit,
+  god_object: enrichGodObject,
+  todo_detection: enrichTodoDetection,
+  spec_completeness: enrichSpecCompleteness,
+};
+
+// ---------------------------------------------------------------------------
+// Recurrence detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check how many recent gate runs had this gate failing.
+ * Uses working state history entries where command === 'gates'.
+ * @param {string} gateName
+ * @param {object|null} state - Working state object
+ * @returns {{ count: number, lastSeen: string }|null}
+ */
+function getRecurrence(gateName, state) {
+  if (!state?.history) return null;
+
+  // Look at previous gate run results stored in state.gates
+  // History entries only have command + summary, but state.gates.results
+  // has the per-gate results from the LAST run. For recurrence we need
+  // to check if the current failure matches blockers that existed before.
+  // Since we only store the latest gate results, we count consecutive
+  // history entries with "blocked" in their summary.
+  const gateEntries = state.history.filter(h => h.command === 'gates');
+  if (gateEntries.length <= 1) return null; // Only the current run
+
+  let count = 0;
+  let lastSeen = null;
+
+  // Count backward from second-to-last (the previous runs, not current)
+  for (let i = gateEntries.length - 2; i >= 0; i--) {
+    const entry = gateEntries[i];
+    // Summary format: "N passed, M blocked, K warned"
+    // Must check for non-zero blocked count (not just substring "blocked")
+    const blockedMatch = entry.summary && entry.summary.match(/(\d+) blocked/);
+    if (blockedMatch && parseInt(blockedMatch[1], 10) > 0) {
+      count++;
+      if (!lastSeen) lastSeen = entry.timestamp;
+    } else {
+      break; // Stop at first non-blocked run
+    }
+  }
+
+  if (count === 0) return null;
+
+  // Format lastSeen as relative time
+  const lastSeenRelative = formatTimeSince(lastSeen);
+
+  return { count, lastSeen: lastSeenRelative };
+}
+
+/**
+ * Format an ISO timestamp as a relative time string.
+ * @param {string} isoTimestamp
+ * @returns {string}
+ */
+function formatTimeSince(isoTimestamp) {
+  if (!isoTimestamp) return 'unknown';
+  const diff = Date.now() - new Date(isoTimestamp).getTime();
+  if (isNaN(diff)) return 'unknown';
+
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+// ---------------------------------------------------------------------------
+// Main enrichment function
+// ---------------------------------------------------------------------------
+
+/**
+ * Enrich gate results with contextual feedback.
+ * @param {object} report - Pipeline report from evaluateGates()
+ * @param {object} context
+ * @param {object} [context.spec] - Resolved spec
+ * @param {object} [context.state] - Working state (from loadState)
+ * @returns {Map<string, object>} Map of gate name → enrichment object
+ */
+function enrichGateResults(report, context = {}) {
+  const { spec, state } = context;
+  const enrichments = new Map();
+
+  for (const gate of report.gates) {
+    // Only enrich failed or warned gates
+    if (gate.status === 'pass' || gate.status === 'skipped') continue;
+    if (gate.waived) continue;
+
+    const enricher = ENRICHERS[gate.name] || enrichGeneric;
+    const result = enricher(gate, spec);
+    if (!result) continue;
+
+    const category = GATE_CATEGORIES[gate.name] || 'quality';
+    const recurrence = getRecurrence(gate.name, state);
+
+    enrichments.set(gate.name, {
+      gate: gate.name,
+      category,
+      why: result.why,
+      recurrence,
+      nextStep: result.nextStep,
+      remediation: result.remediation,
+    });
+  }
+
+  return enrichments;
+}
+
+module.exports = {
+  enrichGateResults,
+  getRecurrence,
+  formatTimeSince,
+  GATE_CATEGORIES,
+};