atris 3.58.7 → 3.59.0

package/commands/sync.js

@@ -615,7 +615,7 @@ Detect: Project has \`atris/\` folder with MAP.md, TODO.md, PERSONA.md
 Commands: plan → do → review
 
 Key behaviors:
-- Read PERSONA.md (3-4 sentences, ASCII visuals)
+- Read PERSONA.md (MAP.md first, plain words, lead with the outcome)
 - Check MAP.md for file:line refs
 - Use \`atris task\` for claims, proof, ready, and accept
 - Give every task a plain first layer: what changes, why it matters, and what

package/commands/task.js

@@ -634,6 +634,12 @@ function goldenPathMissionXpTask(task) {
     && /\b(?:golden[- ]path|zero[- ]knowledge|zero[- ]papercuts?|fresh[- ](?:laptop|environment|install|home)|self[- ]landed)\b/i.test(text);
 }
 
+// A receipt that cannot be read drops out of review evidence; name it under
+// ATRIS_DEBUG so the gap is findable, matching lib/todo.js.
+function debugUnreadableReceipt(rel, err) {
+  if (process.env.ATRIS_DEBUG) console.error(`[task] receipt unreadable, skipped: ${rel}: ${err && err.message}`);
+}
+
 function receiptTextForProof(proof, root = process.cwd()) {
   const chunks = [];
   const pattern = new RegExp(RECEIPT_PATH_PATTERN.source, 'g');
@@ -652,7 +658,9 @@ function receiptTextForProof(proof, root = process.cwd()) {
         last_landing: parsed.last_landing || null,
         summary: parsed.summary || null,
       }).slice(0, 12000));
-    } catch {}
+    } catch (err) {
+      debugUnreadableReceipt(rel, err);
+    }
   }
   return chunks.join(' ');
 }
@@ -672,7 +680,10 @@ function missionReceiptResultForProof(task, proof, root = process.cwd()) {
     try {
       const parsed = JSON.parse(fs.readFileSync(path.resolve(root, rel), 'utf8'));
       landing = parsed?.result?.landing || parsed?.landing || parsed?.last_landing || null;
-    } catch { continue; }
+    } catch (err) {
+      debugUnreadableReceipt(rel, err);
+      continue;
+    }
     const changed = String(landing?.changed || landing?.happened || '').replace(/\s+/g, ' ').trim();
     if (!changed) continue;
     if (/\brecorded tick \d+\.?$/i.test(changed) || /^recorded a proof heartbeat\b/i.test(changed)) continue;

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,
@@ -21,6 +22,10 @@ const { loadContext } = require('../lib/state-detection');
 const { buildToolResultBody } = require('../lib/tool-result-encode');
 const { commitReviewLearning } = require('./learn');
 
+function reviewLearningLine(timestamp, answer) {
+  return `- ${timestamp} - ${String(answer).trim().replace(/\s*\u2014\s*/g, ', ')}`;
+}
+
 function appendReviewLearningToJournal(journalContent, learning) {
   const text = String(journalContent || '').replace(/\r\n/g, '\n');
   const note = String(learning || '');
@@ -487,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');
@@ -769,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`;
@@ -1249,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`;
     }
@@ -1782,7 +1796,7 @@ async function reviewAtris() {
         if (fs.existsSync(logFile)) {
           let journalContent = fs.readFileSync(logFile, 'utf8');
           const timestamp = new Date().toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false });
-          const learning = `- ${timestamp} \u2014 ${answer.trim()}`;
+          const learning = reviewLearningLine(timestamp, answer);
 
           journalContent = appendReviewLearningToJournal(journalContent, learning);
 
@@ -1894,10 +1908,12 @@ async function executeAgentSDKFast(userInput) {
 }
 
 module.exports = {
+  mapPromptSection,
   planAtris,
   doAtris,
   reviewAtris,
   appendReviewLearningToJournal,
+  reviewLearningLine,
   renderReviewMinute,
   executorAgentPrompt,
   executorDispatchForTask,

package/lib/codex-flight.js

@@ -1,10 +1,12 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
 
-const CODEX_COMPANION = '/Users/keshavrao/.claude/plugins/cache/openai-codex/codex/1.0.4/scripts/codex-companion.mjs';
+// Worktree flights need full file access to edit and ship the requested repo.
+const FLIGHT_SANDBOX = 'danger-full-access';
 const CONTRACT = "CRITICAL: complete the entire job in this single run; never end your reply on a plan. Do NOT run any atris boot/brain/state commands; the only atris commands allowed are 'atris worktree guard' and 'atris worktree ship'.";
 const COAUTHOR = 'Co-authored-by: Atris <299057014+atris-builder[bot]@users.noreply.github.com>';
 
@@ -96,12 +98,30 @@ function parseTaskId(stdout) {
   return asMatch ? asMatch[1] : '';
 }
 
-function spawnCodex(worktreePath, prompt) {
+function resolveCodexCompanion() {
+  if (process.env.ATRIS_CODEX_COMPANION) {
+    const override = path.resolve(process.env.ATRIS_CODEX_COMPANION);
+    return fs.existsSync(override) && fs.statSync(override).isFile() ? override : null;
+  }
+  const cache = path.join(os.homedir(), '.claude', 'plugins', 'cache', 'openai-codex', 'codex');
+  if (!fs.existsSync(cache)) return null;
+  const versions = fs.readdirSync(cache, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  for (const version of versions) {
+    const script = path.join(cache, version, 'scripts', 'codex-companion.mjs');
+    if (fs.existsSync(script) && fs.statSync(script).isFile()) return script;
+  }
+  return null;
+}
+
+function spawnCodex(worktreePath, prompt, companion) {
   return new Promise((resolve, reject) => {
-    const argv = [CODEX_COMPANION, 'task', '--background', '--write', prompt];
+    const argv = [companion, 'task', '--background', '--write', prompt];
     const child = spawn('node', argv, {
       cwd: worktreePath,
-      env: { ...process.env, CODEX_COMPANION_SANDBOX: 'danger-full-access' },
+      env: { ...process.env, CODEX_COMPANION_SANDBOX: FLIGHT_SANDBOX },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     let stdout = '';
@@ -143,12 +163,15 @@ async function dispatchCodexFlight({ repoPath, slug, brief, verifyCmd, dryRun =
     return { dryRun: true, prompt };
   }
 
+  const companion = resolveCodexCompanion();
+  if (!companion) throw new Error('codex companion not found. set ATRIS_CODEX_COMPANION to its script path.');
   runWorktreeAdd(repo.repoPath, branch, worktreePath);
-  const task = await spawnCodex(worktreePath, prompt);
+  const task = await spawnCodex(worktreePath, prompt, companion);
   return { taskId: task.taskId, worktreePath, branch };
 }
 
 module.exports = {
   dispatchCodexFlight,
   buildPrompt,
+  resolveCodexCompanion,
 };

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');