dual-brain 0.1.21 → 0.1.23

package/bin/dual-brain.mjs

@@ -909,7 +909,7 @@ function cmdBreakGlass(reason) {
 // ─── Screen helpers ───────────────────────────────────────────────────────────
 
 /**
- * Render the data-tools-style rounded header box for the main screen.
+ * Render the dual-brain-style rounded header box for the main screen.
  * Inner width is 39 chars. Lines are padded with spaces to fill the box.
  */
 function renderHeader(version, providerLines, dtVersion) {
@@ -924,11 +924,11 @@ function renderHeader(version, providerLines, dtVersion) {
   const bottom = `  └${'─'.repeat(W)}┘`;
 
   const title  = `🧠 Dual Brain v${version}`;
-  const credit = `by Steve Moraco + dual-brain`;
+  const credit = `dual-brain`;
 
   const allProviderLines = [...providerLines];
   if (dtVersion) {
-    allProviderLines.push(`📦 data-tools v${dtVersion} detected`);
+    allProviderLines.push(`📦 replit-tools v${dtVersion} detected`);
   }
 
   const lines = [top];
@@ -1711,7 +1711,7 @@ async function mainScreen(rl, ask) {
 
   const statusRows = [row(providerLine)];
   if (dtVersion) {
-    statusRows.push(row(`\x1b[2m📦 data-tools v${dtVersion}\x1b[0m`));
+    statusRows.push(row(`\x1b[2m📦 replit-tools v${dtVersion}\x1b[0m`));
   }
 
   // ── Observer observations (top 2, high priority first) ───────────────────
@@ -1837,13 +1837,13 @@ async function mainScreen(rl, ask) {
     });
   }
 
-  // ── Actions bar — four product verbs first, then navigation ────────────────
-  const actionsContent = 'd Do  p Plan  r Review  s Ship  │  n New  / Search  q Quit';
+  // ── Actions bar — navigation only (pipeline verbs are internal stages, not menu items) ─
+  const actionsContent = 'n New session  / 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 data-tools · Steve Moraco\x1b[0m');
+  const poweredByRow = row('\x1b[2mPowered by dual-brain\x1b[0m');
   const lines = [
     top,
     ...statusRows,
@@ -1948,7 +1948,7 @@ async function mainScreen(rl, ask) {
       // Single-key commands only fire when buffer is empty
       if (taskBuffer.length === 0) {
         const lower = str.toLowerCase();
-        const singleKeySet = new Set(['n', 's', 'q', '/', 'i', 'd', 'p', 'r']);
+        const singleKeySet = new Set(['n', 's', 'q', '/', 'i']);
         if (singleKeySet.has(lower)) {
           cleanup();
           process.stdout.write('\n');
@@ -2017,37 +2017,6 @@ async function mainScreen(rl, ask) {
 
   if (choice === 'n') { return { next: 'new-session' }; }
 
-  // Four product verbs
-  if (choice === 'd') {
-    // "Do" — prompt user for a task description, then dispatch
-    const prompt = (await ask('  What do you want to do? ')).trim();
-    if (!prompt) return { next: 'main' };
-    return { next: 'go', prompt };
-  }
-
-  if (choice === 'p') {
-    // "Plan" — dry-run routing for a task
-    const prompt = (await ask('  Describe the task to plan: ')).trim();
-    if (!prompt) return { next: 'main' };
-    return { next: 'go', prompt, dryRun: true };
-  }
-
-  if (choice === 'r') {
-    // "Review" — dual-brain review current diff
-    const { spawnSync } = await import('node:child_process');
-    process.stdout.write('\n  Running dual-brain review...\n\n');
-    spawnSync('node', ['.claude/hooks/dual-brain-review.mjs'], { stdio: 'inherit', cwd });
-    return { next: 'main' };
-  }
-
-  if (choice === 's') {
-    // "Ship" — run quality gate then prompt for commit/PR
-    const { spawnSync } = await import('node:child_process');
-    process.stdout.write('\n  Running quality gate + ship flow...\n\n');
-    spawnSync('node', ['.claude/hooks/quality-gate.mjs'], { stdio: 'inherit', cwd });
-    return { next: 'main' };
-  }
-
   if (choice === '/') {
     const query = (await ask('  Search: ')).trim();
     if (!query) return { next: 'main' };
@@ -2084,6 +2053,7 @@ async function mainScreen(rl, ask) {
     return { next: 'main' };
   }
 
+  if (choice === 's') { return { next: 'settings' }; }
   if (choice === 'i') { return { next: 'import-picker' }; }
   if (choice === 'q' || choice === 'exit') { return { next: 'exit' }; }
 
@@ -2097,26 +2067,8 @@ async function newSessionScreen(rl, ask) {
   const input = (await ask('\n  What do you want to do? ')).trim();
   if (!input) { return { next: 'main' }; }
 
-  const profile = loadProfile(cwd);
-  const detection = detectTask({ prompt: input });
-  const decision = decideRoute({ profile, detection, cwd });
-
-  console.log(`\n  Routing: ${decision.provider}/${decision.model} (${decision.tier})`);
-  console.log(`  Reason: ${decision.explanation}\n`);
-
-  const { spawnSync } = await import('node:child_process');
-  const launchTool = decision.provider === 'openai' ? 'codex' : 'claude';
-  if (launchTool === 'codex') {
-    spawnSync('codex', [input], { stdio: 'inherit' });
-  } else {
-    spawnSync('claude', ['-p', input], { stdio: 'inherit' });
-  }
-
-  // After session ends, capture the most-recent session ID so [c] can resume it
-  const freshSessions = importReplitSessions(cwd);
-  if (freshSessions.length > 0) {
-    saveTerminalState(cwd, getTerminalId(), freshSessions[0].id, launchTool);
-  }
+  // All work routes through pipeline — detect → decide → dispatch with mandatory gates.
+  await cmdGo([input], { cwd });
 
   return { next: 'main' };
 }
@@ -4094,27 +4046,11 @@ async function runScreens(startScreen = 'dashboard') {
   let current = startScreen;
   let ctx = {};
   while (current && current !== 'exit') {
-    // Handle type-to-start dispatch from mainScreen
+    // Handle type-to-start dispatch from mainScreen — all work routes through pipeline.
     if (current === 'go' && ctx.prompt) {
       const prompt = ctx.prompt;
-      const cwd    = process.cwd();
-      const profile   = loadProfile(cwd);
-      const detection = detectTask({ prompt });
-      const decision  = decideRoute({ profile, detection, cwd });
-      process.stdout.write(`\n  Routing: ${decision.provider}/${decision.model} (${decision.tier})\n`);
-      process.stdout.write(`  Reason: ${decision.explanation}\n\n`);
-      const { spawnSync } = await import('node:child_process');
-      const launchTool = decision.provider === 'openai' ? 'codex' : 'claude';
-      if (launchTool === 'codex') {
-        spawnSync('codex', [prompt], { stdio: 'inherit' });
-      } else {
-        spawnSync('claude', ['-p', prompt], { stdio: 'inherit' });
-      }
-      const freshSessions = importReplitSessions(cwd);
-      if (freshSessions.length > 0) {
-        saveTerminalState(cwd, getTerminalId(), freshSessions[0].id, launchTool);
-      }
-      await offerAutoCommit(cwd);
+      const dryRun = ctx.dryRun || false;
+      await cmdGo([prompt], { dryRun });
       current = 'main';
       ctx = {};
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {

package/src/doctor.mjs

@@ -1,10 +1,20 @@
 /**
- * doctor.mjs — Internal honesty checker for dual-brain development.
- * NOT for npm users. For developers working on this repo.
+ * doctor.mjs — Diagnostic and recovery stage in the dual-brain pipeline.
+ * Doctor is a diagnostic/recovery stage in the pipeline. It proposes, never implements.
  *
- * Exports: runDoctor, formatDoctorReport, scanClaims, checkDecisions,
- *          checkFoundations, checkRoleBoundaries, checkEvidence, checkTokenWaste,
- *          runHealthCheck, formatHealthReport, compareHealth
+ * Doctor can diagnose problems and propose recovery actions, but it NEVER directly
+ * edits files, dispatches agents, or runs commands. All proposals are returned as
+ * data for the pipeline to execute through its normal gated flow.
+ *
+ * Pipeline interface:
+ *   doctorDiagnose(run)          — pre-execution diagnostic check
+ *   doctorRecover(run, failure)  — post-failure recovery proposal
+ *
+ * Internal honesty checks (for developers working on this repo):
+ *   runDoctor, formatDoctorReport, scanClaims, checkDecisions,
+ *   checkFoundations, checkRoleBoundaries, checkEvidence, checkTokenWaste,
+ *   runHealthCheck, formatHealthReport, compareHealth,
+ *   doctorDiagnose, doctorRecover
  */
 
 import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
@@ -372,6 +382,173 @@ export function formatHealthReport(results) {
   return out.join('\n');
 }
 
+// ─── Pipeline Stage: Diagnose ─────────────────────────────────────────────────
+
+/**
+ * Pipeline-compatible diagnostic check. Called before execution to surface
+ * blocking or advisory findings based on the current pipeline run context.
+ *
+ * @param {object} run - PipelineRun object
+ * @param {object}   run.context         - Context pack (prompt, files, detection, profile, cwd)
+ * @param {object[]} run.failureHistory  - Prior failures for this prompt fingerprint
+ * @param {object[]} run.priorOutcomes   - Recent outcome records
+ * @param {object}   run.plan            - Execution plan (may be null before buildExecutionPlan)
+ * @returns {Promise<{
+ *   findings: Array<{check: string, severity: string, message: string}>,
+ *   canProceed: boolean,
+ *   suggestedFixes: string[],
+ *   blockedApproaches: string[]
+ * }>}
+ */
+export async function doctorDiagnose(run) {
+  const { context = {}, failureHistory = [], priorOutcomes = [], plan = null } = run;
+  const cwd = context.cwd ?? process.cwd();
+
+  const findings = [];
+  const suggestedFixes = [];
+
+  // ── Role boundary check: pull from audit log ──────────────────────────────
+  const roleBoundaries = await checkRoleBoundaries(cwd);
+  for (const rb of roleBoundaries) {
+    findings.push({ check: 'role-boundaries', severity: rb.severity, message: rb.message });
+  }
+  if (roleBoundaries.length > 0) {
+    suggestedFixes.push('Dispatch search/work agents instead of using Read/Write/Bash directly from HEAD.');
+  }
+
+  // ── Evidence integrity check ──────────────────────────────────────────────
+  const evidenceIssues = await checkEvidence(cwd);
+  for (const ev of evidenceIssues) {
+    findings.push({ check: 'evidence', severity: ev.severity, message: ev.message });
+  }
+  if (evidenceIssues.some(e => e.type === 'false-file-claim')) {
+    suggestedFixes.push('Verify file claims match actual git state before recording outcomes as successful.');
+  }
+
+  // ── Token waste check ─────────────────────────────────────────────────────
+  const wasteIssues = await checkTokenWaste(cwd);
+  for (const tw of wasteIssues) {
+    findings.push({ check: 'token-waste', severity: tw.severity, message: tw.message });
+  }
+
+  // ── Foundation integrity check ────────────────────────────────────────────
+  const { issues: foundationIssues } = await checkFoundations(cwd);
+  for (const fi of foundationIssues) {
+    if (fi.type === 'dependent-on-invalidated') {
+      findings.push({
+        check: 'foundations',
+        severity: 'block',
+        message: `Active work depends on invalidated foundation "${fi.invalidatedFoundation}" via ${fi.file.join(', ')}`,
+      });
+      suggestedFixes.push(`Resolve dependency on invalidated foundation "${fi.invalidatedFoundation}" before proceeding.`);
+    }
+  }
+
+  // ── Repeated failure detection ────────────────────────────────────────────
+  const repeatFailures = failureHistory.filter(f => !f.resolved);
+  if (repeatFailures.length >= 2) {
+    findings.push({
+      check: 'failure-history',
+      severity: 'block',
+      message: `${repeatFailures.length} unresolved prior failures for this prompt — repeated approach likely to fail again.`,
+    });
+    suggestedFixes.push('Escalate to dual-brain think flow before retrying. Prior approaches must not be repeated.');
+  } else if (repeatFailures.length === 1) {
+    findings.push({
+      check: 'failure-history',
+      severity: 'warn',
+      message: '1 prior failure for this prompt — verify the approach differs before proceeding.',
+    });
+  }
+
+  // ── Risk/plan consistency check ───────────────────────────────────────────
+  if (plan && context.detection) {
+    const { risk } = context.detection;
+    if (risk === 'critical' && !plan.useChallenger) {
+      findings.push({
+        check: 'plan-consistency',
+        severity: 'warn',
+        message: 'Critical-risk task routed without challenger — dual-brain think is recommended.',
+      });
+      suggestedFixes.push('Enable challenger or run dual-brain think before executing critical-risk tasks.');
+    }
+  }
+
+  // ── Derive blocked approaches from failure history ────────────────────────
+  const blockedApproaches = repeatFailures
+    .filter(f => f.approach)
+    .map(f => f.approach);
+
+  const canProceed = !findings.some(f => f.severity === 'block');
+
+  return { findings, canProceed, suggestedFixes, blockedApproaches };
+}
+
+// ─── Pipeline Stage: Recover ──────────────────────────────────────────────────
+
+/**
+ * Pipeline-compatible recovery proposer. Called when pipeline execution fails.
+ * Returns a recovery proposal for the pipeline to route — never executes directly.
+ *
+ * @param {object} run - PipelineRun object (same shape as doctorDiagnose)
+ * @param {object} failure - Failure context from the failed execution
+ * @param {string}  [failure.error]      - Error message
+ * @param {string}  [failure.approach]   - What was attempted
+ * @param {string}  [failure.tier]       - Tier that failed ('search'|'execute'|'think')
+ * @param {number}  [failure.failCount]  - How many times this has failed
+ * @returns {Promise<{
+ *   proposal: string,
+ *   avoidApproaches: string[],
+ *   escalation: string|null
+ * }>}
+ */
+export async function doctorRecover(run, failure = {}) {
+  const { failureHistory = [] } = run;
+  const { error = '', approach = '', tier = 'execute', failCount = 1 } = failure;
+
+  // Collect all previously failed approaches from history + this failure
+  const avoidApproaches = [
+    ...failureHistory.filter(f => f.approach).map(f => f.approach),
+    ...(approach ? [approach] : []),
+  ].filter(Boolean);
+
+  // Determine escalation: 2+ failures → dual-brain think
+  const totalFailures = failureHistory.filter(f => !f.resolved).length + 1;
+  const escalation = totalFailures >= 2 ? 'dual-brain' : null;
+
+  // Build a concrete recovery proposal without implementing anything
+  const proposalParts = [];
+
+  if (escalation === 'dual-brain') {
+    proposalParts.push(
+      `Escalate to dual-brain think flow: ${totalFailures} failures indicate the approach is fundamentally flawed.`,
+      'Run: node .claude/hooks/dual-brain-think.mjs --question "<revised problem statement>"',
+      'Do not retry the same implementation path.',
+    );
+  } else {
+    if (tier === 'search') {
+      proposalParts.push('Retry search with narrower scope or different file patterns.');
+    } else if (tier === 'execute') {
+      proposalParts.push(
+        'Re-route through execute tier with a revised task description.',
+        error ? `Prior error was: ${error.slice(0, 120)}` : '',
+      );
+    } else if (tier === 'think') {
+      proposalParts.push('Re-run think tier with more context or an explicit constraint list.');
+    } else {
+      proposalParts.push('Retry with a revised task description that avoids the failed approach.');
+    }
+
+    if (avoidApproaches.length > 0) {
+      proposalParts.push(`Explicitly exclude these approaches: ${avoidApproaches.join(', ')}`);
+    }
+  }
+
+  const proposal = proposalParts.filter(Boolean).join(' ');
+
+  return { proposal, avoidApproaches, escalation };
+}
+
 // ─── Health Baseline Comparison ───────────────────────────────────────────────
 export async function compareHealth(cwd = process.cwd()) {
   const bpath = join(cwd, '.dualbrain', 'health-baseline.json');

package/src/pipeline.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 // pipeline.mjs — Unified Pipeline for dual-brain.
 // Every feature (go, think, review, watch, auto-commit, pr-triage, wave) routes through here.
-// Exports: runPipeline, buildExecutionPlan, formatExecutionPlan
+// Exports: runPipeline, buildExecutionPlan, formatExecutionPlan, createPipelineRun
+// Gate exports: contextGate, planningGate, principleGate, executionGate, outcomeGate
 
 import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { detectTask } from './detect.mjs';
 import { decideRoute, getWorkStyle, WORK_STYLES } from './decide.mjs';
 import { dispatch } from './dispatch.mjs';
@@ -11,6 +13,209 @@ import { loadProfile } from './profile.mjs';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+// ─── PipelineRun factory ──────────────────────────────────────────────────────
+
+/**
+ * Create a fresh PipelineRun object.
+ * @param {string} trigger
+ * @param {string} prompt
+ * @returns {object}
+ */
+export function createPipelineRun(trigger = '', prompt = '') {
+  return {
+    id: randomUUID(),
+    startedAt: Date.now(),
+    trigger,
+    prompt,
+
+    // Phase 1: Context
+    context: null,
+    failureHistory: null,   // result of checkFailureHistory — even empty counts as "queried"
+    priorOutcomes: null,    // result of getRelevantOutcomes — even empty counts as "queried"
+
+    // Gate results
+    gates: {
+      context:   null,   // { passed: bool, reason: string }
+      planning:  null,
+      principle: null,
+      execution: null,
+      outcome:   null,
+    },
+
+    // Phase 2: Plan
+    plan: null,
+
+    // Phase 3: Execution
+    result: null,
+
+    // Phase 4: Verification
+    verification: null,
+
+    // Phase 5: Outcome
+    outcome: null,
+
+    completedAt: null,
+  };
+}
+
+// ─── Gate helpers ─────────────────────────────────────────────────────────────
+
+function gate(passed, reason) {
+  return { passed: Boolean(passed), reason: reason ?? '' };
+}
+
+// ─── Principle predicates ─────────────────────────────────────────────────────
+
+/**
+ * Block if 2 or more prior failures on the same approach.
+ */
+function rejectsRepeatedFailedApproach(run) {
+  const count = run.failureHistory?.failureCount ?? 0;
+  if (count >= 2) {
+    return { blocked: true, reason: `${count} prior failures on similar approach — must change strategy or use dual-brain` };
+  }
+  return { blocked: false };
+}
+
+/**
+ * Block if no plan is present.
+ */
+function requiresApprovedPlan(run) {
+  if (!run.plan) {
+    return { blocked: true, reason: 'No execution plan — pipeline cannot proceed without a plan' };
+  }
+  return { blocked: false };
+}
+
+/**
+ * Warn if plan touches more than 10 files or 3+ unrelated areas.
+ * Not a hard block — returns warning in reason but blocked: false.
+ */
+function rejectsScopeCreep(run) {
+  const fileCount = run.context?.files?.explicit?.length ?? 0;
+  const extractedCount = run.context?.files?.extracted?.length ?? 0;
+  const total = fileCount + extractedCount;
+
+  if (total > 10) {
+    return { blocked: false, reason: `Scope warning: plan touches ${total} files — consider splitting into smaller tasks` };
+  }
+  return { blocked: false };
+}
+
+/**
+ * Block high/critical risk tasks that have no challenger configured.
+ */
+function requiresDualBrainForHighRisk(run) {
+  const risk = run.context?.detection?.risk ?? 'low';
+  const hasChallenger = run.plan?.useChallenger && run.plan?.challengerModel;
+
+  if ((risk === 'high' || risk === 'critical') && !hasChallenger) {
+    return { blocked: true, reason: `High-risk task (${risk}) requires dual-brain challenger — configure OpenAI provider or lower risk scope` };
+  }
+  return { blocked: false };
+}
+
+// ─── Five mandatory gates ─────────────────────────────────────────────────────
+
+/**
+ * Gate 1: Context gate.
+ * Passes only if failureHistory and priorOutcomes were actually queried (not null).
+ */
+export function contextGate(run) {
+  if (run.failureHistory === null) {
+    return gate(false, 'failureHistory was never queried — context phase incomplete');
+  }
+  if (run.priorOutcomes === null) {
+    return gate(false, 'priorOutcomes was never queried — context phase incomplete');
+  }
+  if (run.context === null) {
+    return gate(false, 'context pack was never built — context phase incomplete');
+  }
+  return gate(true, 'context loaded');
+}
+
+/**
+ * Gate 2: Planning gate.
+ * Passes if plan exists AND the proposed approach doesn't repeat a known failure.
+ */
+export function planningGate(run) {
+  if (!run.plan) {
+    return gate(false, 'No execution plan built');
+  }
+
+  // Check if the approach matches a prior failure
+  const history = run.failureHistory;
+  if (history?.hasPriorFailures && history?.escalation?.recommended) {
+    const esc = history.escalation;
+    // If the plan doesn't reflect the escalation (still using low depth when ultra is recommended)
+    const planDepth = run.plan.reasoningDepth ?? 'low';
+    const needsDepth = esc.toDepth ?? 'low';
+    const depthOrder = ['low', 'medium', 'high', 'ultra'];
+    const planIdx = depthOrder.indexOf(planDepth);
+    const needsIdx = depthOrder.indexOf(needsDepth);
+
+    if (planIdx < needsIdx) {
+      return gate(
+        false,
+        `Plan uses ${planDepth} reasoning but prior failures require ${needsDepth}. ${esc.reason}. Use a different strategy.`
+      );
+    }
+  }
+
+  return gate(true, 'plan approved');
+}
+
+/**
+ * Gate 3: Principle gate.
+ * Runs all principle predicates — any hard block fails the gate.
+ */
+export function principleGate(run) {
+  const checks = [
+    rejectsRepeatedFailedApproach(run),
+    requiresApprovedPlan(run),
+    rejectsScopeCreep(run),
+    requiresDualBrainForHighRisk(run),
+  ];
+
+  const blocked = checks.find(c => c.blocked);
+  if (blocked) {
+    return gate(false, blocked.reason);
+  }
+
+  // Collect non-blocking warnings for the reason field
+  const warnings = checks.filter(c => !c.blocked && c.reason).map(c => c.reason);
+  return gate(true, warnings.length ? warnings.join('; ') : 'all principles satisfied');
+}
+
+/**
+ * Gate 4: Execution gate.
+ * Final "cleared to work?" check — all previous gates must have passed and plan must exist.
+ */
+export function executionGate(run) {
+  const prevGates = ['context', 'planning', 'principle'];
+  for (const name of prevGates) {
+    const g = run.gates[name];
+    if (!g || !g.passed) {
+      return gate(false, `Upstream gate '${name}' did not pass — cannot proceed to execution`);
+    }
+  }
+  if (!run.plan) {
+    return gate(false, 'No plan present at execution gate');
+  }
+  return gate(true, 'cleared for execution');
+}
+
+/**
+ * Gate 5: Outcome gate.
+ * After execution, checks that an outcome was recorded.
+ */
+export function outcomeGate(run) {
+  if (run.result && run.outcome === null) {
+    return gate(false, 'Execution completed but outcome was not recorded');
+  }
+  return gate(true, 'outcome recorded');
+}
+
 // ─── Context Pack ─────────────────────────────────────────────────────────────
 
 /**
@@ -336,10 +541,12 @@ async function verify(result, plan, cwd) {
 
 // ─── Outcome recording ────────────────────────────────────────────────────────
 
-async function recordOutcomeSafe(plan, result, verification) {
+async function recordOutcomeSafe(run) {
   try {
     const { recordOutcome } = await import('./outcome.mjs');
-    await recordOutcome({ plan, result, verification });
+    const cwd = run.context?.cwd ?? process.cwd();
+    const recorded = await recordOutcome(run.plan, run.result, run.verification, cwd);
+    run.outcome = recorded;
   } catch {
     // outcome.mjs doesn't exist yet — silently skip
   }
@@ -371,6 +578,27 @@ async function _loadProfileSafe(cwd) {
   }
 }
 
+// ─── Gate runner ─────────────────────────────────────────────────────────────
+
+/**
+ * Run a named gate, store its result in run.gates, and return whether it passed.
+ * If gate throws, it is treated as a failure (fail-closed).
+ */
+function runGate(run, gateName, gateFn) {
+  let result;
+  try {
+    result = gateFn(run);
+  } catch (err) {
+    result = gate(false, `Gate '${gateName}' threw: ${err.message}`);
+  }
+  // Treat missing result or missing passed field as fail-closed
+  if (!result || typeof result.passed !== 'boolean') {
+    result = gate(false, `Gate '${gateName}' returned invalid result`);
+  }
+  run.gates[gateName] = result;
+  return result.passed;
+}
+
 // ─── Main entry point ─────────────────────────────────────────────────────────
 
 /**
@@ -386,7 +614,7 @@ async function _loadProfileSafe(cwd) {
  * @param {string}   [options.forceDepth]      Override reasoning depth
  * @param {boolean}  [options.forceChallenger] Force dual-brain challenger
  * @param {boolean}  [options.silent]          Suppress all output
- * @returns {Promise<{ plan: object, result: object|null, verification: object|null }>}
+ * @returns {Promise<{ plan: object, result: object|null, verification: object|null } | { success: false, gateFailure: string, reason: string, run: object } | { success: true, run: object }>}
  */
 export async function runPipeline(trigger, prompt, options = {}) {
   const {
@@ -401,67 +629,131 @@ export async function runPipeline(trigger, prompt, options = {}) {
 
   const log = silent ? () => {} : (msg) => process.stderr.write(msg + '\n');
 
-  let contextPack, plan, result = null, verification = null;
+  // Create the PipelineRun state object
+  const run = createPipelineRun(trigger, prompt);
 
   try {
-    // ── Step 1: Context Pack ─────────────────────────────────────────────────
-    contextPack = await buildContextPack(prompt, files, cwd);
+    // ── Phase 1: Context ──────────────────────────────────────────────────────
+
+    // Build context pack
+    run.context = await buildContextPack(prompt, files, cwd);
 
-    // ── Step 2: Execution Plan ───────────────────────────────────────────────
-    plan = buildExecutionPlan(contextPack, trigger, { forceDepth, forceChallenger });
+    // Query failure history (must happen before context gate)
+    try {
+      const { checkFailureHistory } = await import('./failure-memory.mjs');
+      run.failureHistory = await checkFailureHistory(prompt, files, cwd);
+    } catch {
+      // failure-memory.mjs unavailable — set to empty result so gate still passes
+      run.failureHistory = { hasPriorFailures: false, failureCount: 0, lastFailure: null, escalation: { recommended: false } };
+    }
+
+    // Query relevant outcomes (must happen before context gate)
+    try {
+      const { getRelevantOutcomes } = await import('./outcome.mjs');
+      run.priorOutcomes = await getRelevantOutcomes(prompt, files, cwd);
+    } catch {
+      // outcome.mjs unavailable — set to empty array so gate still passes
+      run.priorOutcomes = [];
+    }
+
+    // Gate 1: Context gate
+    if (!runGate(run, 'context', contextGate)) {
+      run.completedAt = Date.now();
+      return { success: false, gateFailure: 'context', reason: run.gates.context.reason, run };
+    }
+
+    // ── Phase 2: Plan ─────────────────────────────────────────────────────────
+
+    run.plan = buildExecutionPlan(run.context, trigger, { forceDepth, forceChallenger });
 
     if (verbose || dryRun) {
-      log(formatExecutionPlan(plan));
+      log(formatExecutionPlan(run.plan));
+    }
+
+    // Gate 2: Planning gate
+    if (!runGate(run, 'planning', planningGate)) {
+      run.completedAt = Date.now();
+      return { success: false, gateFailure: 'planning', reason: run.gates.planning.reason, run };
+    }
+
+    // Gate 3: Principle gate
+    if (!runGate(run, 'principle', principleGate)) {
+      run.completedAt = Date.now();
+      return { success: false, gateFailure: 'principle', reason: run.gates.principle.reason, run };
     }
 
     if (dryRun) {
-      return { plan, result: null, verification: null };
+      run.completedAt = Date.now();
+      // Return legacy-compatible shape for dry-run callers
+      return { plan: run.plan, result: null, verification: null, run };
     }
 
-    // ── Step 3: Checkpoint (best-effort, before execute) ────────────────────
-    if (plan.checkpointRequired) {
-      await createCheckpoint(cwd, contextPack);
+    // Gate 4: Execution gate (cleared to work?)
+    if (!runGate(run, 'execution', executionGate)) {
+      run.completedAt = Date.now();
+      return { success: false, gateFailure: 'execution', reason: run.gates.execution.reason, run };
     }
 
-    // ── Step 4: Execute ──────────────────────────────────────────────────────
-    const decision = {
-      ...plan._decision,
-      // Pass reasoning depth as a hint; dispatch uses effort from decision
-    };
+    // ── Phase 3: Execute ──────────────────────────────────────────────────────
 
-    result = await dispatch({
+    // Checkpoint (best-effort, before execute)
+    if (run.plan.checkpointRequired) {
+      await createCheckpoint(cwd, run.context);
+    }
+
+    const decision = { ...run.plan._decision };
+
+    run.result = await dispatch({
       decision,
       prompt,
       files,
       cwd,
       dryRun: false,
       verbose,
-      profile: contextPack.profile,
+      profile: run.context.profile,
     });
 
-    // ── Step 5: Verify ───────────────────────────────────────────────────────
-    verification = await verify(result, plan, cwd);
+    // ── Phase 4: Verification ─────────────────────────────────────────────────
+
+    run.verification = await verify(run.result, run.plan, cwd);
 
     if (verbose) {
-      log(`[pipeline] verification: ${verification.ok ? 'ok' : 'failed'}`);
-      for (const note of verification.notes) log(`[pipeline]   ${note}`);
+      log(`[pipeline] verification: ${run.verification.ok ? 'ok' : 'failed'}`);
+      for (const note of run.verification.notes) log(`[pipeline]   ${note}`);
     }
 
-    if (!verification.ok) {
+    if (!run.verification.ok) {
       _incrementFailureCache(prompt);
     }
 
+    // ── Phase 5: Outcome ──────────────────────────────────────────────────────
+
+    await recordOutcomeSafe(run);
+
+    // Gate 5: Outcome gate
+    if (!runGate(run, 'outcome', outcomeGate)) {
+      run.completedAt = Date.now();
+      return { success: false, gateFailure: 'outcome', reason: run.gates.outcome.reason, run };
+    }
+
   } catch (err) {
     log(`[pipeline] error in pipeline step: ${err.message}`);
-    result = { status: 'error', error: err.message };
-    verification = { ok: false, notes: [err.message] };
-    if (contextPack) _incrementFailureCache(prompt);
+    run.result = { status: 'error', error: err.message };
+    run.verification = { ok: false, notes: [err.message] };
+    if (run.context) _incrementFailureCache(prompt);
+    run.completedAt = Date.now();
+    return { success: false, gateFailure: 'error', reason: err.message, run };
   }
 
-  // ── Step 6: Outcome Record ───────────────────────────────────────────────
-  if (plan) {
-    await recordOutcomeSafe(plan, result, verification);
-  }
+  run.completedAt = Date.now();
 
-  return { plan: plan ?? null, result, verification };
+  // Return both new-style and legacy-compatible shapes
+  return {
+    success: true,
+    run,
+    // Legacy compatibility
+    plan: run.plan,
+    result: run.result,
+    verification: run.verification,
+  };
 }