@paths.design/caws-cli 10.0.1 → 10.1.0

package/dist/commands/waivers.js

@@ -66,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'
           );
       }
     },
@@ -178,9 +180,8 @@ async function createWaiver(options) {
     const { createValidator, getSchemaPath } = require('../utils/schema-validator');
     const schemaPath = getSchemaPath('waivers.schema.json', process.cwd());
     const validate = createValidator(schemaPath);
-    // waivers.schema.json uses patternProperties keyed by waiver ID
-    const waiverDoc = { [waiverId]: waiver };
-    const result = validate(waiverDoc);
+    // 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) => {
@@ -248,7 +249,7 @@ async function listWaivers(_options) {
 
     // Validate each loaded waiver against schema
     if (waiverValidate && waiver && waiver.id) {
-      const result = waiverValidate({ [waiver.id]: waiver });
+      const result = waiverValidate(waiver);
       if (!result.valid) {
         console.warn(chalk.yellow(`Schema warning for ${file}:`));
         result.errors.forEach((err) => {
@@ -405,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,6 +12,10 @@ const {
   mergeWorktree,
   pruneWorktrees,
   repairWorktrees,
+  loadRegistry,
+  saveRegistry,
+  getRepoRoot,
+  findFeatureSpecPath,
 } = require('../worktree/worktree-manager');
 const { getAgentSessionId } = require('../utils/agent-session');
 
@@ -35,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) {
@@ -303,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/gates/budget-limit.js

@@ -60,8 +60,13 @@ async function run({ stagedFiles, spec, _policy, projectRoot, riskTier, context
 
   // Budget limits apply to changes, not to the entire repo.
   // In cli context with all tracked files, budget check is meaningless.
+  // Return 'skipped' (not 'pass') so the pipeline summary counts this gate under
+  // `skipped`, matching pipeline.js semantics for gates that did not actually run.
   if (context === 'cli') {
-    return { status: 'pass', messages: ['Budget check skipped in CLI context (budget applies to changes, not full repo)'] };
+    return {
+      status: 'skipped',
+      messages: ['Budget check skipped in CLI context (budget applies to changes, not full repo)'],
+    };
   }
 
   // Build a minimal spec for deriveBudget

package/dist/gates/spec-completeness.js

@@ -42,10 +42,17 @@ async function run({ projectRoot, spec }) {
     return { status: 'fail', messages: ['Resolved spec is empty'] };
   }
 
-  // Try to find and load the schema
+  // Try to find and load the schema.
+  // CAWSFIX-03: The canonical project-level schema lives at
+  // `.caws/working-spec.schema.json` (flat layout, matches the pattern used for
+  // policy.schema.json and waiver.schema.json). Older projects may still have
+  // a `.caws/schemas/` directory from scaffolded templates, so we check both.
+  // Bundled fallbacks cover packaged installs.
   const schemaPaths = [
+    path.join(projectRoot, '.caws', 'working-spec.schema.json'),
     path.join(projectRoot, '.caws', 'schemas', 'working-spec.schema.json'),
     path.join(projectRoot, 'node_modules', '@caws', 'cli', 'templates', '.caws', 'schemas', 'working-spec.schema.json'),
+    path.join(projectRoot, 'node_modules', '@paths.design', 'caws-cli', 'templates', '.caws', 'schemas', 'working-spec.schema.json'),
   ];
 
   let schema = null;

package/dist/index.js

@@ -55,6 +55,7 @@ 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');
@@ -380,6 +381,22 @@ worktreeCmd
   .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')
@@ -552,6 +569,15 @@ 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
 program
   .command('workflow <type>')
@@ -745,6 +771,7 @@ const VALID_COMMANDS = [
   'session',
   'parallel',
   'verify-acs',
+  'scope',
 ];
 
 program.exitOverride((err) => {

package/dist/policy/PolicyManager.js

@@ -270,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`);
       }
     }
 

package/dist/session/session-manager.js

@@ -12,6 +12,7 @@ const path = require('path');
 const crypto = require('crypto');
 
 const { mergeFilesTouched } = require('../utils/working-state');
+const { appendEventSync } = require('../utils/event-log');
 
 const SESSIONS_DIR = '.caws/sessions';
 const REGISTRY_FILE = '.caws/sessions.json';
@@ -297,6 +298,22 @@ function startSession(options = {}) {
   };
   saveRegistry(root, registry);
 
+  // EVLOG-001: emit session_started event via the sync append path.
+  // spec_id is optional for this event type; we include it only when
+  // the session is bound to a spec.
+  const sessionStartedEvent = {
+    actor: 'session',
+    event: 'session_started',
+    data: {
+      session_id: sessionId,
+      role,
+      branch: capsule.base_state.branch,
+      head_rev: capsule.base_state.head_rev,
+    },
+  };
+  if (specId) sessionStartedEvent.spec_id = specId;
+  appendEventSync(sessionStartedEvent, { projectRoot: root, session_id: sessionId });
+
   return capsule;
 }
 
@@ -447,6 +464,23 @@ function endSession(data = {}) {
   registry.sessions[sessionId].ended_at = capsule.ended_at;
   saveRegistry(root, registry);
 
+  // EVLOG-001: emit session_ended event with final files_touched list.
+  // The renderer uses this to merge file touches into the spec view.
+  const sessionEndedEvent = {
+    actor: 'session',
+    event: 'session_ended',
+    data: {
+      session_id: sessionId,
+      files_touched: capsule.work_summary.paths_touched || [],
+      outcome: capsule.known_issues.some((i) => i.type === 'error') ? 'error' : 'success',
+    },
+  };
+  if (capsule.spec_id) {
+    sessionEndedEvent.spec_id = capsule.spec_id;
+    sessionEndedEvent.data.spec_id = capsule.spec_id;
+  }
+  appendEventSync(sessionEndedEvent, { projectRoot: root, session_id: sessionId });
+
   return capsule;
 }
 

package/dist/templates/.caws/schemas/policy.schema.json

@@ -1,50 +1,112 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CAWS Policy",
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
-  "required": ["version", "risk_tiers"],
+  "required": [
+    "version",
+    "risk_tiers",
+    "edit_rules"
+  ],
   "properties": {
-    "version": { "type": "integer", "const": 1 },
+    "version": {
+      "type": "integer",
+      "enum": [
+        1
+      ],
+      "description": "Policy schema version"
+    },
     "risk_tiers": {
       "type": "object",
-      "properties": {
-        "1": { "$ref": "#/$defs/tier" },
-        "2": { "$ref": "#/$defs/tier" },
-        "3": { "$ref": "#/$defs/tier" }
+      "patternProperties": {
+        "^[1-3]$": {
+          "type": "object",
+          "required": [
+            "max_files",
+            "max_loc"
+          ],
+          "properties": {
+            "max_files": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum files allowed for this risk tier"
+            },
+            "max_loc": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum lines of code allowed for this risk tier"
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description of the tier"
+            }
+          },
+          "additionalProperties": false
+        }
       },
-      "required": ["1", "2", "3"]
+      "additionalProperties": false,
+      "description": "Risk tier definitions with budget limits"
     },
     "edit_rules": {
       "type": "object",
+      "required": [
+        "policy_and_code_same_pr",
+        "min_approvers_for_budget_raise"
+      ],
       "properties": {
-        "policy_and_code_same_pr": { "type": "boolean" },
-        "min_approvers_for_budget_raise": { "type": "integer", "minimum": 1 },
-        "require_signed_commits": { "type": "boolean" }
-      }
+        "policy_and_code_same_pr": {
+          "type": "boolean",
+          "description": "Whether policy and code changes can be in the same PR"
+        },
+        "min_approvers_for_budget_raise": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum approvers required for budget increases"
+        },
+        "require_signed_commits": {
+          "type": "boolean",
+          "description": "Whether signed commits are required for policy changes"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Rules governing policy file edits"
     },
     "gates": {
       "type": "object",
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "enabled": { "type": "boolean" },
-          "description": { "type": "string" },
-          "mode": { "type": "string", "enum": ["block", "warn", "skip"] },
-          "thresholds": { "type": "object" }
-        },
-        "required": ["enabled"]
-      }
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "required": [
+            "enabled"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Whether this gate is active"
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "warn",
+                "block",
+                "skip"
+              ],
+              "description": "How the gate reports failures: warn, block, or skip entirely"
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description of the gate"
+            },
+            "thresholds": {
+              "type": "object",
+              "description": "Gate-specific thresholds (e.g. warning/critical limits)"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false,
+      "description": "Quality gate configurations"
     }
   },
-  "$defs": {
-    "tier": {
-      "type": "object",
-      "required": ["max_files", "max_loc"],
-      "properties": {
-        "max_files": { "type": "integer", "minimum": 1 },
-        "max_loc": { "type": "integer", "minimum": 1 },
-        "description": { "type": "string" }
-      }
-    }
-  }
+  "additionalProperties": false,
+  "title": "CAWS Policy"
 }

package/dist/templates/.caws/schemas/scope.schema.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "CAWS Lite Scope Configuration",
-  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs",
+  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs. This schema governs the standalone .caws/scope.json file ONLY; inline scope: blocks inside working-spec.yaml or feature specs are governed by the working-spec schema's scope sub-schema and do NOT invoke this schema. See CAWSFIX-11.",
   "type": "object",
-  "required": ["version", "allowedDirectories"],
+  "required": ["allowedDirectories"],
   "properties": {
     "version": {
       "type": "integer",
       "const": 1,
-      "description": "Schema version"
+      "description": "Schema version. Optional for back-compat with scope.json files that predate versioning; the runtime (src/config/lite-scope.js) defaults to 1 when missing. If present, must be exactly 1. CAWSFIX-11 lifted `version` from the required list because no code path enforces a version mismatch — only the schema did, producing spurious warnings for pre-versioning scope.json files."
     },
     "allowedDirectories": {
       "type": "array",