dual-brain 0.2.13 → 0.2.15

package/src/debrief.mjs

@@ -0,0 +1,228 @@
+const STATUSES = ['success', 'partial', 'blocked', 'pivoted'];
+
+function emptyDebrief() {
+  return {
+    status: 'partial',
+    findings: [],
+    blockers: [],
+    scopeChange: 'same',
+    confidence: 0.5,
+    recommendations: [],
+    artifacts: { filesChanged: [], filesRead: [], testsRun: 0 },
+    pivotReason: undefined,
+    unexpectedFindings: [],
+  };
+}
+
+// ─── Parse debrief from raw agent output ─────────────────────────────────────
+
+const FILE_PATH_RE = /(?:^|\s)([\w./-]+\.(?:mjs|js|ts|tsx|json|md|py|sh|yaml|yml|css|html))/gm;
+const TEST_COUNT_RE = /(\d+)\s*(?:tests?|specs?|assertions?)\s*(?:passed|ran|run|succeeded|ok)/i;
+
+function extractByPatterns(text, patterns, minLen, maxLen, limit) {
+  const results = [];
+  for (const re of patterns) {
+    for (const m of text.matchAll(re)) {
+      const v = m[1].trim();
+      if (v.length > minLen && v.length < maxLen) results.push(v);
+    }
+  }
+  return [...new Set(results)].slice(0, limit);
+}
+
+const extractFindings = t => extractByPatterns(t, [
+  /(?:found|discovered|identified|noticed|see that|observed)\s+(?:that\s+)?(.+?)(?:\.|$)/gim,
+  /^[-•*]\s*(.+)$/gm,
+], 10, 300, 20);
+
+const extractBlockers = t => extractByPatterns(t, [
+  /(?:blocked by|couldn't|cannot|unable to|failed to|can't)\s+(.+?)(?:\.|$)/gim,
+  /(?:blocker|obstacle|issue|problem):\s*(.+?)(?:\.|$)/gim,
+], 5, 200, 10);
+
+const extractRecommendations = t => extractByPatterns(t, [
+  /(?:recommend|suggest|should|next step|consider)\s+(.+?)(?:\.|$)/gim,
+  /(?:TODO|ACTION):\s*(.+?)(?:\.|$)/gim,
+], 5, 200, 10);
+
+const extractUnexpected = t => extractByPatterns(t, [
+  /(?:also noticed|unexpected|surprisingly|interestingly|aside:)\s+(.+?)(?:\.|$)/gim,
+], 10, 200, 5);
+
+function inferStatus(text, blockers, findings) {
+  const lower = text.toLowerCase();
+  if (/pivoted|changed approach|switched to/i.test(lower)) return 'pivoted';
+  if (blockers.length > 0 && findings.length === 0) return 'blocked';
+  if (blockers.length > 0) return 'partial';
+  if (/complete|done|success|finished|all (?:tests )?pass/i.test(lower)) return 'success';
+  return 'partial';
+}
+
+function inferScopeChange(text) {
+  const lower = text.toLowerCase();
+  if (/scope.{0,20}(?:grew|larger|expanded|more than expected)/i.test(lower)) return 'larger';
+  if (/scope.{0,20}(?:smaller|reduced|simpler than)/i.test(lower)) return 'smaller';
+  if (/(?:different approach|completely different|pivoted to)/i.test(lower)) return 'different';
+  return 'same';
+}
+
+function inferConfidence(text, findings, blockers) {
+  if (/(?:very confident|high confidence|certain)/i.test(text)) return 0.9;
+  if (/(?:uncertain|not sure|low confidence|unsure)/i.test(text)) return 0.3;
+  if (blockers.length > 2) return 0.3;
+  if (blockers.length > 0) return 0.5;
+  if (findings.length > 3) return 0.8;
+  return 0.6;
+}
+
+export function parseDebrief(rawOutput) {
+  if (!rawOutput || typeof rawOutput !== 'string') return emptyDebrief();
+
+  // Try JSON-structured debrief first
+  const jsonMatch = rawOutput.match(/```(?:json)?\s*(\{[\s\S]*?"status"[\s\S]*?\})\s*```/);
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1]);
+      if (STATUSES.includes(parsed.status)) {
+        const d = emptyDebrief();
+        return { ...d, ...parsed, artifacts: { ...d.artifacts, ...(parsed.artifacts || {}) } };
+      }
+    } catch {}
+  }
+
+  // Best-effort extraction from prose
+  const findings = extractFindings(rawOutput);
+  const blockers = extractBlockers(rawOutput);
+  const recommendations = extractRecommendations(rawOutput);
+  const unexpectedFindings = extractUnexpected(rawOutput);
+
+  const filesAll = [...rawOutput.matchAll(FILE_PATH_RE)].map(m => m[1]);
+  const lower = rawOutput.toLowerCase();
+  const filesChanged = filesAll.filter(f => lower.includes(`wrote ${f.toLowerCase()}`) || lower.includes(`created ${f.toLowerCase()}`) || lower.includes(`modified ${f.toLowerCase()}`) || lower.includes(`edited ${f.toLowerCase()}`));
+  const filesRead = filesAll.filter(f => !filesChanged.includes(f));
+
+  const testMatch = rawOutput.match(TEST_COUNT_RE);
+  const testsRun = testMatch ? parseInt(testMatch[1], 10) : 0;
+
+  const pivotMatch = rawOutput.match(/pivoted?\s+(?:because|since|due to)\s+(.+?)(?:\.|$)/i);
+
+  return {
+    status: inferStatus(rawOutput, blockers, findings),
+    findings,
+    blockers,
+    scopeChange: inferScopeChange(rawOutput),
+    confidence: inferConfidence(rawOutput, findings, blockers),
+    recommendations,
+    artifacts: { filesChanged, filesRead, testsRun },
+    pivotReason: pivotMatch ? pivotMatch[1].trim() : undefined,
+    unexpectedFindings,
+  };
+}
+
+// ─── Generate debrief instruction for agent prompts ──────────────────────────
+
+const TIER_EMPHASIS = {
+  search: 'Focus on: findings, confidence, unexpectedFindings.',
+  execute: 'Focus on: artifacts (filesChanged, testsRun), blockers, scopeChange.',
+  think: 'Focus on: recommendations, confidence, pivotReason.',
+};
+
+export function generateDebriefInstruction(tier, contract) {
+  const emphasis = TIER_EMPHASIS[tier] || TIER_EMPHASIS.execute;
+  const scope = contract?.scope ? ` Scope: ${contract.scope}.` : '';
+  return `\n---\nRESPONSE FORMAT: End your response with a JSON block:\n\`\`\`json\n{"status":"success|partial|blocked|pivoted","findings":[],"blockers":[],"scopeChange":"same|larger|smaller|different","confidence":0.0-1.0,"recommendations":[],"artifacts":{"filesChanged":[],"filesRead":[],"testsRun":0},"pivotReason":"...if pivoted","unexpectedFindings":[]}\n\`\`\`\n${emphasis}${scope}`;
+}
+
+// ─── Integrate debrief into HEAD's situation model ───────────────────────────
+
+export function integrateDebrief(currentSituation, debrief) {
+  const sit = structuredClone(currentSituation);
+
+  // Update confidence on related ledger entries
+  if (!sit.ledger) sit.ledger = [];
+  for (const finding of debrief.findings) {
+    const existing = sit.ledger.find(e => e.topic && finding.toLowerCase().includes(e.topic.toLowerCase()));
+    if (existing) {
+      existing.confidence = Math.min(1, (existing.confidence || 0.5) + 0.1);
+      existing.resolved = true;
+    } else {
+      sit.ledger.push({ topic: finding.slice(0, 80), confidence: debrief.confidence, resolved: false });
+    }
+  }
+
+  // Blockers create new uncertainty entries
+  for (const blocker of debrief.blockers) {
+    sit.ledger.push({ topic: blocker.slice(0, 80), confidence: 0.3, resolved: false, isBlocker: true });
+  }
+
+  // Scope delta
+  if (debrief.scopeChange !== 'same') {
+    if (!sit.material) sit.material = {};
+    sit.material.scopeTrend = debrief.scopeChange;
+    if (debrief.artifacts?.filesChanged) {
+      sit.material.touchedFiles = [
+        ...new Set([...(sit.material.touchedFiles || []), ...debrief.artifacts.filesChanged]),
+      ];
+    }
+  }
+
+  // Recommendations → next wave planning
+  if (!sit.nextActions) sit.nextActions = [];
+  sit.nextActions.push(...debrief.recommendations);
+
+  // Unexpected findings → noticings
+  if (debrief.unexpectedFindings?.length) {
+    if (!sit.noticings) sit.noticings = [];
+    sit.noticings.push(...debrief.unexpectedFindings);
+  }
+
+  // Overall confidence update
+  sit.confidence = sit.confidence
+    ? sit.confidence * 0.7 + debrief.confidence * 0.3
+    : debrief.confidence;
+
+  return sit;
+}
+
+// ─── Summarize a parallel wave of debriefs ───────────────────────────────────
+
+export function summarizeWaveOutcome(debriefs) {
+  if (!debriefs || debriefs.length === 0) {
+    return {
+      overallStatus: 'blocked',
+      aggregateConfidence: 0,
+      allFindings: [],
+      allBlockers: [],
+      scopeDelta: 'same',
+      nextActions: [],
+    };
+  }
+
+  const statusPriority = { blocked: 0, pivoted: 1, partial: 2, success: 3 };
+  const worstStatus = debriefs.reduce((worst, d) =>
+    (statusPriority[d.status] ?? 2) < (statusPriority[worst] ?? 2) ? d.status : worst,
+    'success'
+  );
+
+  const allFindings = [...new Set(debriefs.flatMap(d => d.findings || []))];
+  const allBlockers = [...new Set(debriefs.flatMap(d => d.blockers || []))];
+  const nextActions = [...new Set(debriefs.flatMap(d => d.recommendations || []))];
+
+  const aggregateConfidence = debriefs.reduce((sum, d) => sum + (d.confidence || 0.5), 0) / debriefs.length;
+
+  // Scope: any non-same scope wins, larger beats smaller, different beats all
+  const scopeDeltas = debriefs.map(d => d.scopeChange || 'same').filter(s => s !== 'same');
+  let scopeDelta = 'same';
+  if (scopeDeltas.includes('different')) scopeDelta = 'different';
+  else if (scopeDeltas.includes('larger')) scopeDelta = 'larger';
+  else if (scopeDeltas.includes('smaller')) scopeDelta = 'smaller';
+
+  return {
+    overallStatus: worstStatus,
+    aggregateConfidence: Math.round(aggregateConfidence * 100) / 100,
+    allFindings,
+    allBlockers,
+    scopeDelta,
+    nextActions,
+  };
+}

package/src/doctor.mjs

@@ -594,8 +594,8 @@ const VERIFIERS = {
     catch { return { status: 'failed', evidence: 'ripgrep not found', probe: 'which rg' }; }
   }},
   'living-docs-init': { ttl: TTL_RUNTIME, fn: (cwd) => {
-    const exists = existsSync(join(cwd || process.cwd(), '.dual-brain'));
-    return { status: exists ? 'verified' : 'failed', evidence: exists ? '.dual-brain/ exists' : '.dual-brain/ not initialized', probe: 'fs check' };
+    const exists = existsSync(join(cwd || process.cwd(), '.dualbrain'));
+    return { status: exists ? 'verified' : 'failed', evidence: exists ? '.dualbrain/ exists' : '.dualbrain/ not initialized', probe: 'fs check' };
   }},
   'model-registry-fresh': { ttl: TTL_REGISTRY, fn: () => {
     try {
@@ -627,15 +627,15 @@ export function verify(claim, cwd) {
 }
 
 /**
- * verifyAll(cwd) — run all registered verifiers and append results to .dual-brain/verifications.jsonl.
+ * verifyAll(cwd) — run all registered verifiers and append results to .dualbrain/verifications.jsonl.
  * Returns array of verification result objects.
  */
 export function verifyAll(cwd = process.cwd()) {
   const results = Object.keys(VERIFIERS).map(claim => verify(claim, cwd));
 
-  // Persist to .dual-brain/verifications.jsonl (append-only)
+  // Persist to .dualbrain/verifications.jsonl (append-only)
   try {
-    const dir = join(cwd, '.dual-brain');
+    const dir = join(cwd, '.dualbrain');
     if (existsSync(dir)) {
       const logPath = join(dir, 'verifications.jsonl');
       const lines = results.map(r => JSON.stringify(r)).join('\n') + '\n';
@@ -647,11 +647,11 @@ export function verifyAll(cwd = process.cwd()) {
 }
 
 /**
- * getVerificationCache(cwd) — read .dual-brain/verifications.jsonl, return most recent
+ * getVerificationCache(cwd) — read .dualbrain/verifications.jsonl, return most recent
  * non-expired result per claim. Expired entries are skipped.
  */
 export function getVerificationCache(cwd = process.cwd()) {
-  const logPath = join(cwd, '.dual-brain', 'verifications.jsonl');
+  const logPath = join(cwd, '.dualbrain', 'verifications.jsonl');
   if (!existsSync(logPath)) return [];
 
   let lines;
@@ -718,7 +718,7 @@ const CODE_TASK_TYPES   = new Set(['fix', 'feature', 'refactor', 'implement', 't
 const REASONING_MODELS  = new Set(['o3']);
 
 function learningsPath(cwd) {
-  return join(cwd, '.dual-brain', 'learnings.jsonl');
+  return join(cwd, '.dualbrain', 'learnings.jsonl');
 }
 
 function readLearnings(cwd) {
@@ -802,7 +802,7 @@ export function recordLearning(taskResult, cwd = process.cwd()) {
     };
 
     const p = learningsPath(cwd);
-    const dir = join(cwd, '.dual-brain');
+    const dir = join(cwd, '.dualbrain');
     if (existsSync(dir)) {
       appendFileSync(p, JSON.stringify(record) + '\n', 'utf8');
     }
@@ -1167,7 +1167,7 @@ function discoverReplitFeatures(cwd) {
 }
 
 function loadLastDiscovery(cwd) {
-  const logPath = join(cwd, '.dual-brain', 'discoveries.jsonl');
+  const logPath = join(cwd, '.dualbrain', 'discoveries.jsonl');
   if (!existsSync(logPath)) return null;
   try {
     const lines = readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
@@ -1177,7 +1177,7 @@ function loadLastDiscovery(cwd) {
 }
 
 function appendDiscoveryLog(cwd, entry) {
-  const dir = join(cwd, '.dual-brain');
+  const dir = join(cwd, '.dualbrain');
   try {
     if (!existsSync(dir)) execSync(`mkdir -p "${dir}"`, { timeout: 2000 });
     appendFileSync(join(dir, 'discoveries.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
@@ -1217,10 +1217,10 @@ export function discover(cwd = process.cwd()) {
 }
 
 /**
- * getDiscoveryLog(cwd, limit) — read recent discovery entries from .dual-brain/discoveries.jsonl.
+ * getDiscoveryLog(cwd, limit) — read recent discovery entries from .dualbrain/discoveries.jsonl.
  */
 export function getDiscoveryLog(cwd = process.cwd(), limit = 20) {
-  const logPath = join(cwd, '.dual-brain', 'discoveries.jsonl');
+  const logPath = join(cwd, '.dualbrain', 'discoveries.jsonl');
   if (!existsSync(logPath)) return [];
   try {
     const lines = readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);

package/src/envelope.mjs

@@ -0,0 +1,139 @@
+// envelope.mjs — Dispatch envelopes that carry understanding to workers.
+//
+// Instead of workers getting bare instructions ("edit file X, add Y"),
+// they get an envelope containing:
+// 1. Context preamble — narrative excerpt explaining the "why"
+// 2. Contract — the typed task (objective, scope, acceptance criteria)
+// 3. Preventions — predicted failure modes and how to avoid them
+// 4. Debrief format — how to report back
+//
+// This is the difference between "do this thing" and "here's where we are,
+// here's why this matters, here's what to do, here's what to watch for."
+
+import * as narrative from './narrative.mjs';
+
+/**
+ * @typedef {object} Envelope
+ * @property {string} preamble - Narrative context for the worker
+ * @property {string} contract - The actual task specification
+ * @property {string} preventions - Predicted failure modes and mitigations
+ * @property {string} debriefFormat - How to report back
+ * @property {string} full - Complete prompt ready to send
+ */
+
+/**
+ * Build a dispatch envelope for a worker agent.
+ *
+ * @param {object} agentSpec - From wave-planner
+ * @param {string} agentSpec.objective - What to accomplish
+ * @param {string[]} agentSpec.scope - Files/areas in scope
+ * @param {string} agentSpec.tier - Worker tier (execute, search, review, etc)
+ * @param {object} opts
+ * @param {string} opts.preventions - From predictive.mjs
+ * @param {string} opts.debriefInstruction - From debrief.mjs
+ * @param {string} opts.inboxBrief - Messages for this worker
+ * @param {object} opts.contract - Additional contract fields (acceptance criteria, risk, allowed ops)
+ * @returns {Envelope}
+ */
+export function build(agentSpec, opts = {}) {
+  const { preventions, debriefInstruction, inboxBrief, contract } = opts;
+
+  // Get narrative excerpt — the "being in the song" piece
+  const preamble = _buildPreamble(agentSpec);
+
+  // Build contract section
+  const contractText = _buildContract(agentSpec, contract);
+
+  // Assemble full prompt
+  const sections = [];
+
+  if (preamble) {
+    sections.push(`## Context\n${preamble}`);
+  }
+
+  sections.push(`## Task\n${contractText}`);
+
+  if (inboxBrief) {
+    sections.push(`## Notes\n${inboxBrief}`);
+  }
+
+  if (preventions) {
+    sections.push(`## Watch For\n${preventions}`);
+  }
+
+  if (debriefInstruction) {
+    sections.push(`## When Done\n${debriefInstruction}`);
+  }
+
+  const full = sections.join('\n\n');
+
+  return {
+    preamble,
+    contract: contractText,
+    preventions: preventions || '',
+    debriefFormat: debriefInstruction || '',
+    full,
+  };
+}
+
+/**
+ * Build a lightweight envelope for simple/fast dispatches.
+ * Used when the task is straightforward and doesn't need full context.
+ *
+ * @param {string} objective
+ * @param {string[]} scope
+ * @returns {string} Simple prompt string
+ */
+export function buildLight(objective, scope = []) {
+  const parts = [objective];
+  if (scope.length > 0) {
+    parts.push(`Scope: ${scope.join(', ')}`);
+  }
+  return parts.join('\n');
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+function _buildPreamble(agentSpec) {
+  const narr = narrative.excerpt(400);
+  if (!narr) return '';
+
+  // Tailor the preamble based on tier
+  const tier = (agentSpec.tier || '').toLowerCase();
+
+  if (tier === 'search' || tier === 'recon') {
+    // Search agents need less context, more focus on what to look for
+    return narr.length > 200 ? narr.slice(-200) : narr;
+  }
+
+  // Implementation agents get fuller context
+  return narr;
+}
+
+function _buildContract(agentSpec, extra = {}) {
+  const parts = [];
+
+  parts.push(agentSpec.objective);
+
+  if (agentSpec.scope?.length) {
+    parts.push(`\nScope: ${agentSpec.scope.join(', ')}`);
+  }
+
+  if (extra?.acceptanceCriteria) {
+    parts.push(`\nDone when: ${extra.acceptanceCriteria}`);
+  }
+
+  if (extra?.risk) {
+    parts.push(`\nRisk level: ${extra.risk}`);
+  }
+
+  if (extra?.allowedOps) {
+    parts.push(`\nAllowed: ${extra.allowedOps.join(', ')}`);
+  }
+
+  if (agentSpec.conditionalPivot) {
+    parts.push(`\nConditional: if ${agentSpec.conditionalPivot.if} → ${agentSpec.conditionalPivot.then}`);
+  }
+
+  return parts.join('');
+}

package/src/head-protocol.mjs

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { processTurn, loadState } from './head.mjs';
+
+const DUALBRAIN = join(process.cwd(), '.dualbrain');
+const DELIBERATION_FILE = join(DUALBRAIN, 'deliberation.json');
+
+/**
+ * Write the deliberation artifact after running HEAD's cognitive pipeline.
+ * This is the contract between HEAD's thinking and the deliberation-gate hook.
+ *
+ * @param {string} userMessage - The user's message to deliberate on
+ * @param {object} context - Optional context (files, priorFailures, patterns, etc.)
+ * @returns {object} The full deliberation result from processTurn
+ */
+export function writeDeliberation(userMessage, context = {}) {
+  const state = loadState();
+  const result = processTurn(state, userMessage, context);
+
+  // Determine if there are multiple independent sub-tasks that could be parallelized
+  const dispatchPlan = _deriveDispatchPlan(result, context);
+
+  // Build the artifact
+  const artifact = {
+    timestamp: Date.now(),
+    createdAt: Date.now(),
+    message: userMessage.slice(0, 500),
+
+    // Core deliberation fields
+    action: result.action,
+    result: result.result,
+    shouldAskUser: result.shouldAskUser,
+    confidence: result.result?.confidence || null,
+
+    // Obligations and noticings
+    obligations: result.obligations || [],
+    surfaceNoticings: result.result?.surfaceNoticings || [],
+
+    // Dispatch plan (parallel-wave support)
+    dispatchPlan,
+
+    // Metadata
+    depth: result.depth,
+    rationale: result.rationale,
+    situation: {
+      taskShape: result.situation?.taskShape || null,
+      urgency: result.situation?.urgency || null,
+      scope: result.situation?.taskShape?.scope || null,
+    },
+  };
+
+  // Write atomically
+  mkdirSync(DUALBRAIN, { recursive: true });
+  const tmpFile = DELIBERATION_FILE + '.tmp.' + process.pid;
+  writeFileSync(tmpFile, JSON.stringify(artifact, null, 2));
+  renameSync(tmpFile, DELIBERATION_FILE);
+
+  return result;
+}
+
+/**
+ * Read the current deliberation artifact.
+ * @returns {object|null} The deliberation artifact, or null if not found/unreadable.
+ */
+export function readDeliberation() {
+  try {
+    if (!existsSync(DELIBERATION_FILE)) return null;
+    return JSON.parse(readFileSync(DELIBERATION_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the current deliberation is fresh (within maxAgeMs).
+ * @param {number} maxAgeMs - Maximum age in milliseconds (default 60000)
+ * @returns {boolean} True if deliberation exists and is fresh.
+ */
+export function isDeliberationFresh(maxAgeMs = 60_000) {
+  const delib = readDeliberation();
+  if (!delib) return false;
+  const timestamp = delib.timestamp || delib.createdAt || 0;
+  return (Date.now() - timestamp) <= maxAgeMs;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Derive a dispatch plan when the situation has multiple independent sub-tasks.
+ * Returns null if parallel dispatch is not applicable.
+ */
+function _deriveDispatchPlan(result, context) {
+  const situation = result.situation;
+  if (!situation) return null;
+
+  // Only generate a parallel plan for multi-file, non-trivial work
+  const scope = situation.taskShape?.scope;
+  const actionType = result.action?.type;
+
+  if (scope !== 'large' && scope !== 'medium') return null;
+  if (actionType !== 'dispatch' && actionType !== 'proceed') return null;
+
+  // Check for independent sub-tasks from context
+  const subtasks = context.subtasks || [];
+  if (subtasks.length < 2) {
+    // Heuristic: large scope with multiple files could be parallel
+    const fileCount = situation.material?.touchedFiles?.length || 0;
+    if (fileCount < 3) return null;
+
+    return {
+      strategy: 'parallel-wave',
+      id: Date.now().toString(36),
+      expectedParallel: Math.min(fileCount, 5),
+      waveSize: Math.min(fileCount, 5),
+      reason: `${fileCount} independent files detected`,
+    };
+  }
+
+  return {
+    strategy: 'parallel-wave',
+    id: Date.now().toString(36),
+    expectedParallel: subtasks.length,
+    waveSize: subtasks.length,
+    subtasks: subtasks.map(t => typeof t === 'string' ? t : t.name || t.description),
+    reason: `${subtasks.length} independent sub-tasks identified`,
+  };
+}
+