atris 3.15.56 → 3.16.0

package/bin/atris.js

@@ -67,8 +67,8 @@ const ensureValidCredentials = (opts) => _ensureValidCredentials(apiRequestJson,
 const fetchMyAgents = (token) => _fetchMyAgents(token, apiRequestJson);
 const displayAccountSummary = () => _displayAccountSummary(apiRequestJson);
 
-// Run update check in background (non-blocking)
-// Skip for 'version', 'update', and help commands to avoid redundant messages or help side effects.
+// Run update check in background (non-blocking).
+// Skip for machine-readable JSON and help commands to avoid corrupting stdout.
 let updateCheckPromise = null;
 const updateCommand = process.argv[2];
 const updateArgs = process.argv.slice(3);
@@ -78,7 +78,8 @@ const helpRequested = updateCommand === 'help'
   || updateArgs.includes('--help')
   || updateArgs.includes('-h')
   || updateArgs[0] === 'help';
-const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested);
+const jsonRequested = updateArgs.includes('--json');
+const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested || jsonRequested);
 if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
@@ -117,15 +118,6 @@ const isBusinessSyncSafetyCommand = command === 'sync'
     || firstCommandArg === 'resolve'
   );
 
-// Keep APP.md app-pack operations independent from the heavier workspace boot
-// path so `atris apps --json` stays machine-readable for agents.
-if (command === 'apps') {
-  const subcommand = process.argv[3];
-  const args = process.argv.slice(4);
-  require('../commands/apps').appsCommand(subcommand, ...args);
-  process.exit(0);
-}
-
 // Auto-sync skills only for commands that modify workspace state
 if (['init', 'update', 'upgrade'].includes(command) || (command === 'sync' && !isBusinessSyncSafetyCommand)) {
   try {
@@ -346,7 +338,7 @@ function showHelp() {
   console.log('  release    - Tag release, bump version, create GitHub release, draft /launch');
   console.log('  learn      - Project learnings (patterns, pitfalls, preferences)');
   console.log('  brain      - Compile MAP/TODO/wiki/state into a loadable agent brain');
-  console.log('  lesson     - Append a one-line lesson to atris/lessons.md');
+  console.log('  lesson     - Append a one-line lesson to atris/lessons.md (mine: distill receipts/episodes/scorecards into policy lessons)');
   console.log('  ingest     - Local-first wiki ingest into atris/wiki/');
   console.log('  query      - Local-first wiki query against atris/wiki/');
   console.log('  lint       - Local-first wiki lint for atris/wiki/');
@@ -355,6 +347,7 @@ function showHelp() {
   console.log('Optional helpers:');
   console.log('  brainstorm - Explore ideas conversationally before planning');
   console.log('  autopilot  - Guided loop that can clarify TODOs and run plan → do → review');
+  console.log('  improve    - Run one paid RL tick (POST /api/improve, deducts credits)');
   console.log('  worktree   - Isolated Git worktrees plus guarded ship/merge for parallel agents');
   console.log('  visualize  - Generate a Slack/deck-ready visual from a prompt');
   console.log('');
@@ -491,14 +484,18 @@ function showDoHelp() {
 
 function showReviewHelp() {
   console.log('');
-  console.log('Usage: atris review [--execute] [--full]');
+  console.log('Usage: atris review [--limit N|--all|--json] [--full|--execute]');
   console.log('');
   console.log('Description:');
-  console.log('  Activate the Validator agent to verify recent changes.');
-  console.log('  Reads TODO.md, MAP.md, and today\'s journal, then prints a validation');
-  console.log('  checklist (and, in agent mode, runs tests and updates docs).');
+  console.log('  Show the certified Review queue: proof-ready work waiting for');
+  console.log('  human accept or revise. Human accept is the AgentXP gate.');
+  console.log('  Use --full/--verbose for the legacy Validator prompt.');
   console.log('');
   console.log('Options:');
+  console.log('  --limit N   Show at most N certified review rows.');
+  console.log('  --all       Show all certified review rows.');
+  console.log('  --json      Emit the task-backed review queue as JSON.');
+  console.log('  --group-by  Group certified rows by tag, owner, or source.');
   console.log('  --execute   Run in agent mode via Atris cloud (requires login + agent).');
   console.log('  --full      Print full spec/context dumps (verbose copy/paste).');
   console.log('  --verbose   Alias for --full.');
@@ -769,7 +766,7 @@ if (command === '2' && ['fast', 'pro'].includes(String(firstCommandArg || '').to
 const knownCommands = ['init', 'log', 'now', 'radar', 'ctop', 'status', 'analytics', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
                        'activate', '_activate', 'agent', 'chat', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'verify', 'search', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
-                       'ingest', 'query', 'lint', 'loop', 'task', 'mission', 'worktree', 'aeo', 'xp', 'play', 'gm', 'x',
+                       'ingest', 'query', 'lint', 'loop', 'task', 'mission', 'worktree', 'aeo', 'improve', 'xp', 'play', 'gm', 'x',
                        'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet'];
 
@@ -1045,7 +1042,6 @@ async function interactiveEntry(userInput) {
 // ASCII Welcome Visualization
 function showWelcomeVisualization() {
   const { getBacklogTasks, getInProgressTasks } = require('../lib/state-detection');
-  const { getLogPath, ensureLogDirectory, createLogFile } = require('../lib/journal');
   const cwd = process.cwd();
   const atrisDir = path.join(cwd, 'atris');
   const projectName = path.basename(cwd);
@@ -1059,16 +1055,6 @@ function showWelcomeVisualization() {
   let isInitialized = fs.existsSync(atrisDir);
 
   if (isInitialized) {
-    // Auto-create today's journal if missing
-    try {
-      ensureLogDirectory();
-      const { logFile, dateFormatted } = getLogPath();
-      if (!fs.existsSync(logFile)) {
-        createLogFile(logFile, dateFormatted);
-      }
-    } catch {
-      // Silently fail - don't block welcome display
-    }
     // Check MAP.md
     const mapPath = path.join(atrisDir, 'MAP.md');
     if (fs.existsSync(mapPath)) {
@@ -1197,6 +1183,11 @@ if (command === 'init') {
   Promise.resolve(require('../commands/aeo').run(process.argv.slice(3)))
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'improve') {
+  // Improve: one paid RL tick via POST /api/improve (deducts credits), local autopilot fallback.
+  Promise.resolve(require('../commands/improve').run(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'brain') {
   Promise.resolve()
     .then(() => require('../commands/brain').brainCommand(process.argv.slice(3)))
@@ -1567,7 +1558,7 @@ if (command === 'init') {
   searchJournal(keyword);
 } else if (command === 'xp') {
   require('../commands/xp').xpCommand(...process.argv.slice(3))
-    .then(() => process.exit(0))
+    .then(() => { process.exitCode = 0; })
     .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'play') {
   require('../commands/play').playCommand(...process.argv.slice(3))
@@ -1622,6 +1613,14 @@ if (command === 'init') {
   integrationsStatus()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'apps') {
+  // Keep APP.md app-pack operations independent from the heavier workspace boot
+  // path so `atris apps --json` stays machine-readable for agents.
+  const subcommand = process.argv[3];
+  const args = process.argv.slice(4);
+  Promise.resolve(require('../commands/apps').appsCommand(subcommand, ...args))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'learn') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
@@ -1637,7 +1636,9 @@ if (command === 'init') {
 } else if (command === 'member') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
-  require('../commands/member').memberCommand(subcommand, ...args);
+  Promise.resolve(require('../commands/member').memberCommand(subcommand, ...args))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'app') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);

package/commands/align.js

@@ -173,20 +173,6 @@ async function walkCloud(token, businessId, workspaceId) {
   return { files: out, errors };
 }
 
-/**
- * Get cloud file content (for hash computation when /files doesn't return hashes).
- */
-async function fetchCloudFileHash(token, businessId, workspaceId, filePath) {
-  const result = await apiRequestJson(
-    `/business/${businessId}/workspaces/${workspaceId}/file?path=${encodeURIComponent(filePath)}`,
-    { method: 'GET', token }
-  );
-  if (!result.ok) return null;
-  const content = result.data && result.data.content;
-  if (typeof content !== 'string') return null;
-  return hashContent(Buffer.from(content, 'utf-8'));
-}
-
 /**
  * Wake the EC2 computer and wait until it's running.
  * Returns the endpoint URL or null on timeout.

package/commands/apps.js

@@ -1,6 +1,10 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { ensureValidCredentials } = require('../utils/auth');
+const { apiRequestJson } = require('../utils/api');
+
+const CLOUD_LOAD_COMMANDS = new Set(['load', 'cloud', 'mine']);
 
 function findAppsPackRoot(startDir = process.cwd()) {
   const explicit = process.env.ATRIS_APPS_PACK;
@@ -25,6 +29,7 @@ function appsUsageLines() {
     '',
     'Commands:',
     '  list [--json]                List available local apps',
+    '  load [--filter kind] [--json] Load owned cloud apps from Atris',
     '  run <slug> [--lines N]       Run an app and print data/latest.md or --json status',
     '  owner <slug> [--json]        Show owner view: launch, usage, learning, next actions',
     '  status [--json]              Show local app health',
@@ -156,7 +161,99 @@ function runPackScript(packRoot, script, args) {
   process.exit(result.status ?? 0);
 }
 
-function appsCommand(subcommand, ...rawArgs) {
+function normalizeCloudAppsPayload(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.apps)) return data.apps;
+  if (Array.isArray(data?.items)) return data.items;
+  if (Array.isArray(data?.data)) return data.data;
+  return [];
+}
+
+function compactCloudApp(app) {
+  const slug = app?.slug || app?.id || app?.name || 'unknown';
+  return {
+    id: app?.id || null,
+    name: app?.name || slug,
+    slug,
+    description: app?.description || null,
+    template: app?.template || app?.template_slug || null,
+    status: app?.status || app?.health || null,
+    last_run: app?.last_run || app?.lastRun || app?.last_run_at || null,
+    next_run: app?.next_run || app?.nextRun || app?.next_run_at || null,
+  };
+}
+
+function printCloudApps(apps, filter) {
+  const suffix = filter ? ` (${filter})` : '';
+  if (apps.length === 0) {
+    console.log(`No cloud apps found${suffix}.`);
+    return;
+  }
+  console.log(`Cloud apps${suffix}:`);
+  for (const app of apps) {
+    const name = String(app.name || app.slug || 'Untitled app');
+    const slug = String(app.slug || app.id || 'unknown');
+    const status = app.status ? ` status=${app.status}` : '';
+    const template = app.template ? ` template=${app.template}` : '';
+    console.log(`  ${slug.padEnd(24)} ${name}${status}${template}`);
+  }
+}
+
+function printAppsLoadHelp() {
+  console.log('');
+  console.log('Usage: atris apps load [--filter <template|paid|free>] [--json]');
+  console.log('');
+  console.log('Load owned cloud apps from Atris. Requires `atris login`.');
+  console.log('');
+}
+
+async function loadCloudApps(rawArgs) {
+  const args = [...rawArgs];
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    printAppsLoadHelp();
+    return;
+  }
+  const json = args.includes('--json');
+  if (json) args.splice(args.indexOf('--json'), 1);
+  let filter = popOption(args, '--filter', null);
+  if (!filter && args[0] && !args[0].startsWith('-')) filter = args.shift();
+  if (args.length > 0) {
+    exitAppsError(`Unknown apps load option: ${args[0]}`, json, { usage: true, code: 2 });
+  }
+
+  const ensured = await ensureValidCredentials(apiRequestJson);
+  if (ensured.error || !ensured.credentials?.token) {
+    exitAppsError('Not logged in. Run: atris login', json, {
+      extra: { login: 'atris login' },
+    });
+  }
+
+  const query = filter ? `?filter=${encodeURIComponent(filter)}` : '';
+  const result = await apiRequestJson(`/apps${query}`, {
+    method: 'GET',
+    token: ensured.credentials.token,
+  });
+  if (!result.ok) {
+    exitAppsError(`Failed to load cloud apps: ${result.error || result.status || 'request failed'}`, json, {
+      extra: { status: result.status || null },
+    });
+  }
+
+  const apps = normalizeCloudAppsPayload(result.data).map(compactCloudApp);
+  if (json) {
+    console.log(JSON.stringify({
+      ok: true,
+      source: 'cloud',
+      filter: filter || null,
+      count: apps.length,
+      apps,
+    }, null, 2));
+    return;
+  }
+  printCloudApps(apps, filter || null);
+}
+
+async function appsCommand(subcommand, ...rawArgs) {
   const jsonRequested = wantsJson(subcommand, rawArgs);
   const normalized = normalizeInvocation(subcommand, rawArgs);
   subcommand = normalized.subcommand;
@@ -166,6 +263,10 @@ function appsCommand(subcommand, ...rawArgs) {
     printAppsHelp();
     return;
   }
+  if (CLOUD_LOAD_COMMANDS.has(subcommand)) {
+    await loadCloudApps(rawArgs);
+    return;
+  }
   const packRoot = findAppsPackRoot();
   if (!packRoot) {
     if (jsonRequested) {

package/commands/autopilot.js

@@ -25,6 +25,46 @@ const pkg = require('../package.json');
 
 const PHASE_TIMEOUT = 600000; // 10 min per phase
 
+function looksOwnerClaimed(claimed) {
+  const text = String(claimed || '').toLowerCase();
+  return /\bkeshav(?:rao)?\b/.test(text) || /\b(owner|human|operator)\b/.test(text);
+}
+
+function looksOwnerGatedTitle(title) {
+  const text = String(title || '').toLowerCase();
+  return (
+    /\bowner[- ](?:approval|input|gate|gated)\b/.test(text) ||
+    /\bhuman[- ](?:approval|input|gate|gated)\b/.test(text) ||
+    /\bmanual send\b/.test(text) ||
+    /\broute confirmation\b/.test(text) ||
+    /\bconfirm pallet destination\b/.test(text) ||
+    /\bconfirm .+ destination before .+ approval\b/.test(text) ||
+    /\bapprove and manually send\b/.test(text)
+  );
+}
+
+function shouldSkipAutoHumanGate(task) {
+  if (!task) return false;
+  return looksOwnerClaimed(task.claimed) || looksOwnerGatedTitle(task.title || task.task);
+}
+
+function repoMapAuditReportsClean(cwd) {
+  const auditPath = path.join(cwd, 'scripts', 'audit_map_refs.py');
+  if (!fs.existsSync(auditPath)) return false;
+
+  const result = spawnSync('python3', [auditPath], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120000,
+    maxBuffer: 1024 * 1024
+  });
+  if (result.status !== 0) return false;
+
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  const match = output.match(/Total broken references:\s*(\d+)/i);
+  return Boolean(match && Number(match[1]) === 0);
+}
+
 /**
  * Scan workspace for the next thing worth doing.
  * Returns { task, why, kind } or null.
@@ -54,7 +94,7 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
   // --- Resume interrupted work ---
   if (todo.inProgress.length > 0) {
     const t = todo.inProgress[0];
-    if (!(t.tags && t.tags.includes('unverified')) && !skipped.has(t.title)) {
+    if (!(t.tags && t.tags.includes('unverified')) && !skipped.has(t.title) && !(auto && shouldSkipAutoHumanGate(t))) {
       suggestions.push({
         task: t.title,
         why: `This was already started${t.claimed ? ` by ${t.claimed}` : ''} but never finished.`,
@@ -75,6 +115,7 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
       why: `"${sp.staleSource}" changed on ${sp.sourceDate} but the page was last compiled ${sp.compiledDate}. The content may be wrong.`,
       kind: 'staleness',
       priority: 2,
+      files: [pageName, sp.staleSource],
       skipKey: key
     });
     break;
@@ -95,7 +136,9 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
   }
 
   // --- Broken MAP.md references ---
-  const { unhealable } = healBrokenMapRefs(cwd, atrisDir, true); // dry-run
+  const { unhealable } = repoMapAuditReportsClean(cwd)
+    ? { unhealable: [] }
+    : healBrokenMapRefs(cwd, atrisDir, true); // dry-run
   if (unhealable.length > 0 && !skipped.has('fix-map-refs')) {
     const sample = unhealable.slice(0, 3).map(r => `${r.file}:${r.line}`).join(', ');
     suggestions.push({
@@ -127,6 +170,7 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false } = {})
   for (const t of todo.backlog) {
     if (t.tags && t.tags.includes('unverified')) continue;
     if (shouldSkipEndgameAtPicker(cwd, t)) continue;
+    if (auto && shouldSkipAutoHumanGate(t)) continue;
     if (skipped.has(t.title)) continue;
     const remaining = todo.backlog.filter(b => !(b.tags && b.tags.includes('unverified'))).length;
     suggestions.push({
@@ -383,10 +427,6 @@ function executePhaseDetailed(phase, context, options = {}) {
   }
 }
 
-function executePhase(phase, context, options = {}) {
-  return executePhaseDetailed(phase, context, options).output;
-}
-
 /**
  * Build context-aware file list for prompts.
  */
@@ -422,7 +462,13 @@ function buildPrompt(phase, context, options = {}) {
     contextNote = '',
     runnerName = '',
   } = options;
-  const readFiles = getContextFiles(phase, options);
+  const readFiles = getContextFiles(phase, {
+    ...options,
+    extraReadFiles: [
+      ...(options.extraReadFiles || []),
+      ...(Array.isArray(context.files) ? context.files : []),
+    ],
+  });
   const benchmarkProtocol = benchmarkStrategy === 'stack'
     ? 'coordinated stack run'
     : (benchmarkStrategy === 'single' ? 'pinned single-model baseline run' : '');
@@ -478,12 +524,24 @@ When done, reply: done.`;
     }
 
     if (kind === 'staleness' || kind === 'docs' || kind === 'review') {
+      const fileList = Array.isArray(context.files) && context.files.length
+        ? context.files.map((file) => `- ${file}`).join('\n')
+        : '- target page or MAP entry from the task title\n- source file(s) that changed';
       return `${baseRules}
 
 Maintenance task: ${task}
 
-Figure out what needs to change and why. Create focused tasks in atris/TODO.md.
+Relevant files:
+${fileList}
+
+Figure out what needs to change and why. Create exactly one focused task in atris/TODO.md unless the drift truly requires separate commits.
 For stale pages, read both the page and its sources to understand the drift.
+The task row must include these fields so plan-review can prove it is executable:
+- **Files:** concrete target page plus source file paths
+- **Exit:** the observable post-update state
+- **Verify:** one raw shell command that checks concrete facts and rejects stale phrases; use shell operators like \`&&\`, \`grep -q\`, or \`test\`, not Markdown backticks or English like "returns 1" / "shows today's date"
+- **Rollback:** git checkout -- <changed-files> before commit, or git revert HEAD --no-edit after commit
+Do not write tasks without Verify and Rollback. Do not use \`true\`, \`echo ok\`, or vague "review manually" verification.
 
 When done, reply: done.`;
     }
@@ -802,6 +860,56 @@ function getVerifyCommand(cwd, taskTitle) {
   return { cmd: detectDefaultVerify(cwd), explicit: false };
 }
 
+function collectExplicitVerifyTasks(cwd) {
+  const todoPath = path.join(cwd, 'atris', 'TODO.md');
+  if (!fs.existsSync(todoPath)) return [];
+  const todo = parseTodo(todoPath);
+  return [...todo.inProgress, ...(todo.review || []), ...todo.backlog, ...todo.completed]
+    .filter((task) => task && task.verify)
+    .map((task) => ({
+      title: task.title,
+      verify: task.verify,
+      key: `${task.title}\0${task.verify}`,
+    }));
+}
+
+function findNewExplicitVerifyCommand(cwd, beforeKeys) {
+  const prior = beforeKeys instanceof Set ? beforeKeys : new Set(beforeKeys || []);
+  const added = collectExplicitVerifyTasks(cwd).filter((task) => !prior.has(task.key));
+  if (added.length !== 1) return null;
+  return { cmd: added[0].verify, explicit: true, task: added[0].title };
+}
+
+function shouldAdoptPlannedVerify(kind) {
+  return ['staleness', 'docs', 'review', 'inbox', 'cleanup', 'feature', 'lessons', 'imagined'].includes(kind);
+}
+
+function validateVerifyCommandShape(cmd) {
+  const text = String(cmd || '').trim();
+  if (!text) return { ok: true };
+  if (text.includes('`')) {
+    return { ok: false, reason: 'Verify contains markdown backticks instead of a raw shell command' };
+  }
+  if (/\b(returns?|shows?|equals?|should|must)\b/i.test(text)) {
+    return { ok: false, reason: 'Verify contains prose expectations instead of shell operators/assertions' };
+  }
+  return { ok: true };
+}
+
+function haltInvalidVerify(cwd, context, verifyCmd, reason, startedAt, phaseResults = {}) {
+  writeLesson(cwd, 'verify-not-runnable', 'fail',
+    `Verify \`${verifyCmd}\` for "${context.task}" is not a runnable shell command: ${reason}. Tick halted.`);
+  return {
+    outcome: 'halted',
+    reason: 'verify-not-runnable',
+    phaseResults,
+    elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+    verifyRan: false,
+    verifyPass: false,
+    verifyCmd,
+  };
+}
+
 /**
  * Infer a default verify command from the repo shape. Order matters:
  * package.json with a non-stub test script → `npm test`; then pytest/python;
@@ -878,7 +986,7 @@ Read from disk:
 - 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).
+1. Verify points at a falsifiable raw shell command or rubric (not \`true\`, \`echo ok\`, Markdown backticks, or English like "returns 1" / "shows today's date").
    Prefer \`atris verify <slug> --section <name>\`.
 2. Files are explicitly declared (not empty, not vague).
 3. Rollback is named (commit, checkpoint, or \`git revert\`).
@@ -1170,8 +1278,15 @@ function runTaskOnce(context, options = {}) {
 
   const phaseResults = {};
   const startedAt = Date.now();
-  const verifyResult = getVerifyCommand(cwd, context.task);
-  const verifyCmd = verifyResult.cmd;
+  let verifyResult = getVerifyCommand(cwd, context.task);
+  let verifyCmd = verifyResult.cmd;
+  const explicitVerifyBefore = new Set(
+    collectExplicitVerifyTasks(cwd).map((task) => task.key)
+  );
+  const initialVerifyShape = validateVerifyCommandShape(verifyCmd);
+  if (!initialVerifyShape.ok) {
+    return haltInvalidVerify(cwd, context, verifyCmd, initialVerifyShape.reason, startedAt, phaseResults);
+  }
 
   // Guard: endgame tasks must have an explicit Verify field.
   // Reactive signals (inbox, staleness, imagined) use npm test as default.
@@ -1264,6 +1379,18 @@ function runTaskOnce(context, options = {}) {
     }
   }
 
+  if (!verifyResult.explicit && shouldAdoptPlannedVerify(context.kind)) {
+    const plannedVerify = findNewExplicitVerifyCommand(cwd, explicitVerifyBefore);
+    if (plannedVerify) {
+      verifyResult = plannedVerify;
+      verifyCmd = plannedVerify.cmd;
+    }
+  }
+  const plannedVerifyShape = validateVerifyCommandShape(verifyCmd);
+  if (!plannedVerifyShape.ok) {
+    return haltInvalidVerify(cwd, context, verifyCmd, plannedVerifyShape.reason, startedAt, phaseResults);
+  }
+
   // Phase: do
   {
     const t0 = Date.now();
@@ -1975,12 +2102,13 @@ function findCodeTodos(cwd) {
   try {
     const out = execFileSync('git', [
       'grep', '-n', '-I', '-E', '(TODO|FIXME)',
-      '--', ':!test/', ':!node_modules/', ':!atris/', ':!**/*.md'
+      '--', ':!test/', ':!node_modules/', ':!atris/', ':!**/_archive/**', ':!**/*.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;
+      if (m[1].split(/[\\/]/).includes('_archive')) 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
@@ -2160,16 +2288,63 @@ function isLessonResolved(lessonLine, cwd, options = {}) {
   if (!slugMatch) return false;
   const slug = slugMatch[1];
 
+  if (isCleanMapBrokenRefFailLesson(lessonLine, cwd)) return true;
+
   // Detector-backed check (typed lesson sidecar)
   const meta = options.meta || loadLessonMetadata(cwd)[slug];
   if (meta && meta.detector) {
     return runLessonDetector(meta.detector, cwd, options.detectorTimeout);
   }
 
+  if (inlinePythonVerifyFailureNowPasses(lessonLine, cwd, options.detectorTimeout)) return true;
+
   // Legacy fallback: keyword grep against referenced files.
   return isLessonResolvedLegacy(lessonLine, cwd);
 }
 
+function isCleanMapBrokenRefFailLesson(lessonLine, cwd) {
+  const text = String(lessonLine || '').toLowerCase();
+  if (!/fix \d+ broken references? in map\.md/.test(text)) return false;
+  return repoMapAuditReportsClean(cwd);
+}
+
+function extractInlinePythonVerifyFailure(lessonLine) {
+  const commandMatch = String(lessonLine || '').match(/Verify command\s+``([\s\S]*?)``\s+failed/i);
+  if (!commandMatch) return null;
+  const matches = [...commandMatch[1].matchAll(/\b(python3?)\s+-c\s+(["'])([\s\S]*?)\2/g)];
+  const match = matches[matches.length - 1];
+  if (!match) return null;
+  return {
+    executable: match[1],
+    code: match[3].replace(/\\"/g, '"').replace(/\\'/g, "'")
+  };
+}
+
+function inlinePythonVerifyFailureNowPasses(lessonLine, cwd, timeout = 10000) {
+  const parsed = extractInlinePythonVerifyFailure(lessonLine);
+  if (!parsed) return false;
+  const result = spawnSync(parsed.executable, ['-c', parsed.code], {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    stdio: ['ignore', 'ignore', 'ignore']
+  });
+  return result.status === 0;
+}
+
+function legacyLessonFileRefs(lessonLine) {
+  const fileRefs = [];
+  const filePattern = /`([a-zA-Z0-9_/./-]+\.[a-zA-Z]+(?::\d+(?:-\d+)?)?)`/g;
+  let m;
+  while ((m = filePattern.exec(lessonLine)) !== null) {
+    const ref = m[1].replace(/:\d+(-\d+)?$/, '');
+    if (ref.includes('/') || ref.endsWith('.js') || ref.endsWith('.md') || ref.endsWith('.ts')) {
+      fileRefs.push(ref);
+    }
+  }
+  return fileRefs;
+}
+
 /**
  * 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
@@ -2182,16 +2357,7 @@ function isLessonResolvedLegacy(lessonLine, cwd) {
   if (!slugMatch) return false;
   const slug = slugMatch[1];
 
-  // Extract file paths: patterns like `commands/autopilot.js:116` or `commands/run.js:157`
-  const fileRefs = [];
-  const filePattern = /`([a-zA-Z0-9_/./-]+\.[a-zA-Z]+(?::\d+(?:-\d+)?)?)`/g;
-  let m;
-  while ((m = filePattern.exec(lessonLine)) !== null) {
-    const ref = m[1].replace(/:\d+(-\d+)?$/, ''); // strip line numbers
-    if (ref.includes('/') || ref.endsWith('.js') || ref.endsWith('.md') || ref.endsWith('.ts')) {
-      fileRefs.push(ref);
-    }
-  }
+  const fileRefs = legacyLessonFileRefs(lessonLine);
 
   if (fileRefs.length === 0) return false;
 
@@ -2274,6 +2440,9 @@ function pickUnresolvedFailLesson(cwd) {
   const candidates = [];
   for (const lesson of lessons) {
     if (lesson.verdict !== 'fail') continue;
+    if (lesson.id === 'verify-not-falsifiable') continue;
+    if (lesson.id === 'no-verify-field') continue;
+    if (lesson.id === 'verify-failed' && lesson.legacy) continue;
     if (lesson.resolvedTag) continue;
     // Typed lesson with explicit status wins — respect the sidecar.
     // `resolved` = done. `observed` = process rule, not a fixable code state.
@@ -2284,6 +2453,7 @@ function pickUnresolvedFailLesson(cwd) {
       if (s === 'resolved' || s === 'observed') continue;
       if (s === 'attempted' && (lesson.meta.attempts || 0) >= MAX_ATTEMPTS) continue;
     }
+    if (lesson.legacy && legacyLessonFileRefs(lesson.line).length === 0) continue;
     // Detector-backed or legacy grep check.
     if (isLessonResolved(lesson.line, cwd, { meta: lesson.meta })) continue;
 
@@ -2658,6 +2828,7 @@ async function autopilotAtris(description, options = {}) {
     const context = {
       task: suggestion.task,
       kind: suggestion.kind,
+      ...(suggestion.files ? { files: suggestion.files } : {}),
       ...(suggestion.lessonLine ? { lessonLine: suggestion.lessonLine } : {}),
       ...(suggestion.lessonSlug ? { lessonSlug: suggestion.lessonSlug } : {}),
       ...(suggestion.lessonDate ? { lessonDate: suggestion.lessonDate } : {})
@@ -3052,11 +3223,15 @@ module.exports = {
   proposeCandidateHorizons,
   recordTickCommit,
   regressionCheck,
+  repoMapAuditReportsClean,
+  isCleanMapBrokenRefFailLesson,
+  inlinePythonVerifyFailureNowPasses,
   runPlanReview,
   runTaskOnce,
   buildPlanReviewPrompt,
   parseVerdict,
   scoreEndgameCandidates,
   suggestNextTask,
+  shouldSkipAutoHumanGate,
   writeLesson
 };