compound-agent 1.3.0 → 1.3.1

package/dist/cli.js

@@ -1489,6 +1489,30 @@ function checkBeadsAvailable() {
     };
   }
 }
+function checkBeadsInitialized(repoRoot) {
+  return existsSync(join(repoRoot, ".beads"));
+}
+function checkBeadsHealthy(repoRoot) {
+  try {
+    execSync("bd doctor", { cwd: repoRoot, shell: "/bin/sh", stdio: "pipe", encoding: "utf-8" });
+    return { healthy: true };
+  } catch (e) {
+    const msg = e instanceof Error && "stderr" in e ? String(e.stderr).trim() : "bd doctor failed";
+    return { healthy: false, message: msg };
+  }
+}
+function runFullBeadsCheck(repoRoot) {
+  const cli = checkBeadsAvailable();
+  if (!cli.available) {
+    return { cliAvailable: false, initialized: false, healthy: false, healthMessage: cli.message };
+  }
+  const initialized = checkBeadsInitialized(repoRoot);
+  if (!initialized) {
+    return { cliAvailable: true, initialized: false, healthy: false };
+  }
+  const health = checkBeadsHealthy(repoRoot);
+  return { cliAvailable: true, initialized: true, healthy: health.healthy, healthMessage: health.message };
+}
 
 // src/memory/capture/quality.ts
 var DEFAULT_SIMILARITY_THRESHOLD = 0.8;
@@ -2562,6 +2586,22 @@ function printPnpmConfigStatus(result) {
     console.log(`  pnpm config: Added onlyBuiltDependencies [${result.added.join(", ")}]`);
   }
 }
+function printBeadsFullStatus(check) {
+  console.log(`  Beads CLI:          ${check.cliAvailable ? "OK" : "not found"}`);
+  if (check.cliAvailable) {
+    console.log(`  Beads repo:         ${check.initialized ? "OK" : "not initialized (run: bd init)"}`);
+    if (check.initialized) {
+      console.log(`  Beads health:       ${check.healthy ? "OK" : `issues found${check.healthMessage ? ` \u2014 ${check.healthMessage}` : ""}`}`);
+    }
+  }
+}
+function printScopeStatus(scope) {
+  if (scope.isUserScope) {
+    console.log("  Scope:              user-scope (reduced compounding value)");
+  } else {
+    console.log("  Scope:              OK (repository scope)");
+  }
+}
 async function runStatus(repoRoot) {
   const agentsDir = join(repoRoot, ".claude", "agents", "compound");
   const commandsDir = join(repoRoot, ".claude", "commands", "compound");
@@ -2580,12 +2620,10 @@ async function runStatus(repoRoot) {
   } catch {
   }
   console.log(`  Hooks:              ${hooksInstalled ? "installed" : "not installed"}`);
-  const beads = checkBeadsAvailable();
-  console.log(`  Beads CLI:          ${beads.available ? "available" : "not found"}`);
+  const fullBeads = runFullBeadsCheck(repoRoot);
+  printBeadsFullStatus(fullBeads);
   const scope = checkUserScope(repoRoot);
-  if (scope.isUserScope) {
-    console.log("  Scope:              user-scope (reduced compounding value)");
-  }
+  printScopeStatus(scope);
 }
 var REQUIRED_PATTERNS = ["node_modules/", ".claude/.cache/"];
 var SECTION_COMMENT = "# compound-agent";
@@ -4160,21 +4198,21 @@ npx ca prime
 
 // src/setup/templates/docs.ts
 var DOC_TEMPLATES = {
-  "HOW_TO_COMPOUND.md": `---
+  "README.md": `---
 version: "{{VERSION}}"
 last-updated: "{{DATE}}"
-summary: "Usage guide for compound-agent CLI, skills, and workflows"
+summary: "Overview and getting started guide for compound-agent"
 ---
 
-# How to Compound
+# Compound Agent
 
-A usage guide for humans and AI agents working with compound-agent -- the learning system that helps Claude Code avoid repeating mistakes across sessions.
+A learning system for Claude Code that captures, indexes, and retrieves lessons learned during development sessions -- so the same mistakes are not repeated.
 
 ---
 
-## 1. What is compound-agent
+## What is compound-agent?
 
-Compound-agent is a TypeScript CLI plugin for Claude Code that captures, indexes, and retrieves lessons learned during development sessions. When Claude makes a mistake and gets corrected, or discovers a useful pattern, that knowledge is stored as a **memory item** in \`.claude/lessons/index.jsonl\`. Future sessions search this memory before planning and implementing, so the same mistakes are not repeated.
+Compound-agent is a TypeScript CLI plugin for Claude Code. When Claude makes a mistake and gets corrected, or discovers a useful pattern, that knowledge is stored as a **memory item** in \`.claude/lessons/index.jsonl\`. Future sessions search this memory before planning and implementing.
 
 The system uses:
 
@@ -4183,17 +4221,21 @@ The system uses:
 - **Semantic embeddings** (EmbeddingGemma-300M via node-llama-cpp) for vector similarity search
 - **Claude Code hooks** to inject memory at session start, before compaction, and on tool failures
 
-Memory items have four types: \`lesson\`, \`solution\`, \`pattern\`, and \`preference\`. Each has a trigger (what happened), an insight (what to do differently), tags, severity, and optional citations linking back to source code.
+Memory items have four types: \`lesson\`, \`solution\`, \`pattern\`, and \`preference\`. Each has a trigger, an insight, tags, severity, and optional citations.
 
 ---
 
-## 2. Installation
-
-### Quick start
+## Quick start
 
 \`\`\`bash
-# In your project root:
+# Initialize in your project:
 npx ca init
+
+# Full setup (includes embedding model download):
+npx ca setup
+
+# Verify installation:
+npx ca doctor
 \`\`\`
 
 ### What \`init\` does
@@ -4202,31 +4244,16 @@ npx ca init
 2. Updates \`AGENTS.md\` with a compound-agent section
 3. Adds a reference to \`.claude/CLAUDE.md\`
 4. Creates \`.claude/plugin.json\` manifest
-5. Installs agent templates to \`.claude/agents/compound/\`
-6. Installs workflow slash commands to \`.claude/commands/compound/\`
-7. Installs phase skills to \`.claude/skills/compound/\`
-8. Installs agent role skills to \`.claude/skills/compound/agents/\`
-9. Installs a git pre-commit hook (lesson capture reminder)
-10. Installs Claude Code hooks (SessionStart, PreCompact, UserPromptSubmit, PostToolUseFailure, PostToolUse)
-11. For pnpm projects: auto-configures \`onlyBuiltDependencies\` for native addons
+5. Installs agent templates, workflow commands, phase skills, and agent role skills
+6. Installs a git pre-commit hook (lesson capture reminder)
+7. Installs Claude Code hooks (SessionStart, PreCompact, UserPromptSubmit, PostToolUseFailure, PostToolUse)
+8. For pnpm projects: auto-configures \`onlyBuiltDependencies\` for native addons
 
-### Full setup (with embedding model)
+\`setup\` does everything \`init\` does, plus downloads the EmbeddingGemma-300M model (~278MB). Use \`--skip-model\` to skip the download.
 
-\`\`\`bash
-npx ca setup
-\`\`\`
-
-\`setup\` does everything \`init\` does, plus downloads the EmbeddingGemma-300M model (~278MB) for semantic search. Use \`--skip-model\` to skip the download.
-
-### Verify installation
-
-\`\`\`bash
-npx ca doctor
-\`\`\`
-
-This checks for \`.claude/\` directory, lessons index, embedding model, Claude hooks, and beads (\`bd\`) availability.
+---
 
-### Directory structure after install
+## Directory structure
 
 \`\`\`
 .claude/
@@ -4245,29 +4272,57 @@ This checks for \`.claude/\` directory, lessons index, embedding model, Claude h
 
 ---
 
-## 3. The 5-phase workflow
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| Capture a lesson | \`npx ca learn "insight" --trigger "what happened"\` |
+| Search memory | \`npx ca search "keywords"\` |
+| Check plan against memory | \`npx ca check-plan --plan "description"\` |
+| View stats | \`npx ca stats\` |
+| Run full workflow | \`/compound:lfg <epic-id>\` |
+| Health check | \`npx ca doctor\` |
+
+---
+
+## Further reading
+
+- [WORKFLOW.md](WORKFLOW.md) -- The 5-phase development workflow and LFG orchestrator
+- [CLI_REFERENCE.md](CLI_REFERENCE.md) -- Complete CLI command reference
+- [SKILLS.md](SKILLS.md) -- Phase skills and agent role skills
+- [INTEGRATION.md](INTEGRATION.md) -- Memory system, hooks, beads, and agent guidance
+`,
+  "WORKFLOW.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "The 5-phase compound-agent workflow and LFG orchestrator"
+---
+
+# Workflow
 
-Every feature or epic follows five phases:
+Every feature or epic follows five phases. The \`/compound:lfg\` skill chains them with enforcement gates.
 
-### Phase 1: Brainstorm
+---
+
+## Phase 1: Brainstorm
 
-Explore the problem space before committing to a solution. Produce a structured brainstorm document with decisions, open questions, and a beads epic.
+Explore the problem space before committing to a solution.
 
 - Ask "why" before "how"
 - Search memory for similar past features
 - Generate multiple approaches, then converge
 - Create a beads epic: \`bd create --title="..." --type=epic\`
 
-### Phase 2: Plan
+## Phase 2: Plan
 
-Decompose work into small, testable tasks with dependencies and acceptance criteria.
+Decompose work into small, testable tasks with dependencies.
 
 - Review brainstorm output
 - Create beads tasks: \`bd create --title="..." --type=task\`
 - Create Review and Compound blocking tasks (these survive compaction)
 - Run \`npx ca worktree wire-deps <epic-id>\` if using worktrees
 
-### Phase 3: Work
+## Phase 3: Work
 
 Execute implementation through agent teams using TDD.
 
@@ -4276,7 +4331,7 @@ Execute implementation through agent teams using TDD.
 - Commit incrementally as tests pass
 - Run \`/implementation-reviewer\` before closing tasks
 
-### Phase 4: Review
+## Phase 4: Review
 
 Multi-agent code review with severity classification.
 
@@ -4285,7 +4340,7 @@ Multi-agent code review with severity classification.
 - Classify findings as P1/P2/P3
 - Fix all P1 findings before proceeding
 
-### Phase 5: Compound
+## Phase 5: Compound
 
 Extract and store lessons learned. This is what makes the system compound.
 
@@ -4296,14 +4351,85 @@ Extract and store lessons learned. This is what makes the system compound.
 
 ---
 
-## 4. CLI reference
+## LFG orchestrator
+
+\`/compound:lfg\` chains all 5 phases with enforcement gates.
+
+### Invocation
+
+\`\`\`
+/compound:lfg <epic-id>
+/compound:lfg <epic-id> from plan
+\`\`\`
+
+### Phase execution protocol
+
+For each phase, LFG:
+
+1. Announces progress: \`[Phase N/5] PHASE_NAME\`
+2. Initializes state: \`npx ca phase-check start <phase>\`
+3. Reads the phase skill file (non-negotiable -- never from memory)
+4. Runs \`npx ca search\` with the current goal
+5. Executes the phase following skill instructions
+6. Updates epic notes: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
+7. Verifies the phase gate before proceeding
+
+### Phase gates
+
+| Gate | When | Verification |
+|------|------|-------------|
+| Post-plan | After Plan | \`bd list --status=open\` shows Review + Compound tasks |
+| Gate 3 | After Work | \`bd list --status=in_progress\` returns empty |
+| Gate 4 | After Review | \`/implementation-reviewer\` returned APPROVED |
+| Final | After Compound | \`npx ca verify-gates <epic-id>\` passes, \`pnpm test\` and \`pnpm lint\` pass |
+
+If any gate fails, LFG stops. You must fix the issue before proceeding.
+
+### Resumption
+
+If interrupted, LFG can resume:
+
+1. Run \`bd show <epic-id>\` and read the notes for phase state
+2. Re-invoke with \`from <phase>\` to skip completed phases
+
+### Phase state tracking
+
+LFG persists state in \`.claude/.ca-phase-state.json\`. Useful commands:
+
+\`\`\`bash
+npx ca phase-check status      # See current phase state
+npx ca phase-check clean       # Reset phase state (escape hatch)
+\`\`\`
+
+### Session close
+
+Before saying "done", LFG runs this inviolable checklist:
+
+\`\`\`bash
+git status
+git add <files>
+bd sync
+git commit -m "..."
+bd sync
+git push
+\`\`\`
+`,
+  "CLI_REFERENCE.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Complete CLI command reference for compound-agent"
+---
+
+# CLI Reference
 
 All commands use \`npx ca\` (or \`npx compound-agent\`). Global flags: \`-v, --verbose\` and \`-q, --quiet\`.
 
-### Capture commands
+---
+
+## Capture commands
 
 \`\`\`bash
-# Capture a lesson (primary command for storing knowledge)
+# Capture a lesson (primary command)
 npx ca learn "Always validate epic IDs before shell execution" \\
   --trigger "Shell injection via bd show" \\
   --tags "security,validation" \\
@@ -4311,7 +4437,7 @@ npx ca learn "Always validate epic IDs before shell execution" \\
   --type lesson
 
 # Capture a pattern (requires --pattern-bad and --pattern-good)
-npx ca learn "Use execFileSync instead of execSync for external commands" \\
+npx ca learn "Use execFileSync instead of execSync" \\
   --type pattern \\
   --pattern-bad "execSync(\\\`bd show \\\${id}\\\`)" \\
   --pattern-good "execFileSync('bd', ['show', id])"
@@ -4327,68 +4453,44 @@ npx ca detect --input corrections.json --save --yes
 **Types**: \`lesson\` (default), \`solution\`, \`pattern\`, \`preference\`
 **Severity**: \`high\`, \`medium\`, \`low\`
 
-### Retrieval commands
+## Retrieval commands
 
 \`\`\`bash
-# Keyword search
-npx ca search "sqlite validation"
+npx ca search "sqlite validation"           # Keyword search
 npx ca search "security" --limit 5
-
-# List all memory items
-npx ca list
+npx ca list                                  # List all memory items
 npx ca list --limit 20
-npx ca list --invalidated      # Show only invalidated items
-
-# Semantic search against a plan
+npx ca list --invalidated                    # Show only invalidated items
 npx ca check-plan --plan "Implement git worktree integration"
-echo "Add caching layer" | npx ca check-plan
-
-# Load high-severity lessons for session context
-npx ca load-session
+echo "Add caching layer" | npx ca check-plan # Semantic search against a plan
+npx ca load-session                          # Load high-severity lessons
 npx ca load-session --json
 \`\`\`
 
-### Management commands
+## Management commands
 
 \`\`\`bash
-# View a specific item
-npx ca show <id>
+npx ca show <id>                             # View a specific item
 npx ca show <id> --json
-
-# Update item fields
-npx ca update <id> --insight "Updated insight text"
+npx ca update <id> --insight "Updated text"  # Update item fields
 npx ca update <id> --severity high --tags "security,input-validation"
-
-# Soft delete (creates tombstone)
-npx ca delete <id>
+npx ca delete <id>                           # Soft delete (creates tombstone)
 npx ca delete <id1> <id2> <id3>
-
-# Mark as invalid (excluded from retrieval but preserved)
-npx ca wrong <id> --reason "This advice was incorrect"
-
-# Re-enable an invalidated item
-npx ca validate <id>
-
-# Export as JSON
-npx ca export
+npx ca wrong <id> --reason "Incorrect"       # Mark as invalid
+npx ca validate <id>                         # Re-enable an invalidated item
+npx ca export                                # Export as JSON
 npx ca export --since 2026-01-01 --tags "security"
-
-# Import from JSONL file
-npx ca import lessons-backup.jsonl
-
-# Database maintenance
-npx ca compact                 # Remove tombstones and archive old items
-npx ca compact --dry-run       # Preview without changes
-npx ca compact --force         # Compact even if below threshold
-npx ca rebuild                 # Rebuild SQLite index from JSONL
-npx ca rebuild --force         # Force rebuild even if unchanged
-npx ca stats                   # Show database health and statistics
-
-# Context recovery
-npx ca prime                   # Reload workflow context after compaction
+npx ca import lessons-backup.jsonl           # Import from JSONL file
+npx ca compact                               # Remove tombstones and archive old items
+npx ca compact --dry-run
+npx ca compact --force
+npx ca rebuild                               # Rebuild SQLite index from JSONL
+npx ca rebuild --force
+npx ca stats                                 # Show database health and statistics
+npx ca prime                                 # Reload workflow context after compaction
 \`\`\`
 
-### Setup commands
+## Setup commands
 
 \`\`\`bash
 npx ca init                    # Initialize in current repo
@@ -4396,21 +4498,18 @@ npx ca init --skip-agents      # Skip AGENTS.md and template installation
 npx ca init --skip-hooks       # Skip git hook installation
 npx ca init --skip-claude      # Skip Claude Code hooks
 npx ca init --json             # Output result as JSON
-
 npx ca setup                   # Full setup (init + model download)
 npx ca setup --update          # Regenerate templates (preserves user files)
 npx ca setup --uninstall       # Remove compound-agent integration
 npx ca setup --status          # Show installation status
 npx ca setup --skip-model      # Skip embedding model download
-
 npx ca setup claude            # Install Claude Code hooks only
 npx ca setup claude --status   # Check hook status
-
 npx ca hooks                   # Install git hooks
 npx ca download-model          # Download embedding model (~278MB)
 \`\`\`
 
-### Reviewer commands
+## Reviewer commands
 
 \`\`\`bash
 npx ca reviewer enable gemini  # Enable Gemini as external reviewer
@@ -4419,11 +4518,10 @@ npx ca reviewer disable gemini # Disable a reviewer
 npx ca reviewer list           # List enabled reviewers
 \`\`\`
 
-### Loop command
+## Loop command
 
 \`\`\`bash
-# Generate an infinity loop script for autonomous epic processing
-npx ca loop
+npx ca loop                    # Generate infinity loop script for autonomous processing
 npx ca loop --epics epic-1 epic-2
 npx ca loop --output my-loop.sh
 npx ca loop --max-retries 5
@@ -4431,22 +4529,15 @@ npx ca loop --model claude-opus-4-6
 npx ca loop --force            # Overwrite existing script
 \`\`\`
 
-### Health and audit commands
+## Health, audit, and verification commands
 
 \`\`\`bash
+npx ca version-show             # Show version with animation and recent changelog
 npx ca doctor                  # Check external dependencies and project health
 npx ca audit                   # Run pattern, rule, and lesson quality checks
 npx ca rules check             # Check codebase against .claude/rules.json
 npx ca test-summary            # Run tests and output compact pass/fail summary
-\`\`\`
-
-### Verification commands
-
-\`\`\`bash
-# Verify workflow gates before epic closure
-npx ca verify-gates <epic-id>
-
-# Phase state management (used by LFG workflow)
+npx ca verify-gates <epic-id>  # Verify workflow gates before epic closure
 npx ca phase-check init <epic-id>
 npx ca phase-check status
 npx ca phase-check start <phase>
@@ -4454,39 +4545,37 @@ npx ca phase-check gate <gate-name>   # post-plan, gate-3, gate-4, final
 npx ca phase-check clean
 \`\`\`
 
-### Worktree commands
+## Worktree commands
 
 \`\`\`bash
-# Create an isolated worktree for an epic
-npx ca worktree create <epic-id>
-
-# Connect merge dependencies
-npx ca worktree wire-deps <epic-id>
-
-# Merge worktree back to main (two-phase: resolve in worktree, land on main)
-npx ca worktree merge <epic-id>
-
-# List active worktrees
-npx ca worktree list
-
-# Remove worktree and clean up
-npx ca worktree cleanup <epic-id>
-npx ca worktree cleanup <epic-id> --force   # Force cleanup of dirty worktrees
+npx ca worktree create <epic-id>              # Create isolated worktree
+npx ca worktree wire-deps <epic-id>           # Connect merge dependencies
+npx ca worktree merge <epic-id>               # Merge worktree back to main
+npx ca worktree list                          # List active worktrees
+npx ca worktree cleanup <epic-id>             # Remove worktree and clean up
+npx ca worktree cleanup <epic-id> --force     # Force cleanup of dirty worktrees
 \`\`\`
 
-### Compound command
+## Compound command
 
 \`\`\`bash
-# Synthesize cross-cutting patterns from accumulated lessons
-npx ca compound
+npx ca compound                # Synthesize cross-cutting patterns from accumulated lessons
 \`\`\`
-
+`,
+  "SKILLS.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Phase skills and agent role skills reference"
 ---
 
-## 5. Skills reference
+# Skills Reference
 
 Skills are instructions that Claude reads before executing each phase. They live in \`.claude/skills/compound/\` and are auto-installed by \`npx ca setup\`.
 
+---
+
+## Phase skills
+
 ### \`/compound:brainstorm\`
 
 **Purpose**: Divergent-then-convergent thinking to explore the solution space.
@@ -4533,7 +4622,7 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 **When invoked**: When you want to run an entire epic end-to-end.
 
-**What it does**: Sequences all 5 phases with mandatory gates between them, tracks progress in beads notes, handles resumption after interruption.
+**What it does**: Sequences all 5 phases with mandatory gates between them, tracks progress in beads notes, handles resumption after interruption. See [WORKFLOW.md](WORKFLOW.md) for full details.
 
 ### \`/compound:set-worktree\`
 
@@ -4545,150 +4634,42 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 ---
 
-## 6. The LFG workflow
-
-\`/compound:lfg\` chains all 5 phases with enforcement gates. Here is how it works:
-
-### Invocation
-
-\`\`\`
-/compound:lfg <epic-id>
-\`\`\`
-
-Or with a phase skip:
-
-\`\`\`
-/compound:lfg <epic-id> from plan
-\`\`\`
-
-### Phase execution protocol
-
-For each phase, LFG:
-
-1. Announces progress: \`[Phase N/5] PHASE_NAME\`
-2. Initializes state: \`npx ca phase-check start <phase>\`
-3. Reads the phase skill file (non-negotiable -- never from memory)
-4. Runs \`npx ca search\` with the current goal
-5. Executes the phase following skill instructions
-6. Updates epic notes: \`bd update <epic-id> --notes="Phase: NAME COMPLETE | Next: NEXT"\`
-7. Verifies the phase gate before proceeding
-
-### Phase gates
-
-| Gate | When | Verification |
-|------|------|-------------|
-| Post-plan | After Plan | \`bd list --status=open\` shows Review + Compound tasks |
-| Gate 3 | After Work | \`bd list --status=in_progress\` returns empty |
-| Gate 4 | After Review | \`/implementation-reviewer\` returned APPROVED |
-| Final | After Compound | \`npx ca verify-gates <epic-id>\` passes, \`pnpm test\` and \`pnpm lint\` pass |
-
-If any gate fails, LFG stops. You must fix the issue before proceeding.
-
-### Resumption
-
-If interrupted, LFG can resume:
-
-1. Run \`bd show <epic-id>\` and read the notes for phase state
-2. Re-invoke with \`from <phase>\` to skip completed phases
-
-### Phase state tracking
+## Skill invocation
 
-LFG persists state in \`.claude/.ca-phase-state.json\`. Useful commands:
+Skills are invoked as Claude Code slash commands:
 
-\`\`\`bash
-npx ca phase-check status      # See current phase state
-npx ca phase-check clean       # Reset phase state (escape hatch)
 \`\`\`
-
-### Session close
-
-Before saying "done", LFG runs this inviolable checklist:
-
-\`\`\`bash
-git status
-git add <files>
-bd sync
-git commit -m "..."
-bd sync
-git push
+/compound:brainstorm       # Start brainstorm phase
+/compound:plan             # Start plan phase
+/compound:work             # Start work phase
+/compound:review           # Start review phase
+/compound:compound         # Start compound phase
+/compound:lfg <epic-id>    # Run all phases end-to-end
+/compound:set-worktree <epic-id>  # Set up worktree before LFG
 \`\`\`
 
+Each skill reads its SKILL.md file from \`.claude/skills/compound/<phase>/SKILL.md\` at invocation time. Skills are never executed from memory.
+`,
+  "INTEGRATION.md": `---
+version: "{{VERSION}}"
+last-updated: "{{DATE}}"
+summary: "Memory system, hooks, beads integration, and agent guidance"
 ---
 
-## 7. Worktree integration
-
-Worktrees let you run epics in isolation, enabling parallel execution across multiple Claude Code sessions.
-
-### Creating a worktree
-
-\`\`\`bash
-npx ca worktree create <epic-id>
-\`\`\`
-
-This:
-
-1. Creates a git worktree at \`../<repo>-wt-<epic-id>\` on branch \`epic/<epic-id>\`
-2. Installs dependencies via \`pnpm install --frozen-lockfile\`
-3. Copies \`.claude/lessons/index.jsonl\` to the worktree
-4. Runs \`npx ca setup --skip-model\` in the worktree
-5. Creates a Merge beads task linked to the epic
-
-### Using with LFG
-
-\`\`\`bash
-# From main repo:
-npx ca worktree create my-epic-id
-
-# Then in the worktree directory:
-# Run /compound:lfg or /compound:set-worktree followed by /compound:lfg
-\`\`\`
-
-Or use the skill:
-
-\`\`\`
-/compound:set-worktree <epic-id>
-\`\`\`
-
-### Merging back
-
-When all work tasks complete, the Merge task surfaces via \`bd ready\`:
-
-\`\`\`bash
-npx ca worktree merge <epic-id>
-\`\`\`
-
-This runs a two-phase merge:
+# Integration
 
-1. Merges \`main\` into the worktree branch (resolve conflicts there)
-2. Fast-forwards \`main\` to the worktree branch (clean landing)
-
-### Cleanup
-
-\`\`\`bash
-npx ca worktree cleanup <epic-id>
-npx ca worktree cleanup <epic-id> --force   # For dirty worktrees
-\`\`\`
-
-This removes the worktree directory, deletes the branch, and closes the Merge task.
-
-### Listing worktrees
-
-\`\`\`bash
-npx ca worktree list
-\`\`\`
-
-Shows active worktrees with their epic and merge task status.
+Deep integration topics for compound-agent: memory system internals, Claude Code hooks, beads workflow, worktree integration, and agent guidance.
 
 ---
 
-## 8. Memory system
+## Memory system
 
 ### Storage format
 
 Memory items are stored as newline-delimited JSON in \`.claude/lessons/index.jsonl\`. Each line is a complete JSON object:
 
 \`\`\`json
-{"id":"L-abc123","type":"lesson","trigger":"Shell injection via execSync","insight":"Use execFileSync with array args to prevent shell interpretation","tags":["security"],"source":"manual","context":{"tool":"cli","intent":"manual learning"},"created":"2026-02-15T10:00:00Z","confirmed":true,"severity":"high","supersedes":[],"related":[]}
+{"id":"L-abc123","type":"lesson","trigger":"Shell injection via execSync","insight":"Use execFileSync with array args","tags":["security"],"source":"manual","context":{"tool":"cli","intent":"manual learning"},"created":"2026-02-15T10:00:00Z","confirmed":true,"severity":"high","supersedes":[],"related":[]}
 \`\`\`
 
 ### Indexing
@@ -4709,14 +4690,6 @@ The index is rebuilt automatically when the JSONL changes. Force rebuild with \`
 
 **Session loading** (\`npx ca load-session\`): Returns high-severity confirmed lessons for injection at session start.
 
-### Compounding (pattern synthesis)
-
-\`\`\`bash
-npx ca compound
-\`\`\`
-
-This reads all memory items, computes embeddings, clusters them by similarity, and synthesizes cross-cutting patterns into \`.claude/lessons/cct-patterns.jsonl\`. Clusters with 2+ items become patterns; single-item clusters are filtered as noise.
-
 ### Data lifecycle
 
 | Operation | Effect |
@@ -4729,21 +4702,7 @@ This reads all memory items, computes embeddings, clusters them by similarity, a
 
 ---
 
-## 9. For AI agents
-
-### Integrating into CLAUDE.md
-
-Add a reference to compound-agent in your project's \`.claude/CLAUDE.md\`:
-
-\`\`\`markdown
-## References
-
-- docs/compound/HOW_TO_COMPOUND.md -- Usage guide for humans and AI agents
-\`\`\`
-
-The \`npx ca init\` command does this automatically.
-
-### Claude Code hooks
+## Claude Code hooks
 
 Compound-agent installs five hooks into \`.claude/settings.json\`:
 
@@ -4751,7 +4710,7 @@ Compound-agent installs five hooks into \`.claude/settings.json\`:
 |------|---------|--------|
 | **SessionStart** | New session or resume | Runs \`npx ca prime\` to load workflow context and high-severity lessons |
 | **PreCompact** | Before context compaction | Runs \`npx ca prime\` to preserve context across compaction |
-| **UserPromptSubmit** | Every user message | Detects correction language ("actually", "wrong") and planning language ("implement", "build"), injects memory reminders |
+| **UserPromptSubmit** | Every user message | Detects correction/planning language, injects memory reminders |
 | **PostToolUseFailure** | Bash/Edit/Write failures | After 2 failures on same file or 3 total, suggests \`npx ca search\` |
 | **PostToolUse** | After successful tool use | Resets failure tracking; tracks skill file reads for phase guard |
 
@@ -4778,7 +4737,9 @@ npx ca learn "The insight" --trigger "What happened" --severity medium
 npx ca compound
 \`\`\`
 
-### Beads workflow integration
+---
+
+## Beads integration
 
 Compound-agent works with beads (\`bd\`) for issue tracking:
 
@@ -4801,11 +4762,38 @@ Before closing an epic, verify all gates pass:
 npx ca verify-gates <epic-id>
 \`\`\`
 
-This checks that:
+This checks that a Review task, Compound task, and (if applicable) Merge task all exist and are closed.
+
+---
+
+## Worktree integration
+
+Worktrees let you run epics in isolation, enabling parallel execution across multiple Claude Code sessions.
+
+\`\`\`bash
+npx ca worktree create <epic-id>   # Creates worktree + installs deps + copies lessons
+npx ca worktree merge <epic-id>    # Two-phase merge back to main
+npx ca worktree cleanup <epic-id>  # Remove worktree, delete branch, close Merge task
+npx ca worktree list               # Show active worktrees
+\`\`\`
+
+See [CLI_REFERENCE.md](CLI_REFERENCE.md) for full worktree command details.
 
-1. A Review task exists and is closed
-2. A Compound task exists and is closed
-3. If a Merge task exists (worktree epic), it is also closed
+---
+
+## For AI agents
+
+### Integrating into CLAUDE.md
+
+Add a reference to compound-agent in your project's \`.claude/CLAUDE.md\`:
+
+\`\`\`markdown
+## References
+
+- docs/compound/README.md -- Compound-agent overview and getting started
+\`\`\`
+
+The \`npx ca init\` command does this automatically.
 
 ### Session completion checklist
 
@@ -5386,12 +5374,18 @@ Synthesize analysis results into a refined optimization plan:
 - Estimate impact on test suite speed and coverage
 - Iterate with subagents until the plan is comprehensive
 
-### Phase 3: Adversarial Review
+### Phase 3: Adversarial Review (CRITICAL QUALITY GATE)
+**This is THE KEY PHASE -- the most important phase in the entire workflow. NEVER skip, NEVER rush, NEVER settle for "good enough."**
+
 Expose the plan to two neutral reviewer subagents:
 - **Reviewer A** (Opus): Independent critique of the optimization plan
 - **Reviewer B** (Sonnet): Independent critique from a different perspective
+
 Both reviewers challenge assumptions, identify risks, and suggest improvements.
-Iterate: adapt the plan based on feedback until confident.
+
+**Mandatory iteration loop**: After each reviewer pass, if ANY issues, concerns, or suggestions remain from EITHER reviewer, revise the plan and re-submit to BOTH reviewers. Repeat until BOTH reviewers explicitly approve with ZERO reservations. Do not proceed to Phase 4 until unanimous, unconditional approval is reached.
+
+This is the critical quality gate. Loop as many times as needed. The test suite must be bulletproof before execution begins.
 
 ### Phase 4: Execution
 Apply the agreed changes:
@@ -5417,13 +5411,13 @@ Apply the agreed changes:
 ## Common Pitfalls
 - Deleting tests without verifying coverage is maintained elsewhere
 - Optimizing for speed at the cost of correctness
-- Not running the adversarial review (skipping Phase 3)
+- Settling for partial approval or cutting the Phase 3 review loop short before BOTH reviewers approve with zero reservations
 - Making changes without machine-readable output
 - Not feeding results back into compound-agent memory
 
 ## Quality Criteria
 - All 5 phases completed (analysis, planning, review, execution, verification)
-- Adversarial review with 2 independent reviewers was conducted
+- Both adversarial reviewers approved with zero reservations after iterative refinement
 - Machine-readable output format used throughout
 - Full test suite passes after changes
 - Coverage not degraded
@@ -5726,7 +5720,7 @@ async function stripHeadersRecursive(dir, dryRun = false) {
   return count;
 }
 async function upgradeDocVersion(repoRoot, newVersion, dryRun = false) {
-  const docPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
+  const docPath = join(repoRoot, "docs", "compound", "README.md");
   if (!existsSync(docPath)) return false;
   const content = await readFile(docPath, "utf-8");
   const updated = content.replace(/^(version: ")([^"]+)(")/m, `$1${newVersion}$3`);
@@ -5872,6 +5866,10 @@ async function runUpdate(repoRoot, dryRun) {
   for (const [name, content] of Object.entries(AGENT_ROLE_SKILLS)) {
     await processFile(join(repoRoot, ".claude", "skills", "compound", "agents", name, "SKILL.md"), content);
   }
+  for (const [filename, template] of Object.entries(DOC_TEMPLATES)) {
+    const content = template.replace("{{VERSION}}", VERSION).replace("{{DATE}}", (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+    await processFile(join(repoRoot, "docs", "compound", filename), content);
+  }
   for (const filename of LEGACY_ROOT_SLASH_COMMANDS) {
     const filePath = join(repoRoot, ".claude", "commands", filename);
     if (existsSync(filePath)) {
@@ -5881,6 +5879,14 @@ async function runUpdate(repoRoot, dryRun) {
       }
     }
   }
+  const oldDocPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
+  if (existsSync(oldDocPath)) {
+    const oldContent = await readFile(oldDocPath, "utf-8");
+    if (oldContent.startsWith("---\nversion:")) {
+      if (!dryRun) await rm(oldDocPath);
+      updated++;
+    }
+  }
   let configUpdated = false;
   if (!dryRun) {
     const { hooks } = await configureClaudeSettings();
@@ -5895,11 +5901,12 @@ var MODEL_STATUS_MSG = {
   already_exists: "Already exists",
   failed: "Download failed (run `ca download-model` manually)"
 };
-async function printSetupResult(result, quiet) {
+async function printSetupResult(result, quiet, repoRoot) {
   if (!quiet) {
-    if (result.scope.isUserScope) console.log(`  ${result.scope.message}`);
-    if (!result.beads.available) console.log(`  ${result.beads.message}`);
-    if (result.upgrade?.isUpgrade) console.log(`  ${result.upgrade.message}`);
+    if (result.upgrade?.isUpgrade) {
+      console.log(`  ${result.upgrade.message}`);
+      console.log("  Tip: Run with --update to regenerate managed files with latest templates.");
+    }
     if (process.stdout.isTTY) await playInstallBanner();
   }
   out.success("Compound agent setup complete");
@@ -5910,6 +5917,9 @@ async function printSetupResult(result, quiet) {
   printPnpmConfigStatus(result.pnpmConfig);
   printGitignoreStatus(result.gitignore);
   console.log(`  Model: ${MODEL_STATUS_MSG[result.model]}`);
+  const fullBeads = runFullBeadsCheck(repoRoot);
+  printBeadsFullStatus(fullBeads);
+  printScopeStatus(result.scope);
   console.log("\nNext steps:\n  1. Restart Claude Code to load hooks\n  2. Use `npx ca search` and `npx ca learn` commands");
 }
 function registerSetupAllCommand(setupCommand) {
@@ -5931,6 +5941,7 @@ function registerSetupAllCommand(setupCommand) {
       return;
     }
     if (options.update) {
+      if (!dryRun && process.stdout.isTTY) await playInstallBanner();
       const result2 = await runUpdate(repoRoot, dryRun);
       const prefix = dryRun ? "[dry-run] " : "";
       if (result2.upgrade.isUpgrade) {
@@ -5946,6 +5957,10 @@ function registerSetupAllCommand(setupCommand) {
         console.log(`  ${prefix}.gitignore: Added [${result2.gitignore.added.join(", ")}]`);
       }
       if (result2.configUpdated) console.log(`  ${prefix}Config: hooks updated`);
+      const fullBeads = runFullBeadsCheck(repoRoot);
+      printBeadsFullStatus(fullBeads);
+      const scope = checkUserScope(repoRoot);
+      printScopeStatus(scope);
       return;
     }
     if (options.status) {
@@ -5954,7 +5969,7 @@ function registerSetupAllCommand(setupCommand) {
     }
     const result = await runSetup({ skipModel: options.skipModel, skipHooks: options.skipHooks });
     const { quiet } = getGlobalOpts(this);
-    await printSetupResult(result, quiet);
+    await printSetupResult(result, quiet, repoRoot);
   });
 }
 async function handleStatus(alreadyInstalled, displayPath, settingsPath, options) {
@@ -6175,18 +6190,14 @@ async function initAction(cmd, options) {
   const repoRoot = getRepoRoot();
   const { quiet } = getGlobalOpts(cmd);
   const scopeResult = checkUserScope(repoRoot);
-  if (scopeResult.isUserScope && !quiet && !options.json) {
-    console.log(`  ${scopeResult.message}`);
-  }
-  const beadsResult = checkBeadsAvailable();
-  if (!beadsResult.available && !quiet && !options.json) {
-    console.log(`  ${beadsResult.message}`);
-  }
   let upgradeResult = null;
   if (options.update || detectExistingInstall(repoRoot)) {
     upgradeResult = await runUpgrade(repoRoot);
     if (!quiet && !options.json && upgradeResult.isUpgrade) {
       console.log(`  ${upgradeResult.message}`);
+      if (!options.update) {
+        console.log("  Tip: Run with --update to regenerate managed files with latest templates.");
+      }
     }
   }
   if (!quiet && !options.json && process.stdout.isTTY) {
@@ -6220,8 +6231,9 @@ async function initAction(cmd, options) {
     claudeHooksResult = await installClaudeHooksForInit(repoRoot);
   }
   const gitignoreResult = await ensureGitignore(repoRoot);
+  const fullBeads = runFullBeadsCheck(repoRoot);
   if (options.json) {
-    printInitJson({ lessonsDir, agentsMdUpdated, hookResult, claudeHooksResult, pnpmConfig, beadsResult, scopeResult, upgradeResult, gitignoreResult });
+    printInitJson({ lessonsDir, agentsMdUpdated, hookResult, claudeHooksResult, pnpmConfig, fullBeads, scopeResult, upgradeResult, gitignoreResult });
     return;
   }
   if (quiet) return;
@@ -6232,6 +6244,8 @@ async function initAction(cmd, options) {
   printClaudeHooksStatus(claudeHooksResult, options.skipClaude);
   printPnpmConfigStatus2(pnpmConfig);
   printGitignoreStatus(gitignoreResult);
+  printBeadsFullStatus(fullBeads);
+  printScopeStatus(scopeResult);
 }
 function printInitJson(ctx) {
   const claudeHooksInstalled = ctx.claudeHooksResult.action === "installed";
@@ -6244,7 +6258,9 @@ function printInitJson(ctx) {
     hookStatus: ctx.hookResult?.status ?? "skipped",
     claudeHooks: claudeHooksInstalled,
     pnpmConfig: ctx.pnpmConfig.isPnpm ? { added: ctx.pnpmConfig.added, alreadyConfigured: ctx.pnpmConfig.alreadyConfigured } : null,
-    beadsAvailable: ctx.beadsResult.available,
+    beadsAvailable: ctx.fullBeads.cliAvailable,
+    beadsInitialized: ctx.fullBeads.initialized,
+    beadsHealthy: ctx.fullBeads.healthy,
     userScope: ctx.scopeResult.isUserScope,
     upgrade: ctx.upgradeResult ? { isUpgrade: ctx.upgradeResult.isUpgrade, removedCommands: ctx.upgradeResult.removedCommands, strippedHeaders: ctx.upgradeResult.strippedHeaders } : null,
     gitignore: ctx.gitignoreResult.added
@@ -6514,6 +6530,17 @@ function registerCrudCommands(program2) {
     await deleteAction(ids, options);
   });
 }
+function checkGitignoreHealth(repoRoot) {
+  const gitignorePath = join(repoRoot, ".gitignore");
+  if (!existsSync(gitignorePath)) return false;
+  try {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const lines = new Set(content.split("\n").map((l) => l.trim()));
+    return ["node_modules/", ".claude/.cache/"].every((p) => lines.has(p));
+  } catch {
+    return false;
+  }
+}
 async function runDoctor(repoRoot) {
   const checks = [];
   const claudeDir = join(repoRoot, ".claude");
@@ -6540,20 +6567,21 @@ async function runDoctor(repoRoot) {
   checks.push(modelOk ? { name: "Embedding model", status: "pass" } : { name: "Embedding model", status: "warn", fix: "Run: npx ca download-model" });
   const beadsResult = checkBeadsAvailable();
   checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Install beads: https://github.com/Nathandela/beads" });
-  const gitignorePath = join(repoRoot, ".gitignore");
-  const requiredPatterns = ["node_modules/", ".claude/.cache/"];
-  let gitignoreOk = false;
-  if (existsSync(gitignorePath)) {
+  checks.push(checkGitignoreHealth(repoRoot) ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
+  const docPath = join(repoRoot, "docs", "compound", "README.md");
+  checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
+  const beadsDir = join(repoRoot, ".beads");
+  checks.push(existsSync(beadsDir) ? { name: "Beads initialized", status: "pass" } : { name: "Beads initialized", status: "warn", fix: "Run: bd init" });
+  if (beadsResult.available && existsSync(beadsDir)) {
     try {
-      const content = readFileSync(gitignorePath, "utf-8");
-      const lines = new Set(content.split("\n").map((l) => l.trim()));
-      gitignoreOk = requiredPatterns.every((p) => lines.has(p));
+      execSync("bd doctor", { cwd: repoRoot, shell: "/bin/sh", stdio: "pipe" });
+      checks.push({ name: "Beads healthy", status: "pass" });
     } catch {
+      checks.push({ name: "Beads healthy", status: "warn", fix: "Run: bd doctor" });
     }
   }
-  checks.push(gitignoreOk ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
-  const docPath = join(repoRoot, "docs", "compound", "HOW_TO_COMPOUND.md");
-  checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
+  const scope = checkUserScope(repoRoot);
+  checks.push(!scope.isUserScope ? { name: "Codebase scope", status: "pass" } : { name: "Codebase scope", status: "warn", fix: "Install in a specific repository, not home directory" });
   return checks;
 }
 var STATUS_ICONS = {
@@ -7335,6 +7363,99 @@ function registerVerifyGatesCommand(program2) {
     }
   });
 }
+
+// src/changelog-data.ts
+var CHANGELOG_RECENT = `## [1.3.1] - 2026-02-21
+
+### Added
+
+- **\`ca version-show\` command**: Displays version with terminal animation (tendril growth) and recent changelog entries. Non-TTY environments get plain text output. Changelog is embedded at build time from CHANGELOG.md.
+- **3 new doctor checks**: Beads initialized (\`.beads/\` dir), beads healthy (\`bd doctor\`), codebase scope (user-scope detection)
+- **Beads + scope status in init/setup output**: Full beads health display (CLI available, initialized, healthy) and scope status shown after \`ca init\`, \`ca setup\`, and \`ca setup --update\`
+- **Banner on \`--update\`**: Terminal art animation now plays during \`ca setup --update\` and \`ca init --update\` (same TTY/quiet guards as fresh install)
+
+### Changed
+
+- **Split documentation**: \`HOW_TO_COMPOUND.md\` replaced by 5 focused documents in \`docs/compound/\`: \`README.md\`, \`WORKFLOW.md\`, \`CLI_REFERENCE.md\`, \`SKILLS.md\`, \`INTEGRATION.md\`
+- **Test-cleaner Phase 3 strengthened**: Adversarial review phase now mandates iteration loop until both reviewers give unconditional approval. Heading, emphasis, and quality criteria updated.
+- **Update hint on upgrade**: When \`ca init\` or \`ca setup\` detects an existing install, displays tip to run with \`--update\` to regenerate managed files
+- **HOW_TO_COMPOUND.md migration**: \`ca setup --update\` automatically removes old monolithic \`HOW_TO_COMPOUND.md\` if it has version frontmatter (generated by compound-agent)
+- **Doctor doc check**: Now checks for \`docs/compound/README.md\` instead of \`HOW_TO_COMPOUND.md\`
+
+## [1.3.0] - 2026-02-21
+
+### Added
+
+- **Setup hardening**: Four new pre-flight checks during \`ca init\` and \`ca setup\`:
+  - **Beads CLI check** (\`beads-check.ts\`): Detects if \`bd\` is available, shows install URL if missing (informational, non-blocking)
+  - **User-scope detection** (\`scope-check.ts\`): Warns when installing at home directory level where lessons are shared across projects
+  - **.gitignore injection** (\`gitignore.ts\`): Ensures \`node_modules/\` and \`.claude/.cache/\` patterns exist in \`.gitignore\`
+  - **Upgrade detection** (\`upgrade.ts\`): Detects existing installs and runs migration pipeline (deprecated command removal, header stripping, doc version update)
+- **Upgrade engine**: Automated migration from v1.2.x to v1.3.0:
+  - Removes 5 deprecated CLI wrapper commands (\`search.md\`, \`list.md\`, \`show.md\`, \`stats.md\`, \`wrong.md\`)
+  - Strips legacy \`<!-- generated by compound-agent -->\` headers from installed files
+  - Updates \`HOW_TO_COMPOUND.md\` version during upgrade
+- **\`/compound:research\` skill**: PhD-depth research producing structured survey documents following \`TEMPLATE_FOR_RESEARCH.md\` format
+- **\`/compound:test-clean\` skill**: 5-phase test suite optimization with adversarial review (audit, design, implement, verify, report)
+- **Documentation template**: \`HOW_TO_COMPOUND.md\` deployed to \`docs/compound/\` during setup with version and date placeholders
+- **Test scripts**: \`test:segment\` (run tests for specific module), \`test:random\` (seeded random subset), \`test:critical\` (*.critical.test.ts convention)
+- **3 new doctor checks**: Beads CLI availability, \`.gitignore\` health, usage documentation presence
+
+### Fixed
+
+- **\`setup --update --dry-run\` no longer mutates files**: \`runUpgrade()\` now accepts a \`dryRun\` parameter propagated to all sub-functions (removeDeprecatedCommands, stripGeneratedHeaders, upgradeDocVersion)
+- **\`setup --uninstall\` respects plugin.json ownership**: Checks \`name === "compound-agent"\` before deleting; user-owned plugin manifests are preserved
+- **Upgrade ownership guard**: \`removeDeprecatedCommands\` checks file content for compound-agent markers before deleting, preventing silent removal of user-authored files with the same name
+- **Malformed settings.json no longer silently clobbered**: On parse error, \`configureClaudeSettings\` warns and skips instead of overwriting with empty config
+
+### Changed
+
+- **\`setup --update\` overhaul**: Now uses path-based file detection (compound/ = managed) instead of marker-based. Runs upgrade pipeline and \`.gitignore\` remediation during update
+- **JSON-first \`bd\` parsing in loop**: \`jq\` primary with \`python3\` fallback via \`parse_json()\` helper
+- **CLI test helpers hardened**: Replaced shell string interpolation with \`execFileSync\` for safety and reliability
+- **Beads check portable**: Uses POSIX \`command -v\` instead of non-portable \`which\`
+- **Template expansion**: Brainstorm and plan skills now cross-reference researcher skill; 9 total skills, 11 total commands
+- **Code organization**: Extracted display utilities to \`display-utils.ts\`, uninstall logic to \`uninstall.ts\`
+
+### Removed
+
+- **5 deprecated CLI wrapper commands**: \`search.md\`, \`list.md\`, \`show.md\`, \`stats.md\`, \`wrong.md\` (redundant wrappers around \`npx ca <cmd>\`)
+- **\`GENERATED_MARKER\` on new installs**: New installs use path-based detection; marker retained only for backward-compatible \`--update\` detection
+
+## [1.2.11] - 2026-02-19
+
+### Added
+
+- **Git worktree integration** (\`ca worktree\`): Isolate epic work in separate git worktrees for parallel execution. Five subcommands:
+  - \`ca worktree create <epic-id>\` \u2014 Create worktree, install deps, copy lessons, create Merge beads task
+  - \`ca worktree wire-deps <epic-id>\` \u2014 Connect Review/Compound tasks as merge blockers (graceful no-op without worktree)
+  - \`ca worktree merge <epic-id>\` \u2014 Two-phase merge: resolve conflicts in worktree, then land clean on main
+  - \`ca worktree list\` \u2014 Show active worktrees with epic and merge task status
+  - \`ca worktree cleanup <epic-id>\` \u2014 Remove worktree, branch, and close Merge task (--force for dirty worktrees)
+- **\`/compound:set-worktree\` slash command**: Set up a worktree before running \`/compound:lfg\` for isolated epic execution
+- **Conditional Merge gate in \`verify-gates\`**: Worktree epics require the Merge task to be closed before epic closure. Non-worktree epics unaffected.
+- **Plan skill wire-deps step**: Plan phase now calls \`ca worktree wire-deps\` to connect merge dependencies when a worktree is active.
+
+### Changed
+
+- **Worktree merge safety hardening**: Added branch verification (asserts main repo is on \`main\`), worktree existence guard, structured error messages with worktree paths for conflict resolution and test failures
+- **JSONL reconciliation**: Switched from ID-based to line-based deduplication to preserve last-write-wins semantics for same-ID updates and deletes
+- **Worktree cleanup safety**: Branch deletion uses \`-d\` (safe) by default; \`-D\` (force) only with \`--force\` flag
+- **Shared beads utilities**: Extracted \`validateEpicId\`, \`parseBdShowDeps\`, and \`shortId\` to \`cli-utils.ts\`, eliminating duplication between \`worktree.ts\` and \`verify-gates.ts\`
+- **Sync API**: All worktree functions are now synchronous (removed misleading \`async\` wrapper around purely synchronous \`execFileSync\` calls)`;
+
+// src/commands/version-show.ts
+function registerVersionShowCommand(program2) {
+  program2.command("version-show").description("Show version with animation and recent changelog").action(async () => {
+    if (process.stdout.isTTY) {
+      await playInstallBanner();
+    } else {
+      console.log(`compound-agent v${VERSION}`);
+    }
+    console.log("");
+    console.log(CHANGELOG_RECENT);
+  });
+}
 function parseWorktreeList(raw) {
   const entries = [];
   let currentPath = "";
@@ -8443,6 +8564,7 @@ function registerManagementCommands(program2) {
   registerRulesCommands(program2);
   registerTestSummaryCommand(program2);
   registerVerifyGatesCommand(program2);
+  registerVersionShowCommand(program2);
   registerWorktreeCommands(program2);
 }