@paths.design/caws-cli 10.1.0 → 10.2.0

package/dist/validation/spec-validation.js

@@ -16,31 +16,34 @@ const { createValidator, getSchemaPath } = require('../utils/schema-validator');
  * Accepts:
  *   - Single-segment: FEAT-001, EVLOG-002, CAWSFIX-06 (legacy shape)
  *   - Multi-segment:  P03-IMPL-01, ALG-001A-HARDEN-01, CAWS-FIX-03
+ *   - Lowercase suffix: APC-01a, ALG-01b (CAWSFIX-25 / D2)
  *
  * Rejects:
- *   - lowercase (feat-001)
+ *   - lowercase prefix (feat-001)
+ *   - lowercase in a non-final segment (AB-cd-01)
  *   - leading digit (01-FEAT)
  *   - missing number suffix (FEAT-)
  *   - trailing hyphen (FEAT-01-)
  *   - leading/double hyphen (--FEAT-01, FEAT--001)
  *   - empty string
  *
- * Grammar: [PREFIX](-[SEGMENT])*-NUMBER
+ * Grammar: [PREFIX](-[SEGMENT])*-NUMBER[SUFFIX]?
  *   - PREFIX  = [A-Z] followed by zero+ [A-Z0-9]
  *   - SEGMENT = one+ [A-Z0-9]  (alphanumeric, uppercase only)
  *   - NUMBER  = one+ digits
+ *   - SUFFIX  = zero+ [a-z]    (optional lowercase tail on final segment only)
  *
  * Defined once per A4 invariant; referenced by both the basic validator
  * (line ~125 pre-fix) and the enhanced validator (line ~307 pre-fix).
  */
-const SPEC_ID_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+$/;
+const SPEC_ID_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+[a-z]*$/;
 
 /**
  * User-facing error message for bad spec IDs (CAWSFIX-10 A5).
  * Kept as a module constant so the message stays in sync with the pattern.
  */
 const SPEC_ID_ERROR_MESSAGE =
-  'Project ID should be in format: PREFIX-NUMBER or PREFIX-SEGMENT-NUMBER (e.g., FEAT-001, P03-IMPL-01)';
+  'Project ID should be in format: PREFIX-NUMBER or PREFIX-SEGMENT-NUMBER with optional lowercase suffix (e.g., FEAT-001, P03-IMPL-01, APC-01a)';
 
 /**
  * Get actual budget statistics from git history

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,6 +33,48 @@ 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');
@@ -35,6 +83,18 @@ function writeSpecWithWorktree(filePath, worktreeName) {
     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 });
 }
@@ -84,27 +144,38 @@ 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.
+    // Keep a canonical feature-spec copy inside the worktree.
     const specContent = writeSpecWithWorktree(canonicalSpecPath, worktreeName);
-    fs.writeFileSync(destSpecPath, specContent);
-    fs.writeFileSync(workingSpecPath, specContent);
+    // 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');
   let specContent = generateWorkingSpec({
     projectId: specId,
@@ -150,8 +221,9 @@ function materializeWorktreeSpec(root, cawsDest, specId, worktreeName, scope) {
     // Keep generated spec content if augmentation fails.
   }
 
-  fs.ensureDirSync(path.dirname(workingSpecPath));
-  fs.writeFileSync(workingSpecPath, specContent);
+  fs.ensureDirSync(destSpecsDir);
+  const generatedSpecPath = path.join(destSpecsDir, `${specId}.yaml`);
+  fs.writeFileSync(generatedSpecPath, specContent);
 }
 
 function parseSpecIdFromYamlFile(filePath) {
@@ -332,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
@@ -369,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) {
@@ -550,7 +760,21 @@ function createWorktree(name, options = {}) {
   const worktreePath = path.join(root, WORKTREES_DIR, name);
   const branchName = BRANCH_PREFIX + name;
   const base = baseBranch || getCurrentBranch();
-  const canonicalSpecPath = findFeatureSpecPath(root, specId);
+
+  // 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
@@ -577,8 +801,14 @@ function createWorktree(name, options = {}) {
   // Create the worktree directory
   fs.ensureDirSync(path.dirname(worktreePath));
 
-  if (canonicalSpecPath) {
-    ensureCanonicalSpecCommitted(root, canonicalSpecPath, specId, name);
+  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
@@ -642,16 +872,10 @@ function createWorktree(name, options = {}) {
     }
   }
 
-  // Auto-bind specId: if no explicit --spec-id was passed, scan .caws/specs/
-  // for a spec that declares `worktree: <name>`. This establishes the mutual
-  // reference that the scope guard uses to treat one spec as authoritative.
-  let resolvedSpecId = specId || null;
-  if (!resolvedSpecId) {
-    resolvedSpecId = findSpecByWorktreeName(root, name);
-    if (resolvedSpecId) {
-      console.log(chalk.gray(`   Auto-bound spec: ${resolvedSpecId}`));
-    }
-  }
+  // 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
@@ -683,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;
 }
 
@@ -1075,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) {
@@ -1090,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.
@@ -1222,17 +1471,58 @@ function mergeWorktree(name, options = {}) {
 
   // 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` after merge accumulates stale-active entries (D6). Direct
-  // YAML status flip bypasses the ownership + worktree-reference checks
-  // in `closeSpec` — the caller has already proven authority by merging.
-  let autoClosedSpecId = null;
+  // `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) {
-    autoClosedSpecId = autoCloseBoundSpec(root, 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,
+    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() });
@@ -1240,27 +1530,95 @@ function mergeWorktree(name, options = {}) {
   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.
- * Idempotent: no-op when the spec is already closed or the file is missing.
- * Returns the spec ID on success, null if skipped or failed.
+ * 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 {string|null}
+ * @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 null;
+    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:\s*closed\s*$/m.test(original)) return specId;
-    const patched = original.replace(/^status:\s*active\s*$/m, 'status: closed');
-    if (patched === original) return null; // status was e.g. draft/archived
+    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');
-    return specId;
+    result.specId = specId;
+    result.didWrite = true;
+    return result;
   } catch {
-    return null;
+    return result;
   }
 }
 
@@ -1351,12 +1709,14 @@ module.exports = {
   listWorktrees,
   destroyWorktree,
   mergeWorktree,
+  autoActivateBoundSpec,
   autoCloseBoundSpec,
   pruneWorktrees,
   repairWorktrees,
   reconcileRegistry,
   loadRegistry,
   saveRegistry,
+  assertWorktreeOwnership,
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
@@ -1368,6 +1728,7 @@ module.exports = {
   REGISTRY_FILE,
   BRANCH_PREFIX,
   findFeatureSpecPath,
+  findFeatureSpecPathFromCwd,
   materializeWorktreeSpec,
   inferSpecIdForWorktree,
   findSpecByWorktreeName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "10.1.0",
+  "version": "10.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/.caws/schemas/policy.schema.json

@@ -105,6 +105,11 @@
       },
       "additionalProperties": false,
       "description": "Quality gate configurations"
+    },
+    "non_governed_zones": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns (picomatch, dot:true) for paths declared outside CAWS scope enforcement. Any file matching a pattern is exempt from scope-boundary checks — neither spec.scope.in nor spec.scope.out are consulted. Intended for research, playground, or experimental subtrees where governance is explicitly off by design. Example: [\"research/**\", \"playground/**\"]. (CAWSFIX-26 / D9)"
     }
   },
   "additionalProperties": false,

package/templates/.caws/schemas/working-spec.schema.json

@@ -23,8 +23,8 @@
   "properties": {
     "id": {
       "type": "string",
-      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+$",
-      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-21 alignment)."
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+[a-z]*$",
+      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits with an optional lowercase suffix (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01, APC-01a). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-25 alignment)."
     },
     "title": {
       "type": "string",