dual-brain 7.1.23 → 7.1.24

package/bin/dual-brain.mjs

@@ -1483,9 +1483,9 @@ function detectInterruptedWork(sessions, cwd) {
  * Shows: "● Claude  ● OpenAI  ⚖️  Balanced"
  * Uses ANSI color codes for the dots — no dollar amounts or usage bars.
  */
-function buildProviderStatusLine(profile, auth, maxWidth = 54) {
-  const GREEN = '●';
-  const RED   = '●';
+function buildProviderStatusLine(profile, auth) {
+  const GREEN = '\x1b[32m●\x1b[0m';
+  const RED   = '\x1b[31m●\x1b[0m';
 
   const claudeDot = auth.claude.found ? GREEN : RED;
   const openaiDot = auth.openai.found ? GREEN : RED;
@@ -1498,30 +1498,11 @@ function buildProviderStatusLine(profile, auth, maxWidth = 54) {
     'solo-claude':   '⚡ Fast',
     'solo-openai':   '⚡ Fast',
   };
-  const WORK_STYLE_TIPS = {
-    'auto':          'adapts routing by task risk',
-    'cost-saver':    'single model, minimal reviews',
-    'balanced':      'smart routing, reviews when needed',
-    'quality-first': 'dual-brain on everything important',
-    'solo-claude':   'Claude only, no GPT dispatch',
-    'solo-openai':   'OpenAI only, no Claude dispatch',
-  };
   const bias  = profile?.bias || profile?.mode || 'balanced';
   const label = WORK_STYLE_LABELS[bias] || '⚖️  Balanced';
-  const fullTip = WORK_STYLE_TIPS[bias] || 'smart routing, reviews when needed';
-
-  // Trim tip to fit within box width (measure visible chars: strip ANSI + variation selectors)
-  const labelPlain = label.replace(/[︀-️]/g, '').replace(/[[0-9;]*m/g, '');
-  const prefixLen = ('● Claude  ● OpenAI  ' + labelPlain + ' — ').length;
-  const tipMax = maxWidth - prefixLen;
-  const tip = tipMax >= 6
-    ? (fullTip.length > tipMax ? fullTip.slice(0, tipMax - 1) + '…' : fullTip)
-    : '';
 
-  const suffix = tip ? ` — ${tip}` : '';
-  return `${claudeDot} Claude  ${openaiDot} OpenAI  ${label}${suffix}`;
+  return `${claudeDot} Claude     ${openaiDot} OpenAI     ${label}`;
 }
-
 /**
  * Render a box row padded to inner width W (stripping ANSI for length calculation).
  * Returns a string like: "│ content padded to W │"
@@ -1609,25 +1590,6 @@ async function mainScreen(rl, ask) {
 
   const row = (content) => makeBoxRow(content, W);
 
-  // ── Header: one line above the box ────────────────────────────────────────
-  process.stdout.write(`\n🧠 dual-brain v${version}\n`);
-  {
-    let gitName = '';
-    try {
-      const { execSync } = await import('node:child_process');
-      gitName = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
-    } catch { /* ignore */ }
-    if (gitName) {
-      const hour = new Date().getHours();
-      let greet;
-      if (hour >= 5 && hour <= 11)  greet = 'Good morning';
-      else if (hour >= 12 && hour <= 16) greet = 'Good afternoon';
-      else if (hour >= 17 && hour <= 21) greet = 'Good evening';
-      else                               greet = 'Late night';
-      process.stdout.write(`\x1b[2m${greet}, ${gitName}\x1b[0m\n`);
-    }
-  }
-
   // ── Continuation card (interrupted work) ─────────────────────────────────
   if (interrupted) {
     const ctop = `┌${'─'.repeat(boxW - 2)}┐`;
@@ -1706,15 +1668,74 @@ async function mainScreen(rl, ask) {
     // 's' → fall through to normal dashboard
   }
 
-  // ── Status section ────────────────────────────────────────────────────────
-  const providerLine = buildProviderStatusLine(profile, auth, W);
+  // ── Box 1 — Header row data ─────────────────────────────────────────────
+  const providerLine = buildProviderStatusLine(profile, auth);
 
-  const statusRows = [row(providerLine)];
-  if (dtVersion) {
-    statusRows.push(row(`\x1b[2m📦 replit-tools v${dtVersion}\x1b[0m`));
+  // ── Box 2 — Workspace: gather git data ───────────────────────────────────
+  let gitBranch       = 'unknown';
+  let gitUncommitted  = 0;
+  let gitAheadCount   = 0;
+  let gitLastMsg      = '';
+  let gitLastAgo      = '';
+
+  try {
+    gitBranch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', {
+      cwd, encoding: 'utf8', timeout: 2000, stdio: 'pipe',
+    }).trim() || 'unknown';
+  } catch {}
+
+  try {
+    const status = execSync('git status --porcelain 2>/dev/null', {
+      cwd, encoding: 'utf8', timeout: 2000, stdio: 'pipe',
+    });
+    gitUncommitted = status.trim().split('\n').filter(Boolean).length;
+  } catch {}
+
+  try {
+    const aheadOut = execSync('git rev-list @{u}..HEAD 2>/dev/null | wc -l', {
+      cwd, encoding: 'utf8', timeout: 2000, stdio: 'pipe',
+    });
+    gitAheadCount = parseInt(aheadOut.trim(), 10) || 0;
+  } catch {}
+
+  try {
+    const logOut = execSync('git log -1 --format="%s|%ct" 2>/dev/null', {
+      cwd, encoding: 'utf8', timeout: 2000, stdio: 'pipe',
+    }).trim();
+    if (logOut) {
+      const [msg, ts] = logOut.split('|');
+      gitLastMsg = (msg || '').slice(0, 38);
+      const ageMs  = Date.now() - (parseInt(ts, 10) * 1000);
+      const ageMin = Math.floor(ageMs / 60000);
+      if (ageMin < 60)         gitLastAgo = `${ageMin}m ago`;
+      else if (ageMin < 1440)  gitLastAgo = `${Math.floor(ageMin / 60)}h ago`;
+      else                     gitLastAgo = `${Math.floor(ageMin / 1440)}d ago`;
+    }
+  } catch {}
+
+  // ── Box 2 rows ────────────────────────────────────────────────────────────
+  const uncommittedPart = gitUncommitted > 0 ? ` · ${gitUncommitted} uncommitted` : '';
+  const aheadPart       = gitAheadCount  > 0 ? ` · ${gitAheadCount} ahead`       : '';
+  const workspaceLine1  = `${gitBranch}${uncommittedPart}${aheadPart}`;
+  const workspaceLine2  = gitLastMsg
+    ? `Last: ${gitLastMsg} (${gitLastAgo})`
+    : '';
+
+  // Open PRs
+  const repoState = detectRepoState(cwd);
+  const openPRs   = await detectOpenPRs(cwd);
+
+  const workspaceRows = [row(workspaceLine1)];
+  if (workspaceLine2) workspaceRows.push(row(workspaceLine2));
+  if (openPRs.length > 0) {
+    workspaceRows.push(row(`${openPRs.length} open PR${openPRs.length === 1 ? '' : 's'}`));
   }
 
-  // ── Observer observations (top 2, high priority first) ───────────────────
+  // ── Box 3 — Awareness: observer + roadmap + risk ──────────────────────────
+  let awarenessLine1 = '\x1b[2m💡\x1b[0m Ready to work';
+  let awarenessLine2 = '\x1b[2m📋 No roadmap yet\x1b[0m';
+  let awarenessLine3 = '\x1b[32m✓\x1b[0m No risk flags';
+
   let quickObservations = [];
   try {
     const observerMod = await import('../src/observer.mjs');
@@ -1724,64 +1745,39 @@ async function mainScreen(rl, ask) {
       const sorted = [...quickState.observations].sort(
         (a, b) => (PRIO[a.priority] ?? 2) - (PRIO[b.priority] ?? 2)
       );
-      quickObservations = sorted.slice(0, 2);
-      for (const obs of quickObservations) {
-        let prefix;
-        if (obs.priority === 'high')   prefix = '🔴';
-        else if (obs.priority === 'medium') prefix = '🟡';
-        else                                prefix = '\x1b[2m💡\x1b[0m';
-        statusRows.push(row(`${prefix} ${obs.message}`));
+      quickObservations = sorted.slice(0, 3);
+      const top = quickObservations[0];
+      if (top) {
+        const prefix = top.priority === 'high' ? '🔴' : top.priority === 'medium' ? '🟡' : '\x1b[2m💡\x1b[0m';
+        awarenessLine1 = `${prefix} ${top.message}`;
+      }
+      const hasHighRisk = quickObservations.some(o => o.priority === 'high');
+      if (hasHighRisk) {
+        awarenessLine3 = '\x1b[31m⚠\x1b[0m  Risk flags detected — run: dual-brain review';
       }
     }
-  } catch { /* non-fatal — module may not exist yet */ }
-
-  // ── Action cards (git state + open PRs) ──────────────────────────────────
-  const repoState  = detectRepoState(cwd);
-  const openPRs    = await detectOpenPRs(cwd);
-  const actionRows = buildActionRows(repoState, row, openPRs);
-
-  // ── High-priority observer action cards ───────────────────────────────────
-  if (quickObservations.some(o => o.priority === 'high')) {
-    const DIM   = '\x1b[2m';
-    const RESET = '\x1b[0m';
-    actionRows.push(row(`${DIM}[r] Security review  [t] Run tests  [c] Commit${RESET}`));
-  }
+  } catch { /* non-fatal — observer may not exist */ }
 
-  // ── Related sessions hint (only when no continuation card is showing) ─────
-  if (!interrupted && recentSessions.length > 0) {
-    try {
-      const { findRelatedSessions } = await import('../src/session.mjs');
-      const mostRecent = recentSessions[0];
-      // Build a pseudo-prompt from the most recent session's name/objective
-      const recentPrompt = mostRecent.name || '';
-      // Load session index to get files for the most recent session
-      const indexPath = join(cwd, '.dualbrain', 'session-index.json');
-      let recentFiles = [];
-      try {
-        const idx = JSON.parse(readFileSync(indexPath, 'utf8'));
-        recentFiles = idx[mostRecent.id]?.files || [];
-      } catch {}
-      const related = findRelatedSessions(recentPrompt, recentFiles, cwd);
-      if (related.length > 0) {
-        const relAgeLabel = (isoDate) => {
-          if (!isoDate) return '';
-          const diff  = Date.now() - Date.parse(isoDate);
-          const days  = Math.floor(diff / 86400000);
-          const hours = Math.floor(diff / 3600000);
-          if (days >= 1) return `${days}d`;
-          return `${hours}h ago`;
-        };
-        const relatedParts = related.slice(0, 2).map(r => {
-          const age = relAgeLabel(r.date);
-          return age ? `${r.smartName} (${age})` : r.smartName;
-        });
-        const DIM   = '\x1b[2m';
-        const RESET = '\x1b[0m';
-        actionRows.push(row(`${DIM}📎 Related: ${relatedParts.join(', ')}${RESET}`));
+  // Try roadmap file
+  try {
+    const roadmapPath = join(cwd, '.dual-brain', 'roadmap.md');
+    if (existsSync(roadmapPath)) {
+      const roadmapText = readFileSync(roadmapPath, 'utf8');
+      const lines = roadmapText.split('\n').filter(Boolean);
+      // Skip heading lines, grab first non-heading line
+      const firstItem = lines.find(l => !l.startsWith('#') && l.trim().length > 0);
+      if (firstItem) {
+        const clean = firstItem.replace(/^[-*>]+\s*/, '').trim().slice(0, 45);
+        awarenessLine2 = `\x1b[2m📋\x1b[0m ${clean}`;
       }
-    } catch { /* non-fatal */ }
-  }
-  // ── End related sessions hint ─────────────────────────────────────────────
+    }
+  } catch { /* non-fatal */ }
+
+  const awarenessRows = [
+    row(awarenessLine1),
+    row(awarenessLine2),
+    row(awarenessLine3),
+  ];
 
   // ── Sessions section ──────────────────────────────────────────────────────
   const sessionRows = [];
@@ -1837,23 +1833,28 @@ async function mainScreen(rl, ask) {
     });
   }
 
-  // ── Actions bar — navigation only (pipeline verbs are internal stages, not menu items) ─
-  const actionsContent = 'n New session  / Search  q Quit';
+  // ── Box 5 — Input bar ──────────────────────────────────────────────────
+  const actionsContent = '> type anything...   [s] settings  [/] search  [q] quit';
   const actionsRow     = row(actionsContent);
 
-  // ── Print the full box ────────────────────────────────────────────────────
-  // Include action cards between status and sessions (with separators only when non-empty)
-  const poweredByRow = row('\x1b[2mPowered by dual-brain\x1b[0m');
+  // ── Print the full 5-box layout ───────────────────────────────────────────
+  // Box 1: header (title + provider dots + work style)
+  // Box 2: workspace (branch · uncommitted · ahead, last commit, open PRs)
+  // Box 3: awareness (observer, roadmap, risk)
+  // Box 4: sessions
+  // Box 5: input bar
   const lines = [
     top,
-    ...statusRows,
-    ...(actionRows.length > 0 ? [sep, ...actionRows] : []),
+    row(`🧠 dual-brain v${version}`),
+    row(providerLine),
+    sep,
+    ...workspaceRows,
+    sep,
+    ...awarenessRows,
     sep,
     ...sessionRows,
     sep,
     actionsRow,
-    sep,
-    poweredByRow,
     bot,
   ];
   // ── Stale session hint ──────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "7.1.23",
+  "version": "7.1.24",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
     "./session": "./src/session.mjs",
     "./decompose": "./src/decompose.mjs",
     "./brief": "./src/brief.mjs",
-    "./redact": "./src/redact.mjs"
+    "./redact": "./src/redact.mjs",
+    "./calibration": "./src/calibration.mjs"
   },
   "keywords": [
     "claude-code",
@@ -58,6 +59,7 @@
     "src/decompose.mjs",
     "src/brief.mjs",
     "src/redact.mjs",
+    "src/calibration.mjs",
     "src/pipeline.mjs",
     "src/context.mjs",
     "src/outcome.mjs",
@@ -67,8 +69,10 @@
     "src/receipt.mjs",
     "src/failure-memory.mjs",
     "src/index.mjs",
+    "src/ledger.mjs",
     "src/intelligence.mjs",
     "src/tui.mjs",
+    "src/living-docs.mjs",
     "src/install-hooks.mjs",
     "src/update-check.mjs",
     "bin/*.mjs",

package/src/calibration.mjs

@@ -0,0 +1,148 @@
+// User calibration module — tracks specificity, corrections, and autonomy signals
+// to adapt dual-brain behavior to any user from vague vibe-coder to precise expert.
+
+const FILE_REF_RE = /(?:src\/|\.mjs|\.tsx?|\.jsx?|\.json|\.ya?ml|\.sh|line\s+\d+|\bL\d+\b)/i;
+const TECH_TERM_RE = /\b(?:regex|middleware|api|endpoint|refactor|migration|schema|auth(?:entication)?|jwt|token|hook|dispatch|pipeline|module|function|class|interface|type|import|export|async|await|promise|callback|handler|router|controller|service|repository|factory|singleton|decorator|mixin|proxy|guard|interceptor|serializer|validator|transformer|adapter|facade|strategy|observer|subscriber|emitter|stream|buffer|cache|queue|worker|thread|mutex|semaphore|socket|websocket|http|grpc|graphql|rest|orm|sql|nosql|index|query|transaction|migration|seed|fixture|mock|stub|spy|assertion|coverage|lint|typecheck|bundle|compile|transpile|minify|tree.shake|dead.code|chunk|lazy.load|ssr|csr|hydrat)\b/i;
+const VAGUE_RE = /\b(?:idk|just|make\s+it|fix\s+it|whatever|vibes?|better|nicer|faster|cleaner|improve|help|do\s+it|yeah|sure|ok|okay|hmm|uh|er|um)\b/i;
+const AUTONOMY_HIGH_RE = /\b(?:just\s+do\s+it|go(?:\s+ahead)?|build\s+it|ship\s+it|run\s+it|execute|do\s+it|proceed|continue|carry\s+on|handle\s+it|take\s+care|make\s+it\s+happen|yolo)\b/i;
+const QUESTION_RE = /\?|^(?:how|what|why|when|where|which|should|can|could|would|is|are|do|does|did|will|won't|don't)\b/i;
+const CORRECTION_RE = /^(?:no[,.]?|not\s|wrong|stop|don't|that'?s?\s+not|i\s+said|i\s+meant)\b|(?:\binstead\b|\brather\b|\bactually\b)/i;
+
+export function analyzeInput(input) {
+  const text = (input || '').trim();
+  const lower = text.toLowerCase();
+  const words = text.split(/\s+/).filter(Boolean);
+  const wordCount = words.length;
+
+  const hasFileRefs = FILE_REF_RE.test(text);
+  const hasTechTerms = TECH_TERM_RE.test(text);
+  const hasExactInstructions = /\b(?:step\s+\d|first[,\s]|then[,\s]|finally[,\s]|specifically|exactly|must|should\s+(?:use|call|return|handle)|(?:use|call|return|throw|emit|dispatch)\s+\w)/i.test(text);
+  const isVague = VAGUE_RE.test(lower) || wordCount <= 3;
+
+  let specificity;
+  if (hasFileRefs || /\bline\s*\d+\b|\bL\d+\b/i.test(text) || (hasTechTerms && hasExactInstructions)) {
+    specificity = 5;
+  } else if (hasTechTerms && wordCount >= 6) {
+    specificity = 4;
+  } else if (!isVague && wordCount >= 8) {
+    specificity = 3;
+  } else if (wordCount >= 4 && !isVague) {
+    specificity = 2;
+  } else {
+    specificity = 1;
+  }
+
+  return {
+    specificity,
+    signals: {
+      hasFileRefs,
+      hasTechTerms,
+      hasExactInstructions,
+      isVague,
+      wordCount
+    }
+  };
+}
+
+export function detectCorrection(input) {
+  return CORRECTION_RE.test((input || '').trim());
+}
+
+function clamp(value, min = 1, max = 5) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function round1(value) {
+  return Math.round(value * 10) / 10;
+}
+
+function detectAutonomySignal(input) {
+  const text = (input || '').trim();
+  if (AUTONOMY_HIGH_RE.test(text)) return 5;
+  if (QUESTION_RE.test(text)) return 2;
+  return null;
+}
+
+export function updateCalibration(calibration, input, correction = false) {
+  const { specificity: newSpec } = analyzeInput(input);
+  const autonomySignal = detectAutonomySignal(input);
+
+  const prev = {
+    specificity: calibration.specificity ?? 3,
+    corrections: calibration.corrections ?? 3,
+    autonomy: calibration.autonomy ?? 3,
+    interactions: calibration.interactions ?? 0
+  };
+
+  const specificity = round1(clamp(prev.specificity * 0.7 + newSpec * 0.3));
+
+  const corrections = round1(clamp(
+    correction ? prev.corrections - 0.3 : prev.corrections + 0.1
+  ));
+
+  let autonomy = prev.autonomy;
+  if (autonomySignal !== null) {
+    autonomy = round1(clamp(prev.autonomy * 0.7 + autonomySignal * 0.3));
+  }
+
+  return {
+    specificity,
+    corrections,
+    autonomy,
+    interactions: prev.interactions + 1,
+    lastUpdated: new Date().toISOString()
+  };
+}
+
+export function getAdaptation(calibration) {
+  const s = calibration.specificity ?? 3;
+  const c = calibration.corrections ?? 3;
+  const a = calibration.autonomy ?? 3;
+
+  const clarifyBeforeActing = s < 2.5 || c > 3;
+  const explainReasoning = a < 3;
+  const suggestNextSteps = a < 4;
+  const askForApproval = c < 2.5;
+  const autoExecute = a > 4 && c > 3.5;
+
+  let responseStyle;
+  const combined = (s + c + a) / 3;
+  if (combined >= 4) {
+    responseStyle = 'terse';
+  } else if (combined >= 2.5) {
+    responseStyle = 'normal';
+  } else {
+    responseStyle = 'detailed';
+  }
+
+  let userLevel;
+  if (s >= 4) {
+    userLevel = 'advanced';
+  } else if (s >= 2.5) {
+    userLevel = 'intermediate';
+  } else {
+    userLevel = 'beginner';
+  }
+
+  return {
+    clarifyBeforeActing,
+    explainReasoning,
+    suggestNextSteps,
+    askForApproval,
+    autoExecute,
+    responseStyle,
+    userLevel
+  };
+}
+
+export function formatCalibration(calibration) {
+  const { userLevel, responseStyle } = getAdaptation(calibration);
+  const s = calibration.specificity ?? 3;
+  const c = calibration.corrections ?? 3;
+  const a = calibration.autonomy ?? 3;
+
+  const autonomyLabel = a >= 4 ? 'high autonomy' : a >= 2.5 ? 'normal autonomy' : 'low autonomy';
+  const trustLabel = c >= 4 ? 'high trust' : c >= 2.5 ? 'good trust' : 'low trust';
+
+  return `User: ${userLevel} · ${autonomyLabel} · ${trustLabel}\n      (specificity: ${s}, corrections: ${c}, autonomy: ${a})`;
+}

package/src/ledger.mjs

@@ -0,0 +1,196 @@
+// Task ledger: append-only accountability store for HEAD's promises. Every tracked task has a full snapshot per state change.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const LEDGER_PATH = '.dual-brain/ledger.jsonl';
+
+function ledgerPath(cwd) {
+  return join(cwd || process.cwd(), LEDGER_PATH);
+}
+
+function readAllEntries(cwd) {
+  const p = ledgerPath(cwd);
+  if (!existsSync(p)) return [];
+  const raw = readFileSync(p, 'utf8').trim();
+  if (!raw) return [];
+  return raw.split('\n').map(line => JSON.parse(line));
+}
+
+function appendEntry(entry, cwd) {
+  const p = ledgerPath(cwd);
+  mkdirSync(join(cwd || process.cwd(), '.dual-brain'), { recursive: true });
+  writeFileSync(p, JSON.stringify(entry) + '\n', { flag: 'a' });
+}
+
+function getCurrentTasks(cwd) {
+  const entries = readAllEntries(cwd);
+  const map = new Map();
+  for (const entry of entries) {
+    map.set(entry.id, entry);
+  }
+  return Array.from(map.values());
+}
+
+export function createTask(task, cwd) {
+  const entry = {
+    id: `task_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+    created: new Date().toISOString(),
+    updated: new Date().toISOString(),
+    intent: task.intent || '',
+    status: 'open',
+    owner: task.owner || 'head',
+    priority: task.priority || 'medium',
+    blockers: task.blockers || [],
+    proof: task.proof || null,
+    subtasks: task.subtasks || [],
+    parentTask: task.parentTask || null,
+    files: task.files || [],
+    result: task.result || null,
+    cost: task.cost || null,
+  };
+  appendEntry(entry, cwd);
+  return entry;
+}
+
+export function updateTask(taskId, updates, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+
+  if (updates.status === 'done') {
+    const proof = updates.proof ?? current.proof;
+    const result = updates.result ?? current.result;
+    if (!proof) throw new Error(`Cannot mark task done without proof: ${taskId}`);
+    if (!result) throw new Error(`Cannot mark task done without result: ${taskId}`);
+  }
+
+  const updated = {
+    ...current,
+    ...updates,
+    id: taskId,
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function failTask(taskId, reason, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+  const updated = {
+    ...current,
+    status: 'failed',
+    result: reason || 'failed',
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function blockTask(taskId, blocker, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+  const updated = {
+    ...current,
+    status: 'blocked',
+    blockers: [...(current.blockers || []), blocker],
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function getTask(taskId, cwd) {
+  const entries = readAllEntries(cwd);
+  let latest = null;
+  for (const entry of entries) {
+    if (entry.id === taskId) latest = entry;
+  }
+  return latest;
+}
+
+export function getOpenTasks(cwd) {
+  return getCurrentTasks(cwd).filter(t =>
+    t.status === 'open' || t.status === 'in_progress' || t.status === 'blocked'
+  );
+}
+
+export function getTaskHistory(taskId, cwd) {
+  return readAllEntries(cwd).filter(e => e.id === taskId);
+}
+
+export function getTaskSummary(cwd) {
+  const tasks = getCurrentTasks(cwd);
+  const summary = { open: 0, inProgress: 0, blocked: 0, done: 0, failed: 0, total: tasks.length };
+  for (const t of tasks) {
+    if (t.status === 'open') summary.open++;
+    else if (t.status === 'in_progress') summary.inProgress++;
+    else if (t.status === 'blocked') summary.blocked++;
+    else if (t.status === 'done') summary.done++;
+    else if (t.status === 'failed') summary.failed++;
+  }
+  return summary;
+}
+
+export function formatTaskList(tasks) {
+  const all = tasks;
+  const open = all.filter(t => t.status === 'open' || t.status === 'in_progress').length;
+  const blocked = all.filter(t => t.status === 'blocked').length;
+  const done = all.filter(t => t.status === 'done').length;
+
+  const lines = [`TASKS (${open} open, ${blocked} blocked, ${done} done)`];
+
+  for (const t of all) {
+    const pri = t.priority === 'critical' ? 'crit' : t.priority === 'high' ? 'high' : t.priority === 'low' ? 'low' : 'med';
+    const label = t.intent.length > 48 ? t.intent.slice(0, 45) + '...' : t.intent;
+
+    if (t.status === 'done') {
+      lines.push(`  ✓ [${pri}]  ${label} (done)`);
+    } else if (t.status === 'failed') {
+      lines.push(`  ✗ [${pri}]  ${label} (failed)`);
+    } else if (t.status === 'blocked') {
+      const blockerNote = t.blockers && t.blockers.length ? `: ${t.blockers[t.blockers.length - 1]}` : '';
+      lines.push(`  ◌ [${pri}]  ${label} (blocked${blockerNote})`);
+    } else {
+      lines.push(`  ● [${pri}]  ${label} (${t.status})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function reconcile(cwd) {
+  const tasks = getCurrentTasks(cwd);
+  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+  return tasks.filter(t =>
+    (t.status === 'open' || t.status === 'in_progress') &&
+    new Date(t.updated).getTime() < cutoff
+  );
+}
+
+export function decompose(taskId, subtasks, cwd) {
+  const parent = getTask(taskId, cwd);
+  if (!parent) throw new Error(`Task not found: ${taskId}`);
+
+  const created = subtasks.map(sub =>
+    createTask(
+      {
+        ...sub,
+        parentTask: taskId,
+        owner: sub.owner || parent.owner,
+        priority: sub.priority || parent.priority,
+      },
+      cwd
+    )
+  );
+
+  const subtaskIds = created.map(s => s.id);
+  const updatedParent = {
+    ...parent,
+    subtasks: [...(parent.subtasks || []), ...subtaskIds],
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updatedParent, cwd);
+
+  return { parent: updatedParent, subtasks: created };
+}

package/src/living-docs.mjs

@@ -0,0 +1,210 @@
+// living-docs.mjs — Living document system for .dual-brain/.
+// Manages project.json, vision.md, roadmap.md, state.md, actions.jsonl, decisions.jsonl, checkpoints.jsonl.
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const DIR = '.dual-brain';
+
+function docsDir(cwd = process.cwd()) {
+  return join(cwd, DIR);
+}
+
+function ensureDir(cwd) {
+  mkdirSync(docsDir(cwd), { recursive: true });
+}
+
+function filePath(name, cwd) {
+  return join(docsDir(cwd), name);
+}
+
+function readFileSafe(name, cwd, fallback = '') {
+  try {
+    return readFileSync(filePath(name, cwd), 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+function readJsonSafe(name, cwd, fallback = {}) {
+  try {
+    return JSON.parse(readFileSync(filePath(name, cwd), 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function gitExec(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+export function initLivingDocs(cwd = process.cwd()) {
+  const dir = docsDir(cwd);
+  const existed = existsSync(dir);
+  ensureDir(cwd);
+
+  const pkg = readPackageJson(cwd);
+
+  if (!existsSync(filePath('project.json', cwd))) {
+    const project = {
+      name: pkg.name ?? '',
+      version: pkg.version ?? '0.0.1',
+      created: new Date().toISOString(),
+      workStyle: 'balanced',
+      userCalibration: { specificity: 3, corrections: 3, autonomy: 3 },
+      team: [],
+      providers: {},
+    };
+    writeFileSync(filePath('project.json', cwd), JSON.stringify(project, null, 2));
+  }
+
+  if (!existsSync(filePath('vision.md', cwd))) {
+    writeFileSync(filePath('vision.md', cwd), '# Vision\n\n_Not yet defined. Type your vision and HEAD will maintain this document._\n');
+  }
+
+  if (!existsSync(filePath('roadmap.md', cwd))) {
+    writeFileSync(filePath('roadmap.md', cwd), '# Roadmap\n\n_No roadmap yet. As you work, HEAD will build this from your actions._\n');
+  }
+
+  if (!existsSync(filePath('state.md', cwd))) {
+    writeFileSync(filePath('state.md', cwd), '# Current State\n\n_Fresh project. No history yet._\n');
+  }
+
+  for (const log of ['actions.jsonl', 'decisions.jsonl', 'checkpoints.jsonl']) {
+    if (!existsSync(filePath(log, cwd))) {
+      writeFileSync(filePath(log, cwd), '');
+    }
+  }
+
+  return { created: !existed, path: dir };
+}
+
+export function appendAction(action, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const entry = {
+    id: `act_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+    timestamp: new Date().toISOString(),
+    type: 'task',
+    intent: '',
+    status: 'started',
+    owner: 'head',
+    files: [],
+    proof: null,
+    cost: null,
+    result: null,
+    ...action,
+  };
+  appendFileSync(filePath('actions.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function appendDecision(decision, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const entry = {
+    id: `dec_${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    question: '',
+    decision: '',
+    reasoning: '',
+    participants: [],
+    supersedes: null,
+    ...decision,
+  };
+  appendFileSync(filePath('decisions.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function createCheckpoint(summary, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const gitRef = gitExec('git rev-parse HEAD', cwd) ?? 'unknown';
+  const branch = gitExec('git rev-parse --abbrev-ref HEAD', cwd) ?? 'unknown';
+  const stateSnapshot = readFileSafe('state.md', cwd, '');
+  const entry = {
+    id: `cp_${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    gitRef,
+    branch,
+    summary,
+    stateSnapshot,
+  };
+  appendFileSync(filePath('checkpoints.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function updateState(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  writeFileSync(filePath('state.md', cwd), newContent);
+}
+
+export function updateRoadmap(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  writeFileSync(filePath('roadmap.md', cwd), newContent);
+}
+
+export function updateVision(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const prev = readFileSafe('vision.md', cwd, '');
+  writeFileSync(filePath('vision.md', cwd), newContent);
+  if (prev !== newContent) {
+    appendDecision({
+      question: 'What is the project vision?',
+      decision: newContent.slice(0, 200),
+      reasoning: 'Vision document updated.',
+      participants: ['head'],
+      supersedes: null,
+    }, cwd);
+  }
+}
+
+export function getProjectState(cwd = process.cwd()) {
+  const project = readJsonSafe('project.json', cwd, {});
+  const state = readFileSafe('state.md', cwd, '');
+  const actions = getRecentActions(cwd, 20);
+  const decisions = readLastLines('decisions.jsonl', cwd, 5);
+  const checkpoints = readLastLines('checkpoints.jsonl', cwd, 1);
+  return {
+    project,
+    state,
+    recentActions: actions,
+    recentDecisions: decisions,
+    lastCheckpoint: checkpoints[0] ?? null,
+  };
+}
+
+function readLastLines(name, cwd, n) {
+  const raw = readFileSafe(name, cwd, '');
+  const lines = raw.split('\n').filter(l => l.trim());
+  return lines.slice(-n).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+export function getRecentActions(cwd = process.cwd(), limit = 20) {
+  return readLastLines('actions.jsonl', cwd, limit);
+}
+
+export function getOpenTasks(cwd = process.cwd()) {
+  const raw = readFileSafe('actions.jsonl', cwd, '');
+  const lines = raw.split('\n').filter(l => l.trim());
+  const entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  return entries.filter(e => e.status === 'started' || e.status === 'blocked');
+}
+
+export function updateProject(updates, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const current = readJsonSafe('project.json', cwd, {});
+  const merged = { ...current, ...updates };
+  writeFileSync(filePath('project.json', cwd), JSON.stringify(merged, null, 2));
+  return merged;
+}