@paths.design/caws-cli 10.0.1 → 10.2.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,8 +12,14 @@ const {
   mergeWorktree,
   pruneWorktrees,
   repairWorktrees,
+  loadRegistry,
+  saveRegistry,
+  assertWorktreeOwnership,
+  getRepoRoot,
+  findFeatureSpecPathFromCwd,
+  autoActivateBoundSpec,
 } = require('../worktree/worktree-manager');
-const { getAgentSessionId } = require('../utils/agent-session');
+const { getAgentSessionId, refreshAgentClaim } = require('../utils/agent-session');
 
 /**
  * Handle worktree subcommands
@@ -35,9 +41,13 @@ async function worktreeCommand(subcommand, options = {}) {
         return handlePrune(options);
       case 'repair':
         return handleRepair(options);
+      case 'bind':
+        return handleBind(options);
+      case 'claim':
+        return handleClaim(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, claim'));
         process.exit(1);
     }
   } catch (error) {
@@ -169,7 +179,7 @@ function handleDestroy(options) {
 }
 
 function handleMerge(options) {
-  const { name, dryRun, deleteBranch = true, message } = options;
+  const { name, dryRun, deleteBranch = true, message, takeover = false } = options;
 
   if (!name) {
     console.error(chalk.red('Worktree name is required'));
@@ -187,7 +197,7 @@ function handleMerge(options) {
     console.log(chalk.cyan(`Merging worktree: ${name}`));
   }
 
-  const result = mergeWorktree(name, { dryRun, deleteBranch, message });
+  const result = mergeWorktree(name, { dryRun, deleteBranch, message, takeover });
 
   if (dryRun) {
     if (result.conflicts.length > 0) {
@@ -303,4 +313,190 @@ function handleRepair(options) {
   }
 }
 
+function handleBind(options) {
+  const path = require('path');
+  const fs = require('fs-extra');
+  const yaml = require('js-yaml');
+  const { specId, name, takeover } = options;
+
+  if (!specId) {
+    console.error(chalk.red('Spec ID is required'));
+    console.log(chalk.blue('Usage: caws worktree bind <spec-id> [--name <worktree-name>] [--takeover]'));
+    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();
+  // CAWSFIX-32: probe the registry for existence first, but do NOT load
+  // the full registry into a variable yet — assertWorktreeOwnership may
+  // mutate it on takeover, and we'd overwrite the takeover write later
+  // with our stale in-memory copy. Re-load after the ownership check.
+  const probe = loadRegistry(root);
+  if (!probe.worktrees || !probe.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);
+    return;
+  }
+
+  // CAWSFIX-32: assert ownership BEFORE any registry/spec mutation.
+  // Foreign claim soft-blocks unless --takeover is supplied, mirroring
+  // `caws worktree claim`.
+  const ownership = assertWorktreeOwnership(root, worktreeName, {
+    allowTakeover: !!takeover,
+    takeoverCommandHint: `caws worktree bind ${specId} --name ${worktreeName} --takeover`,
+  });
+  if (!ownership.allowed) {
+    console.error(chalk.yellow(ownership.warning));
+    process.exit(1);
+    return;
+  }
+
+  // Now load the registry fresh — assertWorktreeOwnership may have
+  // rewritten owner + appended prior_owners on takeover.
+  const registry = loadRegistry(root);
+
+  // Load the spec file. CAWSFIX-25 / D8: when bind runs from inside a
+  // worktree, prefer the worktree's own .caws/specs/ copy so specs that
+  // live only on a feature branch (never mirrored to main) can be bound.
+  const specPath = findFeatureSpecPathFromCwd(root, specId, process.cwd());
+  if (!specPath) {
+    console.error(chalk.red(`Spec '${specId}' not found in .caws/specs/ (checked worktree-local first, then main)`));
+    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. CAWSFIX-24 / D10: skip the write
+  // if the parsed spec already declares the target worktree — yaml.dump
+  // would otherwise re-wrap folded scalars with no semantic change.
+  if (specData.worktree !== worktreeName) {
+    specData.worktree = worktreeName;
+    const updatedYaml = yaml.dump(specData, { lineWidth: 120, noRefs: true });
+    fs.writeFileSync(specPath, updatedYaml, 'utf8');
+  }
+
+  // CAWSFIX-23: activate the spec if it's still at draft — bind is the
+  // lifecycle signal that work is starting. CAWSFIX-25 / D8: pass the
+  // resolved specPath so the flip lands on whichever copy (worktree-local
+  // or main) was actually bound.
+  const activated = autoActivateBoundSpec(root, specId, specPath);
+
+  // CAWSFIX-32: heartbeat the current session into agents.json so the
+  // bound worktree+spec context is visible to other agents and to
+  // `caws status` / `caws agents list`.
+  refreshAgentClaim(root, { worktree: worktreeName, specId });
+
+  console.log(chalk.green(`Binding established`));
+  console.log(chalk.gray(`   Worktree: ${worktreeName} -> spec: ${specId}`));
+  console.log(chalk.gray(`   Spec: ${specId} -> worktree: ${worktreeName}`));
+  if (activated) {
+    console.log(chalk.gray(`   Status: draft -> active`));
+  }
+  console.log(chalk.gray(`   Registry: ${path.join(root, '.caws', 'worktrees.json')}`));
+  console.log(chalk.gray(`   Spec file: ${specPath}`));
+}
+
+/**
+ * CAWSFIX-31: caws worktree claim <name> [--takeover]
+ *
+ * Without --takeover: read-only context surface. Prints the current
+ * claim (owner, heartbeat, session-log pointers) and exits 1 when the
+ * worktree is owned by a different session id. Modifies nothing.
+ *
+ * With --takeover: rewrites the owner to the current session id,
+ * appends the prior owner to the worktree entry's prior_owners audit
+ * array (including their lastSeen-at-takeover from agents.json), and
+ * exits 0.
+ *
+ * Same session-id silent-proceed: if the current session already owns
+ * the worktree, the command is a successful no-op (exit 0, brief
+ * confirmation).
+ */
+function handleClaim(options) {
+  const { name, takeover } = options;
+
+  if (!name) {
+    console.error(chalk.red('Worktree name is required'));
+    console.log(chalk.blue('Usage: caws worktree claim <name> [--takeover]'));
+    process.exit(1);
+  }
+
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  if (!registry.worktrees || !registry.worktrees[name]) {
+    console.error(chalk.red(`Worktree '${name}' not found in registry.`));
+    console.log(chalk.blue('Run: caws worktree list  to see available worktrees'));
+    process.exit(1);
+  }
+
+  const result = assertWorktreeOwnership(root, name, {
+    allowTakeover: !!takeover,
+    takeoverCommandHint: `caws worktree claim ${name} --takeover`,
+  });
+
+  if (!result.allowed) {
+    // Foreign claim, no --takeover. Print the structured warning that
+    // assertWorktreeOwnership built (claimer, heartbeat, session-log
+    // pointers, takeover hint) and exit 1. Modifies nothing.
+    console.error(chalk.yellow(result.warning));
+    process.exit(1);
+  }
+
+  // allowed = true. Three sub-cases:
+  //   1. takeover happened (priorOwner present)
+  //   2. orphan-log soft notice (warning present, no priorOwner)
+  //   3. clean / same-session (no warning)
+  if (result.priorOwner) {
+    console.log(
+      chalk.green(`Took over worktree '${name}'.`)
+    );
+    console.log(
+      chalk.gray(
+        `   Prior owner ${result.priorOwner.sessionId}:${result.priorOwner.platform || 'unknown'} recorded in prior_owners audit.`
+      )
+    );
+  } else if (result.warning) {
+    console.log(chalk.yellow(result.warning));
+    console.log(chalk.green(`Proceeding — no CAWS-tracked claim on '${name}'.`));
+  } else {
+    const entry = registry.worktrees[name];
+    if (entry.owner === getAgentSessionId(root)) {
+      console.log(chalk.green(`Worktree '${name}' is already claimed by the current session.`));
+    } else {
+      console.log(chalk.green(`Worktree '${name}' has no active claim.`));
+    }
+  }
+}
+
 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/scope-boundary.js

@@ -21,14 +21,27 @@ function matchesAny(filePath, patterns) {
 }
 
 /**
- * Check if a file is an infrastructure file that always passes scope checks.
- * Root-level files are exempt UNLESS they match an explicit scope.out pattern.
+ * Check if a file is infrastructure or lives in a policy-declared
+ * non-governed zone. Exempt files bypass both scope.in and scope.out.
+ *
  * @param {string} filePath - File path to check
- * @returns {boolean} Whether the file is exempt from scope.in checks
+ * @param {string[]} [nonGovernedZones=[]] - Glob patterns from
+ *   policy.non_governed_zones. Paths matching any pattern are exempt
+ *   from scope enforcement entirely. (CAWSFIX-26 / D9)
+ * @returns {boolean} Whether the file is exempt from scope checks
  */
-function isExempt(filePath) {
+function isExempt(filePath, nonGovernedZones = []) {
   // .caws and .claude directories always pass (infrastructure)
   if (filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) return true;
+
+  // Policy-declared non-governed zones short-circuit scope enforcement.
+  // Intentionally wins over scope.out: the contract is that these
+  // subtrees are outside the governance model, not merely excluded
+  // from one spec's scope.
+  if (nonGovernedZones.length > 0 && matchesAny(filePath, nonGovernedZones)) {
+    return true;
+  }
+
   return false;
 }
 
@@ -47,14 +60,20 @@ function isRootLevel(filePath) {
  * @param {Object} params - Gate parameters
  * @param {string[]} params.stagedFiles - Staged file paths
  * @param {Object} params.spec - Working spec with scope.in/scope.out
+ * @param {Object} [params.policy] - Optional CAWS policy. Reads
+ *   policy.non_governed_zones for path exemption (CAWSFIX-26 / D9).
+ *   When absent or the field is empty, only infra dirs are exempt.
  * @returns {Promise<Object>} Gate result with status and messages
  */
-async function run({ stagedFiles, spec }) {
+async function run({ stagedFiles, spec, policy }) {
   const messages = [];
   const violations = [];
 
   const scopeIn = spec?.scope?.in || [];
   const scopeOut = spec?.scope?.out || [];
+  const nonGovernedZones = Array.isArray(policy?.non_governed_zones)
+    ? policy.non_governed_zones
+    : [];
 
   // If no scope defined, pass
   if (scopeIn.length === 0 && scopeOut.length === 0) {
@@ -62,8 +81,8 @@ async function run({ stagedFiles, spec }) {
   }
 
   for (const file of stagedFiles) {
-    // Infrastructure dirs are always exempt
-    if (isExempt(file)) continue;
+    // Infrastructure dirs AND policy-declared non-governed zones are exempt.
+    if (isExempt(file, nonGovernedZones)) continue;
 
     // Check scope.out first (explicit exclusion) — applies to ALL files including root-level
     if (scopeOut.length > 0 && matchesAny(file, scopeOut)) {

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');
@@ -232,6 +233,11 @@ specsCmd
   .description('Close a completed spec (removes scope enforcement)')
   .action((id) => specsCommand('close', { id }));
 
+specsCmd
+  .command('archive <id>')
+  .description('Archive a spec — move to .caws/specs/.archive/ and flip status to archived')
+  .action((id) => specsCommand('archive', { id }));
+
 specsCmd
   .command('conflicts')
   .description('Check for scope conflicts between specs')
@@ -363,6 +369,7 @@ worktreeCmd
   .option('--dry-run', 'Preview conflicts without merging', false)
   .option('--message <msg>', 'Custom merge commit message')
   .option('--no-delete-branch', 'Keep the branch after merging')
+  .option('--takeover', 'Force takeover of a foreign worktree claim (writes prior_owners audit)', false)
   .action((name, options) => worktreeCommand('merge', { name, ...options }));
 
 worktreeCmd
@@ -380,6 +387,45 @@ 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)')
+  .option('--takeover', 'Force takeover of a foreign worktree claim (writes prior_owners audit)', false)
+  .action((specId, options) => worktreeCommand('bind', { specId, ...options }));
+
+worktreeCmd
+  .command('claim <name>')
+  .description('Claim worktree session ownership (read-only without --takeover)')
+  .option('--takeover', 'Force takeover of a foreign claim (writes prior_owners audit)', false)
+  .action((name, options) => worktreeCommand('claim', { name, ...options }));
+
+// Agents command group
+const { agentsCommand } = require('./commands/agents');
+const agentsCmd = program
+  .command('agents')
+  .description('Inspect the agent registry and session-log pointers');
+
+agentsCmd
+  .command('list')
+  .description('List active CAWS-registered agent sessions')
+  .action(() => agentsCommand('list', {}));
+
+agentsCmd
+  .command('show <session-id>')
+  .description('Show details for a specific agent session, including session-log pointer')
+  .action((id) => agentsCommand('show', { id }));
+
+// 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 +598,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 +800,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`);
       }
     }
 
@@ -354,6 +356,11 @@ class PolicyManager {
           description: 'Scan for TODO/FIXME/HACK/XXX markers',
         },
       },
+      // CAWSFIX-26 / D9: empty by default. Projects that need to opt a
+      // subtree out of scope enforcement (e.g., research/, playground/)
+      // add glob patterns here, e.g. ['research/**']. Paths matching any
+      // pattern bypass scope-boundary checks entirely.
+      non_governed_zones: [],
     };
   }