compound-agent 1.2.10 → 1.2.11

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { getLlama, resolveModelFile } from 'node-llama-cpp';
-import { mkdirSync, writeFileSync, statSync, existsSync, unlinkSync, readFileSync, chmodSync, readdirSync } from 'fs';
+import { mkdirSync, writeFileSync, statSync, unlinkSync, existsSync, readFileSync, copyFileSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
-import { join, dirname, resolve, relative } from 'path';
+import path, { join, dirname, resolve, relative } from 'path';
 import * as fs from 'fs/promises';
 import { readFile, mkdir, appendFile, writeFile, chmod, rm, rename } from 'fs/promises';
 import { createHash } from 'crypto';
@@ -31,6 +31,27 @@ function parseLimit(value, name) {
 function getRepoRoot() {
   return process.env["COMPOUND_AGENT_ROOT"] ?? process.cwd();
 }
+var EPIC_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function validateEpicId(epicId) {
+  if (!EPIC_ID_PATTERN.test(epicId)) {
+    throw new Error(`Invalid epic ID: "${epicId}" (must be alphanumeric with hyphens/underscores)`);
+  }
+}
+function parseBdShowDeps(raw) {
+  const data = JSON.parse(raw);
+  const issue = Array.isArray(data) ? data[0] : data;
+  if (!issue) return [];
+  const depsArray = issue.depends_on ?? issue.dependencies ?? [];
+  return depsArray.map((dep) => ({
+    id: dep.id ?? "",
+    title: dep.title ?? "",
+    status: dep.status ?? "open"
+  }));
+}
+function shortId(fullId) {
+  const parts = fullId.split("-");
+  return parts[parts.length - 1] ?? fullId;
+}
 var MODEL_URI = "hf:ggml-org/embeddinggemma-300M-qat-q4_0-GGUF/embeddinggemma-300M-qat-Q4_0.gguf";
 var MODEL_FILENAME = "hf_ggml-org_embeddinggemma-300M-qat-Q4_0.gguf";
 var DEFAULT_MODEL_DIR = join(homedir(), ".node-llama-cpp", "models");
@@ -805,6 +826,7 @@ async function compact(repoRoot) {
 }
 
 // src/memory/search/vector.ts
+var cctEmbeddingCache = /* @__PURE__ */ new Map();
 function cosineSimilarity(a, b) {
   if (a.length !== b.length) {
     throw new Error("Vectors must have same length");
@@ -867,7 +889,13 @@ async function searchVector(repoRoot, query, options) {
   for (const pattern of cctPatterns) {
     try {
       const text = `${pattern.name} ${pattern.description}`;
-      const vec = await embedText(text);
+      const hash = contentHash(pattern.name, pattern.description);
+      const cacheKey = `${pattern.id}:${hash}`;
+      let vec = cctEmbeddingCache.get(cacheKey);
+      if (!vec) {
+        vec = await embedText(text);
+        cctEmbeddingCache.set(cacheKey, vec);
+      }
       const score = cosineSimilarity(queryVector, vec);
       scored.push({ lesson: cctToMemoryItem(pattern), score });
     } catch {
@@ -1070,11 +1098,17 @@ function registerCompoundCommands(program2) {
       process.exitCode = 1;
       return;
     }
+    openDb(repoRoot);
     const embeddings = [];
     try {
       for (const item of items) {
         const text = `${item.trigger} ${item.insight}`;
-        const vec = await embedText(text);
+        const hash = contentHash(item.trigger, item.insight);
+        let vec = getCachedEmbedding(repoRoot, item.id, hash);
+        if (!vec) {
+          vec = await embedText(text);
+          setCachedEmbedding(repoRoot, item.id, vec, hash);
+        }
         embeddings.push(Array.isArray(vec) ? vec : Array.from(vec));
       }
     } catch (err) {
@@ -1082,6 +1116,8 @@ function registerCompoundCommands(program2) {
       console.error("Run: npx ca download-model");
       process.exitCode = 1;
       return;
+    } finally {
+      closeDb();
     }
     const { clusters } = clusterBySimilarity(items, embeddings);
     const multiClusters = clusters.filter((c) => c.length >= 2);
@@ -2132,7 +2168,7 @@ function formatError(command, code, message, remediation) {
 }
 var STATE_DIR = ".claude";
 var STATE_FILE = ".ca-phase-state.json";
-var EPIC_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_-]+$/;
 var PHASES = ["brainstorm", "plan", "work", "review", "compound"];
 var GATES = ["post-plan", "gate-3", "gate-4", "final"];
 var PHASE_INDEX = {
@@ -2187,9 +2223,9 @@ function initPhaseState(repoRoot, epicId) {
 }
 function getPhaseState(repoRoot) {
   try {
-    const path = getStatePath(repoRoot);
-    if (!existsSync(path)) return null;
-    const raw = readFileSync(path, "utf-8");
+    const path2 = getStatePath(repoRoot);
+    if (!existsSync(path2)) return null;
+    const raw = readFileSync(path2, "utf-8");
     const parsed = JSON.parse(raw);
     return validatePhaseState(parsed) ? parsed : null;
   } catch {
@@ -2215,8 +2251,8 @@ function startPhase(repoRoot, phase) {
 }
 function cleanPhaseState(repoRoot) {
   try {
-    const path = getStatePath(repoRoot);
-    if (existsSync(path)) unlinkSync(path);
+    const path2 = getStatePath(repoRoot);
+    if (existsSync(path2)) unlinkSync(path2);
   } catch {
   }
 }
@@ -2246,9 +2282,10 @@ function printStatusHuman(state) {
 }
 function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
   phaseCheck.command("init <epic-id>").description("Initialize phase state for an epic").action((epicId) => {
-    if (!EPIC_ID_PATTERN.test(epicId)) {
+    if (!EPIC_ID_PATTERN2.test(epicId)) {
       console.error(`Invalid epic ID: "${epicId}"`);
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (getDryRun()) {
       console.log(`[dry-run] Would initialize phase state for epic ${epicId} in ${repoRoot()}`);
@@ -2260,7 +2297,8 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
   phaseCheck.command("start <phase>").description("Start or resume a phase").action((phase) => {
     if (!isPhaseName(phase)) {
       console.error(`Invalid phase: "${phase}". Valid phases: ${PHASES.join(", ")}`);
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (getDryRun()) {
       console.log(`[dry-run] Would start phase ${phase}`);
@@ -2269,14 +2307,16 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
     const state = startPhase(repoRoot(), phase);
     if (state === null) {
       console.error("No active phase state. Run: ca phase-check init <epic-id>");
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     console.log(`Phase updated: ${state.current_phase} (${state.phase_index}/5).`);
   });
   phaseCheck.command("gate <gate-name>").description("Record a phase gate as passed").action((gateName) => {
     if (!isGateName(gateName)) {
       console.error(`Invalid gate: "${gateName}". Valid gates: ${GATES.join(", ")}`);
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (getDryRun()) {
       console.log(`[dry-run] Would record gate ${gateName}`);
@@ -2285,7 +2325,8 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
     const state = recordGatePassed(repoRoot(), gateName);
     if (state === null) {
       console.error("No active phase state. Run: ca phase-check init <epic-id>");
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (gateName === "final") {
       console.log("Final gate recorded. Phase state cleaned.");
@@ -2345,8 +2386,8 @@ function processPhaseGuard(repoRoot, toolName, _toolInput) {
 
 // src/setup/hooks-read-tracker.ts
 var SKILL_PATH_PATTERN = /(?:^|\/)\.claude\/skills\/compound\/([^/]+)\/SKILL\.md$/;
-function normalizePath(path) {
-  return path.replaceAll("\\", "/");
+function normalizePath(path2) {
+  return path2.replaceAll("\\", "/");
 }
 function toCanonicalSkillPath(filePath) {
   const normalized = normalizePath(filePath);
@@ -2744,7 +2785,7 @@ function registerHooksCommand(program2) {
           )
         );
       }
-      process.exit(1);
+      process.exitCode = 1;
     }
   });
 }
@@ -2939,13 +2980,9 @@ Spawned as a **subagent**. Follow the **memory-analyst** role skill for full ins
 `
 };
 
-// src/setup/templates/agents-workflow.ts
-var WORKFLOW_AGENT_TEMPLATES = {};
-
 // src/setup/templates/agents.ts
 var AGENT_TEMPLATES = {
   ...REVIEW_AGENT_TEMPLATES,
-  ...WORKFLOW_AGENT_TEMPLATES,
   ...PHASE11_AGENT_TEMPLATES,
   ...EXTERNAL_AGENT_TEMPLATES
 };
@@ -3608,6 +3645,17 @@ $ARGUMENTS
 # LFG
 
 **MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/lfg/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full orchestration workflow you must follow.
+`,
+  "set-worktree.md": `---
+name: compound:set-worktree
+description: Set up a git worktree for isolated epic execution
+argument-hint: "<epic-id>"
+---
+$ARGUMENTS
+
+# Set Worktree
+
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/set-worktree/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   // =========================================================================
   // Utility commands (CLI wrappers)
@@ -3785,6 +3833,7 @@ Create a concrete implementation plan by decomposing work into small, testable t
 8. Map dependencies between tasks
 9. Create beads issues: \`bd create --title="..." --type=task\`
 10. Create review and compound blocking tasks (\`bd create\` + \`bd dep add\`) that depend on work tasks \u2014 these survive compaction and surface via \`bd ready\` after work completes
+11. Run \`npx ca worktree wire-deps <epic-id>\` to connect merge dependencies (graceful no-op if no worktree is active)
 
 ## Memory Integration
 - Run \`npx ca search\` for patterns related to the feature area
@@ -3817,6 +3866,7 @@ Create a concrete implementation plan by decomposing work into small, testable t
 After creating all tasks, verify review and compound tasks exist:
 - Run \`bd list --status=open\` and check for a "Review:" task and a "Compound:" task
 - If either is missing, CREATE THEM NOW. The plan is NOT complete without these gates.
+- If a Merge: task exists in the dependency graph, verify it has Review and Compound as blockers (run \`bd show <merge-id>\` to confirm)
 `,
   work: `---
 name: Work
@@ -4015,6 +4065,48 @@ Before closing the epic:
 - Run \`pnpm test\` and \`pnpm lint\` -- must pass
 If verify-gates fails, the missing phase was SKIPPED. Go back and complete it.
 CRITICAL: 3/5 phases is NOT success. All 5 phases are required.
+`,
+  "set-worktree": `---
+name: Set Worktree
+description: Configure an isolated git worktree for parallel epic execution
+---
+
+# Set Worktree Skill
+
+## Overview
+Set up a git worktree to isolate epic work from the main branch. This creates a separate working directory, installs dependencies, and creates a Merge beads task that orchestrates the merge lifecycle.
+
+## Methodology
+1. Validate the epic exists: run \`bd show <epic-id>\` to confirm the epic is open
+2. Search memory with \`npx ca search "worktree"\` for past worktree lessons
+3. Run the worktree creation command: \`npx ca worktree create <epic-id>\`
+4. Verify output: confirm worktree path, branch name, and Merge task ID are reported
+5. Note the Merge task ID -- it will surface via \`bd ready\` after all work tasks complete
+6. Confirm the worktree is ready: check that \`.claude/\` directory exists in the worktree
+7. Inform the user: the worktree is set up, they can now run \`/compound:lfg\` to start work
+
+## What Happens Under the Hood
+- A git worktree is created at \`../<repo>-wt-<epic-id>\` on branch \`epic/<epic-id>\`
+- Dependencies are installed via \`pnpm install --frozen-lockfile\`
+- Lessons JSONL is copied (not symlinked) to the worktree
+- A Merge beads task is created with the epic as its dependent
+- When all work completes, the Merge task surfaces via \`bd ready\`
+
+## Memory Integration
+- Run \`npx ca search "worktree"\` before creating to check for known issues
+- Run \`npx ca learn\` if you discover worktree-specific knowledge
+
+## Common Pitfalls
+- Creating a worktree for an epic that already has one (the command checks for this)
+- Forgetting to run \`/compound:lfg\` after setup (the worktree alone does nothing)
+- Not noting the Merge task ID (needed for later reference)
+- Running from inside an existing worktree (must run from main repo)
+
+## Quality Criteria
+- Worktree was created successfully (path exists)
+- \`pnpm install\` completed without errors
+- Merge beads task exists and is linked to the epic
+- User was informed of next steps (\`/compound:lfg\`)
 `,
   lfg: `---
 name: LFG
@@ -4697,7 +4789,8 @@ function registerClaudeSubcommand(setupCommand) {
       } else {
         console.error(formatError("setup", "PARSE_ERROR", "Failed to parse settings file", "Check if JSON is valid"));
       }
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     const alreadyInstalled = hasAllCompoundAgentHooks(settings);
     if (options.status) {
@@ -4934,7 +5027,8 @@ async function showAction(id, options) {
       const msg = wasDeleted ? `Lesson ${id} not found (deleted)` : `Lesson ${id} not found`;
       console.error(formatError("show", "NOT_FOUND", msg, 'Use "ca list" to see available lessons'));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   if (options.json) {
     console.log(JSON.stringify(item, null, SHOW_JSON_INDENT));
@@ -4966,7 +5060,8 @@ async function updateAction(id, options) {
     } else {
       console.error(formatError("update", "NO_FIELDS", "No fields to update", "Specify at least one: --insight, --tags, --severity, ..."));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const { items } = await readMemoryItems(repoRoot);
   const item = items.find((i) => i.id === id);
@@ -4978,7 +5073,8 @@ async function updateAction(id, options) {
       const msg = wasDeleted ? `Lesson ${id} is deleted` : `Lesson ${id} not found`;
       console.error(formatError("update", "NOT_FOUND", msg, 'Use "ca list" to see available lessons'));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   if (options.severity !== void 0) {
     const result = SeveritySchema.safeParse(options.severity);
@@ -4988,7 +5084,8 @@ async function updateAction(id, options) {
       } else {
         console.error(formatError("update", "INVALID_SEVERITY", `Invalid severity: "${options.severity}"`, "Use --severity high|medium|low"));
       }
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   }
   const updatedItem = buildUpdatedItem(item, options);
@@ -4999,7 +5096,8 @@ async function updateAction(id, options) {
     } else {
       console.error(formatError("update", "VALIDATION_FAILED", `Schema validation failed: ${validationResult.error.message}`, "Check field values and try again"));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   await appendMemoryItem(repoRoot, updatedItem);
   await syncIfNeeded(repoRoot);
@@ -5043,7 +5141,8 @@ async function deleteAction(ids, options) {
       out.warn(`${warning.id}: ${warning.message}`);
     }
     if (deleted.length === 0 && warnings.length > 0) {
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   }
 }
@@ -5122,7 +5221,8 @@ function registerInvalidationCommands(program2) {
     const lesson = items.find((l) => l.id === id);
     if (!lesson) {
       console.error(formatError("wrong", "NOT_FOUND", `Lesson not found: ${id}`, 'Use "ca list" to see available lessons'));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (lesson.invalidatedAt) {
       out.warn(`Lesson ${id} is already marked as invalid.`);
@@ -5145,7 +5245,8 @@ function registerInvalidationCommands(program2) {
     const lesson = items.find((l) => l.id === id);
     if (!lesson) {
       console.error(formatError("validate", "NOT_FOUND", `Lesson not found: ${id}`, 'Use "ca list" to see available lessons'));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (!lesson.invalidatedAt) {
       out.info(`Lesson ${id} is not invalidated.`);
@@ -5168,7 +5269,8 @@ async function exportAction(options) {
     const sinceDate = new Date(options.since);
     if (Number.isNaN(sinceDate.getTime())) {
       console.error(formatError("export", "INVALID_DATE", `Invalid date format: ${options.since}`, "Use ISO8601 format (e.g., 2024-01-15)"));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     filtered = filtered.filter((item) => new Date(item.created) >= sinceDate);
   }
@@ -5190,7 +5292,8 @@ async function importAction(file) {
     } else {
       console.error(formatError("import", "READ_ERROR", `Error reading file: ${err.message}`, "Check file permissions"));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const { items: existingItems } = await readMemoryItems(repoRoot);
   const existingIds = new Set(existingItems.map((item) => item.id));
@@ -5486,7 +5589,8 @@ function registerAuditCommands(program2) {
     } catch (err) {
       const msg = err instanceof Error ? err.message : "Audit failed";
       console.error(formatError("audit", "AUDIT_ERROR", msg, "Check repo configuration"));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (opts.json) {
       console.log(JSON.stringify(report, null, JSON_INDENT));
@@ -5513,7 +5617,7 @@ function registerAuditCommands(program2) {
       }
     }
     if (report.summary.errors > 0) {
-      process.exit(1);
+      process.exitCode = 1;
     }
   });
 }
@@ -5523,10 +5627,10 @@ function configPath(repoRoot) {
   return join(repoRoot, ".claude", CONFIG_FILENAME);
 }
 async function readConfig(repoRoot) {
-  const path = configPath(repoRoot);
-  if (!existsSync(path)) return {};
+  const path2 = configPath(repoRoot);
+  if (!existsSync(path2)) return {};
   try {
-    const parsed = JSON.parse(await readFile(path, "utf-8"));
+    const parsed = JSON.parse(await readFile(path2, "utf-8"));
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
     return parsed;
   } catch {
@@ -5628,7 +5732,8 @@ function registerRulesCommands(program2) {
     } catch (err) {
       const msg = err instanceof Error ? err.message : "Failed to load rules config";
       console.error(formatError("rules", "CONFIG_ERROR", msg, "Check .claude/rules.json syntax"));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     if (config.rules.length === 0) {
       if (!quiet) {
@@ -5660,7 +5765,7 @@ function registerRulesCommands(program2) {
     console.log("");
     console.log(`Rules: ${total} checked, ${errors} error(s), ${warnings} warning(s), ${passed} passed`);
     if (errors > 0) {
-      process.exit(1);
+      process.exitCode = 1;
     }
   });
 }
@@ -5761,16 +5866,8 @@ function registerTestSummaryCommand(program2) {
     process.exit(exitCode);
   });
 }
-var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_-]+$/;
 function parseDepsJson(raw) {
-  const data = JSON.parse(raw);
-  const issue = Array.isArray(data) ? data[0] : data;
-  if (!issue) return [];
-  const depsArray = issue.depends_on ?? issue.dependencies ?? [];
-  return depsArray.map((dep) => ({
-    closed: dep.status === "closed",
-    title: dep.title ?? ""
-  }));
+  return parseBdShowDeps(raw).map((d) => ({ closed: d.status === "closed", title: d.title }));
 }
 function parseDepsText(output) {
   const deps = [];
@@ -5805,9 +5902,7 @@ function checkGate(deps, prefix, gateName) {
   return { name: gateName, status: "pass" };
 }
 async function runVerifyGates(epicId, options = {}) {
-  if (!EPIC_ID_PATTERN2.test(epicId)) {
-    throw new Error(`Invalid epic ID: "${epicId}" (must be alphanumeric with hyphens/underscores)`);
-  }
+  validateEpicId(epicId);
   const repoRoot = options.repoRoot ?? getRepoRoot();
   const raw = execFileSync("bd", ["show", epicId, "--json"], { encoding: "utf-8" });
   let deps;
@@ -5821,6 +5916,10 @@ async function runVerifyGates(epicId, options = {}) {
     checkGate(deps, "Review:", "Review task"),
     checkGate(deps, "Compound:", "Compound task")
   ];
+  const mergeTask = deps.find((d) => d.title.startsWith("Merge:"));
+  if (mergeTask) {
+    checks.push(checkGate(deps, "Merge:", "Merge task"));
+  }
   const allPassed = checks.every((check) => check.status === "pass");
   if (allPassed) {
     const state = getPhaseState(repoRoot);
@@ -5863,6 +5962,291 @@ function registerVerifyGatesCommand(program2) {
     }
   });
 }
+function parseWorktreeList(raw) {
+  const entries = [];
+  let currentPath = "";
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      currentPath = line.slice("worktree ".length);
+    } else if (line.startsWith("branch ")) {
+      const branch = line.slice("branch refs/heads/".length);
+      entries.push({ path: currentPath, branch });
+    }
+  }
+  return entries;
+}
+function runWorktreeCreate(epicId) {
+  validateEpicId(epicId);
+  const repoRoot = getRepoRoot();
+  const basename = path.basename(repoRoot);
+  const worktreePath = path.resolve(repoRoot, "..", `${basename}-wt-${epicId}`);
+  const branch = `epic/${epicId}`;
+  const listRaw = execFileSync("git", ["worktree", "list", "--porcelain"], { encoding: "utf-8" });
+  const existing = parseWorktreeList(listRaw);
+  if (existing.some((e) => e.path === worktreePath || e.branch === branch)) {
+    return { worktreePath, branch, mergeTaskId: "", alreadyExists: true };
+  }
+  execFileSync("git", ["worktree", "add", worktreePath, "-b", branch], { encoding: "utf-8" });
+  execFileSync("pnpm", ["install", "--frozen-lockfile"], { cwd: worktreePath, encoding: "utf-8" });
+  const srcJsonl = path.join(repoRoot, ".claude", "lessons", "index.jsonl");
+  const dstDir = path.join(worktreePath, ".claude", "lessons");
+  const dstJsonl = path.join(dstDir, "index.jsonl");
+  if (existsSync(srcJsonl)) {
+    mkdirSync(dstDir, { recursive: true });
+    copyFileSync(srcJsonl, dstJsonl);
+  }
+  execFileSync("pnpm", ["exec", "ca", "setup", "--skip-model"], { cwd: worktreePath, encoding: "utf-8" });
+  const mergeTitle = `Merge: merge ${branch} to main`;
+  const mergeDesc = `INSTRUCTIONS: This task merges the worktree branch back to main. Worktree path: ${worktreePath}. Run \`pnpm exec ca worktree merge ${epicId}\` when all other blocking tasks are resolved.`;
+  const bdOutput = execFileSync("bd", [
+    "create",
+    `--title=${mergeTitle}`,
+    "--type=task",
+    "--priority=1",
+    `--description=${mergeDesc}`
+  ], { encoding: "utf-8" });
+  const idMatch = bdOutput.match(/(\S+)$/);
+  const mergeFullId = idMatch?.[1] ?? "";
+  if (!mergeFullId) {
+    throw new Error("bd create returned no task ID");
+  }
+  const mergeTaskId = shortId(mergeFullId);
+  execFileSync("bd", ["dep", "add", epicId, mergeTaskId], { encoding: "utf-8" });
+  return { worktreePath, branch, mergeTaskId, alreadyExists: false };
+}
+function runWorktreeWireDeps(epicId) {
+  validateEpicId(epicId);
+  const raw = execFileSync("bd", ["show", epicId, "--json"], { encoding: "utf-8" });
+  const deps = parseBdShowDeps(raw);
+  const mergeDep = deps.find((d) => d.title.startsWith("Merge:"));
+  if (!mergeDep) {
+    return { noMergeTask: true, wired: [], warnings: [] };
+  }
+  const mergeId = shortId(mergeDep.id);
+  const wired = [];
+  const warnings = [];
+  const reviewDep = deps.find((d) => d.title.startsWith("Review:"));
+  const compoundDep = deps.find((d) => d.title.startsWith("Compound:"));
+  if (reviewDep) {
+    const reviewId = shortId(reviewDep.id);
+    execFileSync("bd", ["dep", "add", mergeId, reviewId], { encoding: "utf-8" });
+    wired.push(reviewId);
+  } else {
+    warnings.push("No Review task found \u2014 it may not exist yet");
+  }
+  if (compoundDep) {
+    const compoundId = shortId(compoundDep.id);
+    execFileSync("bd", ["dep", "add", mergeId, compoundId], { encoding: "utf-8" });
+    wired.push(compoundId);
+  } else {
+    warnings.push("No Compound task found \u2014 it may not exist yet");
+  }
+  return { noMergeTask: false, wired, warnings };
+}
+function runWorktreeMerge(epicId) {
+  validateEpicId(epicId);
+  const branch = `epic/${epicId}`;
+  const gitCommonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], { encoding: "utf-8" }).trim();
+  const mainRepo = path.resolve(gitCommonDir, "..");
+  const currentBranch = execFileSync(
+    "git",
+    ["-C", mainRepo, "rev-parse", "--abbrev-ref", "HEAD"],
+    { encoding: "utf-8" }
+  ).trim();
+  if (currentBranch !== "main") {
+    throw new Error(`Main repo is on branch "${currentBranch}", expected "main". Checkout main before merging.`);
+  }
+  const listRaw = execFileSync("git", ["worktree", "list", "--porcelain"], { encoding: "utf-8" });
+  const entries = parseWorktreeList(listRaw);
+  const wtEntry = entries.find((e) => e.branch === branch);
+  if (!wtEntry) {
+    throw new Error(`Worktree not found for branch "${branch}". Run \`ca worktree list\` to see active worktrees.`);
+  }
+  const worktreePath = wtEntry.path;
+  try {
+    execFileSync("git", ["merge", "main"], { cwd: worktreePath, encoding: "utf-8" });
+  } catch (err) {
+    throw new Error(
+      `Merge conflict in worktree at ${worktreePath}. Resolve conflicts there and run \`ca worktree merge ${epicId}\` again. Detail: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  try {
+    execFileSync("pnpm", ["test"], { cwd: worktreePath, encoding: "utf-8" });
+  } catch (err) {
+    throw new Error(
+      `Tests failed in worktree at ${worktreePath}. Fix failures before merging. Detail: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  execFileSync("git", ["-C", mainRepo, "merge", branch, "--no-edit"], { encoding: "utf-8" });
+  const mainJsonlPath = path.join(mainRepo, ".claude", "lessons", "index.jsonl");
+  const wtJsonlPath = path.join(worktreePath, ".claude", "lessons", "index.jsonl");
+  let newLessons = 0;
+  if (existsSync(wtJsonlPath)) {
+    const mainContent = existsSync(mainJsonlPath) ? readFileSync(mainJsonlPath, "utf-8") : "";
+    const mainLineSet = new Set(mainContent.split("\n").filter(Boolean));
+    const wtLines = readFileSync(wtJsonlPath, "utf-8").split("\n").filter(Boolean);
+    const newLines = wtLines.filter((line) => !mainLineSet.has(line));
+    if (newLines.length > 0) {
+      const base = mainContent.trimEnd();
+      const appended = base ? `${base}
+${newLines.join("\n")}
+` : `${newLines.join("\n")}
+`;
+      writeFileSync(mainJsonlPath, appended, "utf-8");
+      newLessons = newLines.length;
+    }
+  }
+  execFileSync("git", ["worktree", "remove", worktreePath], { encoding: "utf-8" });
+  execFileSync("git", ["branch", "-d", branch], { encoding: "utf-8" });
+  return { mainRepo, newLessons };
+}
+function runWorktreeList() {
+  const listRaw = execFileSync("git", ["worktree", "list", "--porcelain"], { encoding: "utf-8" });
+  const entries = parseWorktreeList(listRaw);
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.path.includes("-wt-")) continue;
+    const epicIdMatch = entry.path.match(/-wt-(.+)$/);
+    if (!epicIdMatch?.[1]) continue;
+    const epicId = epicIdMatch[1];
+    let status = "unknown";
+    try {
+      const raw = execFileSync("bd", ["show", epicId, "--json"], { encoding: "utf-8" });
+      const data = JSON.parse(raw);
+      const issue = Array.isArray(data) ? data[0] : data;
+      status = issue?.status ?? "unknown";
+    } catch {
+    }
+    results.push({ epicId, path: entry.path, branch: entry.branch, status });
+  }
+  return results;
+}
+function runWorktreeCleanup(epicId, options = {}) {
+  validateEpicId(epicId);
+  const listRaw = execFileSync("git", ["worktree", "list", "--porcelain"], { encoding: "utf-8" });
+  const entries = parseWorktreeList(listRaw);
+  const branch = `epic/${epicId}`;
+  const wtEntry = entries.find((e) => e.branch === branch || e.path.endsWith(`-wt-${epicId}`));
+  if (!wtEntry) {
+    throw new Error(`Worktree not found for epic "${epicId}"`);
+  }
+  if (!options.force) {
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: wtEntry.path,
+      encoding: "utf-8"
+    });
+    if (status.trim()) {
+      throw new Error(`Worktree has uncommitted changes. Use --force to override.`);
+    }
+  }
+  const removeArgs = options.force ? ["worktree", "remove", wtEntry.path, "--force"] : ["worktree", "remove", wtEntry.path];
+  execFileSync("git", removeArgs, { encoding: "utf-8" });
+  const branchFlag = options.force ? "-D" : "-d";
+  execFileSync("git", ["branch", branchFlag, branch], { encoding: "utf-8" });
+  let mergeTaskClosed = false;
+  try {
+    const raw = execFileSync("bd", ["show", epicId, "--json"], { encoding: "utf-8" });
+    const deps = parseBdShowDeps(raw);
+    const mergeDep = deps.find((d) => d.title.startsWith("Merge:"));
+    if (mergeDep) {
+      const mergeId = shortId(mergeDep.id);
+      execFileSync("bd", ["close", mergeId], { encoding: "utf-8" });
+      mergeTaskClosed = true;
+    }
+  } catch {
+  }
+  return { removed: true, mergeTaskClosed };
+}
+function handleError(err) {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exitCode = 1;
+}
+function addCreateCommand(wt) {
+  wt.command("create <epic-id>").description("Create a new worktree for an epic").action((epicId) => {
+    try {
+      const result = runWorktreeCreate(epicId);
+      if (result.alreadyExists) {
+        console.log(`Worktree already exists at ${result.worktreePath}`);
+        return;
+      }
+      console.log(`Worktree created:`);
+      console.log(`  Path:       ${result.worktreePath}`);
+      console.log(`  Branch:     ${result.branch}`);
+      console.log(`  Merge task: ${result.mergeTaskId}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function addWireDepsCommand(wt) {
+  wt.command("wire-deps <epic-id>").description("Wire Review/Compound tasks as merge dependencies").action((epicId) => {
+    try {
+      const result = runWorktreeWireDeps(epicId);
+      if (result.noMergeTask) {
+        console.log("No worktree detected, working on main branch");
+        return;
+      }
+      if (result.wired.length > 0) {
+        console.log(`Wired dependencies: ${result.wired.join(", ")}`);
+      }
+      for (const w of result.warnings) {
+        console.log(`Warning: ${w}`);
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function addMergeCommand(wt) {
+  wt.command("merge <epic-id>").description("Merge worktree branch back to main").action((epicId) => {
+    try {
+      const result = runWorktreeMerge(epicId);
+      console.log(`Merged epic/${epicId} to main`);
+      console.log(`  New lessons: ${result.newLessons}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function addListCommand(wt) {
+  wt.command("list").description("List active worktrees").action(() => {
+    try {
+      const entries = runWorktreeList();
+      if (entries.length === 0) {
+        console.log("No active worktrees.");
+        return;
+      }
+      console.log("Epic ID     | Path                          | Branch          | Status");
+      console.log("------------|-------------------------------|-----------------|-------");
+      for (const e of entries) {
+        console.log(`${e.epicId.padEnd(12)}| ${e.path.padEnd(30)}| ${e.branch.padEnd(16)}| ${e.status}`);
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function addCleanupCommand(wt) {
+  wt.command("cleanup <epic-id>").description("Remove a worktree and clean up associated resources").option("--force", "Force removal even with uncommitted changes").action((epicId, opts) => {
+    try {
+      const result = runWorktreeCleanup(epicId, { force: opts.force });
+      console.log(`Worktree removed for epic/${epicId}`);
+      if (result.mergeTaskClosed) {
+        console.log("Merge task closed.");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function registerWorktreeCommands(program2) {
+  const wt = program2.command("worktree").description("Manage git worktrees for parallel epic execution");
+  addCreateCommand(wt);
+  addWireDepsCommand(wt);
+  addMergeCommand(wt);
+  addListCommand(wt);
+  addCleanupCommand(wt);
+}
 
 // src/commands/capture.ts
 function createLessonFromFlags(trigger, insight, confirmed) {
@@ -5919,19 +6303,22 @@ async function handleLearn(cmd, insight, options) {
   const typeResult = MemoryItemTypeSchema.safeParse(options.type);
   if (!typeResult.success) {
     console.error(formatError("learn", "INVALID_TYPE", `Invalid type: "${options.type}"`, "Use --type lesson|solution|pattern|preference"));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const itemType = typeResult.data;
   if (itemType === "pattern" && (!options.patternBad || !options.patternGood)) {
     console.error(formatError("learn", "MISSING_PATTERN", "type=pattern requires --pattern-bad and --pattern-good", 'Use: learn "insight" --type pattern --pattern-bad "old" --pattern-good "new"'));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   let severity;
   if (options.severity !== void 0) {
     const result = SeveritySchema.safeParse(options.severity);
     if (!result.success) {
       console.error(formatError("learn", "INVALID_SEVERITY", `Invalid severity: "${options.severity}"`, "Use --severity high|medium|low"));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     severity = result.data;
   }
@@ -5986,7 +6373,8 @@ async function handleDetect(options) {
     } else {
       console.error(formatError("detect", "MISSING_FLAG", "--save requires --yes", "Use: detect --input <file> --save --yes"));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   let input;
   try {
@@ -5998,7 +6386,8 @@ async function handleDetect(options) {
     } else {
       console.error(formatError("detect", "INVALID_INPUT", message, "Check the file is valid JSON matching the expected schema"));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const result = await detectAndPropose(repoRoot, input);
   if (!result) {
@@ -6051,7 +6440,8 @@ async function handleCapture(cmd, options) {
       } else {
         console.error(formatError("capture", "INVALID_INPUT", message, "Check the file is valid JSON matching the expected schema"));
       }
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     const result = await detectAndPropose(repoRoot, input);
     if (!result) {
@@ -6072,7 +6462,8 @@ async function handleCapture(cmd, options) {
     } else {
       console.error(formatError("capture", "MISSING_OPTIONS", msg, "Provide --trigger and --insight, or --input"));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   if (!options.yes && !process.stdin.isTTY) {
     if (options.json) {
@@ -6080,7 +6471,8 @@ async function handleCapture(cmd, options) {
     } else {
       console.error(formatError("capture", "NON_INTERACTIVE", "--yes required in non-interactive mode", 'Use: capture --trigger "..." --insight "..." --yes'));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   if (options.json) {
     if (options.yes) await appendLesson(repoRoot, lesson);
@@ -6367,13 +6759,13 @@ function registerLoopCommands(program2) {
     await handleLoop(this, options);
   });
 }
-function parseLimitOrExit(rawLimit, optionName, commandName) {
+function parseLimitOrNull(rawLimit, optionName, commandName) {
   try {
     return parseLimit(rawLimit, optionName);
   } catch (err) {
     const message = err instanceof Error ? err.message : `Invalid ${optionName}`;
     console.error(formatError(commandName, "INVALID_LIMIT", message, `Use --${optionName} with a positive integer`));
-    process.exit(1);
+    return null;
   }
 }
 async function readPlanFromStdin() {
@@ -6434,7 +6826,11 @@ function outputSessionLessonsHuman(lessons, quiet) {
 }
 async function searchAction(cmd, query, options) {
   const repoRoot = getRepoRoot();
-  const limit = parseLimitOrExit(options.limit, "limit", "search");
+  const limit = parseLimitOrNull(options.limit, "limit", "search");
+  if (limit === null) {
+    process.exitCode = 1;
+    return;
+  }
   const { verbose, quiet } = getGlobalOpts(cmd);
   await syncIfNeeded(repoRoot);
   let results;
@@ -6443,7 +6839,8 @@ async function searchAction(cmd, query, options) {
   } catch (err) {
     const message = err instanceof Error ? err.message : "Search failed";
     console.error(formatError("search", "SEARCH_FAILED", message, "Check your query syntax"));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   if (results.length > 0) {
     incrementRetrievalCount(repoRoot, results.map((lesson) => lesson.id));
@@ -6471,7 +6868,11 @@ async function searchAction(cmd, query, options) {
 }
 async function listAction(cmd, options) {
   const repoRoot = getRepoRoot();
-  const limit = parseLimitOrExit(options.limit, "limit", "list");
+  const limit = parseLimitOrNull(options.limit, "limit", "list");
+  if (limit === null) {
+    process.exitCode = 1;
+    return;
+  }
   const { verbose, quiet } = getGlobalOpts(cmd);
   const { items, skippedCount } = await readMemoryItems(repoRoot);
   const filteredItems = options.invalidated ? items.filter((i) => i.invalidatedAt) : items;
@@ -6546,12 +6947,17 @@ async function loadSessionAction(cmd, options) {
 }
 async function checkPlanAction(cmd, options) {
   const repoRoot = getRepoRoot();
-  const limit = parseLimitOrExit(options.limit, "limit", "check-plan");
+  const limit = parseLimitOrNull(options.limit, "limit", "check-plan");
+  if (limit === null) {
+    process.exitCode = 1;
+    return;
+  }
   const { quiet } = getGlobalOpts(cmd);
   const planText = options.plan ?? await readPlanFromStdin();
   if (!planText) {
     console.error(formatError("check-plan", "NO_PLAN", "No plan provided", "Use --plan <text> or pipe text to stdin"));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const usability = await isModelUsable();
   if (!usability.usable) {
@@ -6565,7 +6971,8 @@ async function checkPlanAction(cmd, options) {
     } else {
       console.error(formatError("check-plan", "MODEL_UNAVAILABLE", usability.reason, usability.action));
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   try {
     const result = await retrieveForPlan(repoRoot, planText, limit);
@@ -6589,7 +6996,7 @@ async function checkPlanAction(cmd, options) {
     } else {
       console.error(formatError("check-plan", "PLAN_CHECK_FAILED", message, "Check model installation and try again"));
     }
-    process.exit(1);
+    process.exitCode = 1;
   }
 }
 function registerRetrievalCommands(program2) {
@@ -6628,6 +7035,7 @@ function registerManagementCommands(program2) {
   registerRulesCommands(program2);
   registerTestSummaryCommand(program2);
   registerVerifyGatesCommand(program2);
+  registerWorktreeCommands(program2);
 }
 
 // src/cli.ts