compound-agent 1.7.3 → 1.7.4

package/dist/cli.js

@@ -3901,6 +3901,226 @@ For each pair, classify as one of:
 - **Complementary**: Related but distinct \u2014 propose related links, keep both
 
 Output a structured action plan with specific \`npx ca\` commands to execute.
+`,
+  "lint-classifier.md": `---
+name: Lint Classifier
+description: Classifies compound phase insights as lintable or semantic-only, creating beads tasks for mechanically-enforceable patterns
+model: sonnet
+---
+
+# Lint Classifier
+
+Classify each insight from the compound phase as LINTABLE, PARTIAL, or NOT_LINTABLE. For LINTABLE insights with HIGH confidence, create beads tasks describing lint rules to implement.
+
+## Input
+
+You receive insights via SendMessage from the compound lead. Each message contains:
+- \`id\`: The lesson ID (e.g., \`Laa504c6880ba5d41\`)
+- \`insight\`: The verbatim insight text
+- \`severity\`: high, medium, or low
+
+If no insights are provided via message, read the last 10 entries from \`.claude/lessons/index.jsonl\` (each line is a JSON object; parse and reverse to get newest-first, take up to 10).
+
+## Classification Definition
+
+An insight is **LINTABLE** if and only if:
+- It describes a property determinable from source code alone (text, tokens, AST nodes, import paths, file names)
+- The check would return a deterministic yes/no without running the program
+- The bad pattern can be expressed as a regex, AST selector, or import constraint
+- It does NOT require: runtime state, human intent, cross-session history, deployment processes, or semantic meaning
+
+## Classes
+
+| Class | Meaning |
+|-------|---------|
+| LINTABLE | Check can be written as regex / AST / import rule |
+| PARTIAL | A subset is lintable; the rest is process/semantic |
+| NOT_LINTABLE | Requires runtime state, process knowledge, or human judgment |
+
+## Confidence Levels
+
+| Level | Definition |
+|-------|-----------|
+| HIGH | Named code construct + prohibitive imperative. Check is unambiguous. |
+| MEDIUM | Pattern is conditional on context, or needs AST analysis. |
+| LOW | Genuinely ambiguous. Flag for human review. |
+
+## Few-Shot Examples
+
+**Example 1** -- LINTABLE, HIGH
+> "Use isModelAvailable() instead of isModelUsable() in hot paths"
+- Reasoning: Named function substitution. Can detect \`isModelUsable(\` via regex in \`src/**/*.ts\`.
+- VERDICT: LINTABLE | CONFIDENCE: HIGH | CHECK_TYPE: file-pattern
+
+**Example 2** -- LINTABLE, HIGH
+> "Never use if(condition){expect()} in tests"
+- Reasoning: Structural pattern. Detect IfStatement containing expect() call via AST visitor.
+- VERDICT: LINTABLE | CONFIDENCE: HIGH | CHECK_TYPE: ast
+
+**Example 3** -- PARTIAL, HIGH
+> "When adding new hook types, update ALL user-facing output to include the complete set"
+- Reasoning: Can detect hardcoded hook-type arrays in known files (lintable subset). Cannot verify "all" surfaces were updated (process). The detectable part is unambiguous.
+- VERDICT: PARTIAL | CONFIDENCE: HIGH | CHECK_TYPE: file-pattern
+
+**Example 4** -- PARTIAL, MEDIUM
+> "Update ALL output surfaces when adding hook types"
+- Reasoning: Can check for hardcoded hook-type lists in known files (partial). Cannot verify "all" surfaces were updated (process). Context-dependent which files to check.
+- VERDICT: PARTIAL | CONFIDENCE: MEDIUM | CHECK_TYPE: file-pattern
+
+**Example 5** -- NOT_LINTABLE, HIGH
+> "Inlining phase instructions causes context drift under compaction"
+- Reasoning: Describes a runtime/architectural effect. No code pattern to match.
+- VERDICT: NOT_LINTABLE | CONFIDENCE: HIGH | CHECK_TYPE: N/A
+
+**Example 6** -- NOT_LINTABLE, HIGH
+> "Always verify git diff after subagent completes"
+- Reasoning: Human process step. Cannot be detected from source code.
+- VERDICT: NOT_LINTABLE | CONFIDENCE: HIGH | CHECK_TYPE: N/A
+
+**Example 7** -- LINTABLE, LOW
+> "Avoid complex nested callbacks in async code"
+- Reasoning: "Complex" and "nested" are subjective. Could write a nesting-depth check but threshold is arbitrary. Genuinely ambiguous.
+- VERDICT: LINTABLE | CONFIDENCE: LOW | CHECK_TYPE: ast
+
+## Classification Procedure
+
+For each insight, reason step by step then output:
+
+\`\`\`
+VERDICT: [LINTABLE|PARTIAL|NOT_LINTABLE]
+CONFIDENCE: [HIGH|MEDIUM|LOW]
+CHECK_TYPE: [file-pattern|file-size|script|ast|N/A]
+RULE_CLASS: [A|B|N/A]
+RATIONALE: One sentence summary
+\`\`\`
+
+### Rule Classes
+
+- **Class A** (native \`rules.json\`): The check can be expressed as a regex/glob (\`file-pattern\`), line count (\`file-size\`), or shell command (\`script\`). These map directly to the compound-agent rule engine. No external linter needed.
+- **Class B** (external linter): The check requires AST analysis or linter-specific features. Targets the user's detected linter (ESLint, Ruff, ast-grep, etc.).
+
+CHECK_TYPE must be one of: \`file-pattern\`, \`file-size\`, \`script\` (Class A -- maps to compound-agent rule engine), \`ast\` (Class B -- requires external linter), or \`N/A\` (not lintable).
+
+## Routing Rules
+
+| Classification | Action |
+|---------------|--------|
+| LINTABLE + HIGH | Create beads task under "Linting Improvement" epic |
+| LINTABLE + MEDIUM or PARTIAL + HIGH | Create a follow-up beads task noting the partial lintability for manual triage |
+| NOT_LINTABLE or LOW confidence | No additional action (lesson already stored by compound flow) |
+
+For LINTABLE + MEDIUM or PARTIAL + HIGH, create a triage task:
+\`\`\`bash
+bd create --title="Triage: potentially-lintable lesson <lesson-id>" --type=task --priority=3 --description="Lesson <lesson-id>: <insight>\\n\\nVerdict: <LINTABLE/PARTIAL> | Confidence: <MEDIUM/HIGH>\\nReason lintability is uncertain: <rationale>"
+\`\`\`
+
+**Critical**: ALL insights are already stored as lessons by the compound pipeline (step 8). Lint task creation is purely additive. Do not re-store or modify existing lessons.
+
+## Linter Detection
+
+Before creating Class B tasks, detect the project's linter by checking the repo root for config files (first match wins):
+
+1. \`eslint.config.*\` / \`.eslintrc.*\` -> eslint
+2. \`ruff.toml\` / \`.ruff.toml\` / \`pyproject.toml\` with \`[tool.ruff]\` -> ruff
+3. \`clippy.toml\` / \`.clippy.toml\` -> clippy
+4. \`.golangci.yml\` / \`.golangci.yaml\` -> golangci-lint
+5. \`sgconfig.yml\` -> ast-grep
+6. \`.semgrep.yml\` / \`.semgrep.yaml\` -> semgrep
+
+**When no linter is detected**: For Class A rules, proceed normally (they use the native rule engine). For Class B rules, set target to \`ast-grep\` or \`semgrep\` as universal YAML-based fallbacks and note that no project linter was detected.
+
+## Task Creation
+
+For each LINTABLE + HIGH insight, run:
+
+\`\`\`bash
+bd create --title="Lint Rule: <rule-id> (from <lesson-id>)" --type=task --priority=<N> --description="<structured markdown>"
+\`\`\`
+
+### Description structure (Class A -- native rule engine):
+
+\`\`\`markdown
+## Source Lesson
+ID: <lesson-id>
+Insight: <verbatim insight text>
+
+## Rule Identity
+- ID: <kebab-case-rule-id>
+- Class: A (native rule engine)
+- Severity: <error|warning|info>
+- Scope: <glob pattern for affected files>
+
+## Detection Spec
+Check type: <file-pattern|file-size|script>
+Glob: <glob pattern>
+Pattern: <regex> (for file-pattern)
+mustMatch: <true|false>
+
+## Violation Message
+<What the developer sees. Under 3 lines. Imperative mood.>
+<Must answer: what violated, how to fix.>
+
+## Remediation
+<Concrete fix instruction.>
+
+## Code Examples
+Bad:
+  <code that violates>
+
+Good:
+  <code that follows the rule>
+\`\`\`
+
+### Description structure (Class B -- external linter):
+
+\`\`\`markdown
+## Source Lesson
+ID: <lesson-id>
+Insight: <verbatim insight text>
+
+## Rule Identity
+- ID: <kebab-case-rule-id>
+- Class: B (external linter)
+- Target: <detected linter>
+- Severity: <error|warning|info>
+- Scope: <glob pattern for affected files>
+
+## Detection Spec
+<Natural language description of AST pattern>
+<Suggested selector or rule YAML -- mark "suggested, verify before use">
+
+## Violation Message
+<What the developer sees. Under 3 lines. Imperative mood.>
+<Must answer: what violated, how to fix.>
+
+## Remediation
+<Concrete fix instruction.>
+
+## Code Examples
+Bad:
+  <code that violates>
+
+Good:
+  <code that follows the rule>
+\`\`\`
+
+### Priority mapping: lesson severity high->1, medium->2, low->3 (default: 2)
+
+## Epic Management
+
+1. Check if a "Linting Improvement" epic exists: \`bd search "Linting Improvement"\`
+2. If not found, create: \`bd create --title="Linting Improvement" --type=epic --priority=2 --description="Epic for lint rules graduated from compound phase lessons."\`
+3. Link tasks to the epic: \`bd dep add <epic-id> <task-id>\` (epic blocks the task)
+
+**Important**: Use \`bd dep add <epic-id> <task-id>\` (epic first), NOT \`<task-id> <epic-id>\`. The epic blocks the tasks, not the other way around.
+
+## Constraints
+
+- AST selectors are suggestions only -- mark as "suggested, verify before use"
+- Never skip classification for any insight
+- Do not modify the existing lesson capture flow
+- CHECK_TYPE must map to an actual engine type (\`file-pattern\`, \`file-size\`, \`script\`) for Class A, or \`ast\` for Class B
+- Report a summary at the end: N insights classified, X lintable (Y Class A, Z Class B), T tasks created
 `
 };
 
@@ -5050,7 +5270,7 @@ $ARGUMENTS
 
 **MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/researcher/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file.
 
-Then: scan docs/compound/research/ for gaps, propose topics via AskUserQuestion, spawn parallel researcher subagents.
+Then: scan docs/research/ and docs/compound/research/ for gaps, propose topics via AskUserQuestion, spawn parallel researcher subagents.
 `,
   "agentic-audit.md": `---
 name: compound:agentic-audit
@@ -5077,6 +5297,17 @@ $ARGUMENTS
 **MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/agentic/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file.
 
 Run in **setup** mode. Audit first, then propose and create files to fill gaps.
+`,
+  "architect.md": `---
+name: compound:architect
+description: Decompose a large system specification into cook-it-ready epic beads
+argument-hint: "<system spec epic ID, file path, or description>"
+---
+$ARGUMENTS
+
+# Architect
+
+**MANDATORY FIRST STEP -- NON-NEGOTIABLE**: Use the Read tool to open and read \`.claude/skills/compound/architect/SKILL.md\` NOW. Do NOT proceed until you have read the complete skill file. It contains the full workflow you must follow.
 `,
   // =========================================================================
   // Utility commands (kept: learn-that, check-that, prime)
@@ -5555,9 +5786,9 @@ Skills are instructions that Claude reads before executing each phase. They live
 
 **Purpose**: Conduct deep, PhD-level research to build knowledge for working subagents.
 
-**When invoked**: When agents need domain knowledge not yet covered in \`docs/compound/research/\`.
+**When invoked**: When agents need domain knowledge not yet covered in \`docs/research/\`.
 
-**What it does**: Analyzes beads epics for knowledge gaps, checks existing docs coverage, proposes research topics for user confirmation, spawns parallel researcher subagents, and stores output at \`docs/compound/research/<topic>/<slug>.md\`.
+**What it does**: Analyzes beads epics for knowledge gaps, checks existing docs coverage, proposes research topics for user confirmation, spawns parallel researcher subagents, and stores output at \`docs/research/<topic>/<slug>.md\`.
 
 ### \`/compound:agentic-audit\`
 
@@ -5748,12 +5979,8 @@ Work is not complete until \`git push\` succeeds.
 };
 
 // src/setup/templates/skills.ts
-var _bc = "\x1B[96m";
-var _cn = "\x1B[36m";
-var _gr = "\x1B[32m";
-var _mg = "\x1B[35m";
-var _yl = "\x1B[33m";
-var _rs = "\x1B[0m";
+var cn = "\x1B[36m";
+var rs = "\x1B[0m";
 var PHASE_SKILLS = {
   "spec-dev": `---
 name: Spec Dev
@@ -5787,7 +6014,10 @@ Scale formality to risk: skip for trivial (<1h), lightweight (EARS + epic) for s
 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
+5. **Change volatility**: rate each capability stable/moderate/high. Flag high-volatility areas for modularity investment in architect phase.
+6. **Cynefin classify** each requirement: Clear (apply known solution), Complicated (analyze tradeoffs), Complex (needs safe-to-fail experiments). Complex requirements need experimental validation, not just analysis.
+7. For composed systems, add **composition EARS**: \`When <A> times out, <B> shall...\`, \`If <A> retries, <B> shall...\`
+8. Use \`AskUserQuestion\` to resolve each ambiguity
 
 **Iteration trigger**: If specifying reveals missing knowledge, loop back to Explore.
 
@@ -5844,6 +6074,7 @@ Read \`.claude/skills/compound/spec-dev/references/spec-guide.md\` on demand for
 - Not creating the beads epic
 - Specifying implementation instead of requirements
 - Skipping scenario table generation after EARS requirements
+- Not classifying requirements by Cynefin domain (Complex needs experiments)
 
 ## Quality Criteria
 - [ ] Requirements use EARS notation
@@ -5855,6 +6086,7 @@ Read \`.claude/skills/compound/spec-dev/references/spec-guide.md\` on demand for
 - [ ] Scenario table generated from EARS requirements and diagrams
 - [ ] Spec and scenario table stored in beads epic description
 - [ ] ADRs created for significant decisions
+- [ ] Cynefin classification applied, volatility assessed
 `,
   plan: `---
 name: Plan
@@ -5877,11 +6109,14 @@ Create a concrete implementation plan by decomposing work into small, testable t
 5. Synthesize research findings into a coherent approach. Flag conflicts between ADRs and proposed plan.
 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. 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
+8. **Boundary stability check**: verify each task stays within its epic's scope boundary. If a task crosses epic boundaries, split it or expand scope.
+9. **Last Responsible Moment**: for each task, assess if it can be deferred for information gain. Mark deferrable tasks with rationale: "defer until <milestone> because <information needed>".
+10. **Change coupling check**: if files A and B change together >50% of the time (git log), they should be in the same task, not separate ones.
+11. Define acceptance criteria for each task
+12. Ensure each task traces back to a spec requirement for traceability
+13. Map dependencies between tasks
+14. Create beads issues: \`bd create --title="..." --type=task\`
+15. 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
@@ -5901,6 +6136,8 @@ Create a concrete implementation plan by decomposing work into small, testable t
 - Not reviewing existing ADRs and docs for constraints
 - Making architectural decisions without research backing (use the researcher skill for complex domains)
 - Planning implementation details too early (stay at task level)
+- Not checking tasks against epic boundaries (boundary drift)
+- Splitting change-coupled files into separate tasks
 
 ## Quality Criteria
 - Each task has clear acceptance criteria
@@ -5911,6 +6148,8 @@ Create a concrete implementation plan by decomposing work into small, testable t
 - Ambiguities resolved via \`AskUserQuestion\` before decomposing
 - Complexity estimates are realistic (no "should be quick")
 - Each task traces back to a spec requirement
+- Tasks respect epic scope boundaries (no cross-boundary work)
+- Change-coupled files grouped together
 
 ## POST-PLAN VERIFICATION -- MANDATORY
 After creating all tasks, verify review and compound tasks exist:
@@ -5976,11 +6215,21 @@ for complex changes. For all changes, \`/implementation-reviewer\` is the minimu
 - Run \`npx ca knowledge "TDD test-first"\` for indexed knowledge on testing methodology
 - Run \`npx ca search "testing"\` for lessons from past TDD cycles
 
+## Technical Debt Protocol
+When shortcuts are proposed, classify using Fowler's quadrant: only **Prudent/Deliberate** debt is rational (conscious choice, known trade-off, explicit repayment plan). Reckless or Inadvertent debt must be fixed immediately. Document debt decisions in epic notes.
+
+## Composition Boundary Verification
+If work touches a composition boundary (inter-epic or inter-service interface):
+- Verify implementation matches the interface contracts (explicit + implicit) from architect phase
+- Write tests for implicit contracts: timeout interactions, retry behavior, backpressure
+- Check for metastable failure risk: feedback loops (retry amplification, cache storms)
+
 ## Common Pitfalls
 - Lead writing code instead of delegating to agents
 - Not injecting memory context into agent prompts
 - Modifying tests to make them pass instead of fixing implementation
 - Not running the full test suite after agent work completes
+- Accumulating reckless/inadvertent tech debt without classification
 
 ## Quality Criteria
 - Tests existed before implementation code
@@ -5990,6 +6239,8 @@ for complex changes. For all changes, \`/implementation-reviewer\` is the minimu
 - All tests pass after refactoring
 - Task lifecycle tracked via beads (\`bd\`)
 - Implementation aligns with spec requirements from epic
+- Technical debt classified (only Prudent/Deliberate accepted)
+- Composition boundaries verified against interface contracts
 
 ## PHASE GATE 3 -- MANDATORY
 Before starting Review, verify ALL work tasks are closed:
@@ -6014,7 +6265,8 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 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, scenario-coverage (8 total)
-   - **Large** (500+): all 12 reviewers including docs, consistency, error-handling, pattern-matcher
+   - **Large** (500+): all 12+ reviewers including docs, consistency, error-handling, pattern-matcher
+   - **Composition changes**: add boundary-reviewer (coupling within epic boundaries?), control-structure-reviewer (STPA mitigations implemented?), observability-reviewer (metrics at boundaries?)
 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,scenario-coverage-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\`
@@ -6024,7 +6276,7 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 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
+11. Verify spec alignment: flag unmet EARS requirements as P1. Verify assumptions from architect phase still hold. Check change coupling: do modified files cluster within epic boundaries or leak across?
 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
@@ -6052,6 +6304,7 @@ Perform thorough code review by spawning specialized reviewers in parallel, cons
 - Skipping quality gates before review
 - Bypassing the implementation-reviewer gate
 - Not checking CCT patterns for known Claude mistakes
+- Not verifying architect assumptions still hold after implementation
 
 ## Quality Criteria
 - All quality gates pass (\`pnpm test\`, lint)
@@ -6090,6 +6343,9 @@ 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. 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. **Decomposition quality assessment**: compare actual implementation against predicted boundaries from architect. Did files cluster as predicted? Were assumptions valid? Rate boundary quality: "This boundary [succeeded/failed] because..." Capture as lesson for future architect runs.
+4. **Assumption tracking**: for each assumption from architect phase, record predicted vs actual volatility. Store with \`npx ca learn\` for calibration.
+5. **Emergence analysis**: if unexpected system behaviors occurred, classify root cause: incomplete interface contract (Garlan), control structure inadequacy (STPA), or scale-induced phase transition. Capture preventive lesson.
 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
@@ -6123,6 +6379,8 @@ Lessons go to \`.claude/lessons/index.jsonl\` through the CLI. MEMORY.md is a di
 - Requiring user confirmation for every item (only high-severity needs it)
 - Not classifying items by type (lesson/solution/pattern/preference)
 - Capturing vague lessons ("be careful with X") -- be specific and concrete
+- Not assessing decomposition boundary quality against architect predictions
+- Not tracking assumption accuracy for future calibration
 
 ## Quality Criteria
 - Analysis team was spawned and agents coordinated via pipeline
@@ -6135,6 +6393,9 @@ Lessons go to \`.claude/lessons/index.jsonl\` through the CLI. MEMORY.md is a di
 - Beads checked for related issues (\`bd\`)
 - Each item gives clear, concrete guidance for future sessions
 - Spec drift analyzed and captured
+- Decomposition boundary quality assessed
+- Architect assumptions tracked (predicted vs actual)
+- Emergent failures classified by root cause if any occurred
 
 ## FINAL GATE -- EPIC CLOSURE
 Before closing the epic:
@@ -6151,7 +6412,7 @@ description: Deep research producing structured survey documents for informed de
 # Researcher Skill
 
 ## Overview
-Conduct deep research on a topic and produce a structured survey document following the project's research template. This skill spawns parallel research subagents to gather comprehensive information, then synthesizes findings into a PhD-depth document stored in \`docs/compound/research/\`.
+Conduct deep research on a topic and produce a structured survey document following the project's research template. This skill spawns parallel research subagents to gather comprehensive information, then synthesizes findings into a PhD-depth document stored in \`docs/research/\`.
 
 ## Methodology
 1. Identify the research question, scope, and exclusions
@@ -6172,16 +6433,16 @@ Conduct deep research on a topic and produce a structured survey document follow
    - Conclusion
    - References (full citations)
    - Practitioner Resources (annotated tools/repos)
-6. Store output at \`docs/compound/research/<topic-slug>.md\` (kebab-case filename)
+6. Store output at \`docs/research/<topic-slug>.md\` (kebab-case filename)
 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
-- Check for existing research docs in \`docs/compound/research/\` that overlap
+- Check for existing research docs in \`docs/research/\` and \`docs/compound/research/\` that overlap
 - After completion, key findings can be captured via \`npx ca learn\`
 
 ## Docs Integration
-- Scan \`docs/compound/research/\` for prior survey documents on related topics
+- Scan \`docs/research/\` and \`docs/compound/research/\` for prior survey documents on related topics
 - Check \`docs/decisions/\` for ADRs that inform or constrain the research scope
 - Reference existing project docs as primary sources where relevant
 
@@ -6272,25 +6533,17 @@ Before starting EACH phase, you MUST use the Read tool to open its skill file:
 Do NOT proceed from memory. Read the skill, then follow it exactly.
 
 ## Session Start
-When a cooking session begins, IMMEDIATELY print the brain banner below (copy it verbatim):
-
-        ___    ___
-    .."\`)  "\`.."  "(\`\`.
-  .'; _..=. ${_bc}::${_rs} \`-'._ ;\`.
- : ) ;"\`':._. ${_bc}::${_rs}_.      ( :.
-.:-"   _.  \`"${_cn}##${_rs}"\` "._ \`-:\\
-/."   -"\`  ._.${_bc}::${_rs}._.  .'"  ".:
-: :    ( -: \`" ${_bc}::${_rs} "\` :- )    : )
-( .":==._ ' \`'=._${_cn}##${_rs}_.=' ' _.==: .'
-(:  \`, \`"\`    \`"${_cn}##${_rs}"\`    \`"\` .'\`".)
- \\\`'  \`"--.  "- )( -" ..--"\` \`-/
- (" (_."\`  ="""-..."\`...-""= "._) ")
-  "..__..-"  )${_gr}%${_rs}\`..'\`${_gr}%${_rs}(  "-..__.."
-       (#"...'\\\\${_gr}%%%%${_rs}/\`..."#)
-        \`${_mg}######${_rs}\`--'${_mg}######${_rs}"
-          "${_mg}###${_rs}")${_yl}@@${_rs}(\`${_mg}###${_rs}"
-               \\${_yl}@@${_rs}/
-             Claw'd
+When a cooking session begins, IMMEDIATELY print the banner below (copy it verbatim):
+
+${cn}         o
+        /|\\
+       o-o-o
+      /|\\ /|\\
+     o-o-o-o-o
+      \\|/ \\|/
+       o-o-o
+        \\|/
+         o${rs}
 
 Then proceed with the protocol below.
 
@@ -6664,6 +6917,110 @@ After all approved actions are applied, verify:
 - Setup mode ran audit first
 - No files overwritten without approval
 - Generated content based on actual codebase analysis
+`,
+  "architect": `---
+name: Architect
+description: Decompose a large system specification into cook-it-ready epic beads via DDD bounded contexts
+---
+
+# Architect Skill
+
+## Overview
+Take a large system specification and decompose it into naturally-scoped epic beads that the infinity loop can process via cook-it. Each output epic is sized for one cook-it cycle.
+
+4 phases with 3 human gates. Runs BEFORE spec-dev -- each decomposed epic then goes through full cook-it (including spec-dev to refine its EARS subset).
+
+## Input
+- Beads epic ID: read epic description as input
+- File path: read markdown file as input
+- Neither: use \`AskUserQuestion\` to gather the system description
+
+## Phase 1: Socratic
+**Goal**: Understand the system domain before decomposing.
+1. Search memory: \`npx ca search\` for past features, constraints, decisions
+2. Search knowledge: \`npx ca knowledge "relevant terms"\`
+3. Ask "why" before "how" -- understand the real need
+4. Build a **domain glossary** (ubiquitous language) from the dialogue
+5. Produce a **discovery mindmap** (Mermaid \`mindmap\`) to expose assumptions
+6. **Reversibility analysis**: classify decisions as irreversible (schema, public API, service boundary), moderate (framework), or reversible (library, config). Spend effort proportional to irreversibility.
+7. **Change volatility**: rate each boundary stable/moderate/high. High-volatility justifies modularity investment.
+8. Use \`AskUserQuestion\` to clarify scope and preferences
+
+**Gate 1**: Use \`AskUserQuestion\` to confirm the understanding is complete before proceeding to Spec.
+
+## Phase 2: Spec
+**Goal**: Produce a system-level specification.
+1. Write **system-level EARS requirements** (Ubiquitous/Event/State/Unwanted/Optional patterns)
+2. Produce **architecture diagrams**: C4Context, sequenceDiagram, stateDiagram-v2
+3. Generate a **scenario table** from the EARS requirements
+4. Write the spec to \`docs/specs/<name>.md\` and create a **meta-epic bead**
+
+**Gate 2**: Use \`AskUserQuestion\` to get human approval of the system-level spec.
+
+## Phase 3: Decompose
+**Goal**: Break the system into naturally-scoped epics using DDD bounded contexts.
+
+Spawn **6 parallel subagents** (via Task tool):
+1. **Bounded context mapper**: Identify natural domain boundaries and propose candidate epics
+2. **Dependency analyst**: Structural + change coupling (git history entropy), dependency graph, processing order
+3. **Scope sizer**: "One cook-it cycle" heuristic, cognitive load check (7+/-2 concepts per epic)
+4. **Interface designer**: Explicit contracts (API/data) + implicit contracts (threading, delivery guarantees, timeout/retry, backpressure, resource ownership, failure modes)
+5. **Control structure analyst** (STPA): Identify hazards at composition boundaries, unsafe control actions (commission/omission/timing), propose mitigations
+6. **Structural-semantic gap analyst**: Compare dependency graph partition vs DDD semantic partition, flag disagreements
+
+**Synthesis**: Merge subagent findings into a proposed epic structure. For each epic:
+- Title and scope boundaries (what is in, what is out)
+- Relevant EARS subset from the system spec
+- Interface contracts: explicit (API/data) + implicit (timing, threading, failure modes)
+- Assumptions that must hold for this boundary to remain valid
+- Org alignment: which team type owns this (stream-aligned/platform/enabling/complicated-subsystem)?
+- Pointer to the master spec file
+
+**Multi-criteria validation** before Gate 3 -- for each epic:
+- [ ] Structural: low change coupling, acyclic dependencies
+- [ ] Semantic: stable bounded context, coherent ubiquitous language
+- [ ] Organizational: single team owner, within cognitive budget
+- [ ] Economic: modularity benefit > coordination overhead
+
+**Gate 3**: Use \`AskUserQuestion\` to get human approval of the epic structure, dependency graph, and interface contracts.
+
+## Phase 4: Materialize
+**Goal**: Create the actual beads.
+1. Create epic beads via \`bd create --title="..." --type=epic --priority=<N>\` for each approved epic
+2. Store scope, EARS subset, interface contracts (explicit + implicit), and key assumptions in each epic description
+3. Define **fitness functions** per epic to monitor assumptions. Document re-decomposition trigger.
+4. Wire dependencies via \`bd dep add\` for all relationships
+5. Store processing order as notes on the meta-epic
+6. Capture lessons via \`npx ca learn\`
+
+## Memory Integration
+- \`npx ca search\` before starting each phase
+- \`npx ca knowledge\` for indexed project docs
+- \`npx ca learn\` after corrections or discoveries
+
+## Common Pitfalls
+- Jumping to decomposition without understanding the domain (skip Socratic)
+- Micro-slicing epics too small (each epic should be a natural bounded context, not a single task)
+- Missing interface contracts between epics (coupling will bite during implementation)
+- Not searching memory for past decomposition patterns
+- Skipping human gates (the 3 gates are the quality checkpoints)
+- Creating epics without EARS subset (loses traceability to system spec)
+- Not wiring dependencies (loop will process in wrong order)
+- Treating complex decisions as complicated (Cynefin): service boundaries need experiments, not just analysis
+- Ignoring implicit contracts (threading, timing, backpressure) -- Garlan's architectural mismatch
+- Not capturing assumptions that would invalidate the decomposition if wrong
+
+## Quality Criteria
+- [ ] Socratic phase completed with domain glossary and mindmap
+- [ ] System-level EARS requirements cover all capabilities
+- [ ] Architecture diagrams produced (C4, sequence, state)
+- [ ] Spec written to docs/specs/ and meta-epic created
+- [ ] 6-angle convoy executed for decomposition (DDD + STPA + gap analysis)
+- [ ] Each epic has scope boundaries, EARS subset, interface contracts (explicit + implicit), and assumptions
+- [ ] Dependencies wired via bd dep add
+- [ ] Processing order stored on meta-epic
+- [ ] 3 human gates passed via AskUserQuestion
+- [ ] Memory searched at each phase
 `
 };
 var PHASE_SKILL_REFERENCES = {
@@ -9634,7 +9991,10 @@ async function fetchLatestVersion(packageName = "compound-agent") {
     });
     if (!res.ok) return null;
     const data = await res.json();
-    return data["dist-tags"] ? data["dist-tags"].latest ?? null : null;
+    const tags = data["dist-tags"];
+    if (typeof tags !== "object" || tags === null) return null;
+    const latest = tags["latest"];
+    return typeof latest === "string" ? latest : null;
   } catch {
     return null;
   }
@@ -9647,7 +10007,7 @@ async function checkForUpdate(cacheDir) {
       return {
         current: VERSION,
         latest: cached.latest,
-        updateAvailable: cached.latest !== VERSION
+        updateAvailable: semverGt(cached.latest, VERSION)
       };
     }
     const latest = await fetchLatestVersion();
@@ -9661,7 +10021,7 @@ async function checkForUpdate(cacheDir) {
     return {
       current: VERSION,
       latest,
-      updateAvailable: latest !== VERSION
+      updateAvailable: semverGt(latest, VERSION)
     };
   } catch {
     return null;
@@ -9669,7 +10029,18 @@ async function checkForUpdate(cacheDir) {
 }
 function formatUpdateNotification(current, latest) {
   return `Update available: ${current} -> ${latest}
-Run: pnpm update compound-agent`;
+Run: pnpm update --latest compound-agent`;
+}
+function semverGt(a, b) {
+  const parse = (v) => {
+    const parts = v.split(".").map((n) => parseInt(n, 10) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+  };
+  const [aMaj, aMin, aPat] = parse(a);
+  const [bMaj, bMin, bPat] = parse(b);
+  if (aMaj !== bMaj) return aMaj > bMaj;
+  if (aMin !== bMin) return aMin > bMin;
+  return aPat > bPat;
 }
 function readCache(cachePath) {
   try {
@@ -9796,16 +10167,18 @@ ${formattedLessons}
   if (cookitSection !== null) {
     output += cookitSection;
   }
-  try {
-    const updateResult = await checkForUpdate(join(root, ".claude", ".cache"));
-    if (updateResult?.updateAvailable) {
-      output += `
+  if (!process.stdout.isTTY) {
+    try {
+      const updateResult = await checkForUpdate(join(root, ".claude", ".cache"));
+      if (updateResult?.updateAvailable) {
+        output += `
 ---
 # Update Available
-compound-agent v${updateResult.latest} is available (current: v${updateResult.current}). Run \`pnpm update compound-agent\` to update.
+compound-agent v${updateResult.latest} is available (current: v${updateResult.current}). Run \`pnpm update --latest compound-agent\` to update.
 `;
+      }
+    } catch {
     }
-  } catch {
   }
   return output;
 }
@@ -10532,7 +10905,26 @@ function registerVerifyGatesCommand(program) {
 }
 
 // src/changelog-data.ts
-var CHANGELOG_RECENT = `## [1.7.3] - 2026-03-09
+var CHANGELOG_RECENT = `## [1.7.4] - 2026-03-11
+
+### Added
+
+- **Research-enriched phase skills**: Applied insights from 3 PhD-level research documents (Science of Decomposition, Architecture Under Uncertainty, Emergent Behavior in Composed Systems) across all 6 core phase skills:
+  - **Architect**: reversibility analysis (Baldwin & Clark), change volatility, 6-subagent convoy (added STPA control structure analyst + structural-semantic gap analyst), implicit interface contracts (threading, backpressure, delivery guarantees), organizational alignment (Team Topologies), multi-criteria validation gate (structural/semantic/organizational/economic), assumption capture with fitness functions and re-decomposition triggers
+  - **Spec-dev**: Cynefin classification (Clear/Complicated/Complex), composition EARS templates (timeout/retry interactions), change volatility assessment
+  - **Plan**: boundary stability check, Last Responsible Moment identification, change coupling prevention
+  - **Work**: Fowler technical debt quadrant (only Prudent/Deliberate accepted), composition boundary verification with metastable failure checks
+  - **Review**: composition-specific reviewers (boundary-reviewer, control-structure-reviewer, observability-reviewer), architect assumption validation
+  - **Compound**: decomposition quality assessment, assumption tracking (predicted vs actual), emergence root cause classification (Garlan/STPA/phase transition)
+- **Lint graduation in compound phase**: The compound phase (step 10) now spawns a \`lint-classifier\` subagent that classifies each captured insight as LINTABLE, PARTIAL, or NOT_LINTABLE. High-confidence lintable insights are promoted to beads tasks under a "Linting Improvement" epic with self-contained rule specifications. Two rule classes: Class A (native \`rules.json\` \u2014 regex/glob) and Class B (external linter \u2014 AST analysis).
+- **Linter detection module** (\`src/lint/\`): Scans repos for ESLint (flat + legacy configs including TypeScript variants), Ruff (including \`pyproject.toml\`), Clippy, golangci-lint, ast-grep, and Semgrep. Exported from the package as \`detectLinter()\`, \`LinterInfoSchema\`, \`LinterNameSchema\`.
+- **Lint-classifier agent template**: Ships via \`npx ca init\` to \`.claude/agents/compound/lint-classifier.md\`. Includes 7 few-shot examples, Class A/B routing, and linter-aware task creation.
+
+### Fixed
+
+- **PhD research output path**: \`/compound:get-a-phd\` now writes user-generated research to \`docs/research/\` instead of \`docs/compound/research/\`. The \`docs/compound/\` directory is reserved for shipped library content; project-specific research no longer pollutes it. Overlap scanning checks both directories.
+
+## [1.7.3] - 2026-03-09
 
 ### Added
 
@@ -10574,18 +10966,7 @@ var CHANGELOG_RECENT = `## [1.7.3] - 2026-03-09
 - **Hardcoded model extracted**: Five occurrences of \`'claude-opus-4-6'\` in loop.ts extracted to \`DEFAULT_MODEL\` constant.
 - **EPIC_ID_PATTERN deduplicated**: \`watch.ts\` now imports \`LOOP_EPIC_ID_PATTERN\` from \`loop.ts\` instead of maintaining a duplicate.
 - **\`warn()\` output corrected**: \`shared.ts\` warn helper now writes to \`stderr\` instead of \`stdout\`.
-- **Templates import fixed**: \`templates.ts\` now imports \`VERSION\` from \`../version.js\` instead of barrel re-export.
-
-## [1.7.1] - 2026-03-09
-
-### Added
-
-- **Scenario testing integration**: Spec-dev Phase 3 now generates scenario tables from EARS requirements and Mermaid diagrams with five categories (happy, error, boundary, combinatorial, adversarial). Review phase verifies coverage via a new \`scenario-coverage-reviewer\` agent using heuristic AI-driven matching.
-- **Scenario coverage reviewer**: New medium-tier AgentTeam reviewer that matches test files against epic scenario tables and flags gaps (P1) or partial coverage (P2). Spawned for diffs >100 lines.
-
-### Fixed
-
-- **Stale reviewer count in tests**: Updated "5 reviewer perspectives" test to "6" with \`scenario-coverage\` assertion. Removed no-op \`.replace('security-', 'security-')\` in escalation wiring test.`;
+- **Templates import fixed**: \`templates.ts\` now imports \`VERSION\` from \`../version.js\` instead of barrel re-export.`;
 
 // src/commands/about.ts
 function registerAboutCommand(program) {
@@ -10779,8 +11160,8 @@ function registerKnowledgeIndexCommand(program) {
     }
   });
   program.command("embed-worker <repoRoot>", { hidden: true }).description("Internal: background embedding worker").action(async (repoRoot) => {
-    const { existsSync: existsSync24, statSync: statSync6 } = await import('fs');
-    if (!existsSync24(repoRoot) || !statSync6(repoRoot).isDirectory()) {
+    const { existsSync: existsSync24, statSync: statSync7 } = await import('fs');
+    if (!existsSync24(repoRoot) || !statSync7(repoRoot).isDirectory()) {
       out.error(`Invalid repoRoot: "${repoRoot}" is not a directory`);
       process.exitCode = 1;
       return;
@@ -11169,6 +11550,21 @@ init_embeddings();
 init_search2();
 init_sqlite_knowledge();
 init_compound();
+var LinterNameSchema = z.enum([
+  "eslint",
+  "ruff",
+  "clippy",
+  "golangci-lint",
+  "ast-grep",
+  "semgrep",
+  "unknown"
+]);
+z.object({
+  linter: LinterNameSchema,
+  configPath: z.string().nullable()
+});
+
+// src/index.ts
 init_types();
 
 // src/commands/retrieval.ts
@@ -11493,8 +11889,50 @@ function registerManagementCommands(program) {
 }
 
 // src/commands/loop-templates.ts
-function buildEpicSelector() {
+function buildDependencyCheck() {
   return `
+# check_deps_closed() - Verify all depends_on for an epic are closed
+# Returns 0 if all deps closed (or no deps), 1 if any dep is open
+# Uses the depends_on array from bd show --json (objects with .id/.status)
+check_deps_closed() {
+  local epic_id="$1"
+  local deps_json
+  deps_json=$(bd show "$epic_id" --json 2>/dev/null || echo "")
+  if [ -z "$deps_json" ]; then
+    return 0
+  fi
+  local blocking_dep
+  if [ "$HAS_JQ" = true ]; then
+    blocking_dep=$(echo "$deps_json" | jq -r '
+      if type == "array" then .[0] else . end |
+      (.depends_on // .dependencies // []) |
+      map(select(.status != "closed")) |
+      .[0].id // empty
+    ' 2>/dev/null || echo "")
+  else
+    blocking_dep=$(echo "$deps_json" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+if isinstance(data, list):
+    data = data[0] if data else {}
+deps = data.get('depends_on', data.get('dependencies', []))
+for d in deps:
+    s = d.get('status', 'open') if isinstance(d, dict) else 'open'
+    if s != 'closed':
+        print(d.get('id', d) if isinstance(d, dict) else d)
+        break
+" 2>/dev/null || echo "")
+  fi
+  if [ -n "$blocking_dep" ]; then
+    log "Skip $epic_id: blocked by dependency $blocking_dep (not closed)"
+    return 1
+  fi
+  return 0
+}
+`;
+}
+function buildEpicSelector() {
+  return buildDependencyCheck() + `
 get_next_epic() {
   if [ -n "$EPIC_IDS" ]; then
     for epic_id in $EPIC_IDS; do
@@ -11502,6 +11940,7 @@ get_next_epic() {
       local status
       status=$(bd show "$epic_id" --json 2>/dev/null | parse_json '.status' 2>/dev/null || echo "")
       if [ "$status" = "open" ]; then
+        check_deps_closed "$epic_id" || continue
         echo "$epic_id"
         return 0
       fi
@@ -11512,18 +11951,25 @@ get_next_epic() {
     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
+        check_deps_closed "$id" || continue
         echo "$id"
         break
       done)
     else
-      epic_id=$(bd list --type=epic --ready --json --limit=10 2>/dev/null | python3 -c "
+      # Emit ALL unprocessed candidates so the shell loop can check each one's deps.
+      local candidates epic_id=""
+      candidates=$(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 "")
+        print(item['id'])" 2>/dev/null || echo "")
+      for cid in $candidates; do
+        check_deps_closed "$cid" || continue
+        epic_id="$cid"
+        break
+      done
     fi
     if [ -z "$epic_id" ]; then
       return 1
@@ -12625,12 +13071,19 @@ function createProgram() {
   return program;
 }
 async function runProgram(program, argv = process.argv) {
+  let updatePromise = null;
+  if (process.stdout.isTTY) {
+    try {
+      const cacheDir = join(getRepoRoot(), ".claude", ".cache");
+      updatePromise = checkForUpdate(cacheDir);
+    } catch {
+    }
+  }
   try {
     await program.parseAsync(argv);
-    if (process.stdout.isTTY) {
+    if (updatePromise) {
       try {
-        const cacheDir = join(getRepoRoot(), ".claude", ".cache");
-        const result = await checkForUpdate(cacheDir);
+        const result = await updatePromise;
         if (result?.updateAvailable) {
           console.log(formatUpdateNotification(result.current, result.latest));
         }