atris 3.58.8 → 3.59.0

package/commands/mission.js

@@ -21,6 +21,7 @@ const {
 } = require('../lib/brief-ledger');
 const {
   resolveClaudeRunnerModel,
+  resolvePinnedRunnerModel,
   resolveClaudeRunnerBin,
   resolveClaudeRunnerCommandTemplate,
   buildRunnerCommand,
@@ -385,13 +386,59 @@ function resolveMissionRunnerSelection(value, options = {}) {
   exitMissionError(`Unknown ${noun} "${raw}". ${knownMissionRunnerText()}.`, 2, asJson);
 }
 
-function resolveMissionTickRunner(mission, root = process.cwd()) {
+// The roster line's effort and time cap for this tick, when it sets them.
+function rosterTickPins(engine) {
+  return {
+    ...(engine && engine.roster_effort ? { roster_effort: engine.roster_effort } : {}),
+    ...(engine && engine.roster_max_seconds ? { roster_max_seconds: engine.roster_max_seconds } : {}),
+  };
+}
+
+// A tick's time limit: the time left on the mission, capped by the roster
+// line's "max 20 min" when it sets one, else by the default tick cap.
+function missionTickTimeoutMs(mission, remainingMs) {
+  const cap = Number(mission && mission.roster_max_seconds) > 0
+    ? Number(mission.roster_max_seconds) * 1000
+    : MISSION_RUN_DEFAULTS.claudeTimeoutMs;
+  return clampTimeoutMs(remainingMs, cap);
+}
+
+function resolveMissionTickRunner(mission, root = process.cwd(), options = {}) {
   if (String(mission && mission.runner || '').trim().toLowerCase() !== MISSION_AUTO_RUNNER) {
     return { mission, engine_id: null, requested_engine: null, engine_fallback_reason: null };
   }
-  const resolved = resolveEngineForRoleWithPreference('executor', root, mission.preferred_engine);
+  // A mission owned by a team member runs on that member's roster pick. An
+  // explicit preferred engine (or a run's --engine) still wins, and with no
+  // roster line behind the member, routing stays exactly as it was.
+  if (!String(mission.preferred_engine || '').trim() && mission.owner) {
+    const { memberRosterEngine } = require('../lib/member-engine');
+    const member = memberRosterEngine(mission.owner, root, options);
+    if (member) {
+      if (process.env.ATRIS_ROUTER_EXPLAIN !== '0') console.error(member.reason);
+      return {
+        mission: {
+          ...mission,
+          runner: member.engine.id,
+          runner_kind: 'engine',
+          ...(!mission.model && member.model ? { model: member.model } : {}),
+          ...rosterTickPins(member.engine),
+        },
+        engine_id: member.engine.id,
+        requested_engine: null,
+        engine_fallback_reason: null,
+        member_engine_reason: member.reason,
+      };
+    }
+  }
+  const resolved = resolveEngineForRoleWithPreference('executor', root, mission.preferred_engine, options);
   return {
-    mission: resolved.engine ? { ...mission, runner: resolved.engine.id, runner_kind: 'engine' } : mission,
+    mission: resolved.engine ? {
+      ...mission,
+      runner: resolved.engine.id,
+      runner_kind: 'engine',
+      ...(!mission.model && resolved.engine.roster_model ? { model: resolved.engine.roster_model } : {}),
+      ...rosterTickPins(resolved.engine),
+    } : mission,
     engine_id: resolved.engine ? resolved.engine.id : null,
     requested_engine: resolved.requested_engine,
     engine_fallback_reason: resolved.engine_fallback_reason,
@@ -444,6 +491,20 @@ function applyMissionRunnerProfile(runner) {
   };
 }
 
+// Claude-family engines share the claude CLI, so they keep the resolved
+// default model pin. Every other engine's CLI rejects a claude model name, so
+// it only ever takes an explicit pin (the mission's model or the roster
+// line's); '' lets the engine ride its own default.
+const CLAUDE_FAMILY_RUNNER_ENGINES = new Set(['claude', 'fable', 'haiku']);
+
+function resolveMissionTickRunnerModel(mission) {
+  const engine = canonicalEngineName(mission && mission.runner);
+  if (!engine || CLAUDE_FAMILY_RUNNER_ENGINES.has(engine)) {
+    return resolveClaudeRunnerModel(mission);
+  }
+  return resolvePinnedRunnerModel(mission);
+}
+
 function exitMissionError(message, code = 1, asJson = false) {
   if (asJson) {
     printCliJson(
@@ -8745,7 +8806,7 @@ function spawnGenericRunnerTick(mission, opts) {
     let briefId = null;
     try {
       promptFile = writeRunnerPromptFile(cwd, mission.id, prompt);
-      cmd = buildRunnerCommand({ promptFile, model });
+      cmd = buildRunnerCommand({ promptFile, model, ...(mission.roster_effort ? { effort: mission.roster_effort } : {}) });
       const engine = canonicalEngineName(mission.runner);
       if (engine) {
         const record = appendBriefRecord(cwd, {
@@ -8922,6 +8983,7 @@ function spawnClaudeTick(mission, opts) {
       '--include-partial-messages',
     ];
     if (model) args.push('--model', model);
+    if (mission.roster_effort) args.push('--effort', mission.roster_effort);
     if (sessionMode === 'set') args.push('--session-id', sessionId);
     else if (sessionMode === 'resume') args.push('--resume', sessionId);
 
@@ -9088,7 +9150,7 @@ async function runEngineVerifier(mission, options = {}) {
       signal: options.signal,
       timeoutMs: ENGINE_VERIFY_TIMEOUT_MS,
       prompt: buildEngineVerifyPrompt(mission, options.tickIndex || 1),
-      model: resolveClaudeRunnerModel(verifyMission),
+      model: resolveMissionTickRunnerModel(verifyMission),
     });
   } catch (error) {
     engineResult = { ok: false, error: error.message };
@@ -9668,12 +9730,12 @@ async function executeMissionRunTicksPhase(context) {
         const runClaudeSession = () => spawnClaudeTick(tickRuntimeMission, {
           sessionMode, sessionId: useId, cwd, signal: controller.signal,
           missionLock: lock,
-          timeoutMs: clampTimeoutMs(
+          timeoutMs: missionTickTimeoutMs(
+            tickRuntimeMission,
             (maxWallSeconds - ((Date.now() - startedAt) / 1000)) * 1000,
-            MISSION_RUN_DEFAULTS.claudeTimeoutMs,
           ),
           prompt,
-          model: resolveClaudeRunnerModel(tickRuntimeMission),
+          model: resolveMissionTickRunnerModel(tickRuntimeMission),
         });
         try {
           claudeResult = await runClaudeSession();
@@ -11726,6 +11788,8 @@ module.exports = {
   missionHumanStatusText,
   resolveMissionRunnerSelection,
   resolveMissionTickRunner,
+  resolveMissionTickRunnerModel,
+  missionTickTimeoutMs,
   engineFailureHealthStatus,
   recordMissionEngineTickOutcome,
   tickMadeProgress,

package/commands/one-lap.js

@@ -9,7 +9,10 @@ const { readWishes } = require('../lib/wish-store');
 const {
   engineRegistryView,
   resolveEngineForRole,
+  resolveEngineForRoleRanked,
   resolveRegisteredEngine,
+  rosterPinFor,
+  rosterDecided,
 } = require('../lib/engine-registry');
 const { parseVerifyCommand } = require('../lib/auto-accept-certified');
 const fleet = require('../lib/fleet');
@@ -155,7 +158,8 @@ function readyExecutor(root, preferred = '') {
     if (!selected.roles.includes('executor')) throw new Error(`engine ${selected.id} is not an executor`);
     if (!selected.health || selected.health.status !== 'ready') throw new Error(`engine ${selected.id} is not ready`);
     if (!fleet.FLEET_CAPABLE.includes(selected.id)) throw new Error(`engine ${selected.id} cannot build headlessly`);
-    return selected;
+    const pin = rosterPinFor('executor', selected.id, root);
+    return Object.keys(pin).length ? { ...selected, ...pin } : selected;
   }
   const routed = resolveEngineForRole('executor', root);
   if (routed && fleet.FLEET_CAPABLE.includes(routed.id)) return routed;
@@ -168,16 +172,30 @@ function readyExecutor(root, preferred = '') {
 
 function readyValidators(root, preferred = '', exclude = '') {
   const blocked = String(exclude || '').trim();
+  const rosterRanked = resolveEngineForRoleRanked('validator', root);
+  const fromRoster = rosterDecided(rosterRanked.source);
+  const rosterOrder = !preferred && fromRoster
+    ? rosterRanked.ranked.map((engine) => engine.id)
+    : [];
+  const pinned = fromRoster && rosterRanked.engine
+    && (rosterRanked.engine.roster_model || rosterRanked.engine.roster_effort || rosterRanked.engine.roster_max_seconds)
+    ? rosterRanked.engine
+    : null;
+  // A roster pick can name an engine that reviews only when picked (codex),
+  // so the roster's list joins even when an engine lacks the role.
+  const rosterPicked = new Set(fromRoster ? rosterRanked.ranked.map((engine) => engine.id) : []);
   const candidates = engineRegistryView(root)
-    .filter((engine) => engine.roles.includes('validator'))
+    .filter((engine) => engine.roles.includes('validator') || rosterPicked.has(engine.id))
     .filter((engine) => engine.id !== blocked)
     .sort((a, b) => {
       const aPreferred = preferred && a.id === preferred ? 0 : 1;
       const bPreferred = preferred && b.id === preferred ? 0 : 1;
       return aPreferred - bPreferred
+        || (rosterOrder.length ? (rosterOrder.indexOf(a.id) - rosterOrder.indexOf(b.id)) : 0)
         || Number(a.fallback_order) - Number(b.fallback_order)
         || String(a.id).localeCompare(String(b.id));
-    });
+    })
+    .map((engine) => (pinned && engine.id === pinned.id ? { ...engine, ...pinFields(pinned) } : engine));
   const ready = candidates.filter((engine) => engine.health && engine.health.status === 'ready');
   // Route-time determinism: which validator binaries exist on this machine
   // must not change the lap's route. When none are ready, dispatch with the
@@ -187,6 +205,39 @@ function readyValidators(root, preferred = '', exclude = '') {
   return ready.length ? ready : candidates;
 }
 
+function pinFields(engine) {
+  const pin = {};
+  for (const field of ['roster_model', 'roster_effort', 'roster_max_seconds']) {
+    if (engine && engine[field]) pin[field] = engine[field];
+  }
+  return pin;
+}
+
+// The roster's pins ride into the flight: the builder's model, effort, and
+// time cap for the builder, and each reviewer's for that reviewer only. A
+// reviewer with only a model keeps the plain model string.
+function lapModelPins(executor, validators = []) {
+  const validatorModels = {};
+  for (const engine of validators) {
+    if (!engine) continue;
+    if (engine.roster_effort || engine.roster_max_seconds) {
+      validatorModels[engine.id] = {
+        model: engine.roster_model || '',
+        effort: engine.roster_effort || '',
+        max_seconds: engine.roster_max_seconds || 0,
+      };
+    } else if (engine.roster_model) {
+      validatorModels[engine.id] = engine.roster_model;
+    }
+  }
+  return {
+    model: executor && executor.roster_model || '',
+    ...(executor && executor.roster_effort ? { effort: executor.roster_effort } : {}),
+    ...(executor && executor.roster_max_seconds ? { maxSeconds: executor.roster_max_seconds } : {}),
+    validatorModels: Object.keys(validatorModels).length ? validatorModels : null,
+  };
+}
+
 function taskById(runCli, taskId) {
   const result = runCli(['task', 'show', taskId, '--json']);
   if (!result || result.status !== 0) return null;
@@ -656,6 +707,7 @@ async function runOneLap(ask, options = {}) {
       reviewOnly: true,
       verifierCommand: verifier,
       validatorEngines: validators.map((entry) => entry.id),
+      ...lapModelPins(executor, validators),
       actor: mission.owner || 'mission-lead',
       installedEngines: engineRegistryView(root)
         .filter((entry) => entry.health && entry.health.status === 'ready')
@@ -773,4 +825,7 @@ async function runOneLap(ask, options = {}) {
 module.exports = {
   oneLapSafetyIssue,
   runOneLap,
+  readyExecutor,
+  readyValidators,
+  lapModelPins,
 };

package/commands/run.js

@@ -9,6 +9,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { mapNotesPath } = require('../lib/map-refs');
 const { execSync, spawnSync } = require('child_process');
 const { getLogPath, ensureLogDirectory, createLogFile } = require('../lib/journal');
 const { parseTodo } = require('../lib/todo');
@@ -118,11 +119,12 @@ function execPhaseCommandSync(cmd, opts = {}) {
  * what the validator found - closing the try → notice → adjust loop.
  */
 function buildRunPrompt(phase, context, priorCycleReview) {
-  const { mapPath, todoPath, personaPath, lessonsPath, journalPath } = context;
+  const { mapPath, notesPath, todoPath, personaPath, lessonsPath, journalPath } = context;
 
   const readFiles = [
     personaPath && `- ${personaPath}`,
     mapPath && `- ${mapPath}`,
+    notesPath && `- ${notesPath}`,
     todoPath && `- ${todoPath}`,
     lessonsPath && `- ${lessonsPath}`,
     journalPath && `- ${journalPath}`,
@@ -413,6 +415,7 @@ async function runAtris(options = {}) {
   // Build context paths
   const context = {
     mapPath: fs.existsSync(path.join(atrisDir, 'MAP.md')) ? 'atris/MAP.md' : null,
+    notesPath: mapNotesPath(path.dirname(atrisDir)),
     todoPath: fs.existsSync(path.join(atrisDir, 'TODO.md')) ? 'atris/TODO.md' : null,
     personaPath: fs.existsSync(path.join(atrisDir, 'PERSONA.md')) ? 'atris/PERSONA.md' : null,
     lessonsPath: fs.existsSync(path.join(atrisDir, 'lessons.md')) ? 'atris/lessons.md' : null,

package/commands/scout.js

@@ -53,7 +53,7 @@ const ENGINES = {
 function scoutPrompt(question, dir) {
   return [
     `You are a read-only scout in ${dir}. You NEVER write, edit, or run mutating commands.`,
-    `Search order: index files first (atris/MAP.md, atris/TODO.md, README) via targeted reads, then grep. Cheap reads only.`,
+    `Search order: index files first (atris/MAP.md, atris/refs/MAP-NOTES.md if present for exact file:line refs, atris/TODO.md, README) via targeted reads, then grep. Cheap reads only.`,
     ``,
     `Question: ${question}`,
     ``,

package/commands/search.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { existingMapDocs } = require('../lib/map-refs');
 
 const MEMORY_LAYERS = [
   { key: 'features', dir: path.join('atris', 'features') },
@@ -226,10 +227,11 @@ function scanLayer(root, layer, terms) {
   return scanFiles(root, layer.key, layer.dir.split(path.sep).join('/'), listMarkdownFiles(dir), terms);
 }
 
+// The map layer covers the boot map and the notes file that holds its deep refs.
 function scanMap(root, terms) {
-  const mapPath = path.join(root, 'atris', 'MAP.md');
-  if (!fs.existsSync(mapPath)) return emptyLayerResult('map', 'atris/MAP.md');
-  return scanFiles(root, 'map', 'atris/MAP.md', [mapPath], terms);
+  const files = existingMapDocs(root).map((doc) => path.join(root, doc));
+  if (!files.length) return emptyLayerResult('map', 'atris/MAP.md');
+  return scanFiles(root, 'map', 'atris/MAP.md', files, terms);
 }
 
 function scanSource(root, terms) {

package/commands/unknowns.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { mapNotesPath } = require('../lib/map-refs');
 const { spawnSync } = require('child_process');
 const taskDb = require('../lib/task-db');
 const {
@@ -167,6 +168,8 @@ function formatTaskEvents(rows) {
 
 function gatherTerritoryContext(root, db) {
   const map = readFileBestEffort(path.join(root, 'atris', 'MAP.md'), { lines: 100 });
+  const notesPath = mapNotesPath(root);
+  const notes = notesPath ? readFileBestEffort(path.join(root, notesPath), { lines: 100 }) : '';
   const lessonsMd = readFileBestEffort(path.join(root, 'atris', 'lessons.md'), { maxChars: READ_LIMIT });
   const lessonsJson = readFileBestEffort(path.join(root, 'atris', 'lessons.json'), { maxChars: READ_LIMIT });
   const journals = readRecentJournals(root);
@@ -176,6 +179,7 @@ function gatherTerritoryContext(root, db) {
   return [
     section('workspace_root', root),
     section('atris/MAP.md first 100 lines', map),
+    ...(notesPath ? [section(`${notesPath} first 100 lines`, notes)] : []),
     section('atris/lessons.md', lessonsMd),
     section('atris/lessons.json', lessonsJson),
     section('last 3 daily journals', journals),
@@ -614,4 +618,5 @@ module.exports = {
   unknownsCommand,
   showHelp,
   fallbackPayload,
+  gatherTerritoryContext,
 };

package/commands/verify.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const escapeRegExp = require('../lib/escape-regexp');
+const { existingMapDocs } = require('../lib/map-refs');
 
 /**
  * atris verify [task] - Validate work is actually done
@@ -397,13 +398,13 @@ function checkDocsVsChanges(cwd, atrisDir) {
     return result;
   }
 
-  // Check if significant files are in MAP.md
+  // Check if significant files are in MAP.md or the notes file it points to
   const mapFile = path.join(atrisDir, 'MAP.md');
   if (!fs.existsSync(mapFile)) {
     return result;
   }
 
-  const mapContent = fs.readFileSync(mapFile, 'utf8');
+  const mapContent = mapDocsText(atrisDir);
 
   const significantExtensions = ['.js', '.ts', '.py', '.go', '.rs', '.rb', '.java'];
   const significantChanges = changedFiles.filter(f =>
@@ -547,6 +548,12 @@ function verifyChange(cwd, change) {
   };
 }
 
+// A file counts as documented when the boot map or atris/refs/MAP-NOTES.md names it.
+function mapDocsText(atrisDir) {
+  const root = path.dirname(atrisDir);
+  return existingMapDocs(root).map((doc) => fs.readFileSync(path.join(root, doc), 'utf8')).join('\n');
+}
+
 /**
  * Check if MAP.md documents the expected files
  */
@@ -556,7 +563,7 @@ function checkMapForFiles(atrisDir, changes) {
     return { documented: false };
   }
 
-  const content = fs.readFileSync(mapFile, 'utf8');
+  const content = mapDocsText(atrisDir);
   const fileChanges = changes.filter(c => c.type === 'file');
 
   if (fileChanges.length === 0) {
@@ -725,5 +732,6 @@ module.exports = {
   escapeRegExp,
   mapCoverage,
   isPathCovered,
-  normalizeMapPath
+  normalizeMapPath,
+  checkMapForFiles,
 };

package/commands/visualize.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { mapNotesPath } = require('../lib/map-refs');
 const { spawnSync } = require('child_process');
 const { getLogPath } = require('../lib/journal');
 const { ensureValidCredentials } = require('../utils/auth');
@@ -153,14 +154,16 @@ function readBusinessMeta(cwd = process.cwd()) {
   }
 }
 
+function promptWords(prompt) {
+  return new Set(String(prompt || '').toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length >= 4));
+}
+
 function findRelevantContextFiles(cwd, prompt) {
   const roots = [
     path.join(cwd, 'atris', 'context'),
     path.join(cwd, 'atris', 'wiki'),
   ];
-  const words = new Set(
-    prompt.toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length >= 4)
-  );
+  const words = promptWords(prompt);
   const files = [];
 
   function walk(dir) {
@@ -192,6 +195,17 @@ function findRelevantContextFiles(cwd, prompt) {
     .slice(0, 4);
 }
 
+// The deep map is large: keep only the lines that share a word with the prompt.
+function mapNotesExcerpt(cwd, prompt, maxChars) {
+  const notesPath = mapNotesPath(cwd);
+  if (!notesPath) return '';
+  const words = promptWords(prompt);
+  if (!words.size) return '';
+  const lines = fs.readFileSync(path.join(cwd, notesPath), 'utf8').split(/\r?\n/)
+    .filter(line => [...words].some(word => line.toLowerCase().includes(word)));
+  return lines.join('\n').slice(0, maxChars);
+}
+
 function collectWorkspaceContext(prompt, cwd = process.cwd()) {
   const business = readBusinessMeta(cwd);
   const chunks = [];
@@ -201,6 +215,8 @@ function collectWorkspaceContext(prompt, cwd = process.cwd()) {
 
   const mapSnippet = readTextIfExists(path.join(cwd, 'atris', 'MAP.md'), 1400);
   if (mapSnippet) chunks.push(`MAP excerpt:\n${mapSnippet}`);
+  const notesSnippet = mapNotesExcerpt(cwd, prompt, 1400);
+  if (notesSnippet) chunks.push(`MAP notes excerpt:\n${notesSnippet}`);
 
   const todoSnippet = readTextIfExists(path.join(cwd, 'atris', 'TODO.md'), 1000);
   if (todoSnippet) chunks.push(`TODO excerpt:\n${todoSnippet}`);
@@ -389,4 +405,5 @@ async function visualizeAtris(args = process.argv.slice(3)) {
 
 module.exports = {
   visualizeAtris,
+  collectWorkspaceContext,
 };

package/commands/workflow.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { mapNotesPath } = require('../lib/map-refs');
 const { getLogPath } = require('../lib/journal');
 const {
   buildFirstMinute,
@@ -491,6 +492,19 @@ async function runAtris2Local(userInput, atris2Mode) {
   }
 }
 
+// Where the agent finds code. When the short routing map has a notes file,
+// point line lookups there so the agent does not hunt for refs the map lacks.
+function mapPromptSection(targetDir, cwd = process.cwd()) {
+  const mapFile = path.join(targetDir, 'MAP.md');
+  if (!fs.existsSync(mapFile)) return '';
+  const mapRef = path.relative(cwd, mapFile);
+  const notes = mapNotesPath(path.dirname(targetDir));
+  if (!notes) return `## MAP.md\nRead this file for file:line references: ${mapRef}\n\n`;
+  const notesRef = path.relative(cwd, path.join(path.dirname(targetDir), notes));
+  return `## MAP.md\nRead this file to find where work lives: ${mapRef}\n\n`
+    + `## MAP-NOTES.md\nRead this file for exact file:line references: ${notesRef}\n\n`;
+}
+
 async function planAtris(userInput = null) {
   const { loadConfig } = require('../utils/config');
   const { loadCredentials, ensureValidCredentials } = require('../utils/auth');
@@ -773,9 +787,7 @@ async function planAtris(userInput = null) {
       systemPrompt += '## PERSONA.md\n' + fs.readFileSync(personaPath, 'utf8') + '\n\n';
     }
 
-    if (mapFileRef) {
-      systemPrompt += `## MAP.md\nRead this file for file:line references: ${mapFileRef}\n\n`;
-    }
+    systemPrompt += mapPromptSection(targetDir);
 
     // Build user prompt with context
     let userPrompt = `You are the Navigator. Take ideas from Inbox → break them down into perfect, manageable tasks.\n\n`;
@@ -1253,9 +1265,7 @@ async function doAtris() {
     if (persona) {
       systemPrompt += '## PERSONA.md\n' + persona + '\n\n';
     }
-    if (mapPath) {
-      systemPrompt += `## MAP.md\nRead this file for file:line references: ${mapPath}\n\n`;
-    }
+    systemPrompt += mapPromptSection(targetDir);
     if (profile) {
       systemPrompt += `## PROJECT CONTEXT\nType: ${context}\nProfile: ${JSON.stringify(profile, null, 2)}\n\n`;
     }
@@ -1898,6 +1908,7 @@ async function executeAgentSDKFast(userInput) {
 }
 
 module.exports = {
+  mapPromptSection,
   planAtris,
   doAtris,
   reviewAtris,

package/lib/dispatch-scout.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { MAP_REF_DOCS, existingMapDocs } = require('./map-refs');
 const {
   buildReadOnlyEngineInvocation,
   runAskProcess,
@@ -91,9 +92,8 @@ function seedScoutContext({ task, worktreePath }) {
   const trackedList = trackedFiles(worktreePath);
   const tracked = new Set(trackedList);
   const keywords = titleKeywords(task && task.title);
-  const mapPath = 'atris/MAP.md';
-  let mapText = '';
-  try { mapText = fs.readFileSync(path.join(worktreePath, mapPath), 'utf8'); } catch {}
+  const mapPath = MAP_REF_DOCS[0];
+  const mapTexts = readMapTexts(worktreePath);
 
   const scores = new Map();
   const gotchaCandidates = [];
@@ -103,18 +103,21 @@ function seedScoutContext({ task, worktreePath }) {
   };
   if (tracked.has(mapPath)) addScore(mapPath, 1);
 
-  const mapLines = mapText.split(/\r?\n/);
-  for (let index = 0; index < mapLines.length; index += 1) {
-    const line = mapLines[index];
-    const lower = line.toLowerCase();
-    const matches = keywords.filter((keyword) => lower.includes(keyword));
-    const refs = mapPathRefs(line, tracked);
-    for (const ref of refs) {
-      const pathMatches = keywords.filter((keyword) => ref.toLowerCase().includes(keyword)).length;
-      if (matches.length || pathMatches) addScore(ref, 80 + (matches.length * 5) + (pathMatches * 8));
-    }
-    if (matches.length && line.trim() && line.trim().length <= 300 && gotchaCandidates.length < 16) {
-      gotchaCandidates.push({ line: index + 1, text: line.trim() });
+  // The boot map routes; the notes file holds the deep file:line refs. Read both.
+  for (const [doc, mapText] of mapTexts) {
+    const mapLines = mapText.split(/\r?\n/);
+    for (let index = 0; index < mapLines.length; index += 1) {
+      const line = mapLines[index];
+      const lower = line.toLowerCase();
+      const matches = keywords.filter((keyword) => lower.includes(keyword));
+      const refs = mapPathRefs(line, tracked);
+      for (const ref of refs) {
+        const pathMatches = keywords.filter((keyword) => ref.toLowerCase().includes(keyword)).length;
+        if (matches.length || pathMatches) addScore(ref, 80 + (matches.length * 5) + (pathMatches * 8));
+      }
+      if (matches.length && line.trim() && line.trim().length <= 300 && gotchaCandidates.length < 16) {
+        gotchaCandidates.push({ ...(doc === mapPath ? {} : { file: doc }), line: index + 1, text: line.trim() });
+      }
     }
   }
 
@@ -268,15 +271,22 @@ function verifyHit(hit, { worktreePath, tracked, allowed }) {
   return { path: citedPath, line: nearest.line, excerpt, why };
 }
 
-function verifyMapGotcha(gotcha, mapText) {
+// Map text by doc, boot map first. A missing doc is simply absent.
+function readMapTexts(root) {
+  return new Map(existingMapDocs(root).map((doc) => [doc, fs.readFileSync(path.join(root, doc), 'utf8')]));
+}
+
+function verifyMapGotcha(gotcha, mapTexts) {
   if (!gotcha || typeof gotcha !== 'object' || Array.isArray(gotcha)) return null;
   const text = String(gotcha.text || '').trim();
   const citedLine = Number(gotcha.line);
+  const file = gotcha.file === undefined ? MAP_REF_DOCS[0] : String(gotcha.file);
   if (!text || text.length > 300 || !Number.isInteger(citedLine) || citedLine < 1) return null;
-  const lines = mapText.split(/\r?\n/);
+  if (!mapTexts.has(file)) return null;
+  const lines = mapTexts.get(file).split(/\r?\n/);
   const actualLine = lines.findIndex((line) => line.trim() === text) + 1;
   if (!actualLine) return null;
-  return { line: actualLine, text };
+  return { ...(file === MAP_REF_DOCS[0] ? {} : { file }), line: actualLine, text };
 }
 
 function verifyScoutPack(rawPack, { task, worktreePath, allowedFiles, expectedCommit = '' }) {
@@ -301,11 +311,10 @@ function verifyScoutPack(rawPack, { task, worktreePath, allowedFiles, expectedCo
   });
   if (hits.length < 2) return null;
 
-  let mapText = '';
-  try { mapText = fs.readFileSync(path.join(worktreePath, 'atris', 'MAP.md'), 'utf8'); } catch {}
+  const mapTexts = readMapTexts(worktreePath);
   const mapGotchas = (Array.isArray(rawPack.map_gotchas) ? rawPack.map_gotchas : [])
     .slice(0, SCOUT_MAX_MAP_GOTCHAS)
-    .map((gotcha) => verifyMapGotcha(gotcha, mapText))
+    .map((gotcha) => verifyMapGotcha(gotcha, mapTexts))
     .filter(Boolean);
   const notChecked = (Array.isArray(rawPack.not_checked) ? rawPack.not_checked : [])
     .map((entry) => String(entry || '').trim())
@@ -360,7 +369,7 @@ function renderVerifiedScoutBlock(pack, { worktreePath }) {
   }
   if (pack.map_gotchas.length) {
     lines.push('MAP gotchas:');
-    lines.push(...pack.map_gotchas.map((gotcha) => `- MAP line ${gotcha.line}: ${gotcha.text}`));
+    lines.push(...pack.map_gotchas.map((gotcha) => `- ${gotcha.file || 'MAP'} line ${gotcha.line}: ${gotcha.text}`));
   }
   if (pack.not_checked.length) lines.push(`Not checked: ${pack.not_checked.join('; ')}`);
   return lines.join('\n');