dual-brain 4.0.0 → 4.1.0

package/CLAUDE.md

@@ -64,18 +64,49 @@ Profile persists to `.claude/dual-brain.profile.json` (gitignored).
 Switch profiles: `npx dual-brain mode cost-saver`
 Check status: `npx dual-brain status`
 
+Natural language aliases work everywhere: "go aggressive", "be careful", "cheap mode", "fast", "thorough", "smart". The system strips prefixes like "go"/"be"/"use" and resolves to the canonical profile name.
+
 ## Adaptive Routing (Auto Mode)
 
 Auto mode classifies risk from file paths and adjusts routing in real-time:
 
 - **Risk classification**: auth/secrets→critical, billing/migrations→high, tests/utils→medium, docs→low
-- **Failure detection**: 2+ failures on same prompt in 2 hours → auto-escalate tier or trigger dual-brain
+- **Failure detection**: 2+ failures on same prompt in 2 hours → auto-escalate tier or trigger dual-brain. Uses time-weighted decay (recent failures count more) and ledger pruning for entries >24hrs.
 - **Provider balance**: Routes to underused provider when one subscription is hot
+- **Burst awareness**: Suppresses duplicate warnings and balance hints during agent waves (3+ agents in 90s)
+
+## Vibe Coding
+
+Casual natural language → structured work. The vibe coding system translates informal requests into properly routed, risk-classified, quality-gated work.
+
+**Intent compiler** — decompose multi-task requests:
+```bash
+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
+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
+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
 
+- `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
+- `node .claude/hooks/test-orchestrator.mjs` — run self-tests (40 tests)

package/README.md

@@ -51,10 +51,35 @@ npx -y dual-brain
 
 **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
+
+Speak naturally. The orchestrator handles the structure.
+
+```bash
+# Decompose a casual request into structured work
+node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
+
+# Generate a Steve-style execution plan
+node .claude/hooks/plan-generator.mjs --utterance "refactor the auth flow" --write
+
+# Switch profiles with natural language
+npx dual-brain mode "go aggressive"
+npx dual-brain mode "be careful"
+npx dual-brain mode "cheap"
+
+# Check persistent preferences and work 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.
+
 ## Scripts
 
 | Script | Purpose |
 |--------|---------|
+| `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` | Send git diff to GPT for independent review |
 | `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions |
@@ -63,7 +88,7 @@ npx -y dual-brain
 | `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 (39 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 |
 

package/hooks/quality-gate.mjs

@@ -30,6 +30,40 @@ const DUAL_BRAIN = resolve(__dirname, 'dual-brain-review.mjs');
 
 const RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
 
+const APPROVAL_MAP = {
+  low:      { recommendation: 'self_check',           message: 'Low risk — self-check is sufficient' },
+  medium:   { recommendation: 'review_recommended',   message: 'Medium risk — a code review would catch edge cases' },
+  high:     { recommendation: 'dual_brain_review',    message: 'High risk — recommending dual-brain review for safety' },
+  critical: { recommendation: 'user_approval_needed', message: 'Critical risk — this needs your explicit approval before merging' },
+};
+
+/**
+ * Compute approval recommendation from risk level + profile overrides.
+ * Profile escalation: if dual_brain_minimum is at or below the current risk,
+ * escalate the recommendation by one tier (e.g. medium → dual_brain_review
+ * under quality-first where dual_brain_minimum is 'medium').
+ */
+function computeApproval(risk, profileGate) {
+  let effectiveRisk = risk;
+
+  // Profile escalation: when dual_brain_minimum <= risk and the base
+  // recommendation would be below dual_brain_review, escalate one level.
+  const riskIdx = RISK_LEVELS.indexOf(risk);
+  const dualBrainIdx = RISK_LEVELS.indexOf(profileGate.dual_brain_minimum);
+  if (dualBrainIdx >= 0 && riskIdx >= dualBrainIdx && riskIdx < RISK_LEVELS.length - 1) {
+    const baseRec = APPROVAL_MAP[risk].recommendation;
+    if (baseRec !== 'dual_brain_review' && baseRec !== 'user_approval_needed') {
+      effectiveRisk = RISK_LEVELS[riskIdx + 1];
+    }
+  }
+
+  const entry = APPROVAL_MAP[effectiveRisk] || APPROVAL_MAP[risk];
+  return {
+    approval_recommendation: entry.recommendation,
+    approval_message: entry.message,
+  };
+}
+
 function loadProfileGateSettings() {
   try {
     return _getProfileOverrides('quality-gate');
@@ -189,6 +223,7 @@ function main() {
       reason: `${sensitivity.risk} risk — below profile floor (${profileGate.sensitivity_floor})`,
       profile_floor: profileGate.sensitivity_floor,
       files: qualifyingFiles,
+      ...computeApproval(sensitivity.risk, profileGate),
     });
   }
 
@@ -267,6 +302,7 @@ function main() {
   }
 
   // 9. Build output object — common fields first
+  const approval = computeApproval(sensitivity.risk, profileGate);
   const output = {
     gate: gateStatus,
     risk: sensitivity.risk,
@@ -278,6 +314,8 @@ function main() {
     review_path: reviewFile,
     model: reviewResult.model || null,
     auth_type: reviewResult.auth_type || null,
+    approval_recommendation: approval.approval_recommendation,
+    approval_message: approval.approval_message,
   };
 
   // High risk: recommend dual-brain-think in addition

package/hooks/summary-checkpoint.mjs

@@ -16,6 +16,7 @@
  *   getTokenAverages()           → moving averages of actual tokens by tier
  */
 
+import { execSync as _execSync } from 'child_process';
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -65,6 +66,15 @@ function emptySummary() {
       dual_brain_useful: false,
       balance_posture: 'no activity yet',
     },
+
+    // Session handoff fields — enriched checkpoint for cross-session continuity
+    session_handoff: {
+      gate_passed: [],              // completed milestones/tasks this session
+      evidence: [],                 // concrete evidence: commit hashes, file paths, PR URLs
+      pickup_prompt: 'none recorded', // one-sentence continuation prompt
+      friction: [],                 // problems encountered during the session
+      cross_workstream_patterns: [], // generalizable lessons beyond this task
+    },
   };
 }
 
@@ -158,6 +168,57 @@ function applyEntry(summary, entry) {
     avg.avg_output += (entry.output_tokens - avg.avg_output) / avg.count;
   }
 
+  // Session handoff: auto-populate from entry metadata
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  // Track completed gates/milestones from quality-gate or review results
+  if (entry.type === 'gate_result' && entry.gate === 'pass') {
+    summary.session_handoff.gate_passed.push({
+      what: entry.reason || 'quality gate passed',
+      ts,
+    });
+  }
+
+  // Track evidence: file paths from execute-tier entries, commit hashes, PR URLs
+  if (tier === 'execute' && entry.files_changed) {
+    const files = Array.isArray(entry.files_changed) ? entry.files_changed : [entry.files_changed];
+    for (const f of files) {
+      if (!summary.session_handoff.evidence.includes(f)) {
+        summary.session_handoff.evidence.push(f);
+      }
+    }
+  }
+  if (entry.commit_hash) {
+    const ref = `commit:${entry.commit_hash}`;
+    if (!summary.session_handoff.evidence.includes(ref)) {
+      summary.session_handoff.evidence.push(ref);
+    }
+  }
+  if (entry.pr_url) {
+    if (!summary.session_handoff.evidence.includes(entry.pr_url)) {
+      summary.session_handoff.evidence.push(entry.pr_url);
+    }
+  }
+
+  // Track friction: failures, escalations, retries
+  if (entry.type === 'failure' || entry.escalated || entry.retry) {
+    summary.session_handoff.friction.push({
+      what: entry.error || entry.reason || 'unknown failure',
+      tier,
+      provider,
+      ts,
+    });
+    // Keep friction list bounded
+    if (summary.session_handoff.friction.length > 50) {
+      summary.session_handoff.friction = summary.session_handoff.friction.slice(-50);
+    }
+  }
+
   // Codex latencies
   if (entry.codex_startup_ms != null) {
     summary.codex_latencies.push({
@@ -237,6 +298,125 @@ function getAdaptiveCodexThreshold(date) {
   };
 }
 
+/**
+ * Update a specific session handoff field.
+ * Valid keys: gate_passed, evidence, pickup_prompt, friction, cross_workstream_patterns
+ *
+ * For array fields, `value` is appended (string or object).
+ * For pickup_prompt, `value` replaces the current string.
+ */
+function updateHandoff(key, value, date) {
+  const arrayFields = ['gate_passed', 'evidence', 'friction', 'cross_workstream_patterns'];
+  const validKeys = [...arrayFields, 'pickup_prompt'];
+  if (!validKeys.includes(key)) return;
+
+  const summary = readSummary(date);
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  if (key === 'pickup_prompt') {
+    summary.session_handoff.pickup_prompt = String(value);
+  } else if (arrayFields.includes(key)) {
+    if (!Array.isArray(summary.session_handoff[key])) {
+      summary.session_handoff[key] = [];
+    }
+    summary.session_handoff[key].push(value);
+  }
+
+  summary.updated_at = new Date().toISOString();
+  atomicWrite(summaryPath(date), summary);
+  return summary;
+}
+
+/**
+ * Generate a full session checkpoint for handoff.
+ *
+ * Auto-enriches evidence from git state (changed files, HEAD commit)
+ * and builds a pickup prompt if none was set manually.
+ */
+function generateCheckpoint(date) {
+  const summary = readSummary(date);
+
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  const handoff = summary.session_handoff;
+
+  // Auto-enrich evidence from git if available
+  try {
+    // Current HEAD commit
+    const head = _execSync('git rev-parse --short HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (head) {
+      const ref = `commit:${head}`;
+      if (!handoff.evidence.includes(ref)) {
+        handoff.evidence.push(ref);
+      }
+    }
+
+    // Changed files in working tree
+    const diff = _execSync('git diff --name-only HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (diff) {
+      for (const f of diff.split('\n').filter(Boolean)) {
+        const ref = `changed:${f}`;
+        if (!handoff.evidence.includes(ref)) {
+          handoff.evidence.push(ref);
+        }
+      }
+    }
+
+    // Current branch
+    const branch = _execSync('git branch --show-current 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (branch) {
+      handoff.evidence.push(`branch:${branch}`);
+    }
+  } catch {
+    // Git not available — skip enrichment
+  }
+
+  // Auto-generate pickup_prompt if not manually set
+  if (handoff.pickup_prompt === 'none recorded' && summary.totals.calls > 0) {
+    const topTier = Object.entries(summary.totals.by_tier)
+      .sort(([, a], [, b]) => b - a)[0];
+    const tierLabel = topTier ? topTier[0] : 'mixed';
+    const fileCount = handoff.evidence.filter(e => e.startsWith('changed:')).length;
+    const frictionCount = handoff.friction.length;
+
+    let prompt = `Session had ${summary.totals.calls} calls (mostly ${tierLabel})`;
+    if (fileCount > 0) prompt += `, ${fileCount} files modified`;
+    if (frictionCount > 0) prompt += `, ${frictionCount} friction points to review`;
+    prompt += '.';
+    handoff.pickup_prompt = prompt;
+  }
+
+  // Build the checkpoint object
+  const checkpoint = {
+    version: 1,
+    generated_at: new Date().toISOString(),
+    date: summary.date,
+
+    // Existing summary data
+    totals: summary.totals,
+    session_insights: summary.session_insights,
+
+    // New handoff fields
+    gate_passed: handoff.gate_passed,
+    evidence: handoff.evidence,
+    pickup_prompt: handoff.pickup_prompt,
+    friction: handoff.friction,
+    cross_workstream_patterns: handoff.cross_workstream_patterns,
+  };
+
+  return checkpoint;
+}
+
 export {
   readSummary,
   updateSummary,
@@ -246,5 +426,7 @@ export {
   getTokenAverages,
   getAdaptiveCodexThreshold,
   updateSessionInsight,
+  updateHandoff,
+  generateCheckpoint,
   atomicWrite,
 };

package/hooks/vibe-router.mjs

@@ -140,6 +140,46 @@ function determineQualityGates(tasks) {
   return [...gates];
 }
 
+// ─── Ordered Language Detection ───────────────────────────────────────────
+
+const DEPENDENCY_MARKERS = /\b(then|after\s+that|once\s+\S+\s+is\s+done|before|first|next|finally|afterwards|subsequently|followed\s+by|depends?\s+on|requires?)\b/i;
+
+// ─── Subsystem Detection ─────────────────────────────────────────────────
+
+const SUBSYSTEM_PATTERNS = [
+  { key: 'auth', regex: /\b(auth|login|sign[-\s]?in|sign[-\s]?up|session|credential|password|oauth|jwt|token)\b/i },
+  { key: 'billing', regex: /\b(billing|payment|subscription|invoice|charge|stripe|pricing)\b/i },
+  { key: 'api', regex: /\b(api|endpoint|route|controller|handler|middleware|rest|graphql)\b/i },
+  { key: 'ui', regex: /\b(ui|nav|button|page|component|layout|style|css|modal|form|menu|sidebar|header|footer|dashboard)\b/i },
+  { key: 'db', regex: /\b(database|db|schema|migration|model|query|table|column|index|sql|prisma|sequelize|knex)\b/i },
+  { key: 'infra', regex: /\b(deploy|ci|cd|docker|k8s|terraform|infra|pipeline|build|config|env)\b/i },
+  { key: 'test', regex: /\b(test|spec|fixture|mock|stub|assert|coverage)\b/i },
+  { key: 'docs', regex: /\b(doc|readme|changelog|guide|tutorial|comment)\b/i },
+];
+
+function detectSubsystems(text) {
+  const subs = new Set();
+  for (const pat of SUBSYSTEM_PATTERNS) {
+    if (pat.regex.test(text)) subs.add(pat.key);
+  }
+  return subs;
+}
+
+// ─── Risk Domain Extraction ──────────────────────────────────────────────
+
+function getRiskDomains(task) {
+  const domains = new Set();
+  // Use subsystem as risk domain
+  const subs = detectSubsystems(task.title);
+  for (const s of subs) domains.add(s);
+  // Also include explicit risk reason label
+  if (task.reason) {
+    const match = task.reason.match(/^([^(]+)/);
+    if (match) domains.add(match[1].trim().toLowerCase());
+  }
+  return domains;
+}
+
 // ─── Complexity + Wave Recommendation ──────────────────────────────────────
 
 function determineComplexity(tasks) {
@@ -157,18 +197,102 @@ function determineComplexity(tasks) {
   return 'simple';
 }
 
-function determineWave(tasks, complexity) {
-  if (tasks.length === 1) return 'single';
+/**
+ * determineWave — Sequential by default, parallel only when tasks are truly independent.
+ *
+ * Returns { wave, reasons } where reasons is an array of reason codes:
+ *   shared_surface  — tasks likely touch same files
+ *   high_risk       — risky work should be sequential for review
+ *   dependency_marker — ordered language detected in utterance
+ *   same_subsystem  — tasks in same domain/subsystem
+ *   independent     — truly independent, safe for parallel
+ */
+function determineWave(tasks, complexity, utterance) {
+  if (tasks.length === 1) return { wave: 'single', reasons: [] };
+
+  const reasons = [];
+
+  // 1. Check for ordered language in the original utterance
+  if (utterance && DEPENDENCY_MARKERS.test(utterance)) {
+    reasons.push('dependency_marker');
+  }
 
-  // If any task depends on another (sequential markers like "then", "after that"
-  // were used), we already split them but keep sequential recommendation.
-  // For now, check if tasks share the same tier — parallel is fine for independent work.
-  const tiers = new Set(tasks.map(t => t.tier));
+  // 2. Check for high/critical risk tasks
   const hasHighRisk = tasks.some(t => t.risk === 'high' || t.risk === 'critical');
+  if (hasHighRisk) {
+    reasons.push('high_risk');
+  }
+
+  // 3. Check for overlapping subsystems between tasks
+  const taskSubsystems = tasks.map(t => detectSubsystems(t.title));
+  let hasSharedSubsystem = false;
+  for (let i = 0; i < taskSubsystems.length; i++) {
+    for (let j = i + 1; j < taskSubsystems.length; j++) {
+      for (const sub of taskSubsystems[i]) {
+        if (taskSubsystems[j].has(sub)) {
+          hasSharedSubsystem = true;
+          break;
+        }
+      }
+      if (hasSharedSubsystem) break;
+    }
+    if (hasSharedSubsystem) break;
+  }
+  if (hasSharedSubsystem) {
+    reasons.push('same_subsystem');
+  }
+
+  // 4. Check for overlapping file paths / shared surface area
+  const taskPaths = tasks.map(t => extractPaths(t.title));
+  let hasSharedPaths = false;
+  for (let i = 0; i < taskPaths.length; i++) {
+    for (let j = i + 1; j < taskPaths.length; j++) {
+      for (const p of taskPaths[i]) {
+        // Check if any path from task j shares a directory prefix or exact match
+        for (const q of taskPaths[j]) {
+          if (p === q || p.startsWith(q + '/') || q.startsWith(p + '/') ||
+              p.split('/').slice(0, -1).join('/') === q.split('/').slice(0, -1).join('/')) {
+            hasSharedPaths = true;
+            break;
+          }
+        }
+        if (hasSharedPaths) break;
+      }
+      if (hasSharedPaths) break;
+    }
+    if (hasSharedPaths) break;
+  }
+  if (hasSharedPaths) {
+    reasons.push('shared_surface');
+  }
+
+  // 5. Check for shared risk domains
+  const taskDomains = tasks.map(t => getRiskDomains(t));
+  let hasSharedDomain = false;
+  for (let i = 0; i < taskDomains.length; i++) {
+    for (let j = i + 1; j < taskDomains.length; j++) {
+      for (const d of taskDomains[i]) {
+        if (taskDomains[j].has(d)) {
+          hasSharedDomain = true;
+          break;
+        }
+      }
+      if (hasSharedDomain) break;
+    }
+    if (hasSharedDomain) break;
+  }
+  // Only add same_subsystem if not already added (risk domains overlap with subsystems)
+  if (hasSharedDomain && !reasons.includes('same_subsystem')) {
+    reasons.push('same_subsystem');
+  }
+
+  // Decision: parallel ONLY when no sequential reasons found
+  if (reasons.length === 0) {
+    reasons.push('independent');
+    return { wave: 'parallel', reasons };
+  }
 
-  if (hasHighRisk) return 'sequential'; // high-risk tasks need careful ordering
-  if (tiers.size === 1 && complexity !== 'complex') return 'parallel';
-  return 'parallel';
+  return { wave: 'sequential', reasons };
 }
 
 // ─── Summary Generation ────────────────────────────────────────────────────
@@ -229,7 +353,7 @@ function routeVibe(utterance) {
   const profileHint = detectProfileHint(utterance);
   const qualityGates = determineQualityGates(tasks);
   const complexity = determineComplexity(tasks);
-  const wave = determineWave(tasks, complexity);
+  const { wave, reasons } = determineWave(tasks, complexity, utterance);
   const summary = generateSummary(tasks, complexity, wave, qualityGates, profileHint);
 
   return {
@@ -238,6 +362,7 @@ function routeVibe(utterance) {
     profile_hint: profileHint,
     quality_gates: qualityGates,
     wave_recommendation: wave,
+    wave_reasons: reasons,
     summary,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Dual-provider orchestration for Claude Code — tiered routing, budget balancing, and GPT dual-brain review across Claude + OpenAI subscriptions",
   "type": "module",
   "bin": {