compound-agent 1.6.0 → 1.6.1

package/dist/cli.js

@@ -11,7 +11,7 @@ import { createRequire } from 'module';
 import { execSync, execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
-import chalk4 from 'chalk';
+import chalk5 from 'chalk';
 import { createInterface } from 'readline';
 
 var __defProp = Object.defineProperty;
@@ -2193,7 +2193,10 @@ function acquireEmbedLock(repoRoot) {
     if (err.code !== "EEXIST") throw err;
     const existing = readLock(file);
     if (existing && isProcessAlive(existing.pid)) {
-      return { acquired: false, holder: existing.pid };
+      const lockAge = Date.now() - new Date(existing.startedAt).getTime();
+      if (lockAge < LOCK_MAX_AGE_MS) {
+        return { acquired: false, holder: existing.pid };
+      }
     }
     try {
       unlinkSync(file);
@@ -2221,8 +2224,10 @@ function releaseLock(file) {
   } catch {
   }
 }
+var LOCK_MAX_AGE_MS;
 var init_embed_lock = __esm({
   "src/memory/knowledge/embed-lock.ts"() {
+    LOCK_MAX_AGE_MS = 60 * 60 * 1e3;
   }
 });
 function statusPath(repoRoot) {
@@ -4395,9 +4400,24 @@ async function ensureGitignore(repoRoot) {
   if (missing.length === 0) {
     return { added: [] };
   }
-  const section = [SECTION_COMMENT, ...missing].join("\n");
-  const separator = content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : "";
-  const newContent = content + separator + section + "\n";
+  let newContent;
+  const sectionIdx = lines.findIndex((l) => l.trim() === SECTION_COMMENT);
+  if (sectionIdx >= 0) {
+    let insertAfter = sectionIdx;
+    for (let i = sectionIdx + 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line === void 0) break;
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) break;
+      insertAfter = i;
+    }
+    lines.splice(insertAfter + 1, 0, ...missing);
+    newContent = lines.join("\n");
+  } else {
+    const section = [SECTION_COMMENT, ...missing].join("\n");
+    const separator = content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : "";
+    newContent = content + separator + section + "\n";
+  }
   await writeFile(gitignorePath, newContent, "utf-8");
   return { added: missing };
 }
@@ -4881,7 +4901,7 @@ Analyze the repository to understand its structure, coding conventions, tech sta
 Return findings directly to the caller for synthesis into the plan.
 
 ## Deployment
-Subagent spawned via the Task tool during the **plan** and **brainstorm** phases. Return findings directly to the caller.
+Subagent spawned via the Task tool during the **plan** and **spec-dev** phases. Return findings directly to the caller.
 
 ## Output Format
 Return a structured summary:
@@ -4912,7 +4932,7 @@ Search compound-agent memory to find relevant lessons, patterns, and decisions f
 Return findings directly to the caller for synthesis into the plan.
 
 ## Deployment
-Subagent spawned via the Task tool during the **plan** and **brainstorm** phases. Return findings directly to the caller.
+Subagent spawned via the Task tool during the **plan** and **spec-dev** phases. Return findings directly to the caller.
 
 ## Output Format
 Return a list of relevant memory items:
@@ -5557,16 +5577,16 @@ var AGENT_ROLE_SKILLS = {
 
 // src/setup/templates/commands.ts
 var WORKFLOW_COMMANDS = {
-  "brainstorm.md": `---
-name: compound:brainstorm
-description: Explore requirements through collaborative dialogue before committing to a plan
-argument-hint: "<goal or topic to brainstorm>"
+  "spec-dev.md": `---
+name: compound:spec-dev
+description: Develop precise specifications through Socratic dialogue, EARS notation, and Mermaid diagrams
+argument-hint: "<goal or feature to specify>"
 ---
 $ARGUMENTS
 
-# Brainstorm
+# Spec Dev
 
-**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/brainstorm/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/spec-dev/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   "plan.md": `---
 name: compound:plan
@@ -5612,17 +5632,17 @@ $ARGUMENTS
 
 **MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/compound/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
-  "lfg.md": `---
-name: compound:lfg
+  "cook-it.md": `---
+name: compound:cook-it
 description: Full workflow cycle chaining all five phases
 argument-hint: "<goal>"
 disable-model-invocation: true
 ---
 $ARGUMENTS
 
-# LFG
+# Cook It
 
-**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.
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/cook-it/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full orchestration workflow you must follow.
 `,
   "research.md": `---
 name: compound:research
@@ -5779,7 +5799,7 @@ npx ca doctor
   settings.json                # Claude Code hooks
   plugin.json                  # Plugin manifest
   agents/compound/             # Subagent definitions
-  commands/compound/           # Slash commands (brainstorm, plan, work, review, compound, lfg)
+  commands/compound/           # Slash commands (spec-dev, plan, work, review, compound, cook-it)
   skills/compound/             # Phase skills + agent role skills
   lessons/
     index.jsonl                # Memory items (git-tracked source of truth)
@@ -5800,14 +5820,14 @@ docs/compound/
 | Search docs knowledge | \`npx ca knowledge "query"\` |
 | Check plan against memory | \`npx ca check-plan --plan "description"\` |
 | View stats | \`npx ca stats\` |
-| Run full workflow | \`/compound:lfg <epic-id>\` |
+| Run full workflow | \`/compound:cook-it <epic-id>\` |
 | Health check | \`npx ca doctor\` |
 
 ---
 
 ## Further reading
 
-- [WORKFLOW.md](WORKFLOW.md) -- The 5-phase development workflow and LFG orchestrator
+- [WORKFLOW.md](WORKFLOW.md) -- The 5-phase development workflow and cook-it 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
@@ -5815,29 +5835,29 @@ docs/compound/
   "WORKFLOW.md": `---
 version: "{{VERSION}}"
 last-updated: "{{DATE}}"
-summary: "The 5-phase compound-agent workflow and LFG orchestrator"
+summary: "The 5-phase compound-agent workflow and cook-it orchestrator"
 ---
 
 # Workflow
 
-Every feature or epic follows five phases. The \`/compound:lfg\` skill chains them with enforcement gates.
+Every feature or epic follows five phases. The \`/compound:cook-it\` skill chains them with enforcement gates.
 
 ---
 
-## Phase 1: Brainstorm
+## Phase 1: Spec Dev
 
-Explore the problem space before committing to a solution.
+Develop precise specifications through Socratic dialogue, EARS notation, and Mermaid diagrams.
 
-- Ask "why" before "how"
-- Search memory for similar past features
-- Generate multiple approaches, then converge
+- Ask "why" before "how" -- understand the real need
+- Search memory for past features, constraints, decisions
+- Use EARS notation for clear, testable requirements
 - Create a beads epic: \`bd create --title="..." --type=epic\`
 
 ## Phase 2: Plan
 
 Decompose work into small, testable tasks with dependencies.
 
-- Review brainstorm output
+- Review spec-dev output
 - Create beads tasks: \`bd create --title="..." --type=task\`
 - Create Review and Compound blocking tasks (these survive compaction)
 
@@ -5870,20 +5890,20 @@ Extract and store lessons learned. This is what makes the system compound.
 
 ---
 
-## LFG orchestrator
+## Cook-it orchestrator
 
-\`/compound:lfg\` chains all 5 phases with enforcement gates.
+\`/compound:cook-it\` chains all 5 phases with enforcement gates.
 
 ### Invocation
 
 \`\`\`
-/compound:lfg <epic-id>
-/compound:lfg <epic-id> from plan
+/compound:cook-it <epic-id>
+/compound:cook-it <epic-id> from plan
 \`\`\`
 
 ### Phase execution protocol
 
-For each phase, LFG:
+For each phase, cook-it:
 
 1. Announces progress: \`[Phase N/5] PHASE_NAME\`
 2. Initializes state: \`npx ca phase-check start <phase>\`
@@ -5902,18 +5922,18 @@ For each phase, LFG:
 | 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.
+If any gate fails, cook-it stops. You must fix the issue before proceeding.
 
 ### Resumption
 
-If interrupted, LFG can resume:
+If interrupted, cook-it 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:
+Cook-it persists state in \`.claude/.ca-phase-state.json\`. Useful commands:
 
 \`\`\`bash
 npx ca phase-check status      # See current phase state
@@ -5922,7 +5942,7 @@ npx ca phase-check clean       # Reset phase state (escape hatch)
 
 ### Session close
 
-Before saying "done", LFG runs this inviolable checklist:
+Before saying "done", cook-it runs this inviolable checklist:
 
 \`\`\`bash
 git status
@@ -6084,21 +6104,21 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 ## Phase skills
 
-### \`/compound:brainstorm\`
+### \`/compound:spec-dev\`
 
-**Purpose**: Divergent-then-convergent thinking to explore the solution space.
+**Purpose**: Develop precise specifications through Socratic dialogue, EARS notation, and Mermaid diagrams.
 
 **When invoked**: At the start of a new feature or epic, before any planning.
 
-**What it does**: Spawns research subagents, searches memory for similar past features, generates multiple approaches, converges on a decision with documented rationale, and creates a beads epic.
+**What it does**: Guides the user through 4 phases (Explore, Understand, Specify, Hand off) to produce a rigorous spec. Spawns research subagents, uses Mermaid diagrams as thinking tools, detects NL ambiguity, writes EARS-notation requirements, and stores the consolidated spec in the beads epic description.
 
 ### \`/compound:plan\`
 
 **Purpose**: Decompose work into small testable tasks with dependencies.
 
-**When invoked**: After brainstorm, before any implementation.
+**When invoked**: After spec-dev, before any implementation.
 
-**What it does**: Reviews brainstorm output, spawns analysts, decomposes into tasks with acceptance criteria, creates beads issues, and creates Review + Compound blocking tasks.
+**What it does**: Reviews spec-dev output, spawns analysts, decomposes into tasks with acceptance criteria, creates beads issues, and creates Review + Compound blocking tasks.
 
 ### \`/compound:work\`
 
@@ -6124,7 +6144,7 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 **What it does**: Spawns an analysis pipeline (context-analyzer, lesson-extractor, pattern-matcher, solution-writer, compounding), applies quality filters, classifies items by type and severity, stores via \`npx ca learn\`, runs \`npx ca verify-gates\`.
 
-### \`/compound:lfg\`
+### \`/compound:cook-it\`
 
 **Purpose**: Full-cycle orchestrator chaining all five phases.
 
@@ -6147,12 +6167,12 @@ Skills are instructions that Claude reads before executing each phase. They live
 Skills are invoked as Claude Code slash commands:
 
 \`\`\`
-/compound:brainstorm       # Start brainstorm phase
+/compound:spec-dev         # Start spec-dev 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:cook-it <epic-id>    # Run all phases end-to-end
 /compound:research         # Spawn research subagent
 /compound:test-clean       # Clean test artifacts
 /compound:get-a-phd <focus>       # Deep research for agent knowledge
@@ -6311,61 +6331,91 @@ Work is not complete until \`git push\` succeeds.
 
 // src/setup/templates/skills.ts
 var PHASE_SKILLS = {
-  brainstorm: `---
-name: Brainstorm
-description: Divergent-then-convergent thinking to explore solution space
+  "spec-dev": `---
+name: Spec Dev
+description: Develop precise specifications through Socratic dialogue, EARS notation, and Mermaid diagrams
 ---
 
-# Brainstorm Skill
+# Spec Dev Skill
 
 ## Overview
-Explore the problem space before committing to a solution. This phase produces a structured brainstorm document with decisions, open questions, and a beads epic for handoff to planning.
-
-## Methodology
-1. Ask "why" before "how" -- understand the real problem
-2. Search memory with \`npx ca search\` and docs with \`npx ca knowledge "relevant topic"\` for similar past features and known constraints
-3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
-   - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
-   - Or use \`subagent_type: Explore\` for ad-hoc research
-   - Deploy MULTIPLE when topic spans several domains; synthesize all findings before proceeding
-4. When facing deep unknowns or complex technical domains, invoke the **researcher skill** (read \`.claude/skills/compound/researcher/SKILL.md\`) to produce a structured survey document before narrowing approaches
-5. Use \`AskUserQuestion\` to clarify scope, constraints, and preferences
-6. Divergent phase: generate multiple approaches without filtering
-7. Identify constraints and non-functional requirements (performance, security, etc.)
-8. Convergent phase: evaluate approaches against constraints
-9. Document decisions with rationale, list open questions, and create a beads epic
-10. Auto-create ADR files in \`docs/decisions/\` for significant decisions (lightweight: Status, Context, Decision, Consequences)
+Develop unambiguous, testable specifications before implementation. Structured 4-phase process producing EARS-notation requirements, architecture diagrams, and a beads epic.
+
+Scale formality to risk: skip for trivial (<1h), lightweight (EARS + epic) for small, full 4-phase for medium+. Use \`AskUserQuestion\` early to gauge scope.
+
+## Methodology: 4-Phase Spec Development
+
+### Phase 1: Explore
+**Goal**: Map the problem domain before narrowing.
+1. Ask "why" before "how" -- understand the real need
+2. Search memory: \`npx ca search\` for past features, constraints, decisions
+3. Search knowledge: \`npx ca knowledge "relevant terms"\`
+4. Spawn subagents for research (\`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`, or \`subagent_type: Explore\`)
+5. For deep domain knowledge, consider \`/get-a-phd\`
+6. Build a discovery mindmap (Mermaid \`mindmap\`) -- makes implicit assumptions visible
+7. Use \`AskUserQuestion\` to clarify scope and preferences
+
+**Iteration trigger**: If research reveals the problem is fundamentally different, restart Explore.
+
+### Phase 2: Understand
+**Goal**: Crystallize requirements through Socratic dialogue.
+1. For each capability, ask: triggers? edge cases? constraints? acceptance criteria?
+2. Use Mermaid diagrams (\`sequenceDiagram\`, \`stateDiagram-v2\`) to expose hidden structure
+3. Detect ambiguities: vague adjectives, unclear pronouns, passive voice, compound requirements. See \`references/spec-guide.md\` for full checklist
+4. Build a domain glossary for ambiguous terms
+5. Use \`AskUserQuestion\` to resolve each ambiguity
+
+**Iteration trigger**: If specifying reveals missing knowledge, loop back to Explore.
+
+### Phase 3: Specify
+**Goal**: Produce formal, testable requirements.
+1. Write each requirement using **EARS notation**:
+   - Ubiquitous: \`The system shall <action>.\`
+   - Event-driven: \`When <trigger>, the system shall <action>.\`
+   - State-driven: \`While <state>, the system shall <action>.\`
+   - Unwanted behavior: \`If <condition>, then the system shall <action>.\`
+   - Optional: \`Where <feature>, the system shall <action>.\`
+   - Combined ordering: \`Where > While > When > If/then > shall\`
+2. Verify each requirement: no vague adjectives, edge cases covered, quantities specified, testable
+3. Document trade-offs when requirements conflict (see \`references/spec-guide.md\`)
+4. Produce architecture diagrams (\`erDiagram\`, \`C4Context\`, \`flowchart\`)
+5. Create ADRs in \`docs/decisions/\` for significant decisions
+
+**Iteration trigger**: If contradictions or gaps emerge, loop back to Understand.
+
+### Phase 4: Hand off
+1. Store spec in beads epic description (\`bd update <epic> --description="..."\`) -- single source of truth
+2. Create beads epic if needed (\`bd create\`)
+3. Flag open questions for plan phase
+4. Capture lessons: \`npx ca learn\`
 
 ## Memory Integration
-- Run \`npx ca search\` and \`npx ca knowledge "relevant topic"\` with relevant keywords before generating approaches
-- Look for past architectural decisions, pitfalls, and preferences
-- If the problem domain matches past work, review those lessons first
+- \`npx ca search\` before generating approaches
+- \`npx ca knowledge\` for indexed project docs
+- \`npx ca learn\` after corrections or discoveries
 
-## Docs Integration
-- Spawn docs-explorer to scan \`docs/\` for relevant architecture docs, research, and standards
-- Review existing ADRs in \`docs/decisions/\` -- prior decisions may constrain the brainstorm
-- Auto-create ADR for each significant decision made during convergence
+## Reference Material
+Read \`.claude/skills/compound/spec-dev/references/spec-guide.md\` on demand for EARS patterns, Mermaid templates, ambiguity checklists, and trade-off frameworks.
 
 ## Common Pitfalls
-- Jumping to the first solution without exploring alternatives
-- Ignoring non-functional requirements (scalability, maintainability)
-- Not searching memory for similar past features
-- Not checking existing docs and ADRs for prior decisions
-- Over-scoping: trying to solve everything at once
-- Skipping the "why" and diving into "how"
-- Not invoking the researcher skill when the domain requires deep investigation
-- Not creating a beads epic from conclusions (losing brainstorm output)
+- Jumping to solutions before exploring the problem
+- Skipping diagrams -- they reveal hidden assumptions
+- Vague requirements without EARS patterns
+- Not searching memory for past patterns and pitfalls
+- Over-specifying trivial tasks
+- Ignoring iteration signals when gaps emerge
+- Not creating the beads epic
+- Specifying implementation instead of requirements
 
 ## Quality Criteria
-- Multiple approaches were considered (at least 2-3)
-- Constraints and requirements are explicitly listed
-- Memory was searched for relevant context
-- Existing docs and ADRs were reviewed for prior decisions
-- User was engaged via \`AskUserQuestion\` for clarification
-- A clear decision was made with documented rationale
-- ADRs created for significant architectural decisions
-- Open questions are captured for the plan phase
-- A beads epic was created from conclusions via \`bd create\`
+- [ ] Requirements use EARS notation
+- [ ] Ambiguities detected and resolved via dialogue
+- [ ] Mermaid diagrams used as thinking tools
+- [ ] Memory searched (\`npx ca search\`)
+- [ ] Trade-offs documented with rationale
+- [ ] User engaged via \`AskUserQuestion\` at decisions
+- [ ] Spec stored in beads epic description
+- [ ] ADRs created for significant decisions
 `,
   plan: `---
 name: Plan
@@ -6378,7 +6428,7 @@ description: Decompose work into small testable tasks with clear dependencies
 Create a concrete implementation plan by decomposing work into small, testable tasks with dependencies and acceptance criteria.
 
 ## Methodology
-1. Review brainstorm output for decisions and open questions
+1. Read the spec from the epic description (\`bd show <epic>\`) for EARS requirements, decisions, and open questions
 2. Search memory with \`npx ca search\` and docs with \`npx ca knowledge "relevant topic"\` for architectural patterns and past mistakes
 3. Spawn **subagents** via Task tool in parallel for research (lightweight, no inter-agent coordination):
    - Available agents: \`.claude/agents/compound/repo-analyst.md\`, \`memory-analyst.md\`
@@ -6389,9 +6439,10 @@ Create a concrete implementation plan by decomposing work into small, testable t
 6. Use \`AskUserQuestion\` to resolve ambiguities, conflicting constraints, or priority trade-offs before decomposing
 7. Decompose into tasks small enough to verify individually
 8. Define acceptance criteria for each task
-9. Map dependencies between tasks
-10. Create beads issues: \`bd create --title="..." --type=task\`
-11. 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
+9. Ensure each task traces back to a spec requirement for traceability
+10. Map dependencies between tasks
+11. Create beads issues: \`bd create --title="..." --type=task\`
+12. 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
 
 ## Memory Integration
 - Run \`npx ca search\` and \`npx ca knowledge "relevant topic"\` for patterns related to the feature area
@@ -6420,6 +6471,7 @@ Create a concrete implementation plan by decomposing work into small, testable t
 - Existing docs and ADRs were checked for constraints
 - Ambiguities resolved via \`AskUserQuestion\` before decomposing
 - Complexity estimates are realistic (no "should be quick")
+- Each task traces back to a spec requirement
 
 ## POST-PLAN VERIFICATION -- MANDATORY
 After creating all tasks, verify review and compound tasks exist:
@@ -6439,18 +6491,20 @@ Execute implementation through an AgentTeam using adaptive TDD. The lead coordin
 ## Methodology
 1. Pick tasks from \`bd ready\` or \`$ARGUMENTS\`
 2. Mark tasks in progress: \`bd update <id> --status=in_progress\`
-3. Run \`npx ca search\` per agent/subtask for targeted context. Display results.
-4. Assess parallelization: identify independent tasks that can be worked simultaneously
-5. Deploy an **AgentTeam** (TeamCreate + Task with \`team_name\`) with MULTIPLE test-writers and implementers:
+3. Read the epic description (\`bd show <epic>\`) for spec context -- EARS requirements guide what "done" looks like
+4. Run \`npx ca search\` per agent/subtask for targeted context. Display results.
+5. Assess parallelization: identify independent tasks that can be worked simultaneously
+6. Deploy an **AgentTeam** (TeamCreate + Task with \`team_name\`) with MULTIPLE test-writers and implementers:
    - Role skills: \`.claude/skills/compound/agents/{test-writer,implementer}/SKILL.md\`
    - Scale teammate count to independent tasks; pairs coordinate via SendMessage on shared interfaces
-6. Agents communicate via SendMessage when working on overlapping areas.
-7. Lead coordinates: review agent outputs, resolve conflicts, verify tests pass. Do not write code directly.
-8. If blocked, use AskUserQuestion to get user direction.
-9. Shut down the team when done: send shutdown_request to all teammates.
-10. Commit incrementally as tests pass.
-11. Run full test suite for regressions.
-12. Close tasks: \`bd close <id>\`
+7. Agents communicate via SendMessage when working on overlapping areas.
+8. Lead coordinates: review agent outputs, resolve conflicts, verify tests pass. Do not write code directly.
+9. If implementation diverges from spec requirements, stop and discuss with user via AskUserQuestion before proceeding.
+10. If blocked, use AskUserQuestion to get user direction.
+11. Shut down the team when done: send shutdown_request to all teammates.
+12. Commit incrementally as tests pass.
+13. Run full test suite for regressions.
+14. Close tasks: \`bd close <id>\`
 
 ## Memory Integration
 - Run \`npx ca search\` per delegated subtask with the subtask's specific description
@@ -6477,6 +6531,12 @@ for complex changes. For all changes, \`/implementation-reviewer\` is the minimu
 - **Subagent spawning within teammates**: each teammate should spawn opus subagents for independent subtasks (e.g., a test-writer spawning subagents to write tests for multiple modules in parallel)
 - **Coordinate on shared interfaces**: teammates working on overlapping APIs must communicate via SendMessage before implementing
 
+## Literature
+- Consult \`docs/compound/research/tdd/\` for TDD methodology, test-first development evidence, and best practices
+- Consult \`docs/compound/research/property-testing/\` for property-based testing theory and invariant design
+- Run \`npx ca knowledge "TDD test-first"\` for indexed knowledge on testing methodology
+- Run \`npx ca search "testing"\` for lessons from past TDD cycles
+
 ## Common Pitfalls
 - Lead writing code instead of delegating to agents
 - Not injecting memory context into agent prompts
@@ -6490,6 +6550,7 @@ for complex changes. For all changes, \`/implementation-reviewer\` is the minimu
 - Incremental commits made as tests pass
 - All tests pass after refactoring
 - Task lifecycle tracked via beads (\`bd\`)
+- Implementation aligns with spec requirements from epic
 
 ## PHASE GATE 3 -- MANDATORY
 Before starting Review, verify ALL work tasks are closed:
@@ -6509,23 +6570,25 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 
 ## Methodology
 1. Run quality gates first: \`pnpm test && pnpm lint\`
-2. Search memory with \`npx ca search\` for known patterns and recurring issues
-3. Select reviewer tier based on diff size:
+2. Read the epic description (\`bd show <epic>\`) for EARS requirements -- reviewers verify each requirement is met
+3. Search memory with \`npx ca search\` for known patterns and recurring issues
+4. Select reviewer tier based on diff size:
    - **Small** (<100 lines): 4 core -- security, test-coverage, simplicity, cct-reviewer
    - **Medium** (100-500): add architecture, performance, edge-case (7 total)
    - **Large** (500+): all 11 reviewers including docs, consistency, error-handling, pattern-matcher
-4. Spawn reviewers in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
+5. Spawn reviewers in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
    - Role skills: \`.claude/skills/compound/agents/{security-reviewer,architecture-reviewer,performance-reviewer,test-coverage-reviewer,simplicity-reviewer}/SKILL.md\`
    - Security specialist skills (on-demand, spawned by security-reviewer): \`.claude/skills/compound/agents/{security-injection,security-secrets,security-auth,security-data,security-deps}/SKILL.md\`
    - For large diffs (500+), deploy MULTIPLE instances; split files across instances, coordinate via SendMessage
-5. Reviewers communicate findings to each other via \`SendMessage\`
-6. Collect, consolidate, and deduplicate all findings
-7. Classify by severity: P0 (blocks merge), P1 (critical/blocking), P2 (important), P3 (minor)
-8. Use \`AskUserQuestion\` when severity is ambiguous or fix has multiple valid options
-9. Create beads issues for P1 findings: \`bd create --title="P1: ..."\`
-10. Fix all P1 findings before proceeding
-11. Run \`/implementation-reviewer\` as mandatory gate
-12. Capture novel findings with \`npx ca learn\`; pattern-matcher auto-reinforces recurring issues
+6. Reviewers communicate findings to each other via \`SendMessage\`
+7. Collect, consolidate, and deduplicate all findings
+8. Classify by severity: P0 (blocks merge), P1 (critical/blocking), P2 (important), P3 (minor)
+9. Use \`AskUserQuestion\` when severity is ambiguous or fix has multiple valid options
+10. Create beads issues for P1 findings: \`bd create --title="P1: ..."\`
+11. Verify spec alignment: flag unmet EARS requirements as P1, flag requirements met but missing from acceptance criteria as gaps
+12. Fix all P1 findings before proceeding
+13. Run \`/implementation-reviewer\` as mandatory gate
+14. Capture novel findings with \`npx ca learn\`; pattern-matcher auto-reinforces recurring issues
 
 ## Memory Integration
 - Run \`npx ca search\` before review for known recurring issues
@@ -6537,6 +6600,11 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 - **docs-reviewer** checks code/docs alignment and ADR compliance
 - Flags undocumented public APIs and ADR violations
 
+## Literature
+- Consult \`docs/compound/research/code-review/\` for systematic review methodology, severity taxonomies, and evidence-based review practices
+- Run \`npx ca knowledge "code review methodology"\` for indexed knowledge on review techniques
+- Run \`npx ca search "review"\` for lessons from past review cycles
+
 ## Common Pitfalls
 - Ignoring reviewer feedback because "it works"
 - Not running all 11 reviewer perspectives (skipping dimensions)
@@ -6556,6 +6624,7 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 - security-reviewer P0 findings: none (blocks merge)
 - security-reviewer P1 findings: all acknowledged or resolved
 - All P1 findings fixed before \`/implementation-reviewer\` approval
+- All spec requirements verified against implementation
 - \`/implementation-reviewer\` approved as mandatory gate
 
 ## PHASE GATE 4 -- MANDATORY
@@ -6580,26 +6649,32 @@ Lessons go to \`.claude/lessons/index.jsonl\` through the CLI. MEMORY.md is a di
 
 ## Methodology
 1. Review what happened during this cycle (git diff, test results, plan context)
-2. Spawn the analysis pipeline in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
+2. Detect spec drift: compare final implementation against original EARS requirements in the epic description (\`bd show <epic>\`). Note any divergences -- what changed, why, was it justified. If drift reveals a spec was wrong or incomplete, flag that for lesson extraction.
+3. Spawn the analysis pipeline in an **AgentTeam** (TeamCreate + Task with \`team_name\`):
    - Role skills: \`.claude/skills/compound/agents/{context-analyzer,lesson-extractor,pattern-matcher,solution-writer,compounding}/SKILL.md\`
    - For large diffs, deploy MULTIPLE context-analyzers and lesson-extractors
    - Pipeline: context-analyzers -> lesson-extractors -> pattern-matcher + solution-writer -> compounding
    - Agents coordinate via SendMessage throughout the pipeline
-3. Agents pass results through the pipeline via \`SendMessage\`. The lead coordinates: context-analyzer and lesson-extractor feed pattern-matcher and solution-writer, which feed compounding.
-4. Apply quality filters: novelty check (>0.98 cosine similarity = skip), specificity check
-5. Classify each item by type: lesson, solution, pattern, or preference
-6. Classify severity: high (data loss/security/contradictions), medium (workflow/patterns), low (style/optimizations)
-7. Store via \`npx ca learn\` with supersedes/related links where applicable.
+4. Agents pass results through the pipeline via \`SendMessage\`. The lead coordinates: context-analyzer and lesson-extractor feed pattern-matcher and solution-writer, which feed compounding.
+5. Apply quality filters: novelty check (>0.98 cosine similarity = skip), specificity check
+6. Classify each item by type: lesson, solution, pattern, or preference
+7. Classify severity: high (data loss/security/contradictions), medium (workflow/patterns), low (style/optimizations)
+8. Store via \`npx ca learn\` with supersedes/related links where applicable.
    At minimum, capture 1 lesson per significant decision made during this cycle
-8. Delegate to the \`compounding\` subagent to run synthesis: cluster accumulated lessons by similarity and write CCT patterns to \`.claude/lessons/cct-patterns.jsonl\`
-9. Update outdated docs and deprecate superseded ADRs (set status to \`deprecated\`)
-10. Use \`AskUserQuestion\` to confirm high-severity items with the user before storing; medium/low items are auto-stored
+9. Delegate to the \`compounding\` subagent to run synthesis: cluster accumulated lessons by similarity and write CCT patterns to \`.claude/lessons/cct-patterns.jsonl\`
+10. Update outdated docs and deprecate superseded ADRs (set status to \`deprecated\`)
+11. Use \`AskUserQuestion\` to confirm high-severity items with the user before storing; medium/low items are auto-stored
 
 ## Docs Integration
 - docs-reviewer checks if \`docs/\` content is outdated after the cycle
 - Check \`docs/decisions/\` for ADRs contradicted by the work done
 - Set ADR status to \`deprecated\` if a decision was reversed, referencing the new ADR
 
+## Literature
+- Consult \`docs/compound/research/learning-systems/\` for knowledge compounding theory, spaced repetition, and lesson extraction methodology
+- Run \`npx ca knowledge "knowledge compounding"\` for indexed knowledge on learning systems
+- Run \`npx ca search "compound"\` for lessons from past compounding cycles
+
 ## Common Pitfalls
 - Not spawning the analysis team (analyzing solo misses cross-cutting patterns)
 - Capturing without checking for duplicates via \`npx ca search\`
@@ -6619,6 +6694,7 @@ Lessons go to \`.claude/lessons/index.jsonl\` through the CLI. MEMORY.md is a di
 - User confirmed high-severity items
 - Beads checked for related issues (\`bd\`)
 - Each item gives clear, concrete guidance for future sessions
+- Spec drift analyzed and captured
 
 ## FINAL GATE -- EPIC CLOSURE
 Before closing the epic:
@@ -6657,7 +6733,7 @@ Conduct deep research on a topic and produce a structured survey document follow
    - References (full citations)
    - Practitioner Resources (annotated tools/repos)
 6. Store output at \`docs/compound/research/<topic-slug>.md\` (kebab-case filename)
-7. Report key findings back for upstream skill (brainstorm/plan) to act on
+7. Report key findings back for upstream skill (spec-dev/plan) to act on
 
 ## Memory Integration
 - Run \`npx ca search\` with topic keywords before starting research
@@ -6734,19 +6810,30 @@ Annotated tools, repos, articles grouped by category.
 - Practitioner resources annotated
 - No recommendations -- landscape presentation only
 `,
-  lfg: `---
-name: LFG
+  "cook-it": `---
+name: Cook It
 description: Full-cycle orchestrator chaining all five phases with gates and controls
 ---
 
-# LFG Skill
+# Cook It Skill
 
 ## Overview
-Chain all 5 phases end-to-end: Brainstorm, Plan, Work, Review, Compound. This skill governs the orchestration -- phase sequencing, gates, progress tracking, and error recovery.
+
+\`\`\`
+
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+ \u2502\u2592\u2592\u2592\u2592\u2592\u2502
+ \u2590\u259B\u2588\u2588\u2588\u259C\u258C o
+\u259D\u259C\u2588\u2588\u2588\u2588\u2588\u259B\u2598|
+  \u2598\u2598 \u259D\u259D
+Let's cook!
+\`\`\`
+
+Chain all 5 phases end-to-end: Spec Dev, Plan, Work, Review, Compound. This skill governs the orchestration -- phase sequencing, gates, progress tracking, and error recovery.
 
 ## CRITICAL RULE -- READ BEFORE EXECUTE
 Before starting EACH phase, you MUST use the Read tool to open its skill file:
-- .claude/skills/compound/brainstorm/SKILL.md
+- .claude/skills/compound/spec-dev/SKILL.md
 - .claude/skills/compound/plan/SKILL.md
 - .claude/skills/compound/work/SKILL.md
 - .claude/skills/compound/review/SKILL.md
@@ -6780,7 +6867,7 @@ If a gate fails, DO NOT proceed. Fix the issue first.
 - **Progress**: Always announce current phase number before starting.
 
 ## Stop Conditions
-- Brainstorm reveals goal is unclear -- stop, ask user
+- Spec dev reveals goal is unclear -- stop, ask user
 - Tests produce unresolvable failures -- stop, report
 - Review finds critical security issues -- stop, report
 
@@ -6881,6 +6968,103 @@ Apply the agreed changes:
 - Findings captured in compound-agent memory
 `
 };
+var PHASE_SKILL_REFERENCES = {
+  "spec-dev/references/spec-guide.md": `# Spec Dev Quick Reference
+
+## EARS Notation Patterns
+
+EARS (Easy Approach to Requirements Syntax) provides five sentence templates:
+
+| Pattern | Template | Example |
+|---------|----------|---------|
+| **Ubiquitous** | The system shall \`<action>\`. | The system shall validate all inputs. |
+| **Event-driven** | When \`<trigger>\`, the system shall \`<action>\`. | When the user submits the form, the system shall validate all fields. |
+| **State-driven** | While \`<state>\`, the system shall \`<action>\`. | While the system is in maintenance mode, the system shall reject new connections. |
+| **Unwanted behavior** | If \`<condition>\`, then the system shall \`<action>\`. | If the database connection fails, then the system shall retry with exponential backoff. |
+| **Optional** | Where \`<feature>\`, the system shall \`<action>\`. | Where SSO is enabled, the system shall redirect to the identity provider. |
+
+**Combined ordering**: Where > While > When > If/then > shall
+
+### Quality Checks for Each Requirement
+- [ ] Uses one of the five EARS patterns
+- [ ] No vague adjectives (fast, efficient, user-friendly, easy)
+- [ ] Quantities specified where applicable (timeouts, limits, thresholds)
+- [ ] Edge cases addressed (empty input, max values, concurrent access)
+- [ ] Testable \u2014 can write a pass/fail test against it
+- [ ] Single responsibility \u2014 one requirement per sentence
+
+---
+
+## Mermaid Diagram Selection Guide
+
+| Diagram Type | Use When | Syntax |
+|-------------|----------|--------|
+| \`mindmap\` | Exploring problem domain, brainstorming | Phase 1 (Explore) |
+| \`sequenceDiagram\` | Showing interactions between components | Phase 2 (Understand) |
+| \`stateDiagram-v2\` | Modeling lifecycle, state transitions | Phase 2 (Understand) |
+| \`flowchart\` | Showing decision logic, data flow | Phase 3 (Specify) |
+| \`erDiagram\` | Defining data models, relationships | Phase 3 (Specify) |
+| \`C4Context\` | System-level architecture boundaries | Phase 3 (Specify) |
+
+### When to Use Diagrams
+- **Always** use a mindmap in Explore to surface hidden assumptions
+- **Use sequence diagrams** when 2+ components interact
+- **Use state diagrams** when an entity has a lifecycle
+- **Skip diagrams** only for truly trivial features (<1h of work)
+
+---
+
+## NL Ambiguity Detection Checklist
+
+Watch for these ambiguity patterns in requirements:
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| **Vague adjectives** | "fast response" | Specify: "response within 200ms" |
+| **Unclear pronouns** | "it should update" | Name the subject: "the cache should update" |
+| **Passive voice** | "data is validated" | Active: "the API validates data" |
+| **Compound requirements** | "shall validate and log and notify" | Split into 3 separate requirements |
+| **Unbounded lists** | "supports CSV, JSON, etc." | Enumerate all formats explicitly |
+| **Missing quantities** | "handles large files" | Specify: "handles files up to 500MB" |
+| **Implicit assumptions** | "users can access" | Specify: "authenticated users with role X can access" |
+| **Temporal ambiguity** | "after processing" | Specify: "within 5s of processing completion" |
+
+---
+
+## Trade-off Documentation Framework
+
+When requirements conflict, document the trade-off:
+
+### Template
+\`\`\`
+### Trade-off: [Short Title]
+
+**Tension**: [Requirement A] conflicts with [Requirement B].
+
+**Options**:
+1. [Option 1]: [Description]. Pro: [benefit]. Con: [cost].
+2. [Option 2]: [Description]. Pro: [benefit]. Con: [cost].
+
+**Decision**: [Chosen option] because [rationale].
+
+**Consequence**: [What this means for implementation].
+\`\`\`
+
+### Common Trade-off Dimensions
+- **Performance vs. Safety**: Validation adds latency
+- **Flexibility vs. Simplicity**: Configuration adds complexity
+- **Consistency vs. Availability**: Strict consistency limits throughput
+- **Security vs. Usability**: Auth steps add friction
+- **Completeness vs. Time-to-market**: More features delay delivery
+
+### Decision Criteria
+When evaluating trade-offs, consider:
+1. **Reversibility**: Can we change this later? Prefer reversible decisions.
+2. **Blast radius**: How many components does this affect?
+3. **Evidence**: What data supports each option?
+4. **Alignment**: Which option best serves the stated goal?
+`
+};
 
 // src/setup/gemini.ts
 var HOOKS = {
@@ -6942,6 +7126,9 @@ function parseDescription(content, fallback) {
   const raw = content.match(/description:\s*(.*)/)?.[1] ?? fallback;
   return raw.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+function stripFrontmatter(content) {
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, "");
+}
 async function writeSettings(geminiDir) {
   const settingsPath = join(geminiDir, "settings.json");
   let settings = SETTINGS_JSON;
@@ -6979,24 +7166,26 @@ async function writeSkills(geminiDir) {
     const skillDir = join(geminiDir, "skills", `compound-${phase}`);
     await mkdir(skillDir, { recursive: true });
     const description = parseDescription(content, `Compound ${phase} skill`);
+    const body = stripFrontmatter(content);
     await writeFile(join(skillDir, "SKILL.md"), `---
 name: compound-${phase}
 description: ${description}
 ---
 
-${content}
+${body}
 `, "utf8");
   }
   for (const [name, content] of Object.entries(AGENT_ROLE_SKILLS)) {
     const skillDir = join(geminiDir, "skills", `compound-agent-${name}`);
     await mkdir(skillDir, { recursive: true });
     const description = parseDescription(content, `Compound agent ${name} skill`);
+    const body = stripFrontmatter(content);
     await writeFile(join(skillDir, "SKILL.md"), `---
 name: compound-agent-${name}
 description: ${description}
 ---
 
-${content}
+${body}
 `, "utf8");
   }
 }
@@ -7207,10 +7396,10 @@ function processToolSuccess(stateDir) {
 var STATE_DIR = ".claude";
 var STATE_FILE = ".ca-phase-state.json";
 var PHASE_STATE_MAX_AGE_MS = 72 * 60 * 60 * 1e3;
-var PHASES = ["brainstorm", "plan", "work", "review", "compound"];
+var PHASES = ["spec-dev", "plan", "work", "review", "compound"];
 var GATES = ["post-plan", "gate-3", "gate-4", "final"];
 var PHASE_INDEX = {
-  brainstorm: 1,
+  "spec-dev": 1,
   plan: 2,
   work: 3,
   review: 4,
@@ -7232,10 +7421,17 @@ function isIsoDate(value) {
 function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function migrateLegacyFields(raw) {
+  if (raw.cookit_active === void 0 && typeof raw.lfg_active === "boolean") {
+    raw.cookit_active = raw.lfg_active;
+    delete raw.lfg_active;
+  }
+}
 function validatePhaseState(raw) {
   if (typeof raw !== "object" || raw === null) return false;
   const state = raw;
-  return typeof state.lfg_active === "boolean" && typeof state.epic_id === "string" && isPhaseName(state.current_phase) && typeof state.phase_index === "number" && state.phase_index >= 1 && state.phase_index <= 5 && isStringArray(state.skills_read) && Array.isArray(state.gates_passed) && state.gates_passed.every((gate) => isGateName(gate)) && isIsoDate(state.started_at);
+  migrateLegacyFields(state);
+  return typeof state.cookit_active === "boolean" && typeof state.epic_id === "string" && isPhaseName(state.current_phase) && typeof state.phase_index === "number" && state.phase_index >= 1 && state.phase_index <= 5 && isStringArray(state.skills_read) && Array.isArray(state.gates_passed) && state.gates_passed.every((gate) => isGateName(gate)) && isIsoDate(state.started_at);
 }
 function expectedGateForPhase(phaseIndex) {
   if (phaseIndex === 2) return "post-plan";
@@ -7248,10 +7444,10 @@ function initPhaseState(repoRoot, epicId) {
   const dir = join(repoRoot, STATE_DIR);
   mkdirSync(dir, { recursive: true });
   const state = {
-    lfg_active: true,
+    cookit_active: true,
     epic_id: epicId,
-    current_phase: "brainstorm",
-    phase_index: PHASE_INDEX.brainstorm,
+    current_phase: "spec-dev",
+    phase_index: PHASE_INDEX["spec-dev"],
     skills_read: [],
     gates_passed: [],
     started_at: (/* @__PURE__ */ new Date()).toISOString()
@@ -7314,10 +7510,10 @@ function recordGatePassed(repoRoot, gate) {
 }
 function printStatusHuman(state) {
   if (state === null) {
-    console.log("No active LFG session.");
+    console.log("No active cook-it session.");
     return;
   }
-  console.log("Active LFG Session");
+  console.log("Active cook-it Session");
   console.log(`  Epic: ${state.epic_id}`);
   console.log(`  Phase: ${state.current_phase} (${state.phase_index}/5)`);
   console.log(`  Skills read: ${state.skills_read.length === 0 ? "(none)" : state.skills_read.join(", ")}`);
@@ -7336,7 +7532,7 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
       return;
     }
     initPhaseState(repoRoot(), epicId);
-    console.log(`Phase state initialized for ${epicId}. Current phase: brainstorm (1/5).`);
+    console.log(`Phase state initialized for ${epicId}. Current phase: spec-dev (1/5).`);
   });
   phaseCheck.command("start <phase>").description("Start or resume a phase").action((phase) => {
     if (!isPhaseName(phase)) {
@@ -7381,7 +7577,7 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
   phaseCheck.command("status").description("Show current phase state").option("--json", "Output raw JSON").action((options) => {
     const state = getPhaseState(repoRoot());
     if (options.json) {
-      console.log(JSON.stringify(state ?? { lfg_active: false }));
+      console.log(JSON.stringify(state ?? { cookit_active: false }));
       return;
     }
     printStatusHuman(state);
@@ -7396,7 +7592,7 @@ function registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot) {
   });
 }
 function registerPhaseCheckCommand(program2) {
-  const phaseCheck = program2.command("phase-check").description("Manage LFG phase state").option("--dry-run", "Show what would be done without making changes");
+  const phaseCheck = program2.command("phase-check").description("Manage cook-it phase state").option("--dry-run", "Show what would be done without making changes");
   const getDryRun = () => phaseCheck.opts().dryRun ?? false;
   const repoRoot = () => getRepoRoot();
   registerPhaseSubcommands(phaseCheck, getDryRun, repoRoot);
@@ -7411,14 +7607,14 @@ function processPhaseGuard(repoRoot, toolName, _toolInput) {
   try {
     if (toolName !== "Edit" && toolName !== "Write") return {};
     const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
+    if (state === null || !state.cookit_active) return {};
     const expectedSkillPath = `.claude/skills/compound/${state.current_phase}/SKILL.md`;
     const skillRead = state.skills_read.includes(expectedSkillPath);
     if (!skillRead) {
       return {
         hookSpecificOutput: {
           hookEventName: "PreToolUse",
-          additionalContext: `PHASE GUARD WARNING: You are in LFG phase ${state.phase_index}/5 (${state.current_phase}) but have NOT read the skill file yet. Read ${expectedSkillPath} before continuing.`
+          additionalContext: `PHASE GUARD WARNING: You are in cook-it phase ${state.phase_index}/5 (${state.current_phase}) but have NOT read the skill file yet. Read ${expectedSkillPath} before continuing.`
         }
       };
     }
@@ -7443,7 +7639,7 @@ function processReadTracker(repoRoot, toolName, toolInput) {
   try {
     if (toolName !== "Read") return {};
     const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
+    if (state === null || !state.cookit_active) return {};
     const filePath = typeof toolInput.file_path === "string" ? toolInput.file_path : null;
     if (filePath === null) return {};
     const canonicalPath = toCanonicalSkillPath(filePath);
@@ -7471,7 +7667,7 @@ function processStopAudit(repoRoot, stopHookActive = false) {
   try {
     if (stopHookActive) return {};
     const state = getPhaseState(repoRoot);
-    if (state === null || !state.lfg_active) return {};
+    if (state === null || !state.cookit_active) return {};
     const expectedGate = expectedGateForPhase(state.phase_index);
     if (expectedGate === null) return {};
     if (state.gates_passed.includes(expectedGate)) return {};
@@ -7486,6 +7682,12 @@ function processStopAudit(repoRoot, stopHookActive = false) {
 }
 
 // src/setup/hooks.ts
+function logHookError(hookName, err) {
+  if (process.env.CA_DEBUG) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[CA_DEBUG] Hook ${hookName} error: ${msg}`);
+  }
+}
 var HOOK_FILE_MODE = 493;
 function hasCompoundAgentHook(content) {
   return content.includes(HOOK_MARKER);
@@ -7621,7 +7823,8 @@ async function runUserPromptHook() {
     }
     const result = processUserPrompt(data.prompt);
     console.log(JSON.stringify(result));
-  } catch {
+  } catch (err) {
+    logHookError("user-prompt", err);
     console.log(JSON.stringify({}));
   }
 }
@@ -7636,7 +7839,8 @@ async function runPostToolFailureHook() {
     const stateDir = join(getRepoRoot(), ".claude");
     const result = processToolFailure(data.tool_name, data.tool_input ?? {}, stateDir);
     console.log(JSON.stringify(result));
-  } catch {
+  } catch (err) {
+    logHookError("post-tool-failure", err);
     console.log(JSON.stringify({}));
   }
 }
@@ -7646,7 +7850,8 @@ async function runPostToolSuccessHook() {
     const stateDir = join(getRepoRoot(), ".claude");
     processToolSuccess(stateDir);
     console.log(JSON.stringify({}));
-  } catch {
+  } catch (err) {
+    logHookError("post-tool-success", err);
     console.log(JSON.stringify({}));
   }
 }
@@ -7659,7 +7864,8 @@ async function runToolHook(processor) {
       return;
     }
     console.log(JSON.stringify(processor(getRepoRoot(), data.tool_name, data.tool_input ?? {})));
-  } catch {
+  } catch (err) {
+    logHookError("tool-hook", err);
     console.log(JSON.stringify({}));
   }
 }
@@ -7668,7 +7874,8 @@ async function runStopAuditHook() {
     const input = await readStdin();
     const data = JSON.parse(input);
     console.log(JSON.stringify(processStopAudit(getRepoRoot(), data.stop_hook_active ?? false)));
-  } catch {
+  } catch (err) {
+    logHookError("stop-audit", err);
     console.log(JSON.stringify({}));
   }
 }
@@ -7796,6 +8003,14 @@ async function installPhaseSkills(repoRoot) {
       created = true;
     }
   }
+  for (const [relPath, content] of Object.entries(PHASE_SKILL_REFERENCES)) {
+    const filePath = join(repoRoot, ".claude", "skills", "compound", relPath);
+    await mkdir(dirname(filePath), { recursive: true });
+    if (!existsSync(filePath)) {
+      await writeFile(filePath, content, "utf-8");
+      created = true;
+    }
+  }
   return created;
 }
 async function installAgentRoleSkills(repoRoot) {
@@ -8054,7 +8269,7 @@ async function runUninstall(repoRoot, dryRun) {
   return actions;
 }
 var GENERATED_HEADER = "<!-- generated by compound-agent -->\n";
-var DEPRECATED_COMMANDS = ["search.md", "list.md", "show.md", "stats.md", "wrong.md", "learn.md"];
+var DEPRECATED_COMMANDS = ["search.md", "list.md", "show.md", "stats.md", "wrong.md", "learn.md", "brainstorm.md", "lfg.md"];
 function detectExistingInstall(repoRoot) {
   return existsSync(join(repoRoot, ".claude", "lessons", "index.jsonl"));
 }
@@ -8129,7 +8344,7 @@ async function runUpgrade(repoRoot, dryRun = false) {
   const docVersionUpdated = await upgradeDocVersion(repoRoot, VERSION, dryRun);
   const parts = [];
   if (removedCommands.length > 0) {
-    parts.push(`Removed ${removedCommands.length} deprecated command(s)`);
+    parts.push(`Removed ${removedCommands.length} deprecated command(s): ${removedCommands.join(", ")}`);
   }
   if (strippedHeaders > 0) {
     parts.push(`Stripped headers from ${strippedHeaders} file(s)`);
@@ -8814,10 +9029,10 @@ init_storage();
 // src/commands/shared.ts
 init_utils();
 var out = {
-  success: (msg) => console.log(chalk4.green("[ok]"), msg),
-  error: (msg) => console.error(chalk4.red("[error]"), msg),
-  info: (msg) => console.log(chalk4.blue("[info]"), msg),
-  warn: (msg) => console.log(chalk4.yellow("[warn]"), msg)
+  success: (msg) => console.log(chalk5.green("[ok]"), msg),
+  error: (msg) => console.error(chalk5.red("[error]"), msg),
+  info: (msg) => console.log(chalk5.blue("[info]"), msg),
+  warn: (msg) => console.log(chalk5.yellow("[warn]"), msg)
 };
 function getGlobalOpts(cmd) {
   const opts = cmd.optsWithGlobals();
@@ -9470,15 +9685,15 @@ function formatLessonForPrime(lesson) {
   return `- **${lesson.insight}**${tags}
   Learned: ${date} via ${source}`;
 }
-function formatActiveLfgSection(repoRoot) {
+function formatActiveCookitSection(repoRoot) {
   const state = getPhaseState(repoRoot);
-  if (state === null || !state.lfg_active) return null;
+  if (state === null || !state.cookit_active) return null;
   const skillsRead = state.skills_read.length === 0 ? "(none)" : state.skills_read.join(", ");
   const gatesPassed = state.gates_passed.length === 0 ? "(none)" : state.gates_passed.join(", ");
   return `
 ---
 
-# ACTIVE LFG SESSION
+# ACTIVE COOK-IT SESSION
 
 Epic: ${state.epic_id}
 Phase: ${state.current_phase} (${state.phase_index}/5)
@@ -9510,9 +9725,9 @@ Critical lessons from past corrections:
 ${formattedLessons}
 `;
   }
-  const lfgSection = formatActiveLfgSection(root);
-  if (lfgSection !== null) {
-    output += lfgSection;
+  const cookitSection = formatActiveCookitSection(root);
+  if (cookitSection !== null) {
+    output += cookitSection;
   }
   return output;
 }
@@ -9553,13 +9768,13 @@ function registerAuditCommands(program2) {
         const line = formatFinding(finding);
         switch (finding.severity) {
           case "error":
-            console.log(chalk4.red(line));
+            console.log(chalk5.red(line));
             break;
           case "warning":
-            console.log(chalk4.yellow(line));
+            console.log(chalk5.yellow(line));
             break;
           default:
-            console.log(chalk4.blue(line));
+            console.log(chalk5.blue(line));
             break;
         }
       }
@@ -9701,13 +9916,13 @@ function registerRulesCommands(program2) {
         const line = formatViolation(result.rule, violation);
         switch (result.rule.severity) {
           case "error":
-            console.log(chalk4.red(line));
+            console.log(chalk5.red(line));
             break;
           case "warning":
-            console.log(chalk4.yellow(line));
+            console.log(chalk5.yellow(line));
             break;
           default:
-            console.log(chalk4.blue(line));
+            console.log(chalk5.blue(line));
             break;
         }
       }
@@ -9873,7 +10088,7 @@ async function runVerifyGates(epicId, options = {}) {
   const allPassed = checks.every((check) => check.status === "pass");
   if (allPassed) {
     const state = getPhaseState(repoRoot);
-    if (state !== null && state.lfg_active && state.gates_passed.includes("final")) {
+    if (state !== null && state.cookit_active && state.gates_passed.includes("final")) {
       cleanPhaseState(repoRoot);
     }
   }
@@ -9914,7 +10129,33 @@ function registerVerifyGatesCommand(program2) {
 }
 
 // src/changelog-data.ts
-var CHANGELOG_RECENT = `## [1.6.0] - 2026-03-02
+var CHANGELOG_RECENT = `## [1.6.1] - 2026-03-05
+
+### Changed
+
+- **Renamed brainstorm phase to spec-dev**: The \`/compound:brainstorm\` slash command is now \`/compound:spec-dev\`. The phase focuses on structured specification development using EARS notation, Mermaid diagrams, and Socratic dialogue rather than open-ended brainstorming. Old \`brainstorm.md\` command files are auto-cleaned during upgrade.
+- **Integration test stability**: Reduced integration test parallelism (\`maxForks: 1\`) and increased timeouts to 60s to eliminate non-deterministic ETIMEDOUT failures under load.
+
+### Added
+
+- **Spec reference file**: \`.claude/skills/compound/spec-dev/references/spec-guide.md\` provides quick-reference material for EARS patterns, Mermaid diagram selection, NL ambiguity detection, and trade-off documentation frameworks. Installed automatically during \`ca setup\`.
+- **Hook error visibility**: Hook runners now log errors to stderr when \`CA_DEBUG\` environment variable is set, instead of silently swallowing all failures.
+- **check-plan stdin safety**: \`ca check-plan\` now enforces a 30-second timeout and 1MB size limit when reading from stdin, preventing hangs in CI/CD environments.
+- **Embed lock expiry**: Embedding lock files now expire after 1 hour as a safety valve against zombie processes holding locks indefinitely.
+- **Phase-state backward compatibility**: Legacy \`lfg_active\` field in phase state files is automatically migrated to \`cookit_active\` on read.
+- **clean-lessons scope messaging**: \`ca clean-lessons\` now reports when non-lesson items are excluded from analysis.
+
+### Fixed
+
+- **Missing spec-guide.md**: The reference file was declared in skill templates and CHANGELOG but never generated during setup. Now installed alongside phase skills.
+- **Upgrade cleanup for lfg.md**: Added \`lfg.md\` to deprecated commands list so \`ca setup --update\` removes stale lfg command files from upgraded repos.
+- **Docs template terminology**: WORKFLOW.md template now uses "Spec Dev" instead of "Brainstorm" for Phase 1.
+- **Test file naming**: Renamed \`brainstorm-phase.test.ts\` to \`spec-dev-phase.test.ts\` to match the refactored phase name.
+- **Library bundle cleanup**: Moved CLI-only re-exports (\`registerWatchCommand\`, \`registerLoopCommands\`) out of the library barrel to eliminate unused import warnings in \`dist/index.js\`.
+- **plan.test.ts embedding guard**: Added \`skipIf(skipEmbedding)\` to unguarded test that calls \`retrieveForPlan\` without mocking.
+- **Agent template test count**: Updated setup.test.ts to expect 9 agent templates (was 8), matching the actual AGENT_TEMPLATES count after \`lessons-reviewer.md\` was added.
+
+## [1.6.0] - 2026-03-02
 
 ### Added
 
@@ -9991,42 +10232,7 @@ var CHANGELOG_RECENT = `## [1.6.0] - 2026-03-02
 - **Gemini phase guard always allowing**: Hook now checks \`ca hooks run phase-guard\` exit code and returns structured \`{"decision": "deny"}\` on failure (exit 0, not exit 2, so Gemini parses the reason from stdout)
 - **Gemini BeforeTool matcher incomplete**: Added \`create_file\` to BeforeTool and AfterTool matchers alongside \`replace\` and \`write_file\`
 - **TOML description escaping**: \`parseDescription\` now escapes \`\\\` and \`"\` to prevent malformed TOML output
-- **Flaky embedding test**: Added 15s timeout to \`isModelUsable\` test
-
-## [1.4.4] - 2026-02-23
-
-### Added
-
-- **Security arc with P0-P3 severity model**: Security-reviewer promoted from generic OWASP checker to mandatory core-4 reviewer with P0 (blocks merge), P1 (requires ack), P2 (should fix), P3 (nice to have) classification
-- **5 on-demand security specialist skills**: \`/security-injection\`, \`/security-secrets\`, \`/security-auth\`, \`/security-data\`, \`/security-deps\` -- spawned by security-reviewer via SendMessage within the review AgentTeam for deep trace analysis
-- **6 security reference docs** (\`docs/research/security/\`): overview, injection-patterns, secrets-checklist, auth-patterns, data-exposure, dependency-security -- distilled from the secure-coding-failure PhD survey into actionable agent guides
-- **Native addon build injection** (\`scripts/postinstall.mjs\`): Postinstall script auto-patches consumer \`package.json\` with \`pnpm.onlyBuiltDependencies\` config for \`better-sqlite3\` and \`node-llama-cpp\`. Handles indent preservation, BOM stripping, atomic writes
-- **CLI preflight diagnostics** (\`src/cli-preflight.ts\`): Catches native module load failures before commands run, prints PM-specific fix instructions (pnpm: 3 options; npm/yarn: rebuild + build tool hints)
-- **\`ca doctor\` pnpm check**: Verifies \`onlyBuiltDependencies\` is configured correctly for pnpm projects, recognizes wildcard \`["*"]\` as valid
-- **Escalation-wiring tests**: 7 new tests verifying security-reviewer mentions all 5 specialists, each specialist declares "Spawned by security-reviewer", P0 documented as merge-blocking, each specialist has \`npx ca knowledge\` and references correct research doc
-- **better-sqlite3 injection patterns**: Added project-specific \`db.exec()\` vs \`db.prepare().run()\` examples to \`injection-patterns.md\`
-
-### Fixed
-
-- **Noisy \`node-llama-cpp\` warnings on headless Linux**: Vulkan binary fallback and \`special_eos_id\` tokenizer warnings no longer print during \`ca search\` / \`ca knowledge\` -- GPU auto-detection preserved via \`progressLogs: false\` + \`logLevel: error\`
-- **Resource leak in \`isModelUsable()\`**: \`Llama\` and \`LlamaModel\` instances are now properly disposed after the preflight usability check
-- **Wildcard \`onlyBuiltDependencies\`**: Doctor and postinstall now recognize \`["*"]\` as fully configured (no false positive)
-- **Infinity loop marker injection**: \`--model\` validated against shell metacharacters; grep patterns anchored (\`^EPIC_COMPLETE\`, \`^EPIC_FAILED\`) to prevent false-positive matches from prompt echo in logs
-- **Template-to-deployed SKILL.md drift**: Backported all deployed specialist improvements (output fields, collaboration notes, \`npx ca knowledge\` lines) into source templates so \`ca setup --update\` no longer regresses
-- **SSRF citations**: 3 OWASP references in \`secure-coding-failure.md\` corrected from A01 (Broken Access Control) to A10 (SSRF)
-- **Stale verification docs**: Exit criteria updated from 6 to 8 categories (added Security Clear + Workflow Gates); closed-loop review process updated with security check in Stage 4 flowchart
-- **Broken dual-path reference** in \`subagent-pipeline.md\`: Now documents both \`docs/research/security/\` (source repo) and \`docs/compound/research/security/\` (consumer repos)
-- **Incomplete OWASP mapping** in \`overview.md\`: Completed from 5/10 to 10/10 (added A04, A05, A07, A08, A09)
-
-### Changed
-
-- **\`getLlama()\` initialization hardened**: Both call sites (\`nomic.ts\`, \`model.ts\`) now pass \`build: 'never'\` to prevent silent compilation from source on exotic platforms; set \`NODE_LLAMA_CPP_DEBUG=true\` to re-enable verbose output
-- **Review skill wired to security arc**: P0 added to severity overview, security specialist skills listed as on-demand members, quality criteria include P0/P1 checks
-- **WORKFLOW template**: Severity classification updated from P1/P2/P3 to P0-P3 with "Fix all P0/P1 findings"
-- **Zero-findings instruction**: All 6 security templates (reviewer + 5 specialists) now include "return CLEAR" instruction when no findings detected
-- **Scope-limiting instruction**: \`security-injection\` prioritizes files with interpreter sinks over pure data/config for large diffs (500+ lines)
-- **Non-web context**: \`security-auth\` includes step for CLI/API-only projects without web routes
-- **Graceful audit skip**: \`security-deps\` handles missing \`pnpm audit\` / \`pip-audit\` gracefully instead of failing`;
+- **Flaky embedding test**: Added 15s timeout to \`isModelUsable\` test`;
 
 // src/commands/about.ts
 function registerAboutCommand(program2) {
@@ -10214,6 +10420,9 @@ async function cleanLessonsAction() {
     await syncIfNeeded(repoRoot);
     const { items } = await readMemoryItems(repoRoot);
     const activeItems = items.filter((item) => !item.invalidatedAt && item.type === "lesson");
+    if (items.length > activeItems.length) {
+      console.log(`Analyzing ${activeItems.length} lesson-type items only (${items.length - activeItems.length} non-lesson items excluded).`);
+    }
     const pairs = await findDuplicatePairs(repoRoot, activeItems);
     if (pairs.length === 0) {
       console.log("No similar lessons found. Your lesson database is clean.");
@@ -10508,137 +10717,452 @@ function registerCaptureCommands(program2) {
     await handleCapture(this, options);
   });
 }
-var LOOP_EPIC_ID_PATTERN = /^[a-zA-Z0-9_.-]+$/;
-var MODEL_PATTERN = /^[a-zA-Z0-9_.:/-]+$/;
-function buildScriptHeader(timestamp, maxRetries, model, epicIds) {
-  return `#!/usr/bin/env bash
-# Infinity Loop - Generated by: ca loop
-# Date: ${timestamp}
-# Autonomously processes beads epics via Claude Code sessions.
-#
-# Usage:
-#   ./infinity-loop.sh
-#   LOOP_DRY_RUN=1 ./infinity-loop.sh  # Preview without executing
-
-set -euo pipefail
-
-# Config
-MAX_RETRIES=${maxRetries}
-MODEL="${model}"
-EPIC_IDS="${epicIds}"
-LOG_DIR="agent_logs"
-
-# Helpers
-timestamp() { date '+%Y-%m-%d_%H-%M-%S'; }
-log() { echo "[$(timestamp)] $*"; }
-die() { log "FATAL: $*"; exit 1; }
-
-command -v claude >/dev/null || die "claude CLI required"
-command -v bd >/dev/null || die "bd (beads) CLI required"
-
-# Detect JSON parser: prefer jq, fall back to python3
-HAS_JQ=false
-command -v jq >/dev/null 2>&1 && HAS_JQ=true
-if [ "$HAS_JQ" = false ]; then
-  command -v python3 >/dev/null 2>&1 || die "jq or python3 required for JSON parsing"
-fi
-
-# parse_json() - extract a value from JSON stdin
-# Uses jq (primary) with python3 fallback
-# Auto-unwraps single-element arrays (bd show --json returns [...])
-# Usage: echo '[{"status":"open"}]' | parse_json '.status'
-parse_json() {
-  local filter="$1"
-  if [ "$HAS_JQ" = true ]; then
-    jq -r "if type == \\"array\\" then .[0] else . end | $filter"
-  else
-    python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-if isinstance(data, list):
-    data = data[0] if data else {}
-f = '$filter'.strip('.')
-parts = [p for p in f.split('.') if p]
-v = data
-try:
-    for p in parts:
-        v = v[p]
-except (KeyError, IndexError, TypeError):
-    v = None
-print('' if v is None else v)
-"
-  fi
+init_storage();
+init_search2();
+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`));
+    return null;
+  }
 }
-
-mkdir -p "$LOG_DIR"
-` + buildEpicSelector() + buildPromptFunction();
+var MAX_STDIN_BYTES = 1048576;
+var STDIN_TIMEOUT_MS = 3e4;
+async function readPlanFromStdin() {
+  const { stdin } = await import('process');
+  if (!stdin.isTTY) {
+    const chunks = [];
+    let totalBytes = 0;
+    const timeout = new Promise(
+      (_, reject) => setTimeout(() => reject(new Error("stdin read timed out after 30s")), STDIN_TIMEOUT_MS)
+    );
+    const read = (async () => {
+      for await (const chunk of stdin) {
+        const buf = chunk;
+        totalBytes += buf.length;
+        if (totalBytes > MAX_STDIN_BYTES) {
+          throw new Error(`stdin exceeds ${MAX_STDIN_BYTES} byte limit`);
+        }
+        chunks.push(buf);
+      }
+      return Buffer.concat(chunks).toString("utf-8").trim();
+    })();
+    try {
+      return await Promise.race([read, timeout]);
+    } catch (err) {
+      console.error(`Warning: ${err instanceof Error ? err.message : String(err)}`);
+      return void 0;
+    }
+  }
+  return void 0;
 }
-function buildEpicSelector() {
-  return `
-get_next_epic() {
-  if [ -n "$EPIC_IDS" ]; then
-    # From explicit list, find first still-open epic not yet processed
-    for epic_id in $EPIC_IDS; do
-      case " $PROCESSED " in *" $epic_id "*) continue ;; esac
-      local status
-      status=$(bd show "$epic_id" --json 2>/dev/null | parse_json '.status' 2>/dev/null || echo "")
-      if [ "$status" = "open" ]; then
-        echo "$epic_id"
-        return 0
-      fi
-    done
-    return 1
-  else
-    # Dynamic: get next ready epic from dependency graph, filtering processed
-    local epic_id
-    if [ "$HAS_JQ" = true ]; then
-      epic_id=$(bd list --type=epic --ready --json --limit=10 2>/dev/null | jq -r '.[].id' 2>/dev/null | while read -r id; do
-        case " $PROCESSED " in *" $id "*) continue ;; esac
-        echo "$id"
-        break
-      done)
-    else
-      epic_id=$(bd list --type=epic --ready --json --limit=10 2>/dev/null | python3 -c "
-import sys, json
-processed = set('$PROCESSED'.split())
-items = json.load(sys.stdin)
-for item in items:
-    if item['id'] not in processed:
-        print(item['id'])
-        break" 2>/dev/null || echo "")
-    fi
-    if [ -z "$epic_id" ]; then
-      return 1
-    fi
-    echo "$epic_id"
-    return 0
-  fi
+function outputCheckPlanJson(lessons) {
+  const jsonOutput = {
+    lessons: lessons.map((l) => ({
+      id: l.lesson.id,
+      insight: l.lesson.insight,
+      rankScore: l.finalScore ?? l.score,
+      // Use finalScore if available, fallback to raw score
+      source: l.lesson.source
+    })),
+    count: lessons.length
+  };
+  console.log(JSON.stringify(jsonOutput));
 }
-`;
+function outputCheckPlanHuman(lessons, quiet) {
+  console.log("## Lessons Check\n");
+  console.log("Relevant to your plan:\n");
+  lessons.forEach((item, i) => {
+    const num = i + 1;
+    console.log(`${num}. ${chalk5.bold(`[${item.lesson.id}]`)} ${item.lesson.insight}`);
+    console.log(`   - Source: ${item.lesson.source}`);
+    console.log();
+  });
+  if (!quiet) {
+    console.log("---");
+    console.log("Consider these lessons while implementing.");
+  }
 }
-function buildPromptFunction() {
-  return `
-build_prompt() {
-  local epic_id="$1"
-  cat <<'PROMPT_HEADER'
-You are running in an autonomous infinity loop. Your task is to fully implement a beads epic.
-
-## Step 1: Load context
-Run these commands to prime your session:
-PROMPT_HEADER
-  cat <<PROMPT_BODY
-\\\`\\\`\\\`bash
-npx ca load-session
-bd show $epic_id
+function formatSource2(source) {
+  return source.replace(/_/g, " ");
+}
+function outputSessionLessonsHuman(lessons, quiet) {
+  console.log("## Lessons from Past Sessions\n");
+  console.log("These lessons were captured from previous corrections and should inform your work:\n");
+  lessons.forEach((lesson, i) => {
+    const num = i + 1;
+    const date = lesson.created.slice(0, ISO_DATE_PREFIX_LENGTH);
+    const tagsDisplay = lesson.tags.length > 0 ? ` (${lesson.tags.join(", ")})` : "";
+    console.log(`${num}. **${lesson.insight}**${tagsDisplay}`);
+    console.log(`   Learned: ${date} via ${formatSource2(lesson.source)}`);
+    console.log();
+  });
+  if (!quiet) {
+    console.log("Consider these lessons when planning and implementing tasks.");
+  }
+}
+async function searchAction(cmd, query, options) {
+  const repoRoot = getRepoRoot();
+  const limit = parseLimitOrNull(options.limit, "limit", "search");
+  if (limit === null) {
+    process.exitCode = 1;
+    return;
+  }
+  const { verbose, quiet } = getGlobalOpts(cmd);
+  await syncIfNeeded(repoRoot);
+  let results;
+  if (isModelAvailable()) {
+    try {
+      const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+      const [vectorResults, keywordResults] = await Promise.all([
+        searchVector(repoRoot, query, { limit: candidateLimit }),
+        searchKeywordScored(repoRoot, query, candidateLimit)
+      ]);
+      const merged = mergeHybridResults(vectorResults, keywordResults, { minScore: MIN_HYBRID_SCORE });
+      const ranked = rankLessons(merged);
+      results = ranked.slice(0, limit).map((r) => r.lesson);
+    } catch {
+      results = await searchKeyword(repoRoot, query, limit);
+    }
+  } else {
+    results = await searchKeyword(repoRoot, query, limit);
+  }
+  if (results.length > 0) {
+    incrementRetrievalCount(repoRoot, results.map((lesson) => lesson.id));
+  }
+  if (results.length === 0) {
+    console.log('No lessons match your search. Try a different query or use "list" to see all lessons.');
+    return;
+  }
+  if (!quiet) {
+    out.info(`Found ${results.length} lesson(s):
+`);
+  }
+  for (const lesson of results) {
+    console.log(`[${chalk5.cyan(lesson.id)}] ${lesson.insight}`);
+    console.log(`  Trigger: ${lesson.trigger}`);
+    if (verbose && lesson.context) {
+      console.log(`  Context: ${lesson.context.tool} - ${lesson.context.intent}`);
+      console.log(`  Created: ${lesson.created}`);
+    }
+    if (lesson.tags.length > 0) {
+      console.log(`  Tags: ${lesson.tags.join(", ")}`);
+    }
+    console.log();
+  }
+}
+async function listAction(cmd, options) {
+  const repoRoot = getRepoRoot();
+  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;
+  if (filteredItems.length === 0) {
+    if (options.invalidated) {
+      console.log("No invalidated lessons found.");
+    } else {
+      console.log('No lessons found. Get started with: learn "Your first lesson"');
+    }
+    if (skippedCount > 0) {
+      out.warn(`${skippedCount} corrupted lesson(s) skipped.`);
+    }
+    return;
+  }
+  const toShow = filteredItems.slice(0, limit);
+  if (!quiet) {
+    const label = options.invalidated ? "invalidated lesson(s)" : "item(s)";
+    out.info(`Showing ${toShow.length} of ${filteredItems.length} ${label}:
+`);
+  }
+  for (const item of toShow) {
+    const invalidMarker = item.invalidatedAt ? chalk5.red("[INVALID] ") : "";
+    console.log(`[${chalk5.cyan(item.id)}] ${invalidMarker}${item.insight}`);
+    if (verbose) {
+      console.log(`  Type: ${item.type} | Source: ${item.source}`);
+      console.log(`  Created: ${item.created}`);
+      if (item.context) {
+        console.log(`  Context: ${item.context.tool} - ${item.context.intent}`);
+      }
+      if (item.invalidatedAt) {
+        console.log(`  Invalidated: ${item.invalidatedAt}`);
+        if (item.invalidationReason) {
+          console.log(`  Reason: ${item.invalidationReason}`);
+        }
+      }
+    } else {
+      console.log(`  Type: ${item.type} | Source: ${item.source}`);
+    }
+    if (item.tags.length > 0) {
+      console.log(`  Tags: ${item.tags.join(", ")}`);
+    }
+    console.log();
+  }
+  if (skippedCount > 0) {
+    out.warn(`${skippedCount} corrupted lesson(s) skipped.`);
+  }
+}
+async function loadSessionAction(cmd, options) {
+  const repoRoot = getRepoRoot();
+  const { quiet } = getGlobalOpts(cmd);
+  const lessons = await loadSessionLessons(repoRoot);
+  const { lessons: allLessons } = await readLessons(repoRoot);
+  const totalCount = allLessons.length;
+  if (options.json) {
+    console.log(JSON.stringify({ lessons, count: lessons.length, totalCount }));
+    return;
+  }
+  if (lessons.length === 0) {
+    console.log("No high-severity lessons found.");
+    return;
+  }
+  outputSessionLessonsHuman(lessons, quiet);
+  if (totalCount > LESSON_COUNT_WARNING_THRESHOLD) {
+    console.log("");
+    out.info(`${totalCount} lessons in index. Consider \`ca compact\` to reduce context pollution.`);
+  }
+  const oldLessons = lessons.filter((l) => getLessonAgeDays(l) > AGE_FLAG_THRESHOLD_DAYS);
+  if (oldLessons.length > 0) {
+    console.log("");
+    out.warn(`${oldLessons.length} lesson(s) are over ${AGE_FLAG_THRESHOLD_DAYS} days old. Review for continued validity.`);
+  }
+}
+async function checkPlanAction(cmd, options) {
+  const repoRoot = getRepoRoot();
+  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.exitCode = 1;
+    return;
+  }
+  await syncIfNeeded(repoRoot);
+  if (!isModelAvailable()) {
+    if (options.json) {
+      console.log(JSON.stringify({
+        lessons: [],
+        count: 0,
+        error: "Embedding model not found",
+        action: "Run: npx ca download-model"
+      }));
+    } else {
+      console.error(formatError("check-plan", "MODEL_UNAVAILABLE", "Embedding model not found", "Run: npx ca download-model"));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const result = await retrieveForPlan(repoRoot, planText, limit);
+    if (options.json) {
+      outputCheckPlanJson(result.lessons);
+      return;
+    }
+    if (result.lessons.length === 0) {
+      console.log("No relevant lessons found for this plan.");
+      return;
+    }
+    outputCheckPlanHuman(result.lessons, quiet);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error";
+    if (options.json) {
+      console.log(JSON.stringify({
+        lessons: [],
+        count: 0,
+        error: message
+      }));
+    } else {
+      console.error(formatError("check-plan", "PLAN_CHECK_FAILED", message, "Check model installation and try again"));
+    }
+    process.exitCode = 1;
+  }
+}
+function registerRetrievalCommands(program2) {
+  program2.command("search <query>").description("Search lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_SEARCH_LIMIT).action(async function(query, options) {
+    await searchAction(this, query, options);
+  });
+  program2.command("list").description("List all lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_LIST_LIMIT).option("--invalidated", "Show only invalidated lessons").action(async function(options) {
+    await listAction(this, options);
+  });
+  program2.command("load-session").description("Load high-severity lessons for session context").option("--json", "Output as JSON").action(async function(options) {
+    await loadSessionAction(this, options);
+  });
+  program2.command("check-plan").description("Check plan against relevant lessons").option("--plan <text>", "Plan text to check").option("--json", "Output as JSON").option("-n, --limit <number>", "Maximum results", DEFAULT_CHECK_PLAN_LIMIT).action(async function(options) {
+    await checkPlanAction(this, options);
+  });
+}
+
+// src/commands/index.ts
+function registerSetupCommands(program2) {
+  registerInitCommand(program2);
+  registerHooksCommand(program2);
+  const setupCommand = program2.command("setup");
+  registerSetupAllCommand(setupCommand);
+  registerClaudeSubcommand(setupCommand);
+  registerGeminiSubcommand(setupCommand);
+  registerDownloadModelCommand(program2);
+}
+function registerManagementCommands(program2) {
+  registerInvalidationCommands(program2);
+  registerMaintenanceCommands(program2);
+  registerIOCommands(program2);
+  registerPrimeCommand(program2);
+  registerCrudCommands(program2);
+  registerAuditCommands(program2);
+  registerDoctorCommand(program2);
+  registerReviewerCommand(program2);
+  registerRulesCommands(program2);
+  registerTestSummaryCommand(program2);
+  registerVerifyGatesCommand(program2);
+  registerAboutCommand(program2);
+  registerKnowledgeCommand(program2);
+  registerKnowledgeIndexCommand(program2);
+  registerCleanLessonsCommand(program2);
+  program2.command("worktree").description("(removed) Use Claude Code native worktree support").action(() => {
+    console.error("ca worktree has been removed. Use Claude Code's native EnterWorktree support instead.");
+    process.exitCode = 1;
+  });
+}
+var LOOP_EPIC_ID_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+var MODEL_PATTERN = /^[a-zA-Z0-9_.:/-]+$/;
+function buildScriptHeader(timestamp, maxRetries, model, epicIds) {
+  return `#!/usr/bin/env bash
+# Infinity Loop - Generated by: ca loop
+# Date: ${timestamp}
+# Autonomously processes beads epics via Claude Code sessions.
+#
+# Usage:
+#   ./infinity-loop.sh
+#   LOOP_DRY_RUN=1 ./infinity-loop.sh  # Preview without executing
+
+set -euo pipefail
+
+# Config
+MAX_RETRIES=${maxRetries}
+MODEL="${model}"
+EPIC_IDS="${epicIds}"
+LOG_DIR="agent_logs"
+
+# Helpers
+timestamp() { date '+%Y-%m-%d_%H-%M-%S'; }
+log() { echo "[$(timestamp)] $*"; }
+die() { log "FATAL: $*"; exit 1; }
+
+command -v claude >/dev/null || die "claude CLI required"
+command -v bd >/dev/null || die "bd (beads) CLI required"
+
+# Detect JSON parser: prefer jq, fall back to python3
+HAS_JQ=false
+command -v jq >/dev/null 2>&1 && HAS_JQ=true
+if [ "$HAS_JQ" = false ]; then
+  command -v python3 >/dev/null 2>&1 || die "jq or python3 required for JSON parsing"
+fi
+
+# parse_json() - extract a value from JSON stdin
+# Uses jq (primary) with python3 fallback
+# Auto-unwraps single-element arrays (bd show --json returns [...])
+# Usage: echo '[{"status":"open"}]' | parse_json '.status'
+parse_json() {
+  local filter="$1"
+  if [ "$HAS_JQ" = true ]; then
+    jq -r "if type == \\"array\\" then .[0] else . end | $filter"
+  else
+    python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+if isinstance(data, list):
+    data = data[0] if data else {}
+f = '$filter'.strip('.')
+parts = [p for p in f.split('.') if p]
+v = data
+try:
+    for p in parts:
+        v = v[p]
+except (KeyError, IndexError, TypeError):
+    v = None
+print('' if v is None else v)
+"
+  fi
+}
+
+mkdir -p "$LOG_DIR"
+` + buildEpicSelector() + buildPromptFunction();
+}
+function buildEpicSelector() {
+  return `
+get_next_epic() {
+  if [ -n "$EPIC_IDS" ]; then
+    # From explicit list, find first still-open epic not yet processed
+    for epic_id in $EPIC_IDS; do
+      case " $PROCESSED " in *" $epic_id "*) continue ;; esac
+      local status
+      status=$(bd show "$epic_id" --json 2>/dev/null | parse_json '.status' 2>/dev/null || echo "")
+      if [ "$status" = "open" ]; then
+        echo "$epic_id"
+        return 0
+      fi
+    done
+    return 1
+  else
+    # Dynamic: get next ready epic from dependency graph, filtering processed
+    local epic_id
+    if [ "$HAS_JQ" = true ]; then
+      epic_id=$(bd list --type=epic --ready --json --limit=10 2>/dev/null | jq -r '.[].id' 2>/dev/null | while read -r id; do
+        case " $PROCESSED " in *" $id "*) continue ;; esac
+        echo "$id"
+        break
+      done)
+    else
+      epic_id=$(bd list --type=epic --ready --json --limit=10 2>/dev/null | python3 -c "
+import sys, json
+processed = set('$PROCESSED'.split())
+items = json.load(sys.stdin)
+for item in items:
+    if item['id'] not in processed:
+        print(item['id'])
+        break" 2>/dev/null || echo "")
+    fi
+    if [ -z "$epic_id" ]; then
+      return 1
+    fi
+    echo "$epic_id"
+    return 0
+  fi
+}
+`;
+}
+function buildPromptFunction() {
+  return `
+build_prompt() {
+  local epic_id="$1"
+  cat <<'PROMPT_HEADER'
+You are running in an autonomous infinity loop. Your task is to fully implement a beads epic.
+
+## Step 1: Load context
+Run these commands to prime your session:
+PROMPT_HEADER
+  cat <<PROMPT_BODY
+\\\`\\\`\\\`bash
+npx ca load-session
+bd show $epic_id
 \\\`\\\`\\\`
 
 Read the epic details carefully. Understand scope, acceptance criteria, and sub-tasks.
 
 ## Step 2: Execute the workflow
 Run the full compound workflow for this epic, starting from the plan phase
-(brainstorm is already done -- the epic exists):
+(spec-dev is already done -- the epic exists):
 
-/compound:lfg from plan -- Epic: $epic_id
+/compound:cook-it from plan -- Epic: $epic_id
 
 Work through all phases: plan, work, review, compound.
 
@@ -10788,540 +11312,244 @@ while true; do
   else
     FAILED=$((FAILED + 1))
     log "Epic $EPIC_ID failed after $((MAX_RETRIES + 1)) attempts. Stopping loop."
-    PROCESSED="$PROCESSED $EPIC_ID"
-    break
-  fi
-
-  PROCESSED="$PROCESSED $EPIC_ID"
-done
-
-log "Loop finished. Completed: $COMPLETED, Failed: $FAILED, Skipped: $SKIPPED"
-[ $FAILED -eq 0 ] && exit 0 || exit 1`;
-}
-function validateOptions(options) {
-  if (!Number.isInteger(options.maxRetries) || options.maxRetries < 0) {
-    throw new Error(`Invalid maxRetries: must be a non-negative integer, got ${options.maxRetries}`);
-  }
-  if (!MODEL_PATTERN.test(options.model)) {
-    throw new Error(`Invalid model "${options.model}": must match ${MODEL_PATTERN}`);
-  }
-  if (options.epics) {
-    for (const id of options.epics) {
-      if (!LOOP_EPIC_ID_PATTERN.test(id)) {
-        throw new Error(`Invalid epic ID "${id}": must match ${LOOP_EPIC_ID_PATTERN}`);
-      }
-    }
-  }
-}
-function generateLoopScript(options) {
-  validateOptions(options);
-  const epicIds = options.epics?.join(" ") ?? "";
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  return buildScriptHeader(timestamp, options.maxRetries, options.model, epicIds) + buildStreamExtractor() + buildMainLoop();
-}
-async function handleLoop(cmd, options) {
-  const outputPath = resolve(options.output ?? "./infinity-loop.sh");
-  if (existsSync(outputPath) && !options.force) {
-    out.error(`File already exists: ${outputPath}`);
-    out.info("Use --force to overwrite");
-    process.exitCode = 1;
-    return;
-  }
-  const maxRetries = Number(options.maxRetries ?? 1);
-  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
-    out.error(`Invalid --max-retries: must be a non-negative integer, got "${options.maxRetries}"`);
-    process.exitCode = 1;
-    return;
-  }
-  let script;
-  try {
-    script = generateLoopScript({
-      epics: options.epics,
-      maxRetries,
-      model: options.model ?? "claude-opus-4-6"
-    });
-  } catch (err) {
-    out.error(err.message);
-    process.exitCode = 1;
-    return;
-  }
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, script, "utf-8");
-  await chmod(outputPath, 493);
-  out.success(`Generated infinity loop script: ${outputPath}`);
-  out.info("Run it with: " + outputPath);
-  out.info("Preview with: LOOP_DRY_RUN=1 " + outputPath);
-}
-function registerLoopCommands(program2) {
-  program2.command("loop").description("Generate infinity loop script for epic tasks").option("--epics <ids...>", "Specific epic IDs to process").option("-o, --output <path>", "Output script path", "./infinity-loop.sh").option("--max-retries <n>", "Max retries per epic on failure", "1").option("--model <model>", "Claude model to use", "claude-opus-4-6").option("--force", "Overwrite existing script").action(async function(options) {
-    await handleLoop(this, options);
-  });
-}
-var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_.-]+$/;
-function formatTime(timestamp) {
-  if (!timestamp) {
-    const now = /* @__PURE__ */ new Date();
-    return now.toTimeString().slice(0, 8);
-  }
-  try {
-    return new Date(timestamp).toTimeString().slice(0, 8);
-  } catch {
-    return (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
-  }
-}
-function formatNumber(n) {
-  return n.toLocaleString();
-}
-function formatStreamEvent(event) {
-  const time = chalk4.dim(formatTime(event.timestamp));
-  switch (event.type) {
-    case "content_block_start": {
-      if (event.content_block?.type === "tool_use") {
-        const name = event.content_block.name ?? "unknown";
-        return `${time} ${chalk4.cyan("TOOL")}    ${name}`;
-      }
-      if (event.content_block?.type === "thinking") {
-        return `${time} ${chalk4.magenta("THINK")}   thinking...`;
-      }
-      return null;
-    }
-    case "content_block_delta": {
-      if (event.delta?.type === "text_delta") {
-        const text = event.delta.text ?? "";
-        const truncated = text.length > 60 ? text.slice(0, 57) + "..." : text;
-        return `${time} ${chalk4.blue("TEXT")}    ${truncated.replace(/\n/g, " ")}`;
-      }
-      return null;
-    }
-    case "message_delta": {
-      const usage = event.usage;
-      if (usage?.output_tokens) {
-        return `${time} ${chalk4.dim("TOKENS")}  ${formatNumber(usage.output_tokens)} out (final)`;
-      }
-      return null;
-    }
-    case "message_start": {
-      if (event.message?.usage) {
-        const { input_tokens, output_tokens } = event.message.usage;
-        const inTok = input_tokens ? formatNumber(input_tokens) : "?";
-        const outTok = output_tokens ? formatNumber(output_tokens) : "?";
-        return `${time} ${chalk4.dim("TOKENS")}  ${inTok} in / ${outTok} out`;
-      }
-      return null;
-    }
-    case "result": {
-      const text = typeof event.result === "string" ? event.result : "";
-      const markers = ["EPIC_COMPLETE", "EPIC_FAILED", "HUMAN_REQUIRED"];
-      const found = markers.find((m) => text.includes(m));
-      if (found) {
-        const markerLine = text.split("\n").find((l) => l.includes(found)) ?? found;
-        const display = markerLine.length > 120 ? markerLine.slice(0, 117) + "..." : markerLine;
-        return `${time} ${chalk4.yellow.bold("MARKER")}  ${display}`;
-      }
-      return null;
-    }
-    default:
-      return null;
-  }
-}
-function findLatestTraceFile(logDir) {
-  if (!existsSync(logDir)) return null;
-  const latestPath = join(logDir, ".latest");
-  if (existsSync(latestPath)) {
-    try {
-      const target = readlinkSync(latestPath);
-      const resolved = resolve(logDir, target);
-      if (existsSync(resolved)) return resolved;
-    } catch {
-    }
-  }
-  try {
-    const files = readdirSync(logDir).filter((f) => f.startsWith("trace_") && f.endsWith(".jsonl")).sort().reverse();
-    const first = files[0];
-    if (first) return join(logDir, first);
-  } catch {
-  }
-  return null;
-}
-function processLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) return;
-  try {
-    const event = JSON.parse(trimmed);
-    const formatted = formatStreamEvent(event);
-    if (formatted) {
-      console.log(formatted);
-    }
-  } catch {
-  }
+    PROCESSED="$PROCESSED $EPIC_ID"
+    break
+  fi
+
+  PROCESSED="$PROCESSED $EPIC_ID"
+done
+
+log "Loop finished. Completed: $COMPLETED, Failed: $FAILED, Skipped: $SKIPPED"
+[ $FAILED -eq 0 ] && exit 0 || exit 1`;
 }
-async function tailFile(filePath, follow) {
-  if (follow) {
-    const child = spawn("tail", ["-f", "-n", "+1", filePath], { stdio: ["ignore", "pipe", "ignore"] });
-    const rl2 = createInterface({ input: child.stdout });
-    rl2.on("line", processLine);
-    const cleanup2 = () => {
-      child.kill("SIGTERM");
-    };
-    process.on("SIGINT", cleanup2);
-    process.on("SIGTERM", cleanup2);
-    return new Promise((done) => {
-      child.on("close", () => {
-        process.off("SIGINT", cleanup2);
-        process.off("SIGTERM", cleanup2);
-        done();
-      });
-    });
-  }
-  const stream = createReadStream(filePath, { encoding: "utf-8" });
-  const rl = createInterface({ input: stream });
-  try {
-    for await (const line of rl) {
-      processLine(line);
-    }
-  } finally {
-    rl.close();
-    stream.destroy();
+function validateOptions(options) {
+  if (!Number.isInteger(options.maxRetries) || options.maxRetries < 0) {
+    throw new Error(`Invalid maxRetries: must be a non-negative integer, got ${options.maxRetries}`);
   }
-}
-async function handleWatch(cmd, options) {
-  let logDir;
-  try {
-    logDir = join(getRepoRoot(), "agent_logs");
-  } catch {
-    logDir = resolve("agent_logs");
+  if (!MODEL_PATTERN.test(options.model)) {
+    throw new Error(`Invalid model "${options.model}": must match ${MODEL_PATTERN}`);
   }
-  const follow = options.follow !== false;
-  let traceFile = null;
-  if (options.epic) {
-    if (!EPIC_ID_PATTERN2.test(options.epic)) {
-      out.error(`Invalid epic ID: ${options.epic}`);
-      process.exitCode = 1;
-      return;
-    }
-    if (existsSync(logDir)) {
-      try {
-        const files = readdirSync(logDir).filter((f) => f.startsWith(`trace_${options.epic}`) && f.endsWith(".jsonl")).sort().reverse();
-        const first = files[0];
-        if (first) traceFile = join(logDir, first);
-      } catch {
+  if (options.epics) {
+    for (const id of options.epics) {
+      if (!LOOP_EPIC_ID_PATTERN.test(id)) {
+        throw new Error(`Invalid epic ID "${id}": must match ${LOOP_EPIC_ID_PATTERN}`);
       }
     }
-    if (!traceFile) {
-      out.error(`No trace file found for epic: ${options.epic}`);
-      process.exitCode = 1;
-      return;
-    }
-  } else {
-    traceFile = findLatestTraceFile(logDir);
-    if (!traceFile) {
-      out.info("No active trace found. Run `ca loop` to generate a loop script first.");
-      process.exitCode = 0;
-      return;
-    }
-  }
-  out.info(`Watching: ${traceFile}`);
-  await tailFile(traceFile, follow);
-}
-function registerWatchCommand(program2) {
-  program2.command("watch").description("Tail and pretty-print live trace from infinity loop sessions").option("--epic <id>", "Watch a specific epic trace").option("--no-follow", "Print existing trace and exit (no live tail)").action(async function(options) {
-    await handleWatch(this, options);
-  });
-}
-init_storage();
-init_search2();
-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`));
-    return null;
-  }
-}
-async function readPlanFromStdin() {
-  const { stdin } = await import('process');
-  if (!stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of stdin) {
-      chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString("utf-8").trim();
-  }
-  return void 0;
-}
-function outputCheckPlanJson(lessons) {
-  const jsonOutput = {
-    lessons: lessons.map((l) => ({
-      id: l.lesson.id,
-      insight: l.lesson.insight,
-      rankScore: l.finalScore ?? l.score,
-      // Use finalScore if available, fallback to raw score
-      source: l.lesson.source
-    })),
-    count: lessons.length
-  };
-  console.log(JSON.stringify(jsonOutput));
-}
-function outputCheckPlanHuman(lessons, quiet) {
-  console.log("## Lessons Check\n");
-  console.log("Relevant to your plan:\n");
-  lessons.forEach((item, i) => {
-    const num = i + 1;
-    console.log(`${num}. ${chalk4.bold(`[${item.lesson.id}]`)} ${item.lesson.insight}`);
-    console.log(`   - Source: ${item.lesson.source}`);
-    console.log();
-  });
-  if (!quiet) {
-    console.log("---");
-    console.log("Consider these lessons while implementing.");
   }
 }
-function formatSource2(source) {
-  return source.replace(/_/g, " ");
-}
-function outputSessionLessonsHuman(lessons, quiet) {
-  console.log("## Lessons from Past Sessions\n");
-  console.log("These lessons were captured from previous corrections and should inform your work:\n");
-  lessons.forEach((lesson, i) => {
-    const num = i + 1;
-    const date = lesson.created.slice(0, ISO_DATE_PREFIX_LENGTH);
-    const tagsDisplay = lesson.tags.length > 0 ? ` (${lesson.tags.join(", ")})` : "";
-    console.log(`${num}. **${lesson.insight}**${tagsDisplay}`);
-    console.log(`   Learned: ${date} via ${formatSource2(lesson.source)}`);
-    console.log();
-  });
-  if (!quiet) {
-    console.log("Consider these lessons when planning and implementing tasks.");
-  }
+function generateLoopScript(options) {
+  validateOptions(options);
+  const epicIds = options.epics?.join(" ") ?? "";
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  return buildScriptHeader(timestamp, options.maxRetries, options.model, epicIds) + buildStreamExtractor() + buildMainLoop();
 }
-async function searchAction(cmd, query, options) {
-  const repoRoot = getRepoRoot();
-  const limit = parseLimitOrNull(options.limit, "limit", "search");
-  if (limit === null) {
+async function handleLoop(cmd, options) {
+  const outputPath = resolve(options.output ?? "./infinity-loop.sh");
+  if (existsSync(outputPath) && !options.force) {
+    out.error(`File already exists: ${outputPath}`);
+    out.info("Use --force to overwrite");
     process.exitCode = 1;
     return;
   }
-  const { verbose, quiet } = getGlobalOpts(cmd);
-  await syncIfNeeded(repoRoot);
-  let results;
-  if (isModelAvailable()) {
-    try {
-      const candidateLimit = limit * CANDIDATE_MULTIPLIER;
-      const [vectorResults, keywordResults] = await Promise.all([
-        searchVector(repoRoot, query, { limit: candidateLimit }),
-        searchKeywordScored(repoRoot, query, candidateLimit)
-      ]);
-      const merged = mergeHybridResults(vectorResults, keywordResults, { minScore: MIN_HYBRID_SCORE });
-      const ranked = rankLessons(merged);
-      results = ranked.slice(0, limit).map((r) => r.lesson);
-    } catch {
-      results = await searchKeyword(repoRoot, query, limit);
-    }
-  } else {
-    results = await searchKeyword(repoRoot, query, limit);
-  }
-  if (results.length > 0) {
-    incrementRetrievalCount(repoRoot, results.map((lesson) => lesson.id));
+  const maxRetries = Number(options.maxRetries ?? 1);
+  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+    out.error(`Invalid --max-retries: must be a non-negative integer, got "${options.maxRetries}"`);
+    process.exitCode = 1;
+    return;
   }
-  if (results.length === 0) {
-    console.log('No lessons match your search. Try a different query or use "list" to see all lessons.');
+  let script;
+  try {
+    script = generateLoopScript({
+      epics: options.epics,
+      maxRetries,
+      model: options.model ?? "claude-opus-4-6"
+    });
+  } catch (err) {
+    out.error(err.message);
+    process.exitCode = 1;
     return;
   }
-  if (!quiet) {
-    out.info(`Found ${results.length} lesson(s):
-`);
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, script, "utf-8");
+  await chmod(outputPath, 493);
+  out.success(`Generated infinity loop script: ${outputPath}`);
+  out.info("Run it with: " + outputPath);
+  out.info("Preview with: LOOP_DRY_RUN=1 " + outputPath);
+}
+function registerLoopCommands(program2) {
+  program2.command("loop").description("Generate infinity loop script for epic tasks").option("--epics <ids...>", "Specific epic IDs to process").option("-o, --output <path>", "Output script path", "./infinity-loop.sh").option("--max-retries <n>", "Max retries per epic on failure", "1").option("--model <model>", "Claude model to use", "claude-opus-4-6").option("--force", "Overwrite existing script").action(async function(options) {
+    await handleLoop(this, options);
+  });
+}
+var EPIC_ID_PATTERN2 = /^[a-zA-Z0-9_.-]+$/;
+function formatTime(timestamp) {
+  if (!timestamp) {
+    const now = /* @__PURE__ */ new Date();
+    return now.toTimeString().slice(0, 8);
   }
-  for (const lesson of results) {
-    console.log(`[${chalk4.cyan(lesson.id)}] ${lesson.insight}`);
-    console.log(`  Trigger: ${lesson.trigger}`);
-    if (verbose && lesson.context) {
-      console.log(`  Context: ${lesson.context.tool} - ${lesson.context.intent}`);
-      console.log(`  Created: ${lesson.created}`);
-    }
-    if (lesson.tags.length > 0) {
-      console.log(`  Tags: ${lesson.tags.join(", ")}`);
-    }
-    console.log();
+  try {
+    return new Date(timestamp).toTimeString().slice(0, 8);
+  } catch {
+    return (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
   }
 }
-async function listAction(cmd, options) {
-  const repoRoot = getRepoRoot();
-  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;
-  if (filteredItems.length === 0) {
-    if (options.invalidated) {
-      console.log("No invalidated lessons found.");
-    } else {
-      console.log('No lessons found. Get started with: learn "Your first lesson"');
+function formatNumber(n) {
+  return n.toLocaleString();
+}
+function formatStreamEvent(event) {
+  const time = chalk5.dim(formatTime(event.timestamp));
+  switch (event.type) {
+    case "content_block_start": {
+      if (event.content_block?.type === "tool_use") {
+        const name = event.content_block.name ?? "unknown";
+        return `${time} ${chalk5.cyan("TOOL")}    ${name}`;
+      }
+      if (event.content_block?.type === "thinking") {
+        return `${time} ${chalk5.magenta("THINK")}   thinking...`;
+      }
+      return null;
     }
-    if (skippedCount > 0) {
-      out.warn(`${skippedCount} corrupted lesson(s) skipped.`);
+    case "content_block_delta": {
+      if (event.delta?.type === "text_delta") {
+        const text = event.delta.text ?? "";
+        const truncated = text.length > 60 ? text.slice(0, 57) + "..." : text;
+        return `${time} ${chalk5.blue("TEXT")}    ${truncated.replace(/\n/g, " ")}`;
+      }
+      return null;
     }
-    return;
-  }
-  const toShow = filteredItems.slice(0, limit);
-  if (!quiet) {
-    const label = options.invalidated ? "invalidated lesson(s)" : "item(s)";
-    out.info(`Showing ${toShow.length} of ${filteredItems.length} ${label}:
-`);
-  }
-  for (const item of toShow) {
-    const invalidMarker = item.invalidatedAt ? chalk4.red("[INVALID] ") : "";
-    console.log(`[${chalk4.cyan(item.id)}] ${invalidMarker}${item.insight}`);
-    if (verbose) {
-      console.log(`  Type: ${item.type} | Source: ${item.source}`);
-      console.log(`  Created: ${item.created}`);
-      if (item.context) {
-        console.log(`  Context: ${item.context.tool} - ${item.context.intent}`);
+    case "message_delta": {
+      const usage = event.usage;
+      if (usage?.output_tokens) {
+        return `${time} ${chalk5.dim("TOKENS")}  ${formatNumber(usage.output_tokens)} out (final)`;
       }
-      if (item.invalidatedAt) {
-        console.log(`  Invalidated: ${item.invalidatedAt}`);
-        if (item.invalidationReason) {
-          console.log(`  Reason: ${item.invalidationReason}`);
-        }
+      return null;
+    }
+    case "message_start": {
+      if (event.message?.usage) {
+        const { input_tokens, output_tokens } = event.message.usage;
+        const inTok = input_tokens ? formatNumber(input_tokens) : "?";
+        const outTok = output_tokens ? formatNumber(output_tokens) : "?";
+        return `${time} ${chalk5.dim("TOKENS")}  ${inTok} in / ${outTok} out`;
       }
-    } else {
-      console.log(`  Type: ${item.type} | Source: ${item.source}`);
+      return null;
     }
-    if (item.tags.length > 0) {
-      console.log(`  Tags: ${item.tags.join(", ")}`);
+    case "result": {
+      const text = typeof event.result === "string" ? event.result : "";
+      const markers = ["EPIC_COMPLETE", "EPIC_FAILED", "HUMAN_REQUIRED"];
+      const found = markers.find((m) => text.includes(m));
+      if (found) {
+        const markerLine = text.split("\n").find((l) => l.includes(found)) ?? found;
+        const display = markerLine.length > 120 ? markerLine.slice(0, 117) + "..." : markerLine;
+        return `${time} ${chalk5.yellow.bold("MARKER")}  ${display}`;
+      }
+      return null;
     }
-    console.log();
-  }
-  if (skippedCount > 0) {
-    out.warn(`${skippedCount} corrupted lesson(s) skipped.`);
+    default:
+      return null;
   }
 }
-async function loadSessionAction(cmd, options) {
-  const repoRoot = getRepoRoot();
-  const { quiet } = getGlobalOpts(cmd);
-  const lessons = await loadSessionLessons(repoRoot);
-  const { lessons: allLessons } = await readLessons(repoRoot);
-  const totalCount = allLessons.length;
-  if (options.json) {
-    console.log(JSON.stringify({ lessons, count: lessons.length, totalCount }));
-    return;
-  }
-  if (lessons.length === 0) {
-    console.log("No high-severity lessons found.");
-    return;
-  }
-  outputSessionLessonsHuman(lessons, quiet);
-  if (totalCount > LESSON_COUNT_WARNING_THRESHOLD) {
-    console.log("");
-    out.info(`${totalCount} lessons in index. Consider \`ca compact\` to reduce context pollution.`);
+function findLatestTraceFile(logDir) {
+  if (!existsSync(logDir)) return null;
+  const latestPath = join(logDir, ".latest");
+  if (existsSync(latestPath)) {
+    try {
+      const target = readlinkSync(latestPath);
+      const resolved = resolve(logDir, target);
+      if (existsSync(resolved)) return resolved;
+    } catch {
+    }
   }
-  const oldLessons = lessons.filter((l) => getLessonAgeDays(l) > AGE_FLAG_THRESHOLD_DAYS);
-  if (oldLessons.length > 0) {
-    console.log("");
-    out.warn(`${oldLessons.length} lesson(s) are over ${AGE_FLAG_THRESHOLD_DAYS} days old. Review for continued validity.`);
+  try {
+    const files = readdirSync(logDir).filter((f) => f.startsWith("trace_") && f.endsWith(".jsonl")).sort().reverse();
+    const first = files[0];
+    if (first) return join(logDir, first);
+  } catch {
   }
+  return null;
 }
-async function checkPlanAction(cmd, options) {
-  const repoRoot = getRepoRoot();
-  const limit = parseLimitOrNull(options.limit, "limit", "check-plan");
-  if (limit === null) {
-    process.exitCode = 1;
-    return;
+function processLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  try {
+    const event = JSON.parse(trimmed);
+    const formatted = formatStreamEvent(event);
+    if (formatted) {
+      console.log(formatted);
+    }
+  } catch {
   }
-  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.exitCode = 1;
-    return;
+}
+async function tailFile(filePath, follow) {
+  if (follow) {
+    const child = spawn("tail", ["-f", "-n", "+1", filePath], { stdio: ["ignore", "pipe", "ignore"] });
+    const rl2 = createInterface({ input: child.stdout });
+    rl2.on("line", processLine);
+    const cleanup2 = () => {
+      child.kill("SIGTERM");
+    };
+    process.on("SIGINT", cleanup2);
+    process.on("SIGTERM", cleanup2);
+    return new Promise((done) => {
+      child.on("close", () => {
+        process.off("SIGINT", cleanup2);
+        process.off("SIGTERM", cleanup2);
+        done();
+      });
+    });
   }
-  await syncIfNeeded(repoRoot);
-  if (!isModelAvailable()) {
-    if (options.json) {
-      console.log(JSON.stringify({
-        lessons: [],
-        count: 0,
-        error: "Embedding model not found",
-        action: "Run: npx ca download-model"
-      }));
-    } else {
-      console.error(formatError("check-plan", "MODEL_UNAVAILABLE", "Embedding model not found", "Run: npx ca download-model"));
+  const stream = createReadStream(filePath, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream });
+  try {
+    for await (const line of rl) {
+      processLine(line);
     }
-    process.exitCode = 1;
-    return;
+  } finally {
+    rl.close();
+    stream.destroy();
   }
+}
+async function handleWatch(cmd, options) {
+  let logDir;
   try {
-    const result = await retrieveForPlan(repoRoot, planText, limit);
-    if (options.json) {
-      outputCheckPlanJson(result.lessons);
+    logDir = join(getRepoRoot(), "agent_logs");
+  } catch {
+    logDir = resolve("agent_logs");
+  }
+  const follow = options.follow !== false;
+  let traceFile = null;
+  if (options.epic) {
+    if (!EPIC_ID_PATTERN2.test(options.epic)) {
+      out.error(`Invalid epic ID: ${options.epic}`);
+      process.exitCode = 1;
       return;
     }
-    if (result.lessons.length === 0) {
-      console.log("No relevant lessons found for this plan.");
+    if (existsSync(logDir)) {
+      try {
+        const files = readdirSync(logDir).filter((f) => f.startsWith(`trace_${options.epic}`) && f.endsWith(".jsonl")).sort().reverse();
+        const first = files[0];
+        if (first) traceFile = join(logDir, first);
+      } catch {
+      }
+    }
+    if (!traceFile) {
+      out.error(`No trace file found for epic: ${options.epic}`);
+      process.exitCode = 1;
       return;
     }
-    outputCheckPlanHuman(result.lessons, quiet);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : "Unknown error";
-    if (options.json) {
-      console.log(JSON.stringify({
-        lessons: [],
-        count: 0,
-        error: message
-      }));
-    } else {
-      console.error(formatError("check-plan", "PLAN_CHECK_FAILED", message, "Check model installation and try again"));
+  } else {
+    traceFile = findLatestTraceFile(logDir);
+    if (!traceFile) {
+      out.info("No active trace found. Run `ca loop` to generate a loop script first.");
+      process.exitCode = 0;
+      return;
     }
-    process.exitCode = 1;
   }
+  out.info(`Watching: ${traceFile}`);
+  await tailFile(traceFile, follow);
 }
-function registerRetrievalCommands(program2) {
-  program2.command("search <query>").description("Search lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_SEARCH_LIMIT).action(async function(query, options) {
-    await searchAction(this, query, options);
-  });
-  program2.command("list").description("List all lessons").option("-n, --limit <number>", "Maximum results", DEFAULT_LIST_LIMIT).option("--invalidated", "Show only invalidated lessons").action(async function(options) {
-    await listAction(this, options);
-  });
-  program2.command("load-session").description("Load high-severity lessons for session context").option("--json", "Output as JSON").action(async function(options) {
-    await loadSessionAction(this, options);
-  });
-  program2.command("check-plan").description("Check plan against relevant lessons").option("--plan <text>", "Plan text to check").option("--json", "Output as JSON").option("-n, --limit <number>", "Maximum results", DEFAULT_CHECK_PLAN_LIMIT).action(async function(options) {
-    await checkPlanAction(this, options);
-  });
-}
-
-// src/commands/index.ts
-function registerSetupCommands(program2) {
-  registerInitCommand(program2);
-  registerHooksCommand(program2);
-  const setupCommand = program2.command("setup");
-  registerSetupAllCommand(setupCommand);
-  registerClaudeSubcommand(setupCommand);
-  registerGeminiSubcommand(setupCommand);
-  registerDownloadModelCommand(program2);
-}
-function registerManagementCommands(program2) {
-  registerInvalidationCommands(program2);
-  registerMaintenanceCommands(program2);
-  registerIOCommands(program2);
-  registerPrimeCommand(program2);
-  registerCrudCommands(program2);
-  registerAuditCommands(program2);
-  registerDoctorCommand(program2);
-  registerReviewerCommand(program2);
-  registerRulesCommands(program2);
-  registerTestSummaryCommand(program2);
-  registerVerifyGatesCommand(program2);
-  registerAboutCommand(program2);
-  registerKnowledgeCommand(program2);
-  registerKnowledgeIndexCommand(program2);
-  registerCleanLessonsCommand(program2);
-  program2.command("worktree").description("(removed) Use Claude Code native worktree support").action(() => {
-    console.error("ca worktree has been removed. Use Claude Code's native EnterWorktree support instead.");
-    process.exitCode = 1;
+function registerWatchCommand(program2) {
+  program2.command("watch").description("Tail and pretty-print live trace from infinity loop sessions").option("--epic <id>", "Watch a specific epic trace").option("--no-follow", "Print existing trace and exit (no live tail)").action(async function(options) {
+    await handleWatch(this, options);
   });
 }