@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/test-analysis.js

@@ -7,6 +7,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
+const { resolveSpec } = require('./utils/spec-resolver');
 
 /**
  * Waiver Pattern Learning Engine
@@ -198,7 +199,7 @@ class WaiverPatternLearner {
   /**
    * Analyze budget overrun patterns
    */
-  analyzeBudgetOverruns(waivers, specs) {
+  analyzeBudgetOverruns(waivers, _specs) {
     const budgetWaivers = waivers.filter((w) => w.gates?.includes('budget_limit'));
 
     if (budgetWaivers.length === 0) {
@@ -266,7 +267,7 @@ class WaiverPatternLearner {
   /**
    * Identify risk factors from waiver patterns
    */
-  identifyRiskFactors(waivers, specs) {
+  identifyRiskFactors(waivers, _specs) {
     // Simple risk factor identification based on waiver frequency
     const riskFactors = [];
 
@@ -595,17 +596,17 @@ class BudgetPredictor {
 /**
  * Main Test Analysis CLI handler
  */
-async function testAnalysisCommand(subcommand, options = []) {
+async function testAnalysisCommand(subcommand, options = [], commandOptions = {}) {
   const chalk = (await import('chalk')).default;
 
   try {
     switch (subcommand) {
       case 'assess-budget':
-        return await handleAssessBudget(options);
+        return await handleAssessBudget(options, commandOptions);
       case 'analyze-patterns':
         return await handleAnalyzePatterns(options);
       case 'find-similar':
-        return await handleFindSimilar(options);
+        return await handleFindSimilar(options, commandOptions);
       default:
         console.log(chalk.red('Unknown test-analysis subcommand'));
         console.log('Available commands:');
@@ -619,28 +620,49 @@ async function testAnalysisCommand(subcommand, options = []) {
   }
 }
 
+/**
+ * Resolve the current spec for analysis commands.
+ * Supports explicit `--spec <path>` for compatibility, but prefers
+ * the suite-standard resolver and `--spec-id`.
+ * @param {string[]} optionArgs
+ * @param {Object} commandOptions
+ * @returns {Promise<{spec: Object, specPath: string}>}
+ */
+async function resolveAnalysisSpec(optionArgs = [], commandOptions = {}) {
+  let specFile = null;
+  if (Array.isArray(optionArgs) && optionArgs.includes('--spec')) {
+    const specIndex = optionArgs.indexOf('--spec');
+    if (specIndex + 1 < optionArgs.length) {
+      specFile = optionArgs[specIndex + 1];
+    }
+  }
+
+  const resolved = await resolveSpec({
+    specId: commandOptions.specId,
+    specFile,
+    warnLegacy: false,
+    interactive: false,
+  });
+
+  return {
+    spec: resolved.spec,
+    specPath: resolved.path,
+  };
+}
+
 /**
  * Handle budget assessment command
  */
-async function handleAssessBudget(options) {
+async function handleAssessBudget(options, commandOptions = {}) {
   const chalk = (await import('chalk')).default;
   const predictor = new BudgetPredictor();
 
-  // Load current spec
-  let specPath = '.caws/working-spec.yaml';
-  if (options.includes('--spec')) {
-    const specIndex = options.indexOf('--spec');
-    if (specIndex + 1 < options.length) {
-      specPath = options[specIndex + 1];
-    }
-  }
-
   try {
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
+    const { spec, specPath } = await resolveAnalysisSpec(options, commandOptions);
 
     console.log(chalk.cyan(`Budget Assessment for ${spec.id}`));
     console.log('==============================================');
+    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
 
     const result = predictor.assessBudget(spec);
 
@@ -681,7 +703,7 @@ async function handleAssessBudget(options) {
 /**
  * Handle pattern analysis command
  */
-async function handleAnalyzePatterns(options) {
+async function handleAnalyzePatterns(_options) {
   const chalk = (await import('chalk')).default;
   const learner = new WaiverPatternLearner();
 
@@ -727,25 +749,16 @@ async function handleAnalyzePatterns(options) {
 /**
  * Handle find similar projects command
  */
-async function handleFindSimilar(options) {
+async function handleFindSimilar(options, commandOptions = {}) {
   const chalk = (await import('chalk')).default;
   const matcher = new ProjectSimilarityMatcher();
 
-  // Load current spec
-  let specPath = '.caws/working-spec.yaml';
-  if (options.includes('--spec')) {
-    const specIndex = options.indexOf('--spec');
-    if (specIndex + 1 < options.length) {
-      specPath = options[specIndex + 1];
-    }
-  }
-
   try {
-    const specContent = fs.readFileSync(specPath, 'utf8');
-    const spec = yaml.load(specContent);
+    const { spec, specPath } = await resolveAnalysisSpec(options, commandOptions);
 
     console.log(chalk.cyan(`Finding projects similar to ${spec.id}`));
     console.log('==============================================');
+    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
 
     const similar = matcher.findSimilarProjects(spec);
 

package/dist/tool-loader.js

@@ -128,7 +128,7 @@ class ToolLoader extends EventEmitter {
       this.emit('tool:loaded', { id: toolId, metadata: tool.metadata });
 
       return tool;
-    }, `Tool loading failed: ${toolId}`);
+    }, 'Tool loading failed');
   }
 
   /**

package/dist/utils/agent-session.js

@@ -0,0 +1,202 @@
+/**
+ * Agent Session Identity
+ *
+ * Provides a unified way to identify the current agent session across
+ * Claude Code, Cursor, and other IDE agent environments.
+ *
+ * Sources checked (first match wins):
+ *   1. CLAUDE_SESSION_ID  — set by Claude Code automatically
+ *   2. .caws/agents.json  — written by Cursor session-log hook (conversation_id)
+ *   3. CURSOR_TRACE_ID    — set by Cursor (per-request, not stable, last resort)
+ *
+ * The agent registry (.caws/agents.json) also tracks active agents for
+ * multi-agent coordination. Entries expire after a configurable TTL.
+ *
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_REGISTRY = '.caws/agents.json';
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Get the current agent's session ID from the best available source.
+ * @param {string} [projectRoot] - Project root (for reading agent registry)
+ * @returns {string|null} Session ID or null if not in an agent context
+ */
+function getAgentSessionId(projectRoot) {
+  // 1. Claude Code — most reliable, set automatically
+  if (process.env.CLAUDE_SESSION_ID) {
+    return process.env.CLAUDE_SESSION_ID;
+  }
+
+  // 2. Agent registry — written by Cursor session-log hook
+  if (projectRoot) {
+    const registry = loadAgentRegistry(projectRoot);
+    const active = findActiveAgent(registry);
+    if (active) {
+      return active.sessionId;
+    }
+  }
+
+  // 3. Cursor trace ID — per-request, not stable, but better than nothing
+  if (process.env.CURSOR_TRACE_ID) {
+    return `cursor:${process.env.CURSOR_TRACE_ID}`;
+  }
+
+  return null;
+}
+
+/**
+ * Get the agent platform name.
+ * @returns {string} 'claude-code' | 'cursor' | 'unknown'
+ */
+function getAgentPlatform() {
+  if (process.env.CLAUDE_SESSION_ID) return 'claude-code';
+  if (process.env.CURSOR_TRACE_ID) return 'cursor';
+  return 'unknown';
+}
+
+/**
+ * Load the agent registry, pruning stale entries.
+ * @param {string} root - Project root
+ * @returns {object} Registry with { agents: { [sessionId]: entry } }
+ */
+function loadAgentRegistry(root) {
+  const registryPath = path.join(root, AGENTS_REGISTRY);
+  let registry = { version: 1, agents: {} };
+
+  if (fs.existsSync(registryPath)) {
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch {
+      // Corrupt file — start fresh
+      registry = { version: 1, agents: {} };
+    }
+  }
+
+  // Prune stale entries on every read
+  const now = Date.now();
+  let pruned = false;
+  for (const [id, entry] of Object.entries(registry.agents || {})) {
+    const ttl = entry.ttl || DEFAULT_TTL_MS;
+    const lastSeenTime = entry.lastSeen ? new Date(entry.lastSeen).getTime() : 0;
+    const lastSeen = isNaN(lastSeenTime) ? 0 : lastSeenTime;
+    if (now - lastSeen > ttl) {
+      delete registry.agents[id];
+      pruned = true;
+    }
+  }
+
+  if (pruned) {
+    saveAgentRegistry(root, registry);
+  }
+
+  return registry;
+}
+
+/**
+ * Save the agent registry atomically (write-then-rename).
+ * @param {string} root - Project root
+ * @param {object} registry - Registry object
+ */
+function saveAgentRegistry(root, registry) {
+  const registryPath = path.join(root, AGENTS_REGISTRY);
+  const dir = path.dirname(registryPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = registryPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2));
+  fs.renameSync(tmpPath, registryPath);
+}
+
+/**
+ * Register or heartbeat an agent session.
+ * Called by session-log hooks to keep entries fresh.
+ * @param {string} root - Project root
+ * @param {object} agent - Agent info
+ * @param {string} agent.sessionId - Unique session/conversation ID
+ * @param {string} agent.platform - 'claude-code' | 'cursor' | 'unknown'
+ * @param {string} [agent.model] - Model name if known
+ * @param {string} [agent.specId] - Active spec ID if known
+ * @param {number} [agent.ttl] - Custom TTL in ms (default 30 min)
+ */
+function heartbeatAgent(root, agent) {
+  const registry = loadAgentRegistry(root);
+  const existing = registry.agents[agent.sessionId] || {};
+
+  registry.agents[agent.sessionId] = {
+    ...existing,
+    sessionId: agent.sessionId,
+    platform: agent.platform || existing.platform || 'unknown',
+    model: agent.model || existing.model || null,
+    specId: agent.specId || existing.specId || null,
+    ttl: agent.ttl || existing.ttl || DEFAULT_TTL_MS,
+    firstSeen: existing.firstSeen || new Date().toISOString(),
+    lastSeen: new Date().toISOString(),
+  };
+
+  saveAgentRegistry(root, registry);
+}
+
+/**
+ * Remove an agent session from the registry.
+ * Called on session stop.
+ * @param {string} root - Project root
+ * @param {string} sessionId - Session to remove
+ */
+function removeAgent(root, sessionId) {
+  const registry = loadAgentRegistry(root);
+  delete registry.agents[sessionId];
+  saveAgentRegistry(root, registry);
+}
+
+/**
+ * Find the most recently active agent for this terminal/process.
+ * Prefers agents that match the current environment.
+ * @param {object} registry - Loaded registry
+ * @returns {object|null} Agent entry or null
+ */
+function findActiveAgent(registry) {
+  const agents = Object.values(registry.agents || {});
+  if (agents.length === 0) return null;
+
+  // If we're in Cursor, prefer cursor agents
+  const isCursor = !!process.env.CURSOR_TRACE_ID;
+  const preferred = agents.filter(a => {
+    if (isCursor) return a.platform === 'cursor';
+    return a.platform === 'claude-code';
+  });
+
+  const pool = preferred.length > 0 ? preferred : agents;
+
+  // Return most recently seen
+  pool.sort((a, b) => new Date(b.lastSeen) - new Date(a.lastSeen));
+  return pool[0];
+}
+
+/**
+ * List all currently active (non-expired) agents.
+ * @param {string} root - Project root
+ * @returns {object[]} Array of agent entries
+ */
+function listActiveAgents(root) {
+  const registry = loadAgentRegistry(root);
+  return Object.values(registry.agents || {});
+}
+
+module.exports = {
+  getAgentSessionId,
+  getAgentPlatform,
+  loadAgentRegistry,
+  saveAgentRegistry,
+  heartbeatAgent,
+  removeAgent,
+  findActiveAgent,
+  listActiveAgents,
+  AGENTS_REGISTRY,
+  DEFAULT_TTL_MS,
+};

package/dist/utils/detection.js

@@ -33,11 +33,17 @@ function findPackageRoot(startDir = __dirname) {
  * @returns {Object} Setup information
  */
 function detectCAWSSetup(cwd = process.cwd()) {
-  // Skip logging for version/help commands
+  // Skip logging for version/help/quiet commands, or when CAWS_QUIET is set.
+  // Verbose detection output contributes to Claude Code context-window
+  // exhaustion when agents run many caws commands in a single session.
   const isQuietCommand =
     process.argv.includes('--version') ||
     process.argv.includes('-V') ||
-    process.argv.includes('--help');
+    process.argv.includes('--help') ||
+    process.argv.includes('--json') ||
+    process.argv.includes('--quiet') ||
+    process.argv.includes('-q') ||
+    process.env.CAWS_QUIET === '1';
 
   if (!isQuietCommand) {
     console.log(chalk.blue('Detecting CAWS setup...'));

package/dist/utils/finalization.js

@@ -95,7 +95,7 @@ async function finalizeProject(projectName, options, answers) {
       ],
       prompts: Object.keys(answers),
       commit: null, // Will be set after git init
-      artifacts: ['.caws/working-spec.yaml'],
+      artifacts: ['.caws/specs/', '.caws/working-spec.yaml'],
       results: {
         project_id: answers.projectId,
         project_title: answers.projectTitle,
@@ -212,13 +212,14 @@ function continueToSuccess() {
   }
 
   console.log(chalk.bold('\nNext steps:'));
-  console.log('1. Customize .caws/working-spec.yaml');
-  console.log('2. Review added CAWS tools and documentation');
+  console.log('1. Customize .caws/specs/<spec-id>.yaml');
+  console.log('2. Treat .caws/working-spec.yaml as a compatibility mirror');
+  console.log('3. Review added CAWS tools and documentation');
   if (!isCurrentDir) {
-    console.log('3. Move CAWS files to your main project if needed');
+    console.log('4. Move CAWS files to your main project if needed');
   }
-  console.log('4. npm install (if using Node.js)');
-  console.log('5. Set up your CI/CD pipeline');
+  console.log('5. npm install (if using Node.js)');
+  console.log('6. Set up your CI/CD pipeline');
   console.log(chalk.blue('\nFor help: caws --help'));
 }
 

package/dist/utils/gitignore-updater.js

@@ -58,6 +58,9 @@ caws-debug.log*
 caws.local.*
 .caws/local.*
 
+# CAWS working state (runtime, not committed)
+.caws/state/
+
 # CAWS Worktrees (local, should not be tracked)
 .caws/worktrees/
 .caws/worktrees.json

package/dist/utils/lifecycle-events.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Governance Lifecycle Events
+ *
+ * A lightweight event system for governance-significant moments in CAWS.
+ * Events fire synchronously within command execution and are consumed by
+ * the working-state layer, feedback enrichment, and future sidecar flows.
+ *
+ * This is NOT the same as IDE hooks (shell scripts in .claude/hooks/).
+ * These are internal CAWS events emitted by CLI commands and gates.
+ *
+ * @author @darianrosebrook
+ */
+
+const { EventEmitter } = require('events');
+
+/**
+ * Singleton lifecycle event emitter.
+ * @type {EventEmitter}
+ */
+const lifecycle = new EventEmitter();
+lifecycle.setMaxListeners(20);
+
+/**
+ * Event name constants.
+ *
+ * @typedef {Object} GatesBlockedPayload
+ * @property {string|null} specId
+ * @property {string} gateName
+ * @property {string} mode
+ * @property {string[]} messages
+ * @property {string} context - cli | commit | edit
+ * @property {string} timestamp - ISO 8601
+ *
+ * @typedef {Object} GatesPassedPayload
+ * @property {string|null} specId
+ * @property {Object} summary - { blocked, warned, passed, skipped, waived }
+ * @property {string} context
+ * @property {string} timestamp
+ *
+ * @typedef {Object} ValidationFailedPayload
+ * @property {string} specId
+ * @property {Object[]} errors
+ * @property {number} errorCount
+ * @property {number} warningCount
+ * @property {string} timestamp
+ *
+ * @typedef {Object} ValidationPassedPayload
+ * @property {string} specId
+ * @property {string} grade
+ * @property {number} complianceScore
+ * @property {string} timestamp
+ *
+ * @typedef {Object} BudgetPressurePayload
+ * @property {string|null} specId
+ * @property {number} filesUsed
+ * @property {number} filesLimit
+ * @property {number} locUsed
+ * @property {number} locLimit
+ * @property {number} percentUsed
+ * @property {string} timestamp
+ *
+ * @typedef {Object} PhaseTransitionPayload
+ * @property {string} specId
+ * @property {string} oldPhase
+ * @property {string} newPhase
+ * @property {string} timestamp
+ *
+ * @typedef {Object} MergePrePayload
+ * @property {string} worktreeName
+ * @property {string} branch
+ * @property {string} baseBranch
+ * @property {string[]} conflicts
+ * @property {string} timestamp
+ *
+ * @typedef {Object} MergePostPayload
+ * @property {string} worktreeName
+ * @property {string} branch
+ * @property {string} baseBranch
+ * @property {boolean} merged
+ * @property {string[]} conflicts
+ * @property {string} timestamp
+ */
+const EVENTS = {
+  GATES_BLOCKED: 'gates:blocked',
+  GATES_PASSED: 'gates:passed',
+  VALIDATION_FAILED: 'validation:failed',
+  VALIDATION_PASSED: 'validation:passed',
+  BUDGET_PRESSURE: 'budget:pressure',
+  PHASE_TRANSITION: 'phase:transition',
+  MERGE_PRE: 'merge:pre',
+  MERGE_POST: 'merge:post',
+};
+
+module.exports = { lifecycle, EVENTS };

package/dist/utils/quality-gates-utils.js

@@ -29,43 +29,6 @@ const CONFIG = {
   },
 };
 
-/**
- * Check if a waiver applies to the given gate
- * @param {string} gate - Gate name to check
- * @returns {Object} Waiver check result
- */
-function checkWaiver(gate) {
-  try {
-    const waiversPath = path.join(process.cwd(), '.caws/waivers.yml');
-    if (!fs.existsSync(waiversPath)) {
-      return { waived: false, reason: 'No waivers file found' };
-    }
-
-    const waiversConfig = yaml.load(fs.readFileSync(waiversPath, 'utf8'));
-    const now = new Date();
-
-    // Find active waivers for this gate
-    const activeWaivers =
-      waiversConfig.waivers?.filter((waiver) => {
-        const expiresAt = new Date(waiver.expires_at);
-        return waiver.gates.includes(gate) && expiresAt > now && waiver.status === 'active';
-      }) || [];
-
-    if (activeWaivers.length > 0) {
-      const waiver = activeWaivers[0];
-      return {
-        waived: true,
-        waiver,
-        reason: `Active waiver: ${waiver.title} (expires: ${waiver.expires_at})`,
-      };
-    }
-
-    return { waived: false, reason: 'No active waivers found' };
-  } catch (error) {
-    return { waived: false, reason: `Waiver check failed: ${error.message}` };
-  }
-}
-
 /**
  * Detect if project is in crisis response mode
  * @returns {boolean} True if in crisis mode
@@ -73,12 +36,32 @@ function checkWaiver(gate) {
 function detectCrisisMode() {
   try {
     const crisisIndicators = [
-      // Check for crisis response in working spec
+      // Check for crisis response in any active spec (feature specs then legacy)
       () => {
-        const specPath = path.join(process.cwd(), '.caws/working-spec.yaml');
-        if (fs.existsSync(specPath)) {
-          const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
-          return spec.mode === 'crisis' || spec.crisis_mode === true;
+        // Check feature specs first
+        const specsDir = path.join(process.cwd(), '.caws/specs');
+        if (fs.existsSync(specsDir)) {
+          try {
+            const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+            for (const file of files) {
+              const spec = yaml.load(fs.readFileSync(path.join(specsDir, file), 'utf8'));
+              if (spec && (spec.mode === 'crisis' || spec.crisis_mode === true)) {
+                return true;
+              }
+            }
+          } catch {
+            // Fall through to legacy check
+          }
+        }
+        // Legacy fallback
+        const legacyPath = path.join(process.cwd(), '.caws/working-spec.yaml');
+        if (fs.existsSync(legacyPath)) {
+          try {
+            const spec = yaml.load(fs.readFileSync(legacyPath, 'utf8'));
+            return spec.mode === 'crisis' || spec.crisis_mode === true;
+          } catch {
+            // Ignore
+          }
         }
         return false;
       },
@@ -110,7 +93,10 @@ function detectCrisisMode() {
  */
 function getStagedFiles() {
   try {
-    const stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' })
+    const stagedFiles = execSync('git diff --cached --name-only', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
       .trim()
       .split('\n')
       .filter((file) => file.trim() !== '');
@@ -395,7 +381,6 @@ module.exports = {
   getStagedFiles,
   checkGodObjects,
   checkHiddenTodos,
-  checkWaiver,
   detectCrisisMode,
   runQualityGates,
   CONFIG,

package/dist/utils/schema-validator.js

@@ -0,0 +1,42 @@
+const Ajv = require('ajv');
+const fs = require('fs-extra');
+const path = require('path');
+
+const ajv = new Ajv({ allErrors: true, allowUnionTypes: true, strict: false, validateFormats: false });
+const cache = new Map();
+
+function createValidator(schemaPath) {
+  const resolved = path.resolve(schemaPath);
+  if (cache.has(resolved)) return cache.get(resolved);
+  let schema;
+  try {
+    schema = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to parse schema file ${resolved}: ${err.message}`);
+  }
+  // Remove $schema keyword — Ajv handles validation without it and
+  // the 2020-12 meta-schema URI is not bundled with the base Ajv package.
+  delete schema.$schema;
+  const validate = ajv.compile(schema);
+  const validator = (data) => {
+    const valid = validate(data);
+    return {
+      valid,
+      errors: valid ? [] : validate.errors.map(e => ({
+        path: e.instancePath,
+        message: e.message,
+        params: e.params,
+      })),
+    };
+  };
+  cache.set(resolved, validator);
+  return validator;
+}
+
+function getSchemaPath(schemaName, projectRoot) {
+  const projectPath = path.join(projectRoot, '.caws', 'schemas', schemaName);
+  if (fs.existsSync(projectPath)) return projectPath;
+  return path.join(__dirname, '../../templates/.caws/schemas', schemaName);
+}
+
+module.exports = { createValidator, getSchemaPath };