atris 3.2.0 → 3.11.0

package/commands/autopilot.js

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync, execFileSync } = require('child_process');
+const { execSync, execFileSync, spawnSync } = require('child_process');
 const readline = require('readline');
 const { getLogPath, ensureLogDirectory, createLogFile } = require('../lib/journal');
 const { parseTodo } = require('../lib/todo');
@@ -73,7 +73,8 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
       task: `Re-read sources and update ${pageName}`,
       why: `"${sp.staleSource}" changed on ${sp.sourceDate} but the page was last compiled ${sp.compiledDate}. The content may be wrong.`,
       kind: 'staleness',
-      priority: 2
+      priority: 2,
+      skipKey: key
     });
     break;
   }
@@ -87,7 +88,8 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
       task: `Finish or remove stale task: ${st.title}`,
       why: `Claimed ${st.daysSinceClaim} days ago and never completed. Either finish it or delete it — stale tasks add noise.`,
       kind: 'cleanup',
-      priority: 3
+      priority: 3,
+      skipKey: key
     });
   }
 
@@ -103,6 +105,23 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
     });
   }
 
+  // --- Self-healing: unresolved fail lessons (bug still present per grep) ---
+  if (!skipped.has('self-heal')) {
+    const failLesson = pickUnresolvedFailLesson(cwd);
+    if (failLesson && !skipped.has(`self-heal:${failLesson.slug}`)) {
+      suggestions.push({
+        task: `Fix unresolved fail lesson: ${failLesson.slug}`,
+        why: `Lesson from ${failLesson.date} tagged \`fail\` and grep confirms the bug pattern is still present in-repo. Self-heal before taking new work.`,
+        kind: 'self-heal',
+        priority: 4.5,
+        lessonLine: failLesson.line,
+        lessonSlug: failLesson.slug,
+        lessonDate: failLesson.date,
+        skipKey: `self-heal:${failLesson.slug}`
+      });
+    }
+  }
+
   // --- Backlog tasks ---
   for (const t of todo.backlog) {
     if (t.tags && t.tags.includes('unverified')) continue;
@@ -117,6 +136,14 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
     break;
   }
 
+  // --- Proactive "surprise me" anomalies (didn't-ask-but-noticed signals) ---
+  try {
+    for (const anomaly of scanAnomalies(cwd)) {
+      if (anomaly.skipKey && skipped.has(anomaly.skipKey)) continue;
+      suggestions.push(anomaly);
+    }
+  } catch { /* anomaly scanner must never crash the tick */ }
+
   // --- Unprocessed inbox items ---
   const { logFile } = getLogPath();
   if (fs.existsSync(logFile)) {
@@ -492,6 +519,27 @@ Read today's journal completions and the git log from the past few days.
 Extract patterns worth remembering — things that surprised you, approaches that worked,
 mistakes that were caught. Append to atris/lessons.md. One line per lesson. Be specific.
 
+When done, reply: done.`;
+    }
+
+    if (kind === 'self-heal') {
+      const { lessonLine = '', lessonSlug = '' } = context;
+      const lessonBlock = lessonLine ? `\nUnresolved fail lesson:\n${lessonLine}\n` : '';
+      return `${baseRules}${lessonBlock}
+Self-heal task: ${task}
+
+This is an unresolved \`fail\` lesson from atris/lessons.md. grep confirms the bug pattern
+is still present in-repo — the fix has NOT been shipped yet.
+
+Plan the smallest fix:
+1. Parse the lesson for file:line references and the described bug pattern.
+2. Read those files to confirm the bug is exactly as described (or has drifted).
+3. Write ONE task in atris/TODO.md with:
+   - **Exit:** the specific behavior that proves the fix
+   - **Verify:** a command that fails now and will pass after the fix${lessonSlug ? ` (include "${lessonSlug}" in the task title so the lesson auto-resolves)` : ''}
+   - **Rollback:** how to revert if the fix misses
+4. Do NOT fix it in this phase — planner only. The executor will do the work.
+
 When done, reply: done.`;
     }
 
@@ -527,6 +575,32 @@ Task: ${task}
 4. Update MAP.md only if file locations truly shifted because of your change.
 5. If updating wiki pages, set last_compiled in frontmatter to today's date.
 
+When done, reply: done.`;
+    }
+
+    if (kind === 'self-heal') {
+      const { lessonLine = '', lessonSlug = '' } = context;
+      const lessonBlock = lessonLine ? `\nUnresolved fail lesson:\n${lessonLine}\n` : '';
+      return `You are the executor. Read your MEMBER.md spec first if available.
+
+Rules:
+- You CAN read and write code. You CANNOT plan or create new tasks.
+- Execute ONE step at a time. Verify each step before moving on.
+- Check MAP.md for file locations before grepping.
+- Stay in scope. Only fix the bug described in the lesson — no side quests.
+
+Read these files first:
+${readFiles}
+${lessonBlock}
+Self-heal task: ${task}
+
+1. Find the self-heal task in TODO.md and claim it (Claimed by: Executor at ${new Date().toISOString()}).
+2. Parse the lesson above for file:line references. Open those files and locate the bug pattern.
+3. Make the smallest change that removes the bug pattern AND makes the lesson's Verify command pass.
+4. Run the Verify command yourself to confirm it passes.
+5. Update MAP.md only if file:line locations shifted because of your fix.
+6. Commit: git add <specific-files> && git commit -m "fix: ${lessonSlug || 'self-heal'}"
+
 When done, reply: done.`;
     }
 
@@ -708,14 +782,46 @@ function regressionCheck(cwd) {
  */
 function getVerifyCommand(cwd, taskTitle) {
   const todoPath = path.join(cwd, 'atris', 'TODO.md');
-  if (!fs.existsSync(todoPath)) return { cmd: null, explicit: false };
-
-  const todo = parseTodo(todoPath);
-  const task = [...todo.inProgress, ...todo.backlog, ...todo.completed]
-    .find(t => t.title === taskTitle);
+  if (fs.existsSync(todoPath)) {
+    const todo = parseTodo(todoPath);
+    const task = [...todo.inProgress, ...todo.backlog, ...todo.completed]
+      .find(t => t.title === taskTitle);
+    if (task && task.verify) return { cmd: task.verify, explicit: true };
+  }
+  // Fallback: detect repo shape and pick a sensible default.
+  // Reactive tasks (inbox/staleness/imagined) don't carry explicit verify fields,
+  // so without shape detection they get `npm test` even on Python/Rust/Go repos.
+  return { cmd: detectDefaultVerify(cwd), explicit: false };
+}
 
-  if (!task || !task.verify) return { cmd: null, explicit: false };
-  return { cmd: task.verify, explicit: true };
+/**
+ * Infer a default verify command from the repo shape. Order matters:
+ * package.json with a non-stub test script → `npm test`; then pytest/python;
+ * then rust/go; otherwise null (no default — skip verify).
+ */
+function detectDefaultVerify(cwd) {
+  const pkg = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkg)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+      const test = parsed.scripts && parsed.scripts.test;
+      if (test && test !== 'echo "Error: no test specified" && exit 1') {
+        return 'npm test';
+      }
+    } catch { /* fall through */ }
+  }
+  if (fs.existsSync(path.join(cwd, 'pytest.ini')) ||
+      fs.existsSync(path.join(cwd, 'pyproject.toml')) ||
+      fs.existsSync(path.join(cwd, 'setup.py'))) {
+    return 'pytest';
+  }
+  if (fs.existsSync(path.join(cwd, 'Cargo.toml'))) {
+    return 'cargo test';
+  }
+  if (fs.existsSync(path.join(cwd, 'go.mod'))) {
+    return 'go test ./...';
+  }
+  return null;
 }
 
 /**
@@ -731,6 +837,303 @@ function verifyJudgeIntegrity() {
   return { ok: actual === REWARD_CHECKSUM, expected: REWARD_CHECKSUM, actual };
 }
 
+/**
+ * Build the validator's plan-review prompt. Fresh context — the validator
+ * reads the plan output and the contract fields as if it has never seen them.
+ */
+function buildPlanReviewPrompt(context, planOutput) {
+  const files = Array.isArray(context.files) && context.files.length
+    ? context.files.join(', ')
+    : 'none declared in context';
+  return `You are the validator in plan-review mode. You have NOT seen the planning context — read everything fresh.
+
+Task: "${context.task}"
+Kind: ${context.kind || 'unknown'}
+Files declared in context: ${files}
+
+Plan output from the navigator:
+---
+${planOutput || '(no plan output captured)'}
+---
+
+Read from disk:
+- atris/atris.md (the workspace protocol — operating rules and task shape)
+- atris/TODO.md (find this task; inspect Files, Exit, Verify, After, Rollback)
+- atris/lessons.md (recent failures — last 20 lines)
+
+Decide if the plan is safe to execute. Check:
+1. Verify points at a falsifiable rubric or test (not \`true\`, \`echo ok\`, or similar).
+   Prefer \`atris verify <slug> --section <name>\`.
+2. Files are explicitly declared (not empty, not vague).
+3. Rollback is named (commit, checkpoint, or \`git revert\`).
+4. The plan's claims match the declared Task fields.
+5. Nothing in lessons.md contradicts this plan.
+
+Output EXACTLY one of these two formats as the LAST thing in your response. No preamble before the verdict line.
+
+SIGNOFF: <one sentence on why the plan is safe>
+
+or
+
+REJECT: <one sentence on what is wrong>
+FIX: <one sentence on what must change>
+PROPOSED:
+  Files: <concrete path list, or omit this line if original is fine>
+  Exit: <sharp observable done condition, or omit this line if original is fine>
+  Verify: <falsifiable shell command, or omit this line if original is fine>
+  Rollback: <git revert <sha> or concrete checkpoint, or omit this line if original is fine>
+
+Be a drafting partner, not just a critic. When you REJECT, write the PROPOSED block as a concrete draft the human can accept as-is, edit, or reject. Include each PROPOSED line only for fields that need changing; skip a line if the original is correct. Omit the entire PROPOSED block only if the rejection is about scope or intent rather than a draftable field.
+`;
+}
+
+/**
+ * Parse the validator's verdict line(s) from their output. Returns one of:
+ *   { verdict: 'SIGNOFF', reason }
+ *   { verdict: 'REJECT', reason, fix }
+ * If neither format is present, treats it as a REJECT with a parse-fail reason.
+ */
+function parseVerdict(output) {
+  const text = String(output || '');
+  const rawLines = text.split('\n');
+  const lines = rawLines.map((l) => l.trim()).filter(Boolean);
+  // Scan from the end backwards — the verdict is supposed to be LAST.
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (/^SIGNOFF\s*:/i.test(line)) {
+      return { verdict: 'SIGNOFF', reason: line.replace(/^SIGNOFF\s*:\s*/i, ''), fix: '', proposed: null };
+    }
+    if (/^REJECT\s*:/i.test(line)) {
+      const reason = line.replace(/^REJECT\s*:\s*/i, '');
+      // Fix line is usually immediately after REJECT.
+      const tail = lines.slice(i);
+      const fixLine = tail.find((l) => /^FIX\s*:/i.test(l));
+      const fix = fixLine ? fixLine.replace(/^FIX\s*:\s*/i, '') : '';
+      const proposed = parseProposedBlock(rawLines.slice(rawLines.findIndex((l) => /PROPOSED\s*:/i.test(l))));
+      return { verdict: 'REJECT', reason, fix, proposed };
+    }
+  }
+  return {
+    verdict: 'REJECT',
+    reason: 'validator output did not contain SIGNOFF or REJECT',
+    fix: 'ensure validator emits machine-parseable verdict as the last line',
+    proposed: null,
+  };
+}
+
+/**
+ * Parse the PROPOSED block: 4 optional indented fields (Files, Exit, Verify,
+ * Rollback). Returns null if no block, or an object with only the fields the
+ * validator chose to propose.
+ */
+function parseProposedBlock(lines) {
+  if (!lines || !lines.length || !/PROPOSED\s*:/i.test(lines[0] || '')) return null;
+  const proposed = {};
+  const fieldMatchers = {
+    files: /^\s*Files\s*:\s*(.+)$/i,
+    exit: /^\s*Exit\s*:\s*(.+)$/i,
+    verify: /^\s*Verify\s*:\s*(.+)$/i,
+    rollback: /^\s*Rollback\s*:\s*(.+)$/i,
+  };
+  for (let j = 1; j < lines.length; j++) {
+    const raw = lines[j];
+    // Stop at a blank line or a new top-level marker (no leading whitespace
+    // and a known verb). Keep scanning through indented lines.
+    if (/^\S/.test(raw) && !/^(Files|Exit|Verify|Rollback)\s*:/i.test(raw)) break;
+    for (const [key, matcher] of Object.entries(fieldMatchers)) {
+      const m = raw.match(matcher);
+      if (m) proposed[key] = m[1].trim();
+    }
+  }
+  return Object.keys(proposed).length ? proposed : null;
+}
+
+/**
+ * Default executor for plan-review: spawn a fresh claude -p call.
+ * Kept thin so tests can inject a stub via options.planReviewExec.
+ */
+function defaultPlanReviewExecutor(prompt, { cwd, timeout = 180000 } = {}) {
+  const tmpFile = path.join(cwd, '.autopilot-plan-review.tmp');
+  fs.writeFileSync(tmpFile, prompt);
+  try {
+    const cmd = `claude -p "$(cat '${tmpFile.replace(/'/g, "'\\''")}')" --allowedTools "Bash,Read,Grep,Glob"`;
+    const env = { ...process.env };
+    delete env.CLAUDECODE;
+    const output = execSync(cmd, {
+      cwd,
+      encoding: 'utf8',
+      timeout,
+      stdio: 'pipe',
+      maxBuffer: 10 * 1024 * 1024,
+      env,
+    });
+    return output || '';
+  } catch (err) {
+    if (err.stdout) return err.stdout;
+    throw err;
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
+/**
+ * Default executor for codex: spawn `codex` with the prompt via stdin.
+ * Users can override with ATRIS_CODEX_CMD env var; tests inject via options.codexExec.
+ */
+function defaultCodexExecutor(prompt, { cwd, timeout = 180000 } = {}) {
+  const cmd = process.env.ATRIS_CODEX_CMD || 'codex';
+  const proc = spawnSync(cmd, ['-p', prompt], {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    stdio: 'pipe',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (proc.status !== 0 && !proc.stdout) {
+    throw new Error(`codex exited with status ${proc.status}: ${proc.stderr || 'no output'}`);
+  }
+  return proc.stdout || '';
+}
+
+/**
+ * Check if codex is available on PATH (or ATRIS_CODEX_CMD points to something runnable).
+ * Kept simple: `which` probe. Tests override via options.hasCodex.
+ */
+function hasCodex() {
+  const cmd = process.env.ATRIS_CODEX_CMD || 'codex';
+  try {
+    const r = spawnSync('which', [cmd], { stdio: 'pipe' });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run plan-review: the validator (and optionally codex) read the plan and
+ * decide if it is safe to execute. Returns { verdict, reason, fix, signers, notes }.
+ *
+ * Codex is invoked only when the task explicitly opts in:
+ *   - env ATRIS_USE_CODEX=1, or
+ *   - context.tags includes 'codex', or
+ *   - context.kind === 'endgame' AND context.tags includes 'gray' or 'high-risk'
+ *
+ * If codex is opted-in but not installed, we skip gracefully and surface a note.
+ * If both signers run and disagree, verdict is REJECT with both opinions in reason.
+ */
+function runPlanReview({ cwd, context, planOutput, options = {} }) {
+  const prompt = buildPlanReviewPrompt(context, planOutput);
+  const tags = Array.isArray(context.tags) ? context.tags : [];
+
+  // Primary signer: validator.
+  const validatorExec = options.planReviewExec || defaultPlanReviewExecutor;
+  const validatorOutput = validatorExec(prompt, { cwd, role: 'validator' });
+  const primary = parseVerdict(validatorOutput);
+
+  // Codex: opted in explicitly, not inferred.
+  const codexOptIn =
+    process.env.ATRIS_USE_CODEX === '1' ||
+    tags.includes('codex') ||
+    tags.includes('gray') ||
+    tags.includes('high-risk');
+
+  if (!codexOptIn) {
+    return { ...primary, signers: ['validator'], proposed: primary.proposed || null };
+  }
+
+  const codexCheck = options.hasCodex != null ? options.hasCodex : hasCodex();
+  if (!codexCheck) {
+    return {
+      ...primary,
+      signers: ['validator'],
+      proposed: primary.proposed || null,
+      notes: 'codex was requested but not on PATH; skipped gracefully',
+    };
+  }
+
+  const codexExec = options.codexExec || defaultCodexExecutor;
+  let codexOutput;
+  try {
+    codexOutput = codexExec(prompt, { cwd, role: 'codex' });
+  } catch (err) {
+    return {
+      ...primary,
+      signers: ['validator'],
+      notes: `codex invocation failed: ${err.message}; falling back to single signer`,
+    };
+  }
+  const codex = parseVerdict(codexOutput);
+
+  if (primary.verdict === 'SIGNOFF' && codex.verdict === 'SIGNOFF') {
+    return {
+      verdict: 'SIGNOFF',
+      reason: primary.reason,
+      fix: '',
+      proposed: null,
+      signers: ['validator', 'codex'],
+    };
+  }
+
+  // Any disagreement or joint reject → halt with both opinions surfaced.
+  // If either signer wrote a PROPOSED draft, surface the validator's first
+  // (or codex's if validator didn't propose one).
+  return {
+    verdict: 'REJECT',
+    reason: `Split verdict. validator=${primary.verdict} (${primary.reason || 'no reason'}); codex=${codex.verdict} (${codex.reason || 'no reason'}).`,
+    fix: primary.fix || codex.fix || 'reconcile the two signers before re-planning',
+    proposed: primary.proposed || codex.proposed || null,
+    signers: ['validator', 'codex'],
+    split: true,
+  };
+}
+
+/**
+ * Append a plan-review rejection to today's journal under ## Notes.
+ * Intentionally does NOT write to lessons.md — rejections only become lessons
+ * if a human spots a reusable failure pattern.
+ */
+function appendPlanRejection(cwd, context, review) {
+  try {
+    // Compute the journal path from the passed cwd so tests and isolated
+    // workspaces both work. getLogPath() resolves against process.cwd()
+    // which isn't always the task's workspace.
+    const date = new Date();
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const logFile = path.join(cwd, 'atris', 'logs', String(year), `${year}-${month}-${day}.md`);
+    if (!fs.existsSync(logFile)) return;
+    const now = new Date().toISOString().slice(0, 16).replace('T', ' ');
+    const signers = (review.signers || []).join(' + ');
+    const proposedBlock = review.proposed
+      ? `**Proposed draft:**\n` +
+        (review.proposed.files ? `- Files: ${review.proposed.files}\n` : '') +
+        (review.proposed.exit ? `- Exit: ${review.proposed.exit}\n` : '') +
+        (review.proposed.verify ? `- Verify: ${review.proposed.verify}\n` : '') +
+        (review.proposed.rollback ? `- Rollback: ${review.proposed.rollback}\n` : '')
+      : '';
+    const block =
+      `\n### Plan rejected — ${now}\n\n` +
+      `**Task:** ${context.task}\n` +
+      `**Signers:** ${signers}\n` +
+      `**Reason:** ${review.reason}\n` +
+      (review.fix ? `**Fix:** ${review.fix}\n` : '') +
+      (proposedBlock ? `${proposedBlock}` : '') +
+      (review.notes ? `**Notes:** ${review.notes}\n` : '');
+    let content = fs.readFileSync(logFile, 'utf8');
+    const notesIdx = content.indexOf('## Notes');
+    if (notesIdx === -1) {
+      content = content.replace(/\s*$/, '') + `\n\n## Notes\n${block}\n`;
+    } else {
+      const eol = content.indexOf('\n', notesIdx);
+      content = content.slice(0, eol + 1) + block + content.slice(eol + 1);
+    }
+    fs.writeFileSync(logFile, content);
+  } catch {
+    // journaling must never crash the tick
+  }
+}
+
 function runTaskOnce(context, options = {}) {
   const { verbose = false, cwd = process.cwd() } = options;
 
@@ -754,10 +1157,11 @@ function runTaskOnce(context, options = {}) {
   const verifyResult = getVerifyCommand(cwd, context.task);
   const verifyCmd = verifyResult.cmd;
 
-  // Guard: refuse to run ticks without an explicit Verify field
-  if (!verifyResult.explicit) {
+  // Guard: endgame tasks must have an explicit Verify field.
+  // Reactive signals (inbox, staleness, imagined) use npm test as default.
+  if (!verifyResult.explicit && context.kind === 'endgame') {
     writeLesson(cwd, 'no-verify-field', 'fail',
-      `Task "${context.task}" has no explicit **Verify:** field in TODO.md. Tick halted — every task must declare how to verify it.`);
+      `Task "${context.task}" has no explicit **Verify:** field in TODO.md. Tick halted — every endgame task must declare how to verify it.`);
     return {
       outcome: 'halted',
       reason: 'no-verify-field',
@@ -768,10 +1172,92 @@ function runTaskOnce(context, options = {}) {
     };
   }
 
-  for (const phase of ['plan', 'do', 'review']) {
+  // Falsifiability gate (endgame + explicit Verify only).
+  // Run Verify BEFORE the work. If it passes, the rubric is trivial or the
+  // task is already done — either way, halt. This is the keystone that makes
+  // Verify load-bearing. The cmd is captured here and reused post-execute so
+  // an agent cannot swap the rubric mid-tick.
+  const skipFalsifiability = options.skipFalsifiability === true;
+  if (!skipFalsifiability && verifyResult.explicit && context.kind === 'endgame' && verifyCmd) {
+    try {
+      execSync(verifyCmd, { cwd, stdio: 'pipe', timeout: 60000 });
+      writeLesson(cwd, 'verify-not-falsifiable', 'fail',
+        `Verify \`${verifyCmd}\` passed before work started on "${context.task}". Either the rubric is trivial or the task is already done. Tick halted.`);
+      return {
+        outcome: 'halted',
+        reason: 'verify-not-falsifiable',
+        phaseResults: {},
+        elapsedSeconds: 0,
+        verifyRan: true,
+        verifyPass: false,
+      };
+    } catch {
+      // Pre-verify failed — good, the rubric is falsifiable. Proceed.
+    }
+  }
+
+  // Phase: plan
+  {
+    const t0 = Date.now();
+    const result = (options.phaseExec || executePhaseDetailed)('plan', context, options);
+    phaseResults.plan = {
+      prompt: result.prompt,
+      output: result.output || '',
+      elapsedSeconds: Math.round((Date.now() - t0) / 1000),
+    };
+  }
+
+  // Phase: plan-review — validator reads the plan fresh and signs off or rejects.
+  // Can be skipped via options.skipPlanReview (tests only). Codex is optional,
+  // opt-in via env var / tags. On REJECT, the tick halts and the rejection is
+  // journaled; lessons.md is NOT touched (only promoted lessons go there).
+  if (!options.skipPlanReview) {
+    const t0 = Date.now();
+    const review = runPlanReview({
+      cwd,
+      context,
+      planOutput: phaseResults.plan.output,
+      options,
+    });
+    const elapsed = Math.round((Date.now() - t0) / 1000);
+    phaseResults['plan-review'] = {
+      output:
+        `${review.verdict}: ${review.reason || ''}` +
+        (review.fix ? `\nFIX: ${review.fix}` : '') +
+        (review.notes ? `\n(${review.notes})` : ''),
+      signers: review.signers,
+      elapsedSeconds: elapsed,
+    };
+
+    if (review.verdict === 'REJECT') {
+      appendPlanRejection(cwd, context, review);
+      return {
+        outcome: 'halted',
+        reason: 'plan-rejected-at-review',
+        phaseResults,
+        elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+        verifyRan: false,
+        verifyPass: false,
+      };
+    }
+  }
+
+  // Phase: do
+  {
     const t0 = Date.now();
-    const result = executePhaseDetailed(phase, context, options);
-    phaseResults[phase] = {
+    const result = (options.phaseExec || executePhaseDetailed)('do', context, options);
+    phaseResults.do = {
+      prompt: result.prompt,
+      output: result.output || '',
+      elapsedSeconds: Math.round((Date.now() - t0) / 1000),
+    };
+  }
+
+  // Phase: review
+  {
+    const t0 = Date.now();
+    const result = (options.phaseExec || executePhaseDetailed)('review', context, options);
+    phaseResults.review = {
       prompt: result.prompt,
       output: result.output || '',
       elapsedSeconds: Math.round((Date.now() - t0) / 1000),
@@ -1379,17 +1865,295 @@ function scoreEndgameCandidates(cwd, candidates) {
   }
 }
 
+/**
+ * Proactive "surprise me" scanner — surfaces things the user didn't ask about.
+ * Returns an array of suggestion objects in the same shape as the reactive
+ * signals in suggestNextTask. Three orthogonal checks, none requiring
+ * cross-session state:
+ *   - orphan-todo: `// TODO` or `// FIXME` in source with no matching backlog item
+ *   - unverified-detector: typed lesson has a detector but no last_detected stamp
+ *   - hotspot: file with >5 git commits in last 24h (churn signal)
+ *
+ * Each suggestion includes a `skipKey` so dry-run / skip doesn't re-fire it.
+ */
+function scanAnomalies(cwd) {
+  const results = [];
+  const atrisDir = path.join(cwd, 'atris');
+
+  // --- orphan-todo: code TODOs not tracked in TODO.md backlog ---
+  try {
+    const codeTodos = findCodeTodos(cwd);
+    if (codeTodos.length > 0) {
+      const todoFile = path.join(atrisDir, 'TODO.md');
+      const backlogText = fs.existsSync(todoFile) ? fs.readFileSync(todoFile, 'utf8') : '';
+      const untracked = codeTodos.filter(t => !isTodoTracked(t.text, backlogText));
+      if (untracked.length > 0) {
+        const first = untracked[0];
+        const sample = untracked.slice(0, 3).map(t => `${t.file}:${t.line}`).join(', ');
+        const firstText = first.text.slice(0, 60);
+        results.push({
+          task: `Track the ${untracked.length} orphan TODO${untracked.length > 1 ? 's' : ''} in source — first: "${firstText}"`,
+          why: `Code has ${untracked.length} \`// TODO\`/\`// FIXME\` comment${untracked.length > 1 ? 's' : ''} never written to TODO.md. First: "${firstText}" (${sample}). Either convert to real tasks or delete if obsolete.`,
+          kind: 'orphan-todo',
+          priority: 6,
+          skipKey: 'orphan-todo'
+        });
+      }
+    }
+  } catch { /* best-effort scan */ }
+
+  // --- unverified-detector: lesson has detector but last_detected missing/stale ---
+  try {
+    const meta = loadLessonMetadata(cwd);
+    const unverified = [];
+    for (const [slug, entry] of Object.entries(meta)) {
+      if (slug === '_schema') continue;
+      if (!entry || typeof entry !== 'object') continue;
+      if (!entry.detector) continue;
+      if (!entry.last_detected) unverified.push(slug);
+    }
+    if (unverified.length > 0) {
+      results.push({
+        task: `Run the ${unverified.length} unverified detector${unverified.length > 1 ? 's' : ''} in atris/lessons.json`,
+        why: `These lessons claim they're resolved via a detector but the detector has never been run: ${unverified.slice(0, 3).join(', ')}${unverified.length > 3 ? ', …' : ''}. Until it runs and exits 0, the resolved claim is unverified.`,
+        kind: 'unverified-detector',
+        priority: 5.5,
+        skipKey: 'unverified-detector'
+      });
+    }
+  } catch { /* best-effort */ }
+
+  // --- hotspot: file with high churn in last 24h ---
+  try {
+    const hotspot = findHotspot(cwd);
+    if (hotspot) {
+      results.push({
+        task: `Pause and review ${hotspot.file} — ${hotspot.commits} commits in the last 24h`,
+        why: `That file has churned more than any other file today. Could be genuine progress or a sign the change isn't sticking. Worth reading the diff before continuing.`,
+        kind: 'hotspot',
+        priority: 6.5,
+        skipKey: `hotspot:${hotspot.file}`
+      });
+    }
+  } catch { /* best-effort */ }
+
+  return results;
+}
+
+/**
+ * Grep source code for TODO/FIXME comments. Skips test/, node_modules/,
+ * atris/, and .md files. Returns [{file, line, text}].
+ *
+ * Uses a loose grep then filters to real comment prefixes in JS — git grep's
+ * -E flag doesn't support `\s` on macOS, so we keep the pattern simple and
+ * refine post-hoc.
+ */
+function findCodeTodos(cwd) {
+  try {
+    const out = execFileSync('git', [
+      'grep', '-n', '-I', '-E', '(TODO|FIXME)',
+      '--', ':!test/', ':!node_modules/', ':!atris/', ':!**/*.md'
+    ], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const results = [];
+    for (const raw of out.split('\n').filter(Boolean)) {
+      const m = raw.match(/^([^:]+):(\d+):(.*)$/);
+      if (!m) continue;
+      const line = m[3];
+      // A real TODO is a comment marker at the start of the line (allowing
+      // leading indent) followed by TODO/FIXME and at least one word. This
+      // rejects "TODO.md" string literals in templates (init.js:398 style).
+      const commentMatch = line.match(/^\s*(?:\/\/|#|\/\*|\*)\s*(TODO|FIXME):?\s+(\S.*)/);
+      if (!commentMatch) continue;
+      const text = commentMatch[2].replace(/\*\/\s*$/, '').trim();
+      if (!text) continue;
+      results.push({ file: m[1], line: parseInt(m[2], 10), text });
+      if (results.length >= 100) break;
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Heuristic: is a code TODO text substring already mentioned in the backlog?
+ * We check for significant words (>=4 chars) overlap. At least 2 must match.
+ */
+function isTodoTracked(todoText, backlogText) {
+  if (!todoText || !backlogText) return false;
+  const significantWords = todoText
+    .toLowerCase()
+    .split(/\W+/)
+    .filter(w => w.length >= 4 && !['todo', 'fixme', 'this', 'that', 'with', 'from', 'when', 'then'].includes(w));
+  if (significantWords.length === 0) return false;
+  const lowerBacklog = backlogText.toLowerCase();
+  const matches = significantWords.filter(w => lowerBacklog.includes(w)).length;
+  return matches >= Math.min(2, significantWords.length);
+}
+
+/**
+ * Find the file with the most commits in the last 24 hours. Returns null if
+ * no file has more than 5 commits (below the "hotspot" threshold).
+ */
+function findHotspot(cwd) {
+  try {
+    const out = execFileSync('git', [
+      'log', '--since=24.hours.ago', '--name-only', '--pretty=format:'
+    ], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const counts = {};
+    for (const f of out.split('\n').map(s => s.trim()).filter(Boolean)) {
+      counts[f] = (counts[f] || 0) + 1;
+    }
+    let best = null;
+    for (const [file, commits] of Object.entries(counts)) {
+      if (commits < 6) continue;
+      if (!best || commits > best.commits) best = { file, commits };
+    }
+    return best;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write `status: attempted` back to the typed lesson sidecar for a slug when
+ * a self-heal tick tried and failed. Increments `attempts`, stamps
+ * `last_attempt` (YYYY-MM-DD) and `last_attempt_reason`. Creates the sidecar
+ * (and the slug entry) if missing.
+ *
+ * This closes the survivorship-bias loop the oracle flagged: without this,
+ * the ledger only records fixes that worked, never the ones that didn't.
+ *
+ * @returns {boolean} true on success, false on malformed sidecar or write error
+ */
+function markLessonAttempted(cwd, slug, reason) {
+  if (!slug || typeof slug !== 'string') return false;
+  const metaPath = path.join(cwd, 'atris', 'lessons.json');
+  let meta = {};
+  if (fs.existsSync(metaPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      if (parsed && typeof parsed === 'object') meta = parsed;
+    } catch { return false; }
+  }
+  if (!meta[slug] || typeof meta[slug] !== 'object') meta[slug] = {};
+  meta[slug].status = 'attempted';
+  meta[slug].attempts = (typeof meta[slug].attempts === 'number' ? meta[slug].attempts : 0) + 1;
+  meta[slug].last_attempt = new Date().toISOString().slice(0, 10);
+  if (reason) meta[slug].last_attempt_reason = String(reason);
+  try {
+    const atrisDir = path.join(cwd, 'atris');
+    if (!fs.existsSync(atrisDir)) fs.mkdirSync(atrisDir, { recursive: true });
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Load the typed lesson metadata sidecar (atris/lessons.json).
+ * Keyed by slug. Each entry may carry: scope, applies_to, detector, status.
+ * Missing file or parse errors → empty object (prose-only fallback).
+ */
+function loadLessonMetadata(cwd) {
+  const metaPath = path.join(cwd, 'atris', 'lessons.json');
+  if (!fs.existsSync(metaPath)) return {};
+  try {
+    const raw = fs.readFileSync(metaPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse atris/lessons.md into structured lesson objects, joined with the
+ * optional atris/lessons.json sidecar by slug. Returns an array of:
+ *   { id, date, verdict, body, line, resolvedTag, meta, legacy }
+ * where `legacy` is true when no sidecar metadata exists for the slug.
+ */
+function parseLessons(cwd) {
+  const lessonsPath = path.join(cwd, 'atris', 'lessons.md');
+  if (!fs.existsSync(lessonsPath)) return [];
+  const content = fs.readFileSync(lessonsPath, 'utf8');
+  const metadata = loadLessonMetadata(cwd);
+
+  const out = [];
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine;
+    if (!line.trim().startsWith('- **[')) continue;
+    const m = line.match(/\*\*\[(\d{4}-\d{2}-\d{2})\]\s+([\w-]+)\*\*\s*[—-]\s*(pass|fail)?\s*[—-]?\s*(.*)$/);
+    if (!m) continue;
+    const [, date, id, verdict, rest] = m;
+    const resolvedTag = /\[resolved\]/.test(rest);
+    const body = rest.replace(/^\[resolved\]\s*/, '').trim();
+    const meta = metadata[id] || null;
+    out.push({
+      id,
+      date,
+      verdict: verdict || null,
+      body,
+      line: line.trim(),
+      resolvedTag,
+      meta,
+      legacy: !meta
+    });
+  }
+  return out;
+}
+
+/**
+ * Run a lesson's detector command. Returns true if the detector exits 0,
+ * false otherwise (non-zero exit, timeout, spawn error).
+ * execFileSync is intentionally avoided for detectors because they may
+ * legitimately shell out (e.g. `node --test path | grep X`).
+ */
+function runLessonDetector(detector, cwd, timeoutMs = 60000) {
+  if (!detector || typeof detector !== 'string') return false;
+  try {
+    execSync(detector, { cwd, stdio: 'pipe', timeout: timeoutMs });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check whether a lesson's bug pattern is still present in the named files.
- * Parses the lesson line for file paths (e.g. `commands/autopilot.js:116`)
- * and the slug (e.g. `inbox-parser-eats-hr-separator`). Greps the named
- * files for slug keywords. If none match → lesson is resolved.
+ *
+ * Detector-backed path (preferred): if sidecar metadata has `detector`, run it.
+ *   exit 0 → resolved (true). non-zero → not resolved (false).
+ *
+ * Legacy path (fallback): parse the lesson line for file paths + slug keywords
+ * and grep. If no keyword matches any named file → resolved (true).
  *
  * @param {string} lessonLine - A single line from lessons.md
  * @param {string} cwd - Current working directory
- * @returns {boolean} true if the lesson's bug pattern is gone (resolved)
+ * @param {object} [options] - Optional pre-loaded metadata ({ meta, detectorTimeout })
+ * @returns {boolean} true if the bug pattern is gone (resolved)
  */
-function isLessonResolved(lessonLine, cwd) {
+function isLessonResolved(lessonLine, cwd, options = {}) {
+  const slugMatch = lessonLine.match(/\*\*\[\d{4}-\d{2}-\d{2}\]\s+([\w-]+)\*\*/);
+  if (!slugMatch) return false;
+  const slug = slugMatch[1];
+
+  // Detector-backed check (typed lesson sidecar)
+  const meta = options.meta || loadLessonMetadata(cwd)[slug];
+  if (meta && meta.detector) {
+    return runLessonDetector(meta.detector, cwd, options.detectorTimeout);
+  }
+
+  // Legacy fallback: keyword grep against referenced files.
+  return isLessonResolvedLegacy(lessonLine, cwd);
+}
+
+/**
+ * The pre-v3.8 resolver — kept as an internal fallback for prose-only lessons
+ * that don't have detector metadata yet. Never auto-promotes a prose lesson to
+ * resolved in the typed system (callers can still use the `resolvedTag` field
+ * from parseLessons for hand-tagged entries).
+ */
+function isLessonResolvedLegacy(lessonLine, cwd) {
   // Extract slug: bold text after date, e.g. **[2026-04-08] inbox-parser-eats-hr-separator**
   const slugMatch = lessonLine.match(/\*\*\[\d{4}-\d{2}-\d{2}\]\s+([\w-]+)\*\*/);
   if (!slugMatch) return false;
@@ -1435,6 +2199,52 @@ function isLessonResolved(lessonLine, cwd) {
   return true;
 }
 
+/**
+ * Pick the oldest unresolved `fail` lesson whose bug pattern is still present.
+ * Returns { date, slug, line } for the top candidate, or null if none.
+ *
+ * Self-healing seed: instead of imagining new horizons via LLM, use what the
+ * system already wrote down about itself. A `fail` lesson with `isLessonResolved
+ * === false` means grep confirms the bug pattern is still present — actionable.
+ */
+function pickUnresolvedFailLesson(cwd) {
+  const lessons = parseLessons(cwd);
+  if (lessons.length === 0) return null;
+
+  const MAX_ATTEMPTS = 3;
+  const candidates = [];
+  for (const lesson of lessons) {
+    if (lesson.verdict !== 'fail') continue;
+    if (lesson.resolvedTag) continue;
+    // Typed lesson with explicit status wins — respect the sidecar.
+    // `resolved` = done. `observed` = process rule, not a fixable code state.
+    // `attempted` with attempts >= MAX_ATTEMPTS = needs human re-scoping, skip.
+    // Only `open` and `attempted` (under the cap) flow to self-heal execution.
+    if (lesson.meta && lesson.meta.status) {
+      const s = lesson.meta.status;
+      if (s === 'resolved' || s === 'observed') continue;
+      if (s === 'attempted' && (lesson.meta.attempts || 0) >= MAX_ATTEMPTS) continue;
+    }
+    // Detector-backed or legacy grep check.
+    if (isLessonResolved(lesson.line, cwd, { meta: lesson.meta })) continue;
+
+    candidates.push({
+      date: lesson.date,
+      slug: lesson.id,
+      line: lesson.line,
+      typed: !lesson.legacy,
+      detector: lesson.meta ? lesson.meta.detector || null : null,
+      attempts: lesson.meta ? (lesson.meta.attempts || 0) : 0
+    });
+  }
+
+  if (candidates.length === 0) return null;
+
+  // Oldest first — longest-standing fails get priority
+  candidates.sort((a, b) => a.date.localeCompare(b.date));
+  return candidates[0];
+}
+
 /**
  * Propose 3 candidate next horizons for the autopilot loop. Combines
  * `getIdleTickCount` + `getRecentSignals` into a prompt asking the LLM
@@ -1725,6 +2535,7 @@ async function autopilotAtris(description, options = {}) {
       }
       // Track as skipped so dry-run shows variety
       skipped.add(suggestion.task);
+      if (suggestion.skipKey) skipped.add(suggestion.skipKey);
       if (suggestion.kind === 'docs') skipped.add('fix-map-refs');
       if (suggestion.kind === 'review') skipped.add('review');
       if (suggestion.kind === 'lessons') skipped.add('lessons');
@@ -1755,7 +2566,7 @@ async function autopilotAtris(description, options = {}) {
 
     if (decision === 'skip') {
       skipped.add(suggestion.task);
-      if (suggestion.kind === 'staleness') skipped.add(`recompile:${suggestion.task}`);
+      if (suggestion.skipKey) skipped.add(suggestion.skipKey);
       if (suggestion.kind === 'docs') skipped.add('fix-map-refs');
       if (suggestion.kind === 'review') skipped.add('review');
       if (suggestion.kind === 'lessons') skipped.add('lessons');
@@ -1775,7 +2586,13 @@ async function autopilotAtris(description, options = {}) {
 
     // Execute: plan → do → review
     lastTaskTitle = suggestion.task;
-    const context = { task: suggestion.task, kind: suggestion.kind };
+    const context = {
+      task: suggestion.task,
+      kind: suggestion.kind,
+      ...(suggestion.lessonLine ? { lessonLine: suggestion.lessonLine } : {}),
+      ...(suggestion.lessonSlug ? { lessonSlug: suggestion.lessonSlug } : {}),
+      ...(suggestion.lessonDate ? { lessonDate: suggestion.lessonDate } : {})
+    };
     const startingEndgame = readEndgameState(cwd);
 
     try {
@@ -1798,6 +2615,9 @@ async function autopilotAtris(description, options = {}) {
         tickOutcome = 'halted';
         tickOutcomeText = `I halted before running "${lastTaskTitle}": ${execution.reason}.`;
         tickNextStep = 'stop until a human looks at the error';
+        if (suggestion.kind === 'self-heal' && suggestion.lessonSlug) {
+          markLessonAttempted(cwd, suggestion.lessonSlug, `halted:${execution.reason}`);
+        }
         if (!verbose) {
           printPlainBlock([
             `I halted: ${execution.reason}.`,
@@ -1823,6 +2643,9 @@ async function autopilotAtris(description, options = {}) {
         tickOutcome = 'halted';
         tickOutcomeText = `I built "${lastTaskTitle}" but review flagged issues.`;
         tickNextStep = 'wait for a human to check the review output';
+        if (suggestion.kind === 'self-heal' && suggestion.lessonSlug) {
+          markLessonAttempted(cwd, suggestion.lessonSlug, 'review-rejected');
+        }
         if (verbose) {
           console.log(`  review flagged issues (${reviewTime}s). stopping for manual check.`);
         } else {
@@ -1842,6 +2665,9 @@ async function autopilotAtris(description, options = {}) {
         tickOutcomeText = `I planned, built, and reviewed "${lastTaskTitle}" but verify failed.`;
         tickNextStep = 'verify failed, halting';
         writeLesson(cwd, 'verify-failed', 'fail', `Task "${lastTaskTitle}" passed review but failed verify command.`);
+        if (suggestion.kind === 'self-heal' && suggestion.lessonSlug) {
+          markLessonAttempted(cwd, suggestion.lessonSlug, 'verify-failed');
+        }
         if (verbose) {
           console.log(`  verify failed. stopping for manual check.`);
         } else {
@@ -2132,6 +2958,12 @@ module.exports = {
   autopilotFromTodo,
   buildPrompt,
   isLessonResolved,
+  isLessonResolvedLegacy,
+  loadLessonMetadata,
+  markLessonAttempted,
+  parseLessons,
+  pickUnresolvedFailLesson,
+  runLessonDetector,
   isStillTrue,
   getTaskAgeDays,
   getIdleTickCount,
@@ -2139,6 +2971,11 @@ module.exports = {
   getTickStatus,
   getVerifyCommand,
   computeTickReward,
+  detectDefaultVerify,
+  findCodeTodos,
+  findHotspot,
+  isTodoTracked,
+  scanAnomalies,
   verifyJudgeIntegrity,
   maybeWriteCompletedEndgameScorecard,
   renderHumanSuggestion,
@@ -2146,7 +2983,10 @@ module.exports = {
   proposeCandidateHorizons,
   recordTickCommit,
   regressionCheck,
+  runPlanReview,
   runTaskOnce,
+  buildPlanReviewPrompt,
+  parseVerdict,
   scoreEndgameCandidates,
   suggestNextTask,
   writeLesson