@paths.design/caws-cli 9.2.0 → 9.3.1

package/dist/templates/.claude/hooks/session-log.sh

@@ -157,6 +157,33 @@ def rel(path):
         return path[len(cwd) + 1:]
     return path or ""
 
+def decode_structured_text_payload(raw):
+    """Decode JSON-escaped text payloads (e.g., Agent/Task tool outputs)."""
+    if not isinstance(raw, str):
+        return raw
+    payload = raw.strip()
+    if not payload or payload[0] not in "[{":
+        return raw
+    try:
+        parsed = json.loads(payload)
+    except Exception:
+        return raw
+
+    text_blocks = []
+    if isinstance(parsed, dict):
+        parsed = [parsed]
+    if isinstance(parsed, list):
+        for item in parsed:
+            if not isinstance(item, dict):
+                continue
+            text = item.get("text")
+            if isinstance(text, str) and text.strip():
+                text_blocks.append(text)
+
+    if text_blocks:
+        return "\n\n".join(text_blocks)
+    return raw
+
 # ---- Accumulate turns as chronological event timelines ----
 turns = []
 # Each turn: {user, timeline: [{kind, ...}, ...], edits, reads, searches, commands}
@@ -242,18 +269,24 @@ for line in sys.stdin:
         tool_info = pending_tools.get(tid, {})
         name = tool_info.get("name", "unknown")
 
-        # Decide if this result is notable enough to show inline
-        # Task results are always notable (subagent did substantive work)
-        notable = is_error or name == "Task"
+        # Always capture tool results for Bash, Task, Agent.
+        # For Read/Write/Edit, only capture if notable (errors, test output, etc.)
+        # to avoid dumping entire file contents into turn logs.
+        always_capture = name in ("Bash", "Task", "Agent")
+        notable = is_error
         if not notable and content:
             content_lower = content.lower()
             notable = any(kw.lower() in content_lower for kw in NOTABLE_KW)
 
-        if notable and content:
+        if (always_capture or notable) and content:
             # Cap file-content tools (full file reads/writes blow out turn files)
             display = content
             if name in ("Read", "Write", "Edit") and len(content) > 2000:
                 display = content[:2000] + "\n...(file content truncated)"
+            elif name in ("Task", "Agent"):
+                display = decode_structured_text_payload(content)
+            elif name == "Bash" and len(content) > 5000:
+                display = content[:5000] + "\n...(output truncated at 5000 chars)"
             # Graft result onto the original tool_call entry (not a separate timeline item)
             if tool_info:
                 tool_info["output"] = display
@@ -281,7 +314,7 @@ for i, turn in enumerate(turns):
     md_lines = [f"# Turn {num}", ""]
 
     if turn["user"]:
-        md_lines.extend([f"> ---user---\n{turn['user']}\n---/user---", ""])
+        md_lines.extend([f"> ---user---\n{turn['user']}\n---\/user---", ""])
 
     for event in turn["timeline"]:
         kind = event["kind"]

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

@@ -12,16 +12,19 @@ When multiple agents are working on this project, each agent MUST work in its ow
 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>`
+4. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
 
 ## Forbidden operations when worktrees are active
 
 - `git commit --amend` -- rewrites history that other agents depend on
+- `git rebase` -- rewrites branch history; the hook blocks this automatically while worktrees are active. If you need code from main, create a new worktree from current main instead
+- `git cherry-pick` -- replays commits across branches; blocked while worktrees are active to prevent cross-boundary contamination
 - `git stash` / `git stash pop` -- stash is shared across all worktrees; using it can destroy another agent's uncommitted work
 - `git reset --hard` -- discards work that other agents may depend on
 - `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`
+- Destroying another agent's worktree -- even with `--force`. If you did not create it, do not destroy it. Period.
 
 ## Merging worktree branches back to base
 

package/dist/templates/.cursor/README.md

@@ -9,7 +9,6 @@ Cursor hooks enable seamless integration between CAWS and the Cursor IDE, provid
 - **Real-time quality validation** as you code
 - **Automatic spec validation** when editing working specs
 - **Scope enforcement** preventing out-of-scope file access
-- **Tool validation** for safe MCP execution
 - **Quality monitoring** after file edits
 
 ## Hook Configuration
@@ -19,7 +18,6 @@ The `hooks.json` file defines when each hook runs:
 ```json
 {
   "beforeShellExecution": ["block-dangerous.sh", "audit.sh"],
-  "beforeMCPExecution": ["audit.sh", "caws-tool-validation.sh"],
   "beforeReadFile": ["scan-secrets.sh", "caws-scope-guard.sh"],
   "afterFileEdit": ["format.sh", "naming-check.sh", "validate-spec.sh", "caws-quality-check.sh", "audit.sh"],
   "beforeSubmitPrompt": ["caws-scope-guard.sh", "audit.sh"],
@@ -43,12 +41,6 @@ The `hooks.json` file defines when each hook runs:
 - **Blocks**: Yes (for out-of-scope file access)
 - **Requires**: `.caws/working-spec.yaml`
 
-#### `caws-tool-validation.sh`
-- **Trigger**: `beforeMCPExecution`
-- **Purpose**: Validates CAWS MCP tool calls for security
-- **Blocks**: Yes (for dangerous operations or invalid waivers)
-- **Validates**: Waiver creation, tool permissions, command safety
-
 ### General Security Hooks
 
 #### `block-dangerous.sh`
@@ -242,7 +234,6 @@ Cursor Hooks ←→ CAWS CLI ←→ VS Code Extension
 
 - **Git Hooks**: `.git/hooks/` for commit/push validation
 - **VS Code Extension**: Rich UI for CAWS operations
-- **MCP Server**: Agent tool integration
 - **CAWS CLI**: Core functionality
 
 ### Data Flow

package/dist/templates/.cursor/hooks/audit.sh

@@ -2,7 +2,7 @@
 # Cursor Hook: Audit Trail
 # 
 # Purpose: Log all Cursor AI events for provenance tracking
-# Event: All (beforeShellExecution, beforeMCPExecution, beforeReadFile, 
+# Event: All (beforeShellExecution, beforeReadFile,
 #        afterFileEdit, beforeSubmitPrompt, stop)
 # 
 # @author @darianrosebrook

package/dist/templates/.cursor/hooks/block-dangerous.sh

@@ -29,6 +29,7 @@ HARD_BLOCKS=(
   "git commit --amend --no-edit" # Can rewrite commit history destructively
   "git reset --hard"            # Can lose uncommitted work and stashed changes
   "git push --force"             # Can overwrite remote repository history
+  "git rebase"                   # Rewrites branch history; blocked while worktrees are active
   "dd if="
   "mkfs"
   "format c:"

package/dist/templates/.cursor/hooks/scan-secrets.sh

@@ -28,14 +28,19 @@ if [[ "$FILE_PATH" =~ \.(pem|key|p12|pfx|cert|crt)$ ]]; then
 fi
 
 # Scan content for common secret patterns
-if echo "$CONTENT" | grep -qiE "(api[_-]?key|secret[_-]?key|password|private[_-]?key|access[_-]?token|bearer\s+[A-Za-z0-9_\-\.]+|AKIA[0-9A-Z]{16})"; then
+# bearer requires 20+ chars to avoid false positives on short tokens in docs
+# AKIA prefix is specific to AWS access keys
+if echo "$CONTENT" | grep -qiE "(api[_-]?key\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|secret[_-]?key\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|password\s*[:=]\s*['\"]?[^\s'\"]{8,}|private[_-]?key\s*[:=]|access[_-]?token\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{16,}|[Bb]earer\s+[A-Za-z0-9_\-\.]{20,}|AKIA[0-9A-Z]{16})"; then
   # Don't block, but warn
   echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential secrets detected in file. Ensure they are not committed.","agentMessage":"This file may contain secrets. Use placeholder values or environment variables."}' 2>/dev/null
   exit 0
 fi
 
-# Check for common PII patterns (SSN, credit card, etc.)
-if echo "$CONTENT" | grep -qE "([0-9]{3}-[0-9]{2}-[0-9]{4}|[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4}[- ]?[0-9]{4})"; then
+# Check for common PII patterns (SSN, credit card)
+# SSN: exactly 3-2-4 digit pattern (not inside longer numbers)
+# Credit card: require at least a Luhn-plausible 13-19 digit sequence with separators
+if echo "$CONTENT" | grep -qE "(^|[^0-9])[0-9]{3}-[0-9]{2}-[0-9]{4}($|[^0-9])" || \
+   echo "$CONTENT" | grep -qE "(^|[^0-9])[0-9]{4}[- ][0-9]{4}[- ][0-9]{4}[- ][0-9]{4}($|[^0-9])"; then
   echo '{"permission":"allow","userMessage":"⚠️ Warning: Potential PII detected. Ensure compliance with data protection policies.","agentMessage":"This file may contain PII (SSN, credit card). Use anonymized test data."}' 2>/dev/null
   exit 0
 fi

package/dist/templates/.cursor/hooks.json

@@ -9,14 +9,6 @@
         "command": "./.cursor/hooks/audit.sh"
       }
     ],
-    "beforeMCPExecution": [
-      {
-        "command": "./.cursor/hooks/audit.sh"
-      },
-      {
-        "command": "./.cursor/hooks/caws-tool-validation.sh"
-      }
-    ],
     "beforeReadFile": [
       {
         "command": "./.cursor/hooks/scan-secrets.sh"

package/dist/templates/.vscode/launch.json

@@ -1,18 +1,6 @@
 {
   "version": "0.2.0",
   "configurations": [
-    {
-      "name": "Debug MCP Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/packages/caws-mcp-server/index.js",
-      "args": [],
-      "env": {
-        "NODE_ENV": "development",
-        "CAWS_DEBUG": "true"
-      },
-      "console": "integratedTerminal"
-    },
     {
       "name": "Debug CAWS CLI",
       "type": "node",

package/dist/utils/detection.js

@@ -196,7 +196,45 @@ function detectCAWSSetup(cwd = process.cwd()) {
   };
 }
 
+/**
+ * Find the CAWS project root by walking up from startDir looking for .caws/
+ * Falls back to git root, then to process.cwd()
+ * @param {string} [startDir] - Directory to start searching from
+ * @returns {string} Project root directory path
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  // In a monorepo, nested packages may have their own .caws/ (scaffold debris).
+  // The git root's .caws/ is authoritative — check it first.
+  try {
+    const { execFileSync } = require('child_process');
+    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      cwd: startDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (gitRoot && fs.existsSync(path.join(gitRoot, '.caws'))) {
+      return gitRoot;
+    }
+  } catch {
+    // Not a git repo or git not available — fall through
+  }
+
+  // Walk up looking for .caws/ directory (non-git projects)
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.caws'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  // Final fallback: cwd
+  return process.cwd();
+}
+
 module.exports = {
   detectCAWSSetup,
   findPackageRoot,
+  findProjectRoot,
 };

package/dist/utils/project-analysis.js

@@ -347,7 +347,6 @@ function getTodoAnalyzerSuggestion(cwd = process.cwd()) {
     suggestions.push(
       '   - Install Node.js: https://nodejs.org/ (then use: npx --yes @paths.design/quality-gates)'
     );
-    suggestions.push('   - Use CAWS MCP server: caws quality-gates (via MCP)');
   }
 
   // Check for project-specific scripts (language-agnostic - if they exist, suggest them)

package/dist/utils/spec-resolver.js

@@ -12,6 +12,7 @@ const chalk = require('chalk');
 
 // Import SPEC_TYPES from constants for consistent display
 const { SPEC_TYPES } = require('../constants/spec-types');
+const { findProjectRoot } = require('./detection');
 
 /**
  * Spec resolution priority:
@@ -22,6 +23,18 @@ const SPECS_DIR = '.caws/specs';
 const LEGACY_SPEC = '.caws/working-spec.yaml';
 const SPECS_REGISTRY = '.caws/specs/registry.json';
 
+/**
+ * Get the project root for spec resolution.
+ * Caches per process to avoid repeated filesystem walks.
+ */
+let _cachedProjectRoot = null;
+function getProjectRoot() {
+  if (!_cachedProjectRoot) {
+    _cachedProjectRoot = findProjectRoot();
+  }
+  return _cachedProjectRoot;
+}
+
 /**
  * Resolve spec file path based on priority
  * @param {Object} options - Resolution options
@@ -36,7 +49,7 @@ async function resolveSpec(options = {}) {
 
   // 1. Explicit file path takes highest priority
   if (specFile) {
-    const explicitPath = path.isAbsolute(specFile) ? specFile : path.join(process.cwd(), specFile);
+    const explicitPath = path.isAbsolute(specFile) ? specFile : path.join(getProjectRoot(), specFile);
 
     if (await fs.pathExists(explicitPath)) {
       const yaml = require('js-yaml');
@@ -55,7 +68,7 @@ async function resolveSpec(options = {}) {
 
   // 2. Feature-specific spec (preferred for multi-agent)
   if (specId) {
-    const featurePath = path.join(process.cwd(), SPECS_DIR, `${specId}.yaml`);
+    const featurePath = path.join(getProjectRoot(), SPECS_DIR, `${specId}.yaml`);
 
     if (await fs.pathExists(featurePath)) {
       const yaml = require('js-yaml');
@@ -83,7 +96,7 @@ async function resolveSpec(options = {}) {
   if (specIds.length === 1) {
     // Single spec - use it automatically
     const singleSpecId = specIds[0];
-    const singleSpecPath = path.join(process.cwd(), SPECS_DIR, registry.specs[singleSpecId].path);
+    const singleSpecPath = path.join(getProjectRoot(), SPECS_DIR, registry.specs[singleSpecId].path);
 
     if (await fs.pathExists(singleSpecPath)) {
       const yaml = require('js-yaml');
@@ -179,7 +192,7 @@ async function resolveSpec(options = {}) {
   }
 
   // 4. Fall back to legacy working-spec.yaml (with warning)
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
 
   if (await fs.pathExists(legacyPath)) {
     const yaml = require('js-yaml');
@@ -211,7 +224,7 @@ async function resolveSpec(options = {}) {
  * @returns {Promise<Object>} Registry data
  */
 async function loadSpecsRegistry() {
-  const registryPath = path.join(process.cwd(), SPECS_REGISTRY);
+  const registryPath = path.join(getProjectRoot(), SPECS_REGISTRY);
 
   if (!(await fs.pathExists(registryPath))) {
     return {
@@ -241,7 +254,7 @@ async function listAvailableSpecs() {
   const specs = [];
 
   // Check feature-specific specs
-  const specsDir = path.join(process.cwd(), SPECS_DIR);
+  const specsDir = path.join(getProjectRoot(), SPECS_DIR);
   if (await fs.pathExists(specsDir)) {
     const files = await fs.readdir(specsDir);
     const yamlFiles = files.filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
@@ -257,7 +270,7 @@ async function listAvailableSpecs() {
 
         specs.push({
           id: spec.id || path.basename(file, path.extname(file)),
-          path: path.relative(process.cwd(), specPath),
+          path: path.relative(getProjectRoot(), specPath),
           type: 'feature',
           title: spec.title || 'Untitled',
         });
@@ -268,7 +281,7 @@ async function listAvailableSpecs() {
   }
 
   // Check legacy working-spec.yaml
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
   if (await fs.pathExists(legacyPath)) {
     try {
       const yaml = require('js-yaml');
@@ -342,7 +355,7 @@ async function interactiveSpecSelection(specIds) {
 async function checkMultiSpecStatus() {
   const registry = await loadSpecsRegistry();
   const hasFeatureSpecs = Object.keys(registry.specs ?? {}).length > 0;
-  const legacyPath = path.join(process.cwd(), LEGACY_SPEC);
+  const legacyPath = path.join(getProjectRoot(), LEGACY_SPEC);
   const hasLegacySpec = await fs.pathExists(legacyPath);
 
   return {
@@ -374,7 +387,7 @@ async function checkScopeConflicts(specIds) {
       try {
         spec = yaml.load(content);
       } catch (yamlError) {
-        const relativePath = path.relative(process.cwd(), specPath);
+        const relativePath = path.relative(getProjectRoot(), specPath);
         throw new Error(
           `Invalid YAML syntax in ${relativePath}: ${yamlError.message}\n` +
             (yamlError.mark

package/dist/worktree/worktree-manager.js

@@ -101,6 +101,106 @@ function saveRegistry(root, registry) {
   fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
 }
 
+/**
+ * Discover git worktrees under .caws/worktrees/ that are not in the registry.
+ * @param {string} root - Repository root
+ * @param {Object} registry - Current registry object
+ * @returns {Array<{ name: string, path: string, branch: string }>}
+ */
+function discoverUnregisteredWorktrees(root, registry) {
+  const unregistered = [];
+  try {
+    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    let worktreesDir;
+    try {
+      worktreesDir = fs.realpathSync(path.resolve(root, WORKTREES_DIR));
+    } catch {
+      // Directory might not exist yet
+      worktreesDir = path.resolve(root, WORKTREES_DIR);
+    }
+
+    const blocks = output.split('\n\n').filter(Boolean);
+    for (const block of blocks) {
+      const lines = block.split('\n');
+      const wtLine = lines.find((l) => l.startsWith('worktree '));
+      const branchLine = lines.find((l) => l.startsWith('branch '));
+      if (!wtLine) continue;
+
+      const wtPath = wtLine.replace('worktree ', '');
+      let resolvedPath;
+      try {
+        resolvedPath = fs.realpathSync(wtPath);
+      } catch {
+        resolvedPath = path.resolve(wtPath);
+      }
+
+      // Only consider worktrees under .caws/worktrees/
+      if (!resolvedPath.startsWith(worktreesDir + path.sep)) continue;
+
+      const name = path.basename(resolvedPath);
+      if (registry.worktrees[name]) continue;
+
+      const branch = branchLine
+        ? branchLine.replace('branch refs/heads/', '')
+        : `${BRANCH_PREFIX}${name}`;
+      unregistered.push({ name, path: resolvedPath, branch });
+    }
+  } catch {
+    // git worktree list failed
+  }
+  return unregistered;
+}
+
+/**
+ * Auto-register an unregistered worktree. Infers baseBranch via merge-base.
+ * @param {string} root - Repository root
+ * @param {Object} registry - Registry object (mutated in place)
+ * @param {{ name: string, path: string, branch: string }} discovered
+ * @returns {Object} The registered entry
+ */
+function autoRegisterWorktree(root, registry, discovered) {
+  let baseBranch = 'main';
+  try {
+    execFileSync(
+      'git',
+      ['merge-base', discovered.branch, 'main'],
+      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+    );
+  } catch {
+    try {
+      execFileSync(
+        'git',
+        ['merge-base', discovered.branch, 'master'],
+        { cwd: root, encoding: 'utf8', stdio: 'pipe' }
+      );
+      baseBranch = 'master';
+    } catch {
+      // Keep 'main' as default
+    }
+  }
+
+  const entry = {
+    name: discovered.name,
+    path: discovered.path,
+    branch: discovered.branch,
+    baseBranch,
+    scope: null,
+    specId: null,
+    owner: null,
+    createdAt: new Date().toISOString(),
+    status: 'active',
+    autoRegistered: true,
+  };
+
+  registry.worktrees[discovered.name] = entry;
+  saveRegistry(root, registry);
+  return entry;
+}
+
 /**
  * Create a new git worktree with scope isolation
  * @param {string} name - Worktree name
@@ -308,6 +408,25 @@ function listWorktrees() {
     };
   });
 
+  // Append unregistered worktrees discovered from git
+  const unregistered = discoverUnregisteredWorktrees(root, registry);
+  for (const discovered of unregistered) {
+    const lastCommit = getLastCommitInfo(discovered.branch, root);
+    entries.push({
+      name: discovered.name,
+      path: discovered.path,
+      branch: discovered.branch,
+      baseBranch: null,
+      scope: null,
+      specId: null,
+      owner: null,
+      createdAt: null,
+      status: 'unregistered',
+      lastCommit,
+      merged: false,
+    });
+  }
+
   return entries;
 }
 
@@ -323,9 +442,17 @@ function destroyWorktree(name, options = {}) {
   const registry = loadRegistry(root);
   const { deleteBranch = false, force = false } = options;
 
-  const entry = registry.worktrees[name];
+  let entry = registry.worktrees[name];
   if (!entry) {
-    throw new Error(`Worktree '${name}' not found in registry`);
+    // Fallback: scan git for unregistered worktree and auto-register
+    const unregistered = discoverUnregisteredWorktrees(root, registry);
+    const discovered = unregistered.find((u) => u.name === name);
+    if (discovered) {
+      console.log(chalk.yellow(`Worktree '${name}' not in registry but found in git. Auto-registering.`));
+      entry = autoRegisterWorktree(root, registry, discovered);
+    } else {
+      throw new Error(`Worktree '${name}' not found in registry or git worktree list`);
+    }
   }
 
   // Ownership check: refuse to destroy another agent's active worktree without --force
@@ -343,10 +470,27 @@ function destroyWorktree(name, options = {}) {
       `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.`
+        `Another agent may be actively working here.\n` +
+        `Do NOT destroy worktrees you did not create. Ask the user if cleanup is needed.`
     );
   }
 
+  // Even with --force, warn loudly when destroying another session's worktree
+  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})` : '';
+    console.log(chalk.red(`\n   ⚠ WARNING: Force-destroying worktree '${name}' owned by another session${recency}`));
+    console.log(chalk.red(`   Owner: ${entry.owner}`));
+    console.log(chalk.red(`   You:   ${currentSession}`));
+    console.log(chalk.red(`   If the other agent is still running, this WILL break their work.\n`));
+  }
+
   // 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
@@ -421,9 +565,17 @@ function mergeWorktree(name, options = {}) {
   const registry = loadRegistry(root);
   const { dryRun = false, deleteBranch = true, message } = options;
 
-  const entry = registry.worktrees[name];
+  let entry = registry.worktrees[name];
   if (!entry) {
-    throw new Error(`Worktree '${name}' not found in registry`);
+    // Fallback: scan git for unregistered worktree and auto-register
+    const unregistered = discoverUnregisteredWorktrees(root, registry);
+    const discovered = unregistered.find((u) => u.name === name);
+    if (discovered) {
+      console.log(chalk.yellow(`Worktree '${name}' not in registry but found in git. Auto-registering.`));
+      entry = autoRegisterWorktree(root, registry, discovered);
+    } else {
+      throw new Error(`Worktree '${name}' not found in registry or git worktree list`);
+    }
   }
 
   const baseBranch = entry.baseBranch || 'main';
@@ -452,7 +604,7 @@ function mergeWorktree(name, options = {}) {
   let conflicts = [];
   try {
     // New-style merge-tree: takes two branches, computes merge-base automatically
-    const mergeTreeResult = execFileSync(
+    execFileSync(
       'git',
       ['merge-tree', '--write-tree', baseBranch, entry.branch],
       { cwd: root, encoding: 'utf8', stdio: 'pipe' }
@@ -607,6 +759,8 @@ module.exports = {
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
+  discoverUnregisteredWorktrees,
+  autoRegisterWorktree,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "9.2.0",
+  "version": "9.3.1",
   "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/tools/README.md

@@ -4,18 +4,15 @@ This directory contains CAWS-specific tools that aren't available in the CLI.
 
 ## scope-guard.js
 
-Enforces that experimental code stays within designated sandbox areas. Used by Cursor hooks for scope validation.
+Checks whether a file is within scope of active working-spec and feature specs. Used by Cursor hooks for scope validation on file attachments.
 
 ```bash
-# Validate experimental code containment
-node .caws/tools/scope-guard.js validate
+# Check if a file is in scope
+node .caws/tools/scope-guard.js check src/index.js
 
-# Check containment status
-node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+# Exit code 0 = in scope, 1 = out of scope
 ```
 
 **Usage in Cursor Hooks:**
 
 The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
-
-