@paths.design/caws-cli 9.1.0 → 9.2.0

package/dist/budget-derivation.js

@@ -204,16 +204,28 @@ async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
       }
     }
 
+    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
+    let riskTier = spec.risk_tier;
+    if (typeof riskTier === 'string') {
+      const match = riskTier.match(/^T?(\d)$/i);
+      if (match) {
+        riskTier = parseInt(match[1], 10);
+      }
+    }
+
     // Check if risk tier exists in policy
-    if (!policy.risk_tiers[spec.risk_tier]) {
+    if (!policy.risk_tiers[riskTier]) {
       throw new Error(
         `Risk tier ${spec.risk_tier} not defined in policy.yaml\n` +
           `Policy only defines tiers: ${Object.keys(policy.risk_tiers).join(', ')}\n` +
-          `Valid tiers are: 1 (critical), 2 (standard), 3 (low-risk)`
+          `Valid tiers are: 1 (critical), 2 (standard), 3 (low-risk)` +
+          (typeof spec.risk_tier === 'string'
+            ? `\nHint: use numeric risk_tier (e.g., 2) instead of "${spec.risk_tier}"`
+            : '')
       );
     }
 
-    const tierBudget = policy.risk_tiers[spec.risk_tier];
+    const tierBudget = policy.risk_tiers[riskTier];
     const baseline = {
       max_files: tierBudget.max_files,
       max_loc: tierBudget.max_loc,

package/dist/commands/tutorial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tutorial.d.ts","sourceRoot":"","sources":["../../src/commands/tutorial.js"],"names":[],"mappings":"AA4aA;;;;GAIG;AACH,8CAHW,MAAM,+BA4ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA/FD;;;;GAIG;AACH,qDAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CA4CzB"}
+{"version":3,"file":"tutorial.d.ts","sourceRoot":"","sources":["../../src/commands/tutorial.js"],"names":[],"mappings":"AA0aA;;;;GAIG;AACH,8CAHW,MAAM,+BA4ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA/FD;;;;GAIG;AACH,qDAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CA4CzB"}

package/dist/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,0CANW,MAAM,YAEd;IAAyB,MAAM,GAAvB,MAAM;IACY,WAAW,GAA7B,OAAO;IACW,MAAM,GAAxB,OAAO;CACjB,iBA6NA"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,0CANW,MAAM,YAEd;IAAyB,MAAM,GAAvB,MAAM;IACY,WAAW,GAA7B,OAAO;IACW,MAAM,GAAxB,OAAO;CACjB,iBAsQA"}

package/dist/commands/validate.js

@@ -49,12 +49,19 @@ async function validateCommand(specFile, options = {}) {
       console.log(chalk.gray(`   Spec: ${path.relative(process.cwd(), specPath)}`));
     }
 
+    // For feature specs (.caws/specs/<id>.yaml), path.dirname(specPath) resolves
+    // to .caws/specs/ — not the project root. Use process.cwd() which is always
+    // the project root when the CLI is invoked.
+    const projectRoot = specType === 'feature'
+      ? process.cwd()
+      : path.dirname(specPath);
+
     const result = validateWorkingSpecWithSuggestions(spec, {
       autoFix: options.autoFix,
       dryRun: options.dryRun,
       suggestions: !options.quiet,
       checkBudget: true,
-      projectRoot: path.dirname(specPath),
+      projectRoot,
       specType,
     });
 
@@ -225,6 +232,40 @@ async function validateCommand(specFile, options = {}) {
       }
     }
   } catch (error) {
+    // Multi-spec project without --spec-id: auto-validate all open specs
+    if (error.message === 'Spec ID required when multiple specs exist' && !options.specId) {
+      const { checkMultiSpecStatus } = require('../utils/spec-resolver');
+      const status = await checkMultiSpecStatus();
+      const specIds = Object.keys(status.registry?.specs || {});
+
+      if (specIds.length === 0) {
+        console.error(chalk.red('No specs found in registry'));
+        if (process.env.NODE_ENV !== 'test' && !process.env.JEST_WORKER_ID) {
+          process.exit(1);
+        }
+        return;
+      }
+
+      console.log(chalk.cyan(`Validating all ${specIds.length} specs...\n`));
+      let allPassed = true;
+
+      for (const sid of specIds) {
+        try {
+          await validateCommand(specFile, { ...options, specId: sid });
+        } catch {
+          allPassed = false;
+        }
+        console.log(''); // blank line between specs
+      }
+
+      if (!allPassed) {
+        if (process.env.NODE_ENV !== 'test' && !process.env.JEST_WORKER_ID) {
+          process.exit(1);
+        }
+      }
+      return;
+    }
+
     if (options.format === 'json') {
       console.log(
         JSON.stringify(

package/dist/commands/worktree.js

@@ -9,6 +9,7 @@ const {
   createWorktree,
   listWorktrees,
   destroyWorktree,
+  mergeWorktree,
   pruneWorktrees,
 } = require('../worktree/worktree-manager');
 
@@ -26,11 +27,13 @@ async function worktreeCommand(subcommand, options = {}) {
         return handleList();
       case 'destroy':
         return handleDestroy(options);
+      case 'merge':
+        return handleMerge(options);
       case 'prune':
         return handlePrune(options);
       default:
         console.error(chalk.red(`Unknown worktree subcommand: ${subcommand}`));
-        console.log(chalk.blue('Available: create, list, destroy, prune'));
+        console.log(chalk.blue('Available: create, list, destroy, merge, prune'));
         process.exit(1);
     }
   } catch (error) {
@@ -70,30 +73,52 @@ function handleList() {
   }
 
   console.log(chalk.bold.cyan('CAWS Worktrees'));
-  console.log(chalk.cyan('='.repeat(70)));
+  console.log(chalk.cyan('='.repeat(85)));
   console.log(
     chalk.bold(
-      'Name'.padEnd(20) +
+      'Name'.padEnd(18) +
         'Status'.padEnd(12) +
         'Branch'.padEnd(20) +
-        'Scope'
+        'Last Commit'.padEnd(16) +
+        'Owner'
     )
   );
-  console.log(chalk.gray('-'.repeat(70)));
+  console.log(chalk.gray('-'.repeat(85)));
 
   for (const entry of entries) {
     const statusColor =
       entry.status === 'active'
         ? chalk.green
         : entry.status === 'destroyed'
-        ? chalk.gray
-        : chalk.yellow;
+          ? chalk.gray
+          : chalk.yellow;
+
+    // Format last commit age
+    let commitAge = chalk.gray('-');
+    if (entry.lastCommit) {
+      commitAge = chalk.white(entry.lastCommit.age);
+    }
+
+    // Format owner — show truncated session ID or '-'
+    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';
+    }
 
     console.log(
-      entry.name.padEnd(20) +
-        statusColor(entry.status.padEnd(12)) +
+      entry.name.padEnd(18) +
+        statusColor(statusStr.padEnd(12)) +
         (entry.branch || '').padEnd(20) +
-        (entry.scope || '-')
+        commitAge.padEnd(16 + 10) + // +10 for chalk color codes
+        ownerStr
     );
   }
 
@@ -117,18 +142,85 @@ function handleDestroy(options) {
   }
 }
 
+function handleMerge(options) {
+  const { name, dryRun, deleteBranch = true, message } = options;
+
+  if (!name) {
+    console.error(chalk.red('Worktree name is required'));
+    console.log(
+      chalk.blue(
+        'Usage: caws worktree merge <name> [--dry-run] [--message "..."] [--no-delete-branch]'
+      )
+    );
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    console.log(chalk.cyan(`Dry-run merge preview for: ${name}`));
+  } else {
+    console.log(chalk.cyan(`Merging worktree: ${name}`));
+  }
+
+  const result = mergeWorktree(name, { dryRun, deleteBranch, message });
+
+  if (dryRun) {
+    if (result.conflicts.length > 0) {
+      console.log(chalk.yellow(`\nConflicts detected (${result.conflicts.length}):`));
+      for (const conflict of result.conflicts) {
+        console.log(chalk.yellow(`   ${conflict}`));
+      }
+      console.log(
+        chalk.blue('\nResolve conflicts in the worktree before merging, or merge manually.')
+      );
+    } else {
+      console.log(chalk.green(`\nNo conflicts detected. Safe to merge.`));
+      console.log(chalk.blue(`Run without --dry-run to merge: caws worktree merge ${name}`));
+    }
+    return;
+  }
+
+  if (result.merged) {
+    console.log(chalk.green(`Worktree '${name}' merged to ${result.baseBranch}`));
+    if (deleteBranch) {
+      console.log(chalk.gray(`   Branch ${result.branch} deleted`));
+    }
+  } else {
+    console.log(chalk.red(`Merge failed for '${name}'`));
+    for (const conflict of result.conflicts) {
+      console.log(chalk.yellow(`   ${conflict}`));
+    }
+    console.log(chalk.blue('\nThe worktree has been destroyed but the merge has conflicts.'));
+    console.log(chalk.blue('Resolve conflicts and commit manually:'));
+    console.log(chalk.gray(`   git merge --no-ff ${result.branch}`));
+    console.log(chalk.gray(`   # resolve conflicts`));
+    console.log(chalk.gray(`   git commit -m "merge(worktree): ${name}"`));
+  }
+}
+
 function handlePrune(options) {
   const maxAge = options.maxAge !== undefined ? parseInt(options.maxAge, 10) : 30;
 
   console.log(chalk.cyan(`Pruning worktrees (max age: ${maxAge} days)`));
-  const pruned = pruneWorktrees({ maxAgeDays: maxAge });
+  const result = pruneWorktrees({ maxAgeDays: maxAge });
+
+  // Handle both old return format (array) and new format (object with pruned/skipped)
+  const pruned = Array.isArray(result) ? result : result.pruned;
+  const skipped = Array.isArray(result) ? [] : result.skipped || [];
 
-  if (pruned.length === 0) {
+  if (pruned.length === 0 && skipped.length === 0) {
     console.log(chalk.gray('Nothing to prune.'));
   } else {
-    console.log(chalk.green(`Pruned ${pruned.length} worktree(s):`));
-    for (const entry of pruned) {
-      console.log(chalk.gray(`   - ${entry.name} (created ${entry.createdAt})`));
+    if (pruned.length > 0) {
+      console.log(chalk.green(`Pruned ${pruned.length} worktree(s):`));
+      for (const entry of pruned) {
+        console.log(chalk.gray(`   - ${entry.name} (created ${entry.createdAt})`));
+      }
+    }
+    if (skipped.length > 0) {
+      console.log(chalk.yellow(`\nSkipped ${skipped.length} worktree(s) with recent activity:`));
+      for (const { name: skName, reason } of skipped) {
+        console.log(chalk.yellow(`   - ${skName}: ${reason}`));
+      }
     }
   }
 }

package/dist/index.js

@@ -127,6 +127,7 @@ program
 // Validate command
 program
   .command('validate')
+  .alias('verify')
   .description('Validate CAWS spec with suggestions')
   .argument('[spec-file]', 'Path to spec file (optional, uses spec resolution)')
   .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth, FEAT-001)')
@@ -379,6 +380,14 @@ worktreeCmd
   .option('--force', 'Force removal even if worktree is dirty', false)
   .action((name, options) => worktreeCommand('destroy', { name, ...options }));
 
+worktreeCmd
+  .command('merge <name>')
+  .description('Merge a worktree branch back to base (destroy + merge + cleanup)')
+  .option('--dry-run', 'Preview conflicts without merging', false)
+  .option('--message <msg>', 'Custom merge commit message')
+  .option('--no-delete-branch', 'Keep the branch after merging')
+  .action((name, options) => worktreeCommand('merge', { name, ...options }));
+
 worktreeCmd
   .command('prune')
   .description('Clean up stale worktree entries')

package/dist/parallel/parallel-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel-manager.d.ts","sourceRoot":"","sources":["../../src/parallel/parallel-manager.js"],"names":[],"mappings":"AA6EA;;;;GAIG;AACH,mCAHW,MAAM,OAoDhB;AAED;;;;GAIG;AACH,0CAFa,KAAQ,CAyCpB;AAED;;;GAGG;AACH,qCAFa,MAAO,IAAI,CA2DvB;AA2CD;;;;;;;GAOG;AACH,wCALG;IAAyB,QAAQ,GAAzB,MAAM;IACY,MAAM,GAAxB,OAAO;IACW,KAAK,GAAvB,OAAO;CACf,OA2GF;AAED;;;;;;GAMG;AACH,2CAJG;IAA0B,cAAc,GAAhC,OAAO;IACW,KAAK,GAAvB,OAAO;CACf,OA0BF;AA3LD;;;;;GAKG;AACH,gDAJW,MAAM,iBACN,KAAQ,GACN,KAAQ,CAmCpB;AAnPD;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAO,IAAI,CAYvB;AAED;;;;GAIG;AACH,2CAHW,MAAM,mBAOhB;AAED;;;GAGG;AACH,6CAFW,MAAM,QAOhB;AAnDD,gCAA0B,qBAAqB,CAAC"}
+{"version":3,"file":"parallel-manager.d.ts","sourceRoot":"","sources":["../../src/parallel/parallel-manager.js"],"names":[],"mappings":"AA0EA;;;;GAIG;AACH,mCAHW,MAAM,OAoDhB;AAED;;;;GAIG;AACH,0CAFa,KAAQ,CAyCpB;AAED;;;GAGG;AACH,qCAFa,MAAO,IAAI,CA2DvB;AA2CD;;;;;;;GAOG;AACH,wCALG;IAAyB,QAAQ,GAAzB,MAAM;IACY,MAAM,GAAxB,OAAO;IACW,KAAK,GAAvB,OAAO;CACf,OA2GF;AAED;;;;;;GAMG;AACH,2CAJG;IAA0B,cAAc,GAAhC,OAAO;IACW,KAAK,GAAvB,OAAO;CACf,OA0BF;AA3LD;;;;;GAKG;AACH,gDAJW,MAAM,iBACN,KAAQ,GACN,KAAQ,CAmCpB;AAnPD;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAO,IAAI,CAYvB;AAED;;;;GAIG;AACH,2CAHW,MAAM,mBAOhB;AAED;;;GAGG;AACH,6CAFW,MAAM,QAOhB;AAnDD,gCAA0B,qBAAqB,CAAC"}

package/dist/templates/.claude/hooks/worktree-write-guard.sh

@@ -65,13 +65,22 @@ if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
   exit 0
 fi
 
-# Allow edits to .claude/ configuration (hooks, settings, rules)
+# Allow edits to configuration and documentation (benign, no merge conflict risk)
 if [[ -n "$FILE_PATH" ]]; then
   case "$FILE_PATH" in
     */.claude/*|*/.caws/*) exit 0 ;;
+    */docs/*) exit 0 ;;
   esac
 fi
 
+# Allow edits during an active merge (conflict resolution).
+# The worktree-isolation rules explicitly permit merge commits on the base branch.
+# Conflict resolution requires Write/Edit on the conflicted files.
+MERGE_HEAD_PATH=$(cd "$AGENT_DIR" && git rev-parse --git-dir 2>/dev/null || echo ".git")
+if [[ -f "$MERGE_HEAD_PATH/MERGE_HEAD" ]]; then
+  exit 0
+fi
+
 # Block: we're on the base branch with active worktrees
 echo "BLOCKED: Cannot write/edit files on '$CURRENT_BRANCH' while $WT_COUNT worktree(s) are active: $WT_NAMES" >&2
 echo "" >&2
@@ -81,4 +90,7 @@ echo "  To create a new worktree:    caws worktree create <name>" >&2
 echo "" >&2
 echo "Do NOT make changes on main and create a worktree retroactively." >&2
 echo "The worktree must exist BEFORE you start making changes." >&2
+echo "" >&2
+echo "If you are merging a worktree branch, use: caws worktree merge <name>" >&2
+echo "Or start the merge first (git merge --no-ff <branch>), then resolve conflicts." >&2
 exit 2

package/dist/templates/.claude/rules/worktree-isolation.md

@@ -9,7 +9,7 @@ When multiple agents are working on this project, each agent MUST work in its ow
 
 ## Before starting work
 
-1. Check if worktrees exist: look for `.caws/worktrees.json` or `.caws/parallel.json`
+1. Check if worktrees exist: `caws worktree list` shows all active worktrees with last commit time and owner
 2. If worktrees are active and you are on the base branch, switch to your assigned worktree
 3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
 
@@ -21,17 +21,47 @@ When multiple agents are working on this project, each agent MUST work in its ow
 - `git push --force` -- rewrites remote history
 - Direct commits to the base branch -- only `merge(worktree):` and `wip(checkpoint):` formats are allowed
 - Copying files between your worktree and the main repo directory -- defeats isolation
+- Destroying another agent's active worktree -- `caws worktree destroy` will block this unless you use `--force`
 
 ## Merging worktree branches back to base
 
 Merge commits ARE allowed on the base branch while other worktrees are active. This lets you incrementally merge completed work without waiting for all agents to finish.
 
+### Recommended: use `caws worktree merge`
+
+The `merge` command handles the full sequence (conflict check, destroy, merge, cleanup):
+
+```bash
+# Preview conflicts before merging
+caws worktree merge <name> --dry-run
+
+# Merge (destroys worktree, merges branch, deletes branch)
+caws worktree merge <name>
+
+# Merge with custom commit message
+caws worktree merge <name> --message "merge(worktree): description of changes"
+```
+
+### Manual merge (if you need more control)
+
 1. Destroy the worktree first: `caws worktree destroy <name>`
 2. Switch to the base branch: `git checkout main`
 3. Merge with: `git merge --no-ff <worktree-branch>`
 4. The commit-msg hook enforces the `merge(worktree): <description>` format for non-FF merges
 5. For manual merge commits: `git commit -m "merge(worktree): integrate scenarios work"`
 
+### Conflict resolution during merge
+
+The write guard allows edits on the base branch while a merge is in progress (MERGE_HEAD exists). This lets you resolve merge conflicts without needing to abort and retry. After resolving, commit with the `merge(worktree):` format.
+
+## What the write guard allows on the base branch
+
+Even when worktrees are active, the following edits are allowed on the base branch:
+
+- `.claude/` and `.caws/` configuration files
+- `docs/` directory (documentation changes are benign)
+- Any file while a merge is in progress (conflict resolution)
+
 ## Virtual environment in worktrees
 
 Do NOT create a new virtual environment in your worktree. Use the main repo's venv:
@@ -46,6 +76,5 @@ If your project uses `.caws/scope.json`, the `designatedVenvPath` field specifie
 
 1. Commit all changes to your worktree branch
 2. Run tests in your worktree to verify
-3. Destroy your worktree with `caws worktree destroy <name>`
-4. Merge your branch to base: `git merge --no-ff <branch>` (uses `merge(worktree):` format)
-5. Delete the branch if no longer needed: `git branch -d <branch>`
+3. Merge: `caws worktree merge <name>` (handles destroy + merge + branch cleanup)
+4. Or manually: destroy worktree, then `git merge --no-ff <branch>`, then delete branch

package/dist/templates/CLAUDE.md

@@ -38,15 +38,19 @@ caws agent evaluate
 
 ### Working Spec
 
-The project spec lives at `.caws/working-spec.yaml`. It defines:
+The project spec lives at `.caws/working-spec.yaml`. Feature specs live at `.caws/specs/<ID>.yaml`. It defines:
 
 - **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
 - **Scope**: Which files you can edit (`scope.in`) and which are off-limits (`scope.out`)
-- **Change budget**: Max files and lines of code per change
-- **Acceptance criteria**: What "done" means
+- **Change budget**: Max files and lines of code per change (see note below)
+- **Acceptance criteria**: What "done" means — IDs must match `^A\d+$` (e.g. `A1`, `A12`)
 
 Always stay within scope boundaries and change budgets.
 
+> **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
+> derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
+> spec is not used by `caws validate` for enforcement.
+
 ### Quality Gates
 
 Quality requirements are tiered:

package/dist/validation/spec-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-validation.d.ts","sourceRoot":"","sources":["../../src/validation/spec-validation.js"],"names":[],"mappings":"AA6DA;;;;;GAKG;AACH,mEA8IC;AAED;;;;;GAKG;AACH,kFAgdC;AAoCD;;;;;GAKG;AACH,0CAJW,MAAM,eAEJ,MAAM,CAkBlB;AAED;;;;;GAKG;AACH,uCAJW,MAAM,eAEJ,OAAO,CAKnB;AAnED;;;;;;GAMG;AACH,0EAFa,MAAM,CAclB;AAED;;;;GAIG;AACH,0CAHW,MAAM,GACJ,MAAM,CAQlB"}
+{"version":3,"file":"spec-validation.d.ts","sourceRoot":"","sources":["../../src/validation/spec-validation.js"],"names":[],"mappings":"AA6DA;;;;;GAKG;AACH,mEA8IC;AAED;;;;;GAKG;AACH,kFAycC;AAoCD;;;;;GAKG;AACH,0CAJW,MAAM,eAEJ,MAAM,CAkBlB;AAED;;;;;GAKG;AACH,uCAJW,MAAM,eAEJ,OAAO,CAKnB;AAnED;;;;;;GAMG;AACH,0EAFa,MAAM,CAclB;AAED;;;;GAIG;AACH,0CAHW,MAAM,GACJ,MAAM,CAQlB"}

package/dist/validation/spec-validation.js

@@ -85,6 +85,14 @@ const validateWorkingSpec = (spec, _options = {}) => {
     // For new policy-based specs, change_budget is not required
     // It's derived from policy.yaml + waivers
 
+    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
+    if (spec.risk_tier !== undefined && typeof spec.risk_tier === 'string') {
+      const match = spec.risk_tier.match(/^T?(\d)$/i);
+      if (match) {
+        spec.risk_tier = parseInt(match[1], 10);
+      }
+    }
+
     for (const field of requiredFields) {
       if (!spec[field]) {
         return {
@@ -563,16 +571,9 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
-    // Warn if change_budget is present (deprecated/informational only)
-    if (spec.change_budget) {
-      warnings.push({
-        instancePath: '/change_budget',
-        message:
-          'change_budget field in working spec is informational only and not used for validation',
-        suggestion:
-          'Budget is derived from policy.yaml risk_tier + waivers. This field is auto-calculated.',
-      });
-    }
+    // Note: change_budget in specs is informational documentation only.
+    // Budget enforcement is derived from policy.yaml risk_tier + waivers.
+    // No warning emitted — the field is valid and expected.
 
     // Derive and check budget if requested
     let budgetCheck = null;

package/dist/worktree/worktree-manager.js

@@ -13,6 +13,46 @@ const WORKTREES_DIR = '.caws/worktrees';
 const REGISTRY_FILE = '.caws/worktrees.json';
 const BRANCH_PREFIX = 'caws/';
 
+/**
+ * Get the last commit info for a branch
+ * @param {string} branch - Branch name
+ * @param {string} root - Repository root
+ * @returns {{ age: string, timestamp: Date, sha: string } | null}
+ */
+function getLastCommitInfo(branch, root) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['log', branch, '-1', '--format=%H%n%aI%n%ar'],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    ).trim();
+    const [sha, iso, age] = output.split('\n');
+    return { sha, timestamp: new Date(iso), age };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a branch has been merged into another branch
+ * @param {string} branch - Branch to check
+ * @param {string} target - Target branch (e.g., "main")
+ * @param {string} root - Repository root
+ * @returns {boolean}
+ */
+function isBranchMerged(branch, target, root) {
+  try {
+    const merged = execFileSync(
+      'git',
+      ['branch', '--merged', target, '--list', branch],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    ).trim();
+    return merged.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Get the git repository root
  * @returns {string} Absolute path to repo root
@@ -250,10 +290,21 @@ function listWorktrees() {
     const inGit = gitWorktrees.some(
       (wt) => path.resolve(wt) === path.resolve(entry.path)
     );
+    const status = exists && inGit ? 'active' : exists ? 'orphaned' : 'missing';
+
+    // Enrich with commit recency
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+
+    // Check if branch is already merged to base
+    const merged = entry.branch && entry.baseBranch
+      ? isBranchMerged(entry.branch, entry.baseBranch, root)
+      : false;
 
     return {
       ...entry,
-      status: exists && inGit ? 'active' : exists ? 'orphaned' : 'missing',
+      status,
+      lastCommit,
+      merged,
     };
   });
 
@@ -277,16 +328,45 @@ function destroyWorktree(name, options = {}) {
     throw new Error(`Worktree '${name}' not found in registry`);
   }
 
+  // Ownership check: refuse to destroy another agent's active worktree without --force
+  const currentSession = process.env.CLAUDE_SESSION_ID || null;
+  if (
+    !force &&
+    entry.status === 'active' &&
+    entry.owner &&
+    currentSession &&
+    entry.owner !== currentSession
+  ) {
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+    const recency = lastCommit ? ` (last commit: ${lastCommit.age})` : '';
+    throw new Error(
+      `Worktree '${name}' belongs to another session${recency}.\n` +
+        `   Owner: ${entry.owner}\n` +
+        `   You:   ${currentSession}\n` +
+        `Another agent may be actively working here. Use --force to override.`
+    );
+  }
+
+  // Auto-force when the branch is already merged to its base branch.
+  // Dirty files in a merged worktree are definitionally stale.
+  const merged = entry.branch && entry.baseBranch
+    ? isBranchMerged(entry.branch, entry.baseBranch, root)
+    : false;
+  const effectiveForce = force || merged;
+  if (merged && !force) {
+    console.log(chalk.gray(`   Branch ${entry.branch} already merged to ${entry.baseBranch}, auto-forcing cleanup`));
+  }
+
   // Remove git worktree — handle already-deleted directories gracefully
   const dirExists = fs.existsSync(entry.path);
   if (dirExists) {
     try {
       const args = ['worktree', 'remove'];
-      if (force) args.push('--force');
+      if (effectiveForce) args.push('--force');
       args.push(entry.path);
       execFileSync('git', args, { cwd: root, stdio: 'pipe' });
     } catch (error) {
-      if (force) {
+      if (effectiveForce) {
         // Force cleanup: remove directory manually
         fs.removeSync(entry.path);
       } else {
@@ -310,7 +390,7 @@ function destroyWorktree(name, options = {}) {
     try {
       execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
     } catch {
-      if (force) {
+      if (effectiveForce) {
         try {
           execFileSync('git', ['branch', '-D', entry.branch], { cwd: root, stdio: 'pipe' });
         } catch {
@@ -326,19 +406,143 @@ function destroyWorktree(name, options = {}) {
   saveRegistry(root, registry);
 }
 
+/**
+ * Merge a worktree branch back to base in one operation.
+ * Sequence: dry-run conflict check → destroy worktree → merge → cleanup.
+ * @param {string} name - Worktree name
+ * @param {Object} options - Merge options
+ * @param {boolean} [options.dryRun] - Preview conflicts without merging
+ * @param {boolean} [options.deleteBranch] - Delete branch after merge
+ * @param {string} [options.message] - Custom merge commit message
+ * @returns {Object} Merge result
+ */
+function mergeWorktree(name, options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const { dryRun = false, deleteBranch = true, message } = options;
+
+  const entry = registry.worktrees[name];
+  if (!entry) {
+    throw new Error(`Worktree '${name}' not found in registry`);
+  }
+
+  const baseBranch = entry.baseBranch || 'main';
+
+  // Check for uncommitted work in the worktree
+  if (fs.existsSync(entry.path)) {
+    try {
+      const status = execFileSync(
+        'git',
+        ['status', '--porcelain'],
+        { cwd: entry.path, encoding: 'utf8', stdio: 'pipe' }
+      ).trim();
+      if (status) {
+        throw new Error(
+          `Worktree '${name}' has uncommitted changes:\n${status}\n` +
+            `Commit or discard changes before merging.`
+        );
+      }
+    } catch (error) {
+      if (error.message.includes('uncommitted changes')) throw error;
+      // Non-fatal: status check failed, proceed cautiously
+    }
+  }
+
+  // Dry-run: check for conflicts using git merge-tree (new-style, git 2.38+)
+  let conflicts = [];
+  try {
+    // New-style merge-tree: takes two branches, computes merge-base automatically
+    const mergeTreeResult = execFileSync(
+      'git',
+      ['merge-tree', '--write-tree', baseBranch, entry.branch],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    );
+    // Exit 0 = clean merge, no conflicts
+  } catch (mergeTreeError) {
+    // Exit 1 = conflicts detected; parse them from output
+    const output = (mergeTreeError.stdout || '') + (mergeTreeError.stderr || '');
+    const conflictLines = output.split('\n').filter(
+      (l) => l.includes('CONFLICT') || l.includes('conflict')
+    );
+    if (mergeTreeError.status === 1 && conflictLines.length > 0) {
+      conflicts = conflictLines;
+    } else if (mergeTreeError.status === 1) {
+      conflicts = ['Merge conflicts detected (run merge manually to inspect)'];
+    }
+    // Other exit codes (e.g., merge-tree not supported) = can't detect, proceed
+  }
+
+  if (dryRun) {
+    return {
+      name,
+      branch: entry.branch,
+      baseBranch,
+      conflicts,
+      wouldMerge: conflicts.length === 0,
+    };
+  }
+
+  // Destroy the worktree (auto-forces since we're about to merge)
+  destroyWorktree(name, { deleteBranch: false, force: true });
+
+  // Switch to base branch
+  const currentBranch = getCurrentBranch();
+  if (currentBranch !== baseBranch) {
+    execFileSync('git', ['checkout', baseBranch], { cwd: root, stdio: 'pipe' });
+  }
+
+  // Merge
+  const mergeMessage = message || `merge(worktree): ${name}`;
+  try {
+    execFileSync(
+      'git',
+      ['merge', '--no-ff', entry.branch, '-m', mergeMessage],
+      { cwd: root, stdio: 'pipe' }
+    );
+  } catch (error) {
+    return {
+      name,
+      branch: entry.branch,
+      baseBranch,
+      merged: false,
+      conflicts: [`Merge failed: ${error.message}`],
+      message: 'Merge conflicts detected. Resolve with git and commit.',
+    };
+  }
+
+  // Delete branch after successful merge
+  if (deleteBranch) {
+    try {
+      execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  return {
+    name,
+    branch: entry.branch,
+    baseBranch,
+    merged: true,
+    conflicts: [],
+  };
+}
+
 /**
  * Prune stale worktree entries
  * @param {Object} options - Prune options
  * @param {number} [options.maxAgeDays] - Remove entries older than this many days
+ * @param {number} [options.recentCommitMinutes] - Protect branches with commits newer than this (default: 60)
  * @returns {Array} Pruned entries
  */
 function pruneWorktrees(options = {}) {
   const root = getRepoRoot();
   const registry = loadRegistry(root);
-  const { maxAgeDays = 30 } = options;
+  const { maxAgeDays = 30, recentCommitMinutes = 60 } = options;
 
   const now = new Date();
   const pruned = [];
+  const skipped = [];
 
   for (const [name, entry] of Object.entries(registry.worktrees)) {
     const created = new Date(entry.createdAt);
@@ -354,6 +558,18 @@ function pruneWorktrees(options = {}) {
       (!dirExists && ageDays > maxAgeDays);
 
     if (shouldPrune) {
+      // Before pruning a non-destroyed entry, check for recent commits
+      if (entry.status !== 'destroyed' && entry.branch) {
+        const lastCommit = getLastCommitInfo(entry.branch, root);
+        if (lastCommit) {
+          const commitAgeMinutes = (now - lastCommit.timestamp) / (1000 * 60);
+          if (commitAgeMinutes < recentCommitMinutes) {
+            skipped.push({ name, reason: `recent commit (${lastCommit.age})`, entry });
+            continue;
+          }
+        }
+      }
+
       // Clean up filesystem if still exists
       if (dirExists) {
         try {
@@ -378,16 +594,19 @@ function pruneWorktrees(options = {}) {
   }
 
   saveRegistry(root, registry);
-  return pruned;
+  return { pruned, skipped };
 }
 
 module.exports = {
   createWorktree,
   listWorktrees,
   destroyWorktree,
+  mergeWorktree,
   pruneWorktrees,
   loadRegistry,
   getRepoRoot,
+  getLastCommitInfo,
+  isBranchMerged,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {

package/templates/.claude/hooks/worktree-write-guard.sh

@@ -65,13 +65,22 @@ if [[ "$WT_COUNT" -le 0 ]] 2>/dev/null; then
   exit 0
 fi
 
-# Allow edits to .claude/ configuration (hooks, settings, rules)
+# Allow edits to configuration and documentation (benign, no merge conflict risk)
 if [[ -n "$FILE_PATH" ]]; then
   case "$FILE_PATH" in
     */.claude/*|*/.caws/*) exit 0 ;;
+    */docs/*) exit 0 ;;
   esac
 fi
 
+# Allow edits during an active merge (conflict resolution).
+# The worktree-isolation rules explicitly permit merge commits on the base branch.
+# Conflict resolution requires Write/Edit on the conflicted files.
+MERGE_HEAD_PATH=$(cd "$AGENT_DIR" && git rev-parse --git-dir 2>/dev/null || echo ".git")
+if [[ -f "$MERGE_HEAD_PATH/MERGE_HEAD" ]]; then
+  exit 0
+fi
+
 # Block: we're on the base branch with active worktrees
 echo "BLOCKED: Cannot write/edit files on '$CURRENT_BRANCH' while $WT_COUNT worktree(s) are active: $WT_NAMES" >&2
 echo "" >&2
@@ -81,4 +90,7 @@ echo "  To create a new worktree:    caws worktree create <name>" >&2
 echo "" >&2
 echo "Do NOT make changes on main and create a worktree retroactively." >&2
 echo "The worktree must exist BEFORE you start making changes." >&2
+echo "" >&2
+echo "If you are merging a worktree branch, use: caws worktree merge <name>" >&2
+echo "Or start the merge first (git merge --no-ff <branch>), then resolve conflicts." >&2
 exit 2

package/templates/.claude/rules/worktree-isolation.md

@@ -9,7 +9,7 @@ When multiple agents are working on this project, each agent MUST work in its ow
 
 ## Before starting work
 
-1. Check if worktrees exist: look for `.caws/worktrees.json` or `.caws/parallel.json`
+1. Check if worktrees exist: `caws worktree list` shows all active worktrees with last commit time and owner
 2. If worktrees are active and you are on the base branch, switch to your assigned worktree
 3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
 
@@ -21,17 +21,47 @@ When multiple agents are working on this project, each agent MUST work in its ow
 - `git push --force` -- rewrites remote history
 - Direct commits to the base branch -- only `merge(worktree):` and `wip(checkpoint):` formats are allowed
 - Copying files between your worktree and the main repo directory -- defeats isolation
+- Destroying another agent's active worktree -- `caws worktree destroy` will block this unless you use `--force`
 
 ## Merging worktree branches back to base
 
 Merge commits ARE allowed on the base branch while other worktrees are active. This lets you incrementally merge completed work without waiting for all agents to finish.
 
+### Recommended: use `caws worktree merge`
+
+The `merge` command handles the full sequence (conflict check, destroy, merge, cleanup):
+
+```bash
+# Preview conflicts before merging
+caws worktree merge <name> --dry-run
+
+# Merge (destroys worktree, merges branch, deletes branch)
+caws worktree merge <name>
+
+# Merge with custom commit message
+caws worktree merge <name> --message "merge(worktree): description of changes"
+```
+
+### Manual merge (if you need more control)
+
 1. Destroy the worktree first: `caws worktree destroy <name>`
 2. Switch to the base branch: `git checkout main`
 3. Merge with: `git merge --no-ff <worktree-branch>`
 4. The commit-msg hook enforces the `merge(worktree): <description>` format for non-FF merges
 5. For manual merge commits: `git commit -m "merge(worktree): integrate scenarios work"`
 
+### Conflict resolution during merge
+
+The write guard allows edits on the base branch while a merge is in progress (MERGE_HEAD exists). This lets you resolve merge conflicts without needing to abort and retry. After resolving, commit with the `merge(worktree):` format.
+
+## What the write guard allows on the base branch
+
+Even when worktrees are active, the following edits are allowed on the base branch:
+
+- `.claude/` and `.caws/` configuration files
+- `docs/` directory (documentation changes are benign)
+- Any file while a merge is in progress (conflict resolution)
+
 ## Virtual environment in worktrees
 
 Do NOT create a new virtual environment in your worktree. Use the main repo's venv:
@@ -46,6 +76,5 @@ If your project uses `.caws/scope.json`, the `designatedVenvPath` field specifie
 
 1. Commit all changes to your worktree branch
 2. Run tests in your worktree to verify
-3. Destroy your worktree with `caws worktree destroy <name>`
-4. Merge your branch to base: `git merge --no-ff <branch>` (uses `merge(worktree):` format)
-5. Delete the branch if no longer needed: `git branch -d <branch>`
+3. Merge: `caws worktree merge <name>` (handles destroy + merge + branch cleanup)
+4. Or manually: destroy worktree, then `git merge --no-ff <branch>`, then delete branch

package/templates/CLAUDE.md

@@ -38,15 +38,19 @@ caws agent evaluate
 
 ### Working Spec
 
-The project spec lives at `.caws/working-spec.yaml`. It defines:
+The project spec lives at `.caws/working-spec.yaml`. Feature specs live at `.caws/specs/<ID>.yaml`. It defines:
 
 - **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
 - **Scope**: Which files you can edit (`scope.in`) and which are off-limits (`scope.out`)
-- **Change budget**: Max files and lines of code per change
-- **Acceptance criteria**: What "done" means
+- **Change budget**: Max files and lines of code per change (see note below)
+- **Acceptance criteria**: What "done" means — IDs must match `^A\d+$` (e.g. `A1`, `A12`)
 
 Always stay within scope boundaries and change budgets.
 
+> **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
+> derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
+> spec is not used by `caws validate` for enforcement.
+
 ### Quality Gates
 
 Quality requirements are tiered: