@paths.design/caws-cli 10.0.1 → 10.2.0

package/dist/worktree/worktree-manager.js

@@ -9,7 +9,13 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const { createValidator, getSchemaPath } = require('../utils/schema-validator');
-const { getAgentSessionId } = require('../utils/agent-session');
+const {
+  getAgentSessionId,
+  loadAgentRegistry,
+  findSessionLogs,
+  refreshAgentClaim,
+} = require('../utils/agent-session');
+const { formatClaimNotice, formatOrphanLogHint } = require('../utils/agent-display');
 const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
 
 const WORKTREES_DIR = '.caws/worktrees';
@@ -27,33 +33,151 @@ function findFeatureSpecPath(root, specId) {
   return candidates.find((candidate) => fs.existsSync(candidate)) || null;
 }
 
+/**
+ * Resolve a feature spec path, preferring a worktree-local copy when cwd
+ * is inside a worktree. Falls back to the main repo.
+ *
+ * Why two-step: `caws worktree bind` may be invoked from inside a worktree
+ * that was forked off a non-main base branch (Option C fork-off-sibling
+ * pattern). In that workflow the spec is committed on the worktree's own
+ * branch and never lands on main. The pre-CAWSFIX-25 behavior of looking
+ * only in `root/.caws/specs/` made bind unusable there (D8 ledger entry).
+ *
+ * @param {string} root - Main repo root (from getRepoRoot())
+ * @param {string} specId - Spec identifier
+ * @param {string} [cwd=process.cwd()] - Directory to resolve from
+ * @returns {string|null} Absolute path to the spec file, or null
+ */
+function findFeatureSpecPathFromCwd(root, specId, cwd) {
+  if (!specId) return null;
+  const effectiveCwd = cwd || process.cwd();
+
+  // Normalize both sides against symlinks before comparing. On macOS
+  // `/tmp` and `/var/folders` are symlinks under `/private`, so the literal
+  // `startsWith` check fails intermittently in the test fixture. Fall back
+  // to the pre-resolution path if realpath throws (e.g., cwd removed).
+  const resolve = (p) => {
+    try { return fs.realpathSync(p); } catch { return p; }
+  };
+  const resolvedCwd = resolve(effectiveCwd);
+  const worktreesBase = resolve(path.join(root, '.caws', 'worktrees'));
+
+  if (resolvedCwd.startsWith(worktreesBase + path.sep)) {
+    const relative = path.relative(worktreesBase, resolvedCwd);
+    const worktreeName = relative.split(path.sep)[0];
+    if (worktreeName) {
+      const worktreeRoot = path.join(worktreesBase, worktreeName);
+      const local = findFeatureSpecPath(worktreeRoot, specId);
+      if (local) return local;
+    }
+  }
+
+  return findFeatureSpecPath(root, specId);
+}
+
+function writeSpecWithWorktree(filePath, worktreeName) {
+  const yaml = require('js-yaml');
+  const content = fs.readFileSync(filePath, 'utf8');
+  const parsed = yaml.load(content);
+  if (!parsed || typeof parsed !== 'object') {
+    return content;
+  }
+
+  // CAWSFIX-24 / D10: if the on-disk spec already declares the target
+  // worktree and reloads to an equivalent object, return the original
+  // bytes untouched. js-yaml.dump re-wraps folded scalars at its own
+  // line-width preference, which otherwise produces spurious bytes-only
+  // diffs on every bind/create. That mechanical churn (a) leaves dirty
+  // files on main after worktree create, and (b) causes merge conflicts
+  // when two validator invocations wrap the same title at different
+  // widths.
+  if (parsed.worktree === worktreeName) {
+    return content;
+  }
+
+  parsed.worktree = worktreeName;
+  return yaml.dump(parsed, { lineWidth: 120, noRefs: true });
+}
+
+function hasPathChanges(root, relativePath) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['status', '--porcelain', '--', relativePath],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    ).trim();
+    return output.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function ensureCanonicalSpecCommitted(root, specPath, specId, worktreeName) {
+  const relativeSpecPath = path.relative(root, specPath);
+  const nextContent = writeSpecWithWorktree(specPath, worktreeName);
+  const currentContent = fs.readFileSync(specPath, 'utf8');
+
+  if (currentContent !== nextContent) {
+    fs.writeFileSync(specPath, nextContent);
+  }
+
+  if (!hasPathChanges(root, relativeSpecPath)) {
+    return false;
+  }
+
+  execFileSync('git', ['add', '--', relativeSpecPath], {
+    cwd: root,
+    stdio: 'pipe',
+  });
+  execFileSync(
+    'git',
+    ['commit', '-m', `chore(caws): bind spec ${specId} to worktree ${worktreeName}`, '--', relativeSpecPath],
+    {
+      cwd: root,
+      stdio: 'pipe',
+    }
+  );
+  return true;
+}
+
 function materializeWorktreeSpec(root, cawsDest, specId, worktreeName, scope) {
   if (!specId) return;
 
   const canonicalSpecPath = findFeatureSpecPath(root, specId);
-  const workingSpecPath = path.join(cawsDest, 'working-spec.yaml');
+  const destSpecsDir = path.join(cawsDest, 'specs');
 
-  if (!canonicalSpecPath) {
-    console.warn(
-      chalk.yellow(`Warning: spec '${specId}' not found in .caws/specs/ — generating default working spec for worktree`)
-    );
-  }
+  // CAWSFIX-24 / D5: never write to .caws/working-spec.yaml inside the
+  // worktree. That file is the shared project baseline and must remain
+  // byte-identical to what was checked out from HEAD. The feature spec
+  // is materialized only under .caws/specs/<id>.yaml, which is what
+  // spec-resolver and commands actually read via --spec-id / registry.
 
   if (canonicalSpecPath) {
-    const destSpecsDir = path.join(cawsDest, 'specs');
     const destSpecPath = path.join(destSpecsDir, path.basename(canonicalSpecPath));
     fs.ensureDirSync(destSpecsDir);
 
-    // Keep a canonical feature-spec copy inside the worktree and align
-    // working-spec.yaml to that exact content for legacy-compatible commands.
-    const specContent = fs.readFileSync(canonicalSpecPath, 'utf8');
-    fs.writeFileSync(destSpecPath, specContent);
-    fs.writeFileSync(workingSpecPath, specContent);
+    // Keep a canonical feature-spec copy inside the worktree.
+    const specContent = writeSpecWithWorktree(canonicalSpecPath, worktreeName);
+    // writeSpecWithWorktree is idempotent (CAWSFIX-24 / D10): if the spec
+    // already has the worktree field and reloads to equivalent YAML, the
+    // returned content matches what's on disk. Skip the write in that case
+    // so `git status` stays clean.
+    const existing = fs.existsSync(destSpecPath) ? fs.readFileSync(destSpecPath, 'utf8') : null;
+    if (existing !== specContent) {
+      fs.writeFileSync(destSpecPath, specContent);
+    }
     return;
   }
 
+  // specId given but no canonical spec found — generate a default feature
+  // spec at .caws/specs/<specId>.yaml so the worktree has something to
+  // resolve against. Do not touch .caws/working-spec.yaml.
+  console.warn(
+    chalk.yellow(`Warning: spec '${specId}' not found in .caws/specs/ — generating default feature spec for worktree`)
+  );
+
   const { generateWorkingSpec } = require('../generators/working-spec');
-  const specContent = generateWorkingSpec({
+  let specContent = generateWorkingSpec({
     projectId: specId,
     projectTitle: `Worktree: ${worktreeName}`,
     projectDescription: `Isolated worktree for ${worktreeName}`,
@@ -86,8 +210,83 @@ function materializeWorktreeSpec(root, cawsDest, specId, worktreeName, scope) {
     complexityFactors: '',
   });
 
-  fs.ensureDirSync(path.dirname(workingSpecPath));
-  fs.writeFileSync(workingSpecPath, specContent);
+  try {
+    const yaml = require('js-yaml');
+    const parsed = yaml.load(specContent);
+    if (parsed && typeof parsed === 'object') {
+      parsed.worktree = worktreeName;
+      specContent = yaml.dump(parsed, { lineWidth: 120, noRefs: true });
+    }
+  } catch {
+    // Keep generated spec content if augmentation fails.
+  }
+
+  fs.ensureDirSync(destSpecsDir);
+  const generatedSpecPath = path.join(destSpecsDir, `${specId}.yaml`);
+  fs.writeFileSync(generatedSpecPath, specContent);
+}
+
+function parseSpecIdFromYamlFile(filePath) {
+  try {
+    const yaml = require('js-yaml');
+    const doc = yaml.load(fs.readFileSync(filePath, 'utf8'));
+    if (doc && typeof doc.id === 'string' && doc.id.trim()) {
+      return doc.id.trim();
+    }
+  } catch {
+    // Ignore malformed YAML during inference
+  }
+  return null;
+}
+
+/**
+ * Scan .caws/specs/ for a spec that declares `worktree: <name>`.
+ * Returns the spec's id if found, null otherwise.
+ * This enables auto-binding: when a spec already names the worktree
+ * it expects, the registry entry gets the specId automatically.
+ * @param {string} root - Repository root
+ * @param {string} worktreeName - Worktree name to match
+ * @returns {string|null} Spec ID or null
+ */
+function findSpecByWorktreeName(root, worktreeName) {
+  const yaml = require('js-yaml');
+  const specsDir = path.join(root, '.caws', 'specs');
+  if (!fs.existsSync(specsDir)) return null;
+
+  const specFiles = fs.readdirSync(specsDir)
+    .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'));
+
+  for (const specFile of specFiles) {
+    try {
+      const doc = yaml.load(fs.readFileSync(path.join(specsDir, specFile), 'utf8'));
+      if (doc && doc.worktree === worktreeName && typeof doc.id === 'string') {
+        return doc.id.trim();
+      }
+    } catch {
+      // Skip malformed spec files
+    }
+  }
+  return null;
+}
+
+function inferSpecIdForWorktree(worktreePath) {
+  if (!worktreePath) return null;
+
+  const specsDir = path.join(worktreePath, '.caws', 'specs');
+  if (fs.existsSync(specsDir)) {
+    const specFiles = fs.readdirSync(specsDir)
+      .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'))
+      .sort();
+
+    for (const specFile of specFiles) {
+      const inferred = parseSpecIdFromYamlFile(path.join(specsDir, specFile));
+      if (inferred) {
+        return inferred;
+      }
+    }
+  }
+
+  return parseSpecIdFromYamlFile(path.join(worktreePath, '.caws', 'working-spec.yaml'));
 }
 
 /**
@@ -205,6 +404,132 @@ function getCurrentBranch() {
 // floods stderr and contributes to Claude Code context-window exhaustion.
 let _schemaWarned = false;
 
+/**
+ * CAWSFIX-31: Assert that the current agent session may operate on
+ * worktree `name`. The decision is purely session-id-equality based —
+ * never TTL, never log freshness — because rolled-over and resumed
+ * sessions should not be auto-blocked just because their registry
+ * entry was pruned.
+ *
+ * Returns `{ allowed, warning?, priorOwner? }`. The caller decides
+ * how to react:
+ *
+ *   - allowed=true,  no warning            → silent proceed (same session id, no claim, etc.)
+ *   - allowed=true,  warning present       → soft notice (orphan session log, no block)
+ *   - allowed=false, warning present       → soft-block; surface warning, exit non-zero
+ *
+ * On takeover (`allowTakeover: true`), the function rewrites the
+ * worktree entry's owner to the current session id and appends the
+ * prior owner to a `prior_owners` audit array (with lastSeen captured
+ * from agents.json at takeover time, or null if pruned).
+ *
+ * @param {string} root - Project root
+ * @param {string} name - Worktree name
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowTakeover=false] - Apply takeover when true
+ * @param {string} [opts.takeoverCommandHint] - Suggested command for the warning
+ * @returns {{ allowed: boolean, warning?: string, priorOwner?: object }}
+ */
+function assertWorktreeOwnership(root, name, opts = {}) {
+  const { allowTakeover = false, takeoverCommandHint } = opts;
+  const registry = loadRegistry(root);
+  const entry = registry.worktrees[name];
+  if (!entry) {
+    return { allowed: true };
+  }
+
+  const currentSession = getAgentSessionId(root);
+  const owner = entry.owner;
+
+  // No CAWS-tracked owner — surface session-log hint if present, but
+  // allow the operation to proceed.
+  if (!owner) {
+    const branch = entry.branch || null;
+    const logs = branch ? findSessionLogs(root, { branch }) : [];
+    if (logs.length > 0) {
+      return {
+        allowed: true,
+        warning: formatOrphanLogHint({ worktree: name, sessionLogs: logs, root }),
+      };
+    }
+    return { allowed: true };
+  }
+
+  // Same session id → silent proceed. Roll-over case included: an
+  // agent that resumed with the same session id is its own claimant.
+  if (currentSession && owner === currentSession) {
+    return { allowed: true };
+  }
+
+  // Foreign claim — gather context.
+  const agentRegistry = loadAgentRegistry(root);
+  const priorOwnerEntry = agentRegistry.agents[owner] || null;
+  const priorOwnerLastSeen = priorOwnerEntry ? priorOwnerEntry.lastSeen : null;
+  const priorOwnerPlatform = priorOwnerEntry ? priorOwnerEntry.platform : 'unknown';
+
+  // Surface session-log pointers (by sid OR by branch).
+  const branch = entry.branch || null;
+  const seen = new Set();
+  const sessionLogs = [];
+  for (const log of findSessionLogs(root, { sessionId: owner })) {
+    if (seen.has(log.path)) continue;
+    seen.add(log.path);
+    sessionLogs.push(log);
+  }
+  if (branch) {
+    for (const log of findSessionLogs(root, { branch })) {
+      if (seen.has(log.path)) continue;
+      seen.add(log.path);
+      sessionLogs.push(log);
+    }
+  }
+
+  const takeoverCommand =
+    takeoverCommandHint || `caws worktree claim ${name} --takeover`;
+  const warning = formatClaimNotice({
+    worktree: name,
+    priorOwnerEntry,
+    priorOwnerSessionId: owner,
+    sessionLogs,
+    root,
+    takeoverCommand,
+  });
+
+  if (!allowTakeover) {
+    return { allowed: false, warning };
+  }
+
+  // Takeover: rewrite owner, append prior_owners audit entry.
+  const priorOwners = Array.isArray(entry.prior_owners) ? entry.prior_owners : [];
+  priorOwners.push({
+    sessionId: owner,
+    platform: priorOwnerPlatform,
+    lastSeen: priorOwnerLastSeen,
+    takenOver_at: new Date().toISOString(),
+  });
+  registry.worktrees[name] = {
+    ...entry,
+    owner: currentSession || null,
+    prior_owners: priorOwners,
+  };
+  saveRegistry(root, registry);
+
+  // Heartbeat the new owner so agents.json reflects the takeover too.
+  // Without this, `caws status` and `caws agents list` would show the
+  // takeover'd worktree with an "unknown / pruned" current owner until
+  // some other lifecycle verb fires.
+  refreshAgentClaim(root, { worktree: name });
+
+  return {
+    allowed: true,
+    priorOwner: {
+      sessionId: owner,
+      platform: priorOwnerPlatform,
+      lastSeen: priorOwnerLastSeen,
+    },
+  };
+}
+
 /**
  * Load the worktree registry
  * @param {string} root - Repository root
@@ -242,10 +567,22 @@ function loadRegistry(root) {
  * @param {Object} registry - Registry object
  */
 function saveRegistry(root, registry) {
-  // Auto-prune destroyed entries whose branch and directory are both gone.
-  // This prevents the registry from accumulating ghost entries over time.
+  // Auto-prune ghost entries: any registry entry whose path directory AND
+  // stored branch are BOTH gone. Previously this only fired for entries
+  // explicitly marked `status: destroyed`, which missed two common cases:
+  //   1. A worktree removed via `git worktree remove` (not `caws worktree
+  //      destroy`) that later had its branch manually deleted with
+  //      `git branch -D`.
+  //   2. A worktree whose create failed partway, leaving a registry entry
+  //      at `fresh`/`active` but no artifacts on disk.
+  // Both are pure ghost state — no recoverable work remains in either
+  // the directory or the branch. Pruning is safe. (CAWSFIX-25 / D7)
+  //
+  // Entries with ONE artifact intact (dir gone but branch still present,
+  // or vice versa) are preserved. The branch may still hold unmerged
+  // commits, or the directory may still hold uncommitted work — the user
+  // should merge or explicitly destroy.
   for (const [name, entry] of Object.entries(registry.worktrees || {})) {
-    if (entry.status !== 'destroyed') continue;
     const dirGone = !fs.existsSync(entry.path);
     let branchGone = true;
     if (entry.branch) {
@@ -356,7 +693,7 @@ function autoRegisterWorktree(root, registry, discovered) {
     branch: discovered.branch,
     baseBranch,
     scope: null,
-    specId: null,
+    specId: inferSpecIdForWorktree(discovered.path),
     owner: null,
     createdAt: new Date().toISOString(),
     status: 'active',
@@ -424,6 +761,21 @@ function createWorktree(name, options = {}) {
   const branchName = BRANCH_PREFIX + name;
   const base = baseBranch || getCurrentBranch();
 
+  // CAWSFIX-27: resolve the bound specId (explicit --spec-id OR auto-bind
+  // via worktree-name match) BEFORE creating the worktree, so the
+  // draft→active flip + bind commit land on the base branch before the
+  // worktree forks. Pre-CAWSFIX-27 the auto-bind path activated the spec
+  // but never committed it, leaving main with a dirty spec after
+  // `caws worktree create <name>` (no --spec-id).
+  let resolvedSpecId = specId || null;
+  if (!resolvedSpecId) {
+    resolvedSpecId = findSpecByWorktreeName(root, name);
+    if (resolvedSpecId) {
+      console.log(chalk.gray(`   Auto-bound spec: ${resolvedSpecId}`));
+    }
+  }
+  const canonicalSpecPath = findFeatureSpecPath(root, resolvedSpecId);
+
   // Check if the branch already exists in git (even if not in registry)
   // This catches cases where another agent created the branch outside CAWS
   try {
@@ -449,6 +801,16 @@ function createWorktree(name, options = {}) {
   // Create the worktree directory
   fs.ensureDirSync(path.dirname(worktreePath));
 
+  if (canonicalSpecPath && resolvedSpecId) {
+    // CAWSFIX-23: flip draft→active BEFORE the bind commit so the spec
+    // lifecycle transition lands in the same commit as the worktree field.
+    // CAWSFIX-27: this block now handles BOTH the explicit --spec-id path
+    // and the auto-bind (findSpecByWorktreeName) path — previously only
+    // the explicit path committed the flip.
+    autoActivateBoundSpec(root, resolvedSpecId);
+    ensureCanonicalSpecCommitted(root, canonicalSpecPath, resolvedSpecId, name);
+  }
+
   // Create git worktree with new branch
   try {
     execFileSync('git', ['worktree', 'add', '-b', branchName, worktreePath, base], {
@@ -510,15 +872,20 @@ function createWorktree(name, options = {}) {
     }
   }
 
+  // CAWSFIX-27: resolvedSpecId is now computed before the worktree is
+  // added (see block above the `fs.ensureDirSync` call). The activation
+  // and bind-commit already ran on the base branch, so the worktree forks
+  // from a base that already includes the flip commit.
+
   // Materialize a worktree-local working spec. Prefer the canonical feature
   // spec when it exists so isolated worktrees stay aligned with the main
   // registry/resolver model.
-  if (specId) {
+  if (resolvedSpecId) {
     try {
-      materializeWorktreeSpec(root, cawsDest, specId, name, scope);
+      materializeWorktreeSpec(root, cawsDest, resolvedSpecId, name, scope);
     } catch (error) {
       console.warn(
-        chalk.yellow(`Could not materialize spec '${specId}' for worktree '${name}': ${error.message}`)
+        chalk.yellow(`Could not materialize spec '${resolvedSpecId}' for worktree '${name}': ${error.message}`)
       );
       // Non-fatal: spec generation is optional
     }
@@ -531,7 +898,7 @@ function createWorktree(name, options = {}) {
     branch: branchName,
     baseBranch: base,
     scope: scope || null,
-    specId: specId || null,
+    specId: resolvedSpecId,
     owner: options.owner || getAgentSessionId(root) || null,
     createdAt: new Date().toISOString(),
     status: 'fresh',
@@ -540,6 +907,11 @@ function createWorktree(name, options = {}) {
   registry.worktrees[name] = entry;
   saveRegistry(root, registry);
 
+  // CAWSFIX-32: heartbeat the current session into agents.json so the
+  // worktree+spec context is visible to other agents and to
+  // `caws status` / `caws agents list` immediately after create.
+  refreshAgentClaim(root, { worktree: name, specId: resolvedSpecId || null });
+
   return entry;
 }
 
@@ -892,9 +1264,31 @@ function destroyWorktree(name, options = {}) {
   }
 
   // Update registry
+  const wasAlreadyDestroyed = registry.worktrees[name].status === 'destroyed';
   registry.worktrees[name].status = 'destroyed';
   registry.worktrees[name].destroyedAt = new Date().toISOString();
   saveRegistry(root, registry);
+
+  // CAWSFIX-18: auto-commit the registry so the working tree stays clean
+  if (!wasAlreadyDestroyed) {
+    try {
+      const status = execFileSync('git', ['status', '--porcelain', '.caws/worktrees.json'], {
+        cwd: root, stdio: ['pipe', 'pipe', 'pipe'],
+      }).toString().trim();
+      if (status) {
+        const otherActive = Object.values(registry.worktrees || {}).some(
+          (e) => e.status === 'active' || e.status === 'fresh'
+        );
+        const prefix = otherActive ? 'wip(checkpoint)' : 'chore(worktree)';
+        execFileSync('git', ['add', '.caws/worktrees.json'], { cwd: root, stdio: 'pipe' });
+        execFileSync('git', ['commit', '-m', `${prefix}: record destroyed ${name}`], {
+          cwd: root, stdio: 'pipe',
+        });
+      }
+    } catch (err) {
+      console.warn(chalk.yellow(`   Warning: could not auto-commit .caws/worktrees.json: ${err.message}`));
+    }
+  }
 }
 
 /**
@@ -910,7 +1304,7 @@ function destroyWorktree(name, options = {}) {
 function mergeWorktree(name, options = {}) {
   const root = getRepoRoot();
   const registry = loadRegistry(root);
-  const { dryRun = false, deleteBranch = true, message } = options;
+  const { dryRun = false, deleteBranch = true, message, takeover = false } = options;
 
   let entry = registry.worktrees[name];
   if (!entry) {
@@ -925,6 +1319,26 @@ function mergeWorktree(name, options = {}) {
     }
   }
 
+  // CAWSFIX-32: assert ownership BEFORE any merge/git work. Foreign
+  // claim soft-blocks unless --takeover is supplied, matching the
+  // bind/claim semantics. Throws on refusal so the CLI command handler
+  // surfaces the structured warning.
+  const ownership = assertWorktreeOwnership(root, name, {
+    allowTakeover: takeover,
+    takeoverCommandHint: `caws worktree merge ${name} --takeover`,
+  });
+  if (!ownership.allowed) {
+    const err = new Error(ownership.warning);
+    err.claimWarning = true;
+    throw err;
+  }
+
+  // CAWSFIX-32: heartbeat the current session into agents.json now that
+  // ownership is confirmed. Same-session merges need this since the
+  // takeover branch only fires inside assertWorktreeOwnership when a
+  // takeover actually occurs.
+  refreshAgentClaim(root, { worktree: name, specId: entry.specId || null });
+
   const baseBranch = entry.baseBranch || 'main';
 
   // Check for uncommitted work in the worktree.
@@ -1055,13 +1469,159 @@ function mergeWorktree(name, options = {}) {
     }
   }
 
-  const mergeResult = { name, branch: entry.branch, baseBranch, merged: true, conflicts: [] };
+  // Auto-close the bound spec if one exists. A worktree merge is the
+  // lifecycle signal that the spec's work is done; leaving the spec
+  // `active` (or `draft`, pre-CAWSFIX-23) after merge accumulates stale
+  // entries (D6). Direct YAML status flip bypasses the ownership +
+  // worktree-reference checks in `closeSpec` — the caller has already
+  // proven authority by merging.
+  let autoClose = {
+    specId: null, acsPassing: null, acsFailureCount: 0, acsTotal: 0, acsFailureIds: [],
+    didWrite: false, specPath: null,
+  };
+  if (entry.specId) {
+    autoClose = autoCloseBoundSpec(root, entry.specId);
+    if (autoClose.acsPassing === false && autoClose.acsFailureCount > 0) {
+      console.warn(chalk.yellow(
+        `   ⚠ Spec ${entry.specId} closed with ${autoClose.acsFailureCount}/${autoClose.acsTotal} failing AC(s): ${autoClose.acsFailureIds.join(', ')}`
+      ));
+      console.warn(chalk.yellow(
+        `     Merge succeeded — the spec reflects that — but follow up to address the failing ACs.`
+      ));
+    }
+
+    // CAWSFIX-24 / D6: if the auto-close flipped the status, commit the
+    // change on the base branch before returning. Leaving it uncommitted
+    // was the "dirty main" footgun: the next worktree merge would abort
+    // on "local changes would be overwritten," after the prior worktree
+    // was already destroyed. Use --no-verify to match the merge commit's
+    // hook-skip discipline (the content was verified when the merge ran).
+    if (autoClose.didWrite && autoClose.specPath) {
+      try {
+        const relPath = path.relative(root, autoClose.specPath);
+        execFileSync('git', ['add', '--', relPath], { cwd: root, stdio: 'pipe' });
+        execFileSync(
+          'git',
+          ['commit', '--no-verify', '-m', `chore(caws): close ${autoClose.specId} spec post-merge`, '--', relPath],
+          { cwd: root, stdio: 'pipe' }
+        );
+      } catch (commitErr) {
+        // Non-fatal: a failed auto-commit leaves the spec dirty but the
+        // merge itself already succeeded. Warn so the caller can clean up.
+        console.warn(chalk.yellow(
+          `   ⚠ Auto-commit of ${autoClose.specId} close flip failed: ${commitErr.message}. Commit manually.`
+        ));
+      }
+    }
+  }
+
+  const mergeResult = {
+    name, branch: entry.branch, baseBranch, merged: true, conflicts: [],
+    specId: entry.specId || null,
+    autoClosedSpecId: autoClose.specId,
+    acsPassing: autoClose.acsPassing,
+    acsFailureCount: autoClose.acsFailureCount,
+    acsTotal: autoClose.acsTotal,
+    acsFailureIds: autoClose.acsFailureIds,
+  };
   try {
     lifecycle.emit(EVENTS.MERGE_POST, { ...mergeResult, timestamp: new Date().toISOString() });
   } catch { /* non-fatal */ }
   return mergeResult;
 }
 
+/**
+ * Flip a spec's status from `draft` to `active` by rewriting just the
+ * `status:` line. Called on worktree-bind so specs whose work is
+ * starting transition out of draft without manual intervention.
+ * Idempotent: no-op when the spec is already active/closed/etc.
+ * @param {string} root - Repo root
+ * @param {string} specId - Spec identifier
+ * @returns {string|null} specId on flip, null if no change
+ */
+function autoActivateBoundSpec(root, specId, specPathOverride = null) {
+  try {
+    // CAWSFIX-25 / D8: callers that resolved a worktree-local spec path
+    // (via findFeatureSpecPathFromCwd) pass it in so the flip lands on
+    // the worktree's copy, not main's. Falls through to main resolution
+    // for backward compatibility when override is null.
+    const specPath = specPathOverride || findFeatureSpecPath(root, specId);
+    if (!specPath || !fs.existsSync(specPath)) return null;
+    const original = fs.readFileSync(specPath, 'utf8');
+    // Idempotent: already active/closed/archived → no write.
+    if (/^status:[ \t]*active[ \t]*$/m.test(original)) return specId;
+    const patched = original.replace(/^status:[ \t]*draft[ \t]*$/m, 'status: active');
+    if (patched === original) return null;
+    fs.writeFileSync(specPath, patched, 'utf8');
+    return specId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Flip a spec's status to `closed` by rewriting just the `status:` line.
+ * Accepts both `draft` and `active` as source states — merge is the
+ * authoritative "work done" signal regardless of whether the spec ever
+ * transitioned through active. Runs verify-acs in collect-only mode
+ * before the flip and returns AC health so the caller can warn.
+ * @param {string} root - Repo root
+ * @param {string} specId - Spec identifier (e.g. CAWSFIX-14)
+ * @returns {{specId: string|null, acsPassing: boolean|null, acsFailureCount: number, acsTotal: number, acsFailureIds: string[]}}
+ */
+function autoCloseBoundSpec(root, specId) {
+  const result = {
+    specId: null,
+    acsPassing: null,
+    acsFailureCount: 0,
+    acsTotal: 0,
+    acsFailureIds: [],
+    didWrite: false,
+    specPath: null,
+  };
+  try {
+    const specPath = findFeatureSpecPath(root, specId);
+    if (!specPath || !fs.existsSync(specPath)) return result;
+    result.specPath = specPath;
+    const original = fs.readFileSync(specPath, 'utf8');
+    // Idempotent: already closed → no-op, no write, no diff.
+    if (/^status:[ \t]*closed[ \t]*$/m.test(original)) {
+      result.specId = specId;
+      return result;
+    }
+    // Run verify-acs in collect-only mode before flipping. Never throws —
+    // any error (missing tests, unavailable runner, malformed spec) leaves
+    // acsPassing: null so the caller knows verification didn't run.
+    try {
+      const yaml = require('js-yaml');
+      const { verifySpec } = require('../commands/verify-acs');
+      const parsed = yaml.load(original);
+      if (parsed && typeof parsed === 'object') {
+        const verdict = verifySpec(parsed, root, { run: false });
+        const fails = (verdict.results || []).filter((r) => r.status === 'FAIL');
+        result.acsTotal = (verdict.results || []).length;
+        result.acsFailureCount = fails.length;
+        result.acsFailureIds = fails.map((r) => r.id);
+        result.acsPassing = fails.length === 0;
+      }
+    } catch {
+      // verify-acs unavailable — don't block close
+    }
+    // Flip status. Accept both draft and active as source so specs that
+    // never transitioned through active (D6 pre-CAWSFIX-23 drift) still close.
+    const patched = original.replace(/^status:[ \t]*(?:draft|active)[ \t]*$/m, 'status: closed');
+    if (patched === original) {
+      return result; // status was archived/unknown — leave alone
+    }
+    fs.writeFileSync(specPath, patched, 'utf8');
+    result.specId = specId;
+    result.didWrite = true;
+    return result;
+  } catch {
+    return result;
+  }
+}
+
 /**
  * Prune stale worktree entries
  * @param {Object} options - Prune options
@@ -1149,10 +1709,14 @@ module.exports = {
   listWorktrees,
   destroyWorktree,
   mergeWorktree,
+  autoActivateBoundSpec,
+  autoCloseBoundSpec,
   pruneWorktrees,
   repairWorktrees,
   reconcileRegistry,
   loadRegistry,
+  saveRegistry,
+  assertWorktreeOwnership,
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
@@ -1164,5 +1728,8 @@ module.exports = {
   REGISTRY_FILE,
   BRANCH_PREFIX,
   findFeatureSpecPath,
+  findFeatureSpecPathFromCwd,
   materializeWorktreeSpec,
+  inferSpecIdForWorktree,
+  findSpecByWorktreeName,
 };