dual-brain 4.6.0 → 4.7.1

package/CLAUDE.md

@@ -1,33 +1,7 @@
 # Dual-Brain Orchestrator
 
-> Extension of data-tools by Steve Moraco. Requires replit-tools for full functionality.
-
 This project uses dual-provider orchestration. Config: `.claude/orchestrator.json`.
 
-## Ship Captain — Primary Workflow
-
-The preferred way to start any task:
-
-```bash
-npx dual-brain do "fix the auth bug and write tests"
-```
-
-Automatically: decomposes goal → selects agents via intent detection → executes →
-runs tests → quality gate → self-heals issues (2 retries) → creates branch → opens PR.
-
-**Flags:**
-- `--yolo` — skip confirmations (still runs tests/gate, never auto-merges)
-- `--careful` — confirm every step
-- `--plan-only` — preview the plan without executing
-- `--no-pr` — skip PR creation
-
-**Intent detection** routes goals automatically: `fix`/`add` → execute chain, `explore`/`understand` → search-then-execute chain, `review` → dual-brain review chain.
-
-**Resume an incomplete run:**
-```bash
-npx dual-brain resume
-```
-
 ## Tier Routing
 
 Route subagents by task complexity:
@@ -36,96 +10,56 @@ Route subagents by task complexity:
 - **Execute** (`model: "sonnet"`): Edits, tests, git ops. Return: files changed, tests run, edge cases.
 - **Think** (main session, Opus): Architecture, review, planning. Return: decision, alternatives, risks.
 
-The `enforce-tier` hook **blocks** severe mismatches in auto/balanced/quality-first profiles rather than just warning.
-
-## Agent Templates
-
-Pre-built specialist agents for common tasks:
-
-```bash
-npx dual-brain agents                    # list all templates
-```
-
-Templates include `explorer`, `fixer`, `reviewer`, `tester`, and more. Ship Captain selects the right template automatically based on intent detection.
-
-## Agent Chains
-
-Multi-step workflows that compose templates:
-
-```bash
-npx dual-brain chains                    # list all chains
-npx dual-brain do "explore auth then fix" # auto-selects explore-then-fix chain
-```
-
-Built-in chains: `explore-then-fix`, `test-and-fix`, `review-and-apply`.
-
 ## GPT Lane
 
 For isolated or parallel work, dispatch to GPT via Codex CLI:
 
-- `npx dual-brain dispatch --task "..." --model gpt-5.4` — execution tasks
+- `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --model gpt-5.4` — execution tasks
 
 ## Dual-Brain Collaboration
 
-Think and review now auto-complete the full 2-round dialogue by default.
+Dual-brain is a multi-round conversation between Claude and GPT — not a single-shot dispatch.
 
 **Think flow** (architecture decisions):
-
-```bash
-npx dual-brain think --question "should we use Redis?"
-# → GPT Round 1 → Claude analysis → GPT Round 2 → Synthesis
-```
-
-Use `--manual` to step through rounds yourself:
-1. Round 1: `npx dual-brain think --question "..." --manual`
-2. You analyze independently
-3. Round 2: `npx dual-brain think --question "..." --round 2 --claude-says "<your analysis>"`
+1. Round 1: `node .claude/hooks/dual-brain-think.mjs --question "..."`
+   → GPT gives independent analysis
+2. You analyze the same question independently
+3. Round 2: `node .claude/hooks/dual-brain-think.mjs --question "..." --round 2 --claude-says "<your analysis>"`
+   → GPT responds to your points: agreements, pushback, refined recommendation
 4. You synthesize both rounds into a final decision
 
 **Review flow** (code review):
-
-```bash
-npx dual-brain review
-# → GPT Round 1 → Claude review → GPT Round 2 → Final verdict
-```
-
-Use `--manual` for the old step-by-step flow.
+1. Round 1: `node .claude/hooks/dual-brain-review.mjs`
+   → GPT reviews the diff independently
+2. You review the same diff independently
+3. Round 2: `node .claude/hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"`
+   → GPT confirms shared findings, acknowledges misses, disputes false positives
+4. You synthesize into a final review verdict
 
 ## Routing Rules
 
 1. Tasks under 3 min → Claude (Codex startup overhead not worth it)
-2. Isolated tasks over 3 min → check balance: `npx dual-brain budget`
-3. High-risk decisions → dual-brain think (auto-triggered by hooks in auto mode)
+2. Isolated tasks over 3 min → check balance: `node .claude/hooks/budget-balancer.mjs`
+3. High-risk decisions → dual-brain think
 4. When a task spans tiers: think > execute > search
 
 ## Quality Gate
 
 Before ending a session with code changes:
-1. Run `npx dual-brain report`
-2. Run `npx dual-brain gate`
+1. Run `node .claude/hooks/session-report.mjs`
+2. Run `node .claude/hooks/quality-gate.mjs`
 
 Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (GPT unavailable).
 
-**Self-healing:** When Ship Captain is running, gate issues are automatically fixed and retried up to 2 times. Test failures are also auto-fixed (2 retries) before surfacing to the user.
-
-## Recovery
-
-```bash
-npx dual-brain doctor    # check system health and report issues
-npx dual-brain repair    # fix corrupt files, stale locks, re-register hooks
-npx dual-brain reset     # clear all state files (keeps config/hooks)
-npx dual-brain resume    # resume last incomplete Ship Captain run
-```
-
 ## Profiles
 
 Active profile controls routing posture, budgets, and quality gate behavior.
 Profile persists to `.claude/dual-brain.profile.json` (gitignored).
 
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Uses file-path risk classification and failure-loop detection to auto-escalate when needed. Blocks major tier mismatches.
-- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk. Blocks major mismatches.
-- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical. Warns on major mismatches (does not block).
-- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews. Blocks minor and major mismatches.
+- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Uses file-path risk classification and failure-loop detection to auto-escalate when needed.
+- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk
+- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical
+- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews
 
 Switch profiles: `npx dual-brain mode cost-saver`
 Check status: `npx dual-brain status`
@@ -147,61 +81,32 @@ Casual natural language → structured work. The vibe coding system translates i
 
 **Intent compiler** — decompose multi-task requests:
 ```bash
-npx dual-brain vibe "fix the login bug and also update the nav"
+node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
 ```
 Returns structured tasks with tier/risk classification, complexity level, quality gates, and wave strategy.
 
 **Plan generator** — Steve-style 3-part markdown plans:
 ```bash
-npx dual-brain plan --utterance "..." [--write]
+node .claude/hooks/plan-generator.mjs --utterance "..." [--write]
 ```
 Generates: (1) dependency-ordered task table, (2) user stories + edge cases, (3) questions with suggested answers. Pass `--write` to save to `.claude/plans/`.
 
 **Durable memory** — preferences persist across sessions:
 ```bash
-npx dual-brain memory                              # show state
-npx dual-brain memory --set preferences.risk_tolerance=careful
-npx dual-brain memory --threads                    # active work
-npx dual-brain memory --infer                      # preference suggestions
+node .claude/hooks/vibe-memory.mjs                              # show state
+node .claude/hooks/vibe-memory.mjs --set preferences.risk_tolerance=careful
+node .claude/hooks/vibe-memory.mjs --threads                    # active work
+node .claude/hooks/vibe-memory.mjs --infer                      # preference suggestions
 ```
 Tracks preferred profile, risk tolerance, active threads, and learns from usage patterns.
 
 ## Available Tools
 
-All commands available via `npx dual-brain <command>`:
-
-**Primary workflow:**
-- `npx dual-brain do "..."` — Ship Captain: goal → plan → execute → gate → PR
-- `npx dual-brain resume` — resume last incomplete run
-
-**Collaboration:**
-- `npx dual-brain think --question "..."` — dual-brain think (auto 2-round; `--manual` for step-by-step)
-- `npx dual-brain review` — dual-brain code review (auto 2-round; `--manual` for step-by-step)
-- `npx dual-brain dispatch --task "..."` — dispatch work to GPT
-
-**Vibe coding:**
-- `npx dual-brain vibe "..."` — decompose casual requests into structured work
-- `npx dual-brain plan --utterance "..."` — generate execution plans
-- `npx dual-brain memory` — persistent preferences and work threads
-
-**Agents and chains:**
-- `npx dual-brain agents` — list agent templates
-- `npx dual-brain chains` — list agent chains
-
-**Quality and reporting:**
-- `npx dual-brain gate` — run quality gate
-- `npx dual-brain report` — generate session report
-- `npx dual-brain cost` — activity and cost estimates
-- `npx dual-brain ledger` — routing outcome insights
-
-**Profiles and config:**
-- `npx dual-brain mode <profile>` — switch profile
-- `npx dual-brain status` — current profile and provider health
-- `npx dual-brain budget` — provider balance status
-
-**Recovery:**
-- `npx dual-brain doctor` — check system health and report issues
-- `npx dual-brain repair` — fix corrupt files, stale locks, re-register hooks
-- `npx dual-brain reset` — clear all state files (keeps config/hooks)
-- `npx dual-brain health` — verify all hooks and dependencies
-- `npx dual-brain test` — run self-tests (78 tests)
+- `node .claude/hooks/vibe-router.mjs "..."` — decompose casual requests into structured work
+- `node .claude/hooks/plan-generator.mjs --utterance "..."` — generate execution plans
+- `node .claude/hooks/vibe-memory.mjs` — persistent preferences and work threads
+- `node .claude/hooks/cost-report.mjs` — activity and cost estimates
+- `node .claude/hooks/health-check.mjs` — verify system health
+- `node .claude/hooks/budget-balancer.mjs` — provider balance status
+- `node .claude/hooks/decision-ledger.mjs` — routing outcome insights
+- `node .claude/hooks/test-orchestrator.mjs` — run self-tests (40 tests)

package/README.md

@@ -1,10 +1,5 @@
 # Dual-Brain Orchestrator
 
-> **Part of the [data-tools](https://github.com/stevemoraco) ecosystem by Steve Moraco**
-> 
-> dual-brain extends data-tools/replit-tools with dual-provider AI orchestration.
-> Best experienced with replit-tools installed for persistent auth, session management, and container survival.
-
 One command. Both brains. Auto-detected. Auto-configured. Default profile: **auto**.
 
 Dual-provider orchestration for Claude Code across Claude and OpenAI subscriptions. Routes search to cheap models, execution to mid-tier, thinking to the most capable. Dispatches work to GPT via Codex CLI. Dual-brain analysis for high-risk decisions.
@@ -41,10 +36,10 @@ npx -y dual-brain
 
 ## How it works
 
-**Two enforcement hooks** are registered in `.claude/settings.json` and fire on each tool use:
+**Two advisory hooks** are registered in `.claude/settings.json` and fire on each tool use. They detect and recommend — they do not execute actions without user confirmation:
 
-- **enforce-tier.mjs** (PreToolUse on Agent): Classifies tasks, assigns the correct model tier, detects duplicates, suggests cross-provider routing. **Blocks severe mismatches** — in auto/balanced/quality-first profiles, major tier mismatches return a hard block rather than a warning.
-- **cost-logger.mjs** (PostToolUse on all tools): Logs usage to daily rotated files for cost tracking.
+- **enforce-tier.mjs** (PreToolUse on Agent): Classifies tasks, recommends the correct model tier, detects duplicates, suggests cross-provider routing
+- **cost-logger.mjs** (PostToolUse on all tools): Logs usage to daily rotated files for cost tracking
 
 **Three tiers route work by complexity:**
 
@@ -54,28 +49,7 @@ npx -y dual-brain
 | Execute | Sonnet | GPT-5.4 | edits, tests, git ops |
 | Think | Opus | GPT-5.5 | architecture, review, planning |
 
-**Dual-brain** is triggered automatically for high-risk decisions — hooks detect the risk level and initiate dual-brain analysis, where both providers think on the same problem independently. Think and review now run the full 2-round dialogue automatically in one command.
-
-**Intent detection** — the Ship Captain reads your natural language goal and routes it to the right chain automatically: `fix` → execute, `explore`/`understand` → search-then-execute, `review` → dual-brain review.
-
-**Self-healing** — gate issues and test failures are automatically retried up to 2 times before surfacing to the user.
-
-## Ship Captain — Intent to PR
-
-One command does everything:
-
-```bash
-npx dual-brain do "fix the auth bug and write tests"
-```
-
-Automatically: decomposes goal → selects agents → executes → runs tests →
-quality gate → self-heals issues (2 retries) → creates branch → opens PR.
-
-Flags:
-- `--yolo` — skip confirmations (still tests/gates, never merges)
-- `--careful` — confirm every step
-- `--plan-only` — preview without executing
-- `--no-pr` — skip PR creation
+**Dual-brain** is recommended automatically for high-risk decisions — hooks detect the risk level and suggest dual-brain analysis, where both providers think on the same problem independently.
 
 ## Vibe Coding
 
@@ -83,10 +57,10 @@ Speak naturally. The orchestrator handles the structure.
 
 ```bash
 # Decompose a casual request into structured work
-npx dual-brain vibe "fix the login bug and also update the nav"
+node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
 
 # Generate a Steve-style execution plan
-npx dual-brain plan --utterance "refactor the auth flow" --write
+node .claude/hooks/plan-generator.mjs --utterance "refactor the auth flow" --write
 
 # Switch profiles with natural language
 npx dual-brain mode "go aggressive"
@@ -94,163 +68,40 @@ npx dual-brain mode "be careful"
 npx dual-brain mode "cheap"
 
 # Check persistent preferences and work threads
-npx dual-brain memory --threads
+node .claude/hooks/vibe-memory.mjs --threads
 ```
 
 The vibe-router splits multi-task requests, classifies risk, assigns tiers, and recommends quality gates. The plan-generator produces 3-part plans (dependency-ordered tasks, user stories, questions with suggested answers). Vibe-memory learns your preferences over time.
 
-## Automatic Collaboration
-
-Think and review now auto-complete the full 2-round dialogue:
-
-```bash
-npx dual-brain think --question "should we use Redis?"
-# → GPT Round 1 → Claude analysis → GPT Round 2 → Synthesis
-```
-
-Use `--manual` to step through rounds yourself (old behavior).
-
-## Agent Templates and Chains
-
-Pre-built specialist agents and opinionated multi-step workflows:
-
-```bash
-npx dual-brain agents                          # list all templates
-npx dual-brain chains                          # list all chains
-npx dual-brain do "explore auth then fix bug"  # auto-selects explore-then-fix chain
-```
-
-Templates include: `explorer`, `fixer`, `reviewer`, `tester`, and more. Chains compose templates into end-to-end workflows — `explore-then-fix`, `test-and-fix`, `review-and-apply`.
-
-## Commands
-
-### Primary workflow
-
-```bash
-npx dual-brain do "..."           # Ship Captain: goal → PR in one command
-npx dual-brain do "..." --yolo    # Skip confirmations
-npx dual-brain do "..." --careful # Confirm every step
-npx dual-brain do "..." --plan-only  # Preview plan without executing
-npx dual-brain do "..." --no-pr   # Skip PR creation
-npx dual-brain resume             # Resume last incomplete run
-```
-
-### Collaboration
-
-```bash
-npx dual-brain think --question "..."   # Dual-brain think (auto 2-round)
-npx dual-brain review                   # Dual-brain code review (auto 2-round)
-npx dual-brain dispatch --task "..."    # Dispatch task to GPT
-```
-
-### Vibe coding
-
-```bash
-npx dual-brain vibe "..."              # Decompose casual request
-npx dual-brain plan --utterance "..."  # Generate execution plan
-npx dual-brain memory                  # Show preferences and threads
-```
-
-### Agents and chains
-
-```bash
-npx dual-brain agents    # List agent templates
-npx dual-brain chains    # List agent chains
-```
-
-### Quality and reporting
-
-```bash
-npx dual-brain gate      # Run quality gate
-npx dual-brain report    # Session report
-npx dual-brain cost      # Activity and cost estimates
-npx dual-brain ledger    # Routing outcome insights
-```
-
-### Profiles and config
-
-```bash
-npx dual-brain mode cost-saver   # Switch profile
-npx dual-brain status            # Current profile and provider health
-npx dual-brain budget            # Provider balance status
-```
-
-### Recovery
-
-```bash
-npx dual-brain doctor    # Check system health and report issues
-npx dual-brain repair    # Fix corrupt files, stale locks, re-register hooks
-npx dual-brain reset     # Clear all state files (keeps config/hooks)
-npx dual-brain health    # Verify all hooks and dependencies
-```
-
-### Install
-
-```bash
-npx -y dual-brain              # detect, configure, install
-npx dual-brain --force          # overwrite all config
-npx dual-brain --dry-run        # detect only, don't write
-npx dual-brain --json           # output detection as JSON
-npx dual-brain --help           # show help
-npx dual-brain --uninstall      # remove hooks and clean state
-```
-
-## Profiles
-
-The active profile controls routing posture, budgets, and quality gate behavior. Default: **auto**.
-
-```bash
-npx dual-brain mode cost-saver   # switch profile
-npx dual-brain status            # check current profile and provider health
-```
-
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Auto-escalates tier on repeated failures. Blocks major tier mismatches.
-- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk.
-- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work. Warns on major mismatches (does not block).
-- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews. Blocks both minor and major mismatches.
-
-## Troubleshooting
-
-**Hooks not firing** — Run `npx dual-brain doctor`. Check that `.claude/settings.json` has the hook entries. Run `npx dual-brain repair` to re-register.
-
-**Codex/GPT features unavailable** — Run `codex --version` and `codex login`. If Codex CLI isn't installed: `npm i -g @openai/codex`. Re-run `npx dual-brain` to detect.
-
-**Auth expired** — Run `claude login` for Claude, `codex login` for OpenAI. Re-run `npx dual-brain` to re-detect.
-
-**Duplicate warnings every time** — Normal during agent waves (3+ agents in 90s). The system auto-suppresses. If persistent with single agents, check for identical task descriptions.
-
-**Budget warnings too aggressive/too lenient** — Switch profile: `npx dual-brain mode cost-saver` or `npx dual-brain mode quality-first`. Or set custom limits with `npx dual-brain budget <session$> [daily$]`.
-
-**Corrupt state / weird behavior** — Run `npx dual-brain repair` for automatic fixes, or `npx dual-brain reset --force` to wipe all state files.
-
-**Multiple Claude Code sessions** — State files may have brief write conflicts. Each session tracks independently. Use a single session for best results.
-
-**Incomplete run** — Use `npx dual-brain resume` to continue where Ship Captain left off.
-
-**Uninstall** — `npx dual-brain --uninstall` removes hooks from settings.json and cleans state files.
-
 ## Scripts
 
 | Script | Purpose |
 |--------|---------|
-| `hooks/ship-captain.mjs` | End-to-end executor: goal → plan → execute → gate → PR |
-| `hooks/agent-templates.mjs` | Pre-built specialist agent templates |
-| `hooks/agent-chains.mjs` | Multi-step agent workflows (explore-then-fix, etc.) |
 | `hooks/vibe-router.mjs` | Decompose casual language into structured work orders |
 | `hooks/plan-generator.mjs` | Generate Steve-style 3-part execution plans |
 | `hooks/vibe-memory.mjs` | Persistent preferences, work threads, preference inference |
 | `hooks/cost-report.mjs` | Activity & cost estimates by model tier |
-| `hooks/dual-brain-review.mjs` | Dual-brain code review (auto 2-round) |
-| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions (auto 2-round) |
+| `hooks/dual-brain-review.mjs` | Send git diff to GPT for independent review |
+| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions |
 | `hooks/quality-gate.mjs` | Sensitivity-scored quality gate with review artifacts |
 | `hooks/budget-balancer.mjs` | Provider balance and routing recommendations |
 | `hooks/gpt-work-dispatcher.mjs` | Dispatch execution tasks to GPT via Codex CLI |
 | `hooks/session-report.mjs` | Session-end summary: activity, compliance, quality |
 | `hooks/health-check.mjs` | Verify all hooks and dependencies are working |
-| `hooks/test-orchestrator.mjs` | Self-test harness (78 tests) |
+| `hooks/test-orchestrator.mjs` | Self-test harness (40 tests) |
 | `hooks/setup-wizard.mjs` | Interactive config (optional — for custom plans) |
 | `hooks/install-git-hooks.mjs` | Git pre-commit hook for quality gate |
 
+## CLI options
+
+```bash
+npx -y dual-brain              # detect, configure, install
+npx dual-brain --force          # overwrite all config
+npx dual-brain --dry-run        # detect only, don't write
+npx dual-brain --json           # output detection as JSON
+npx dual-brain --help           # show help
+```
+
 ## Customize
 
 After install, edit these files:
@@ -259,20 +110,24 @@ After install, edit these files:
 - `review-rules.md` — project-specific rules for GPT code review
 - `settings.json` — hook registrations (auto-generated, safe to extend)
 
+## Profiles
+
+The active profile controls routing posture, budgets, and quality gate behavior. Default: **auto**.
+
+```bash
+npx dual-brain mode cost-saver   # switch profile
+npx dual-brain status            # check current profile and provider health
+```
+
+- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Auto-escalates tier on repeated failures.
+- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk.
+- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work.
+- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews.
+
 ## Requirements
 
 - Node 20+
 - Claude Code (any subscription tier)
 - Codex CLI (optional) — `npm i -g @openai/codex && codex login`
-- replit-tools (recommended on Replit) — `npx -y replit-tools` — provides persistent auth, session management, and container survival
 
 Works with any subscription combination. Without OpenAI, GPT features gracefully degrade — all work routes through Claude.
-On Replit, replit-tools is strongly recommended — dual-brain's persistent state features depend on it.
-
-## Credits
-
-Built as an extension of **data-tools** by [Steve Moraco](https://github.com/stevemoraco).
-
-data-tools/replit-tools provides the foundation: persistent state across container restarts,
-multi-terminal session management, auto-updating scripts, and SSH key persistence.
-dual-brain adds dual-provider orchestration on top.