atris 3.42.0 → 3.44.0

package/commands/task.js

@@ -11,6 +11,7 @@ const os = require('os');
 const { hasFlag } = require('../lib/arg-parser');
 const { taskProofState } = require('../lib/task-proof');
 const {
+  candidatePolicyGate,
   evaluateAutoAccept,
   isAgentCertified,
   isAutoCertifyVerifyCommandAllowed,
@@ -443,6 +444,21 @@ function failTask(label, reason, detail, exitCode = 2) {
   process.exit(exitCode);
 }
 
+function refuseCandidatePolicyGate(label, gate) {
+  if (jsonModeActive()) {
+    printJson({ ok: false, command: label, ...gate });
+  } else {
+    console.error(`${label}: ${gate.reason}: ${gate.message}`);
+    if (Array.isArray(gate.offenders)) {
+      gate.offenders.forEach((offender) => console.error(`  ${offender}`));
+    }
+    if (Array.isArray(gate.lesson_ids) && gate.lesson_ids.length) {
+      console.error(`  lessons: ${gate.lesson_ids.join(', ')}`);
+    }
+  }
+  process.exit(1);
+}
+
 function proofFlagValue(args) {
   const proof = flag(args, '--proof');
   return typeof proof === 'string' ? proof.trim() : '';
@@ -5254,6 +5270,12 @@ function autoAcceptCertifiedSmallReviews(taskDb, db, projection) {
       results.push({ ...evaluation, action: 'queued', task_id: task?.id || item.id || null });
       continue;
     }
+    const policyGate = candidatePolicyGate(task, { executeDetectors: true });
+    if (!policyGate.ok) {
+      results.push({ ...policyGate, action: 'queued', task_id: task?.id || item.id || null });
+      continue;
+    }
+    evaluation.candidate_gate = policyGate.gate;
     const accepted = acceptReviewTask(taskDb, db, task.id, {
       actor: REVIEW_AUTO_ACCEPT_ACTOR,
       proof: evaluation.proof,
@@ -9436,6 +9458,16 @@ function cmdReady(args) {
   if (missionXpIssue) {
     failTask('atris task ready', MISSION_XP_END_TO_END_REASON, missionXpIssue);
   }
+  const readyPolicyTask = {
+    ...beforeTask,
+    workspace_root: process.cwd(),
+    metadata: {
+      ...(beforeTask && beforeTask.metadata || {}),
+      ...(resultFields.files ? { changed_files: resultFields.files } : {}),
+    },
+  };
+  const readyPolicyGate = candidatePolicyGate(readyPolicyTask, { executeDetectors: true });
+  if (!readyPolicyGate.ok) refuseCandidatePolicyGate('atris task ready', readyPolicyGate);
   const resultTrace = buildAutomaticResultTrace(taskDb, db, taskId, {
     actor,
     proof: String(proof),
@@ -9497,12 +9529,12 @@ function cmdReady(args) {
     handoff.codex_prompt = reviewChat.codex_prompt;
     handoff.verification_focus = reviewChat.verification_focus;
   }
-  // Mined policy lessons (atris lesson mine) coach the proof at submission
-  // time: evidence patterns that historically certify get suggested before
-  // the task stalls in the review lane. Advisory only — never blocks ready.
+  // Mined proof lessons without runnable detectors remain coaching. Promoted,
+  // path-scoped detector lessons already passed the hard gate above.
   const { readPolicyLessons, policyHintsForProof } = require('../lib/policy-lessons');
   const policyHints = policyHintsForProof(String(proof), readPolicyLessons(taskDb.workspaceRoot()), taskDb.workspaceRoot());
   if (policyHints.length) handoff.policy_hints = policyHints;
+  if (readyPolicyGate.gate.advisories.length) handoff.policy_gate = readyPolicyGate.gate;
   if (wantsJson(args)) {
     printJson({
       ok: true,
@@ -9998,6 +10030,11 @@ function cmdCertifyVerified(args, options = {}) {
       results.push({ ref, action: 'verify_failed', reason: run.reason, verify });
       continue;
     }
+    const policyGate = candidatePolicyGate(task, { verifyCache, executeDetectors: true });
+    if (!policyGate.ok) {
+      results.push({ ...policyGate, ref, action: 'skipped' });
+      continue;
+    }
     const builderProof = String(review.proof || metadata.latest_agent_proof || '').slice(0, 200);
     const readied = taskDb.readyTask(db, {
       id: task.id,
@@ -10036,7 +10073,12 @@ function cmdCertifyVerified(args, options = {}) {
     console.log('certify-verified: no review rows to consider.');
   } else {
     for (const r of results) {
-      console.log(`${r.action.padEnd(14)} ${r.ref}${r.verify ? `  \`${r.verify}\`` : ''}${r.reason ? `  (${r.reason})` : ''}`);
+      const gateDetail = r.reason === 'slop_gate' && Array.isArray(r.offenders)
+        ? `  [${r.offenders.join('; ')}]`
+        : (r.reason === 'lesson_gate' && Array.isArray(r.lesson_ids)
+          ? `  [lessons: ${r.lesson_ids.join(', ')}]`
+          : '');
+      console.log(`${r.action.padEnd(14)} ${r.ref}${r.verify ? `  \`${r.verify}\`` : ''}${r.reason ? `  (${r.reason})` : ''}${gateDetail}`);
     }
     console.log(`certified ${certified}; humans keep denied lanes and rows without a runnable check.`);
   }
@@ -10348,6 +10390,8 @@ function evaluateSweepAutoAccept(task, root) {
   if (denied) return { eligible: false, ref, reason: denied };
   const proof = autoAcceptSweepLatestProof(task);
   if (!proof) return { eligible: false, ref, reason: 'no_proof' };
+  const policyGate = candidatePolicyGate(task, { executeDetectors: true });
+  if (!policyGate.ok) return { ...policyGate, ref };
 
   // 1. An explicit, stored verifier (`atris task ready --verify`, or a prior
   // certify-verified stamp) is the strongest signal: re-run it live, right
@@ -10367,6 +10411,7 @@ function evaluateSweepAutoAccept(task, root) {
       policy: 'sweep_auto_accept_verified_command',
       proof,
       verify: storedVerify,
+      candidate_gate: policyGate.gate,
       proved_by: [`${storedVerify} exited 0`],
       happened: autoAcceptSweepHappened(task),
     };
@@ -10382,6 +10427,7 @@ function evaluateSweepAutoAccept(task, root) {
       policy: 'sweep_auto_accept_verified',
       proof,
       evidence: verifier.evidence,
+      candidate_gate: policyGate.gate,
       proved_by: verifier.proved_by,
       happened: autoAcceptSweepHappened(task),
     };
@@ -10405,6 +10451,7 @@ function evaluateSweepAutoAccept(task, root) {
           policy: 'sweep_auto_accept_verified_derived',
           proof,
           verify: derived,
+          candidate_gate: policyGate.gate,
           proved_by: [`${derived} exited 0`],
           happened: autoAcceptSweepHappened(task),
         };

package/commands/team.js

@@ -6,6 +6,7 @@ const path = require('path');
 const { canonicalEngineName } = require('../lib/engine-registry');
 const taskDb = require('../lib/task-db');
 const { buildTeamPresence, DEFAULT_FRESHNESS_WINDOW_MS, renderTeamPresence } = require('../lib/team-presence');
+const { readEngineRegistry } = require('./engine');
 const { listMissions, listWorktreeRollupMissions } = require('./mission');
 const { collectSnapshot, collectStreamEvents, repoRoot } = require('./stream');
 
@@ -42,6 +43,7 @@ function collectTeamPresence(deps = {}) {
   return buildTeamPresence({
     nowMs,
     freshnessWindowMs,
+    operator: deps.operator || process.env.USER || process.env.USERNAME || '',
     stream,
     streamEvents,
     missions: collectMissions(root, deps),
@@ -88,8 +90,92 @@ function missionEngine(mission) {
   return canonicalEngineName(mission?.runner) || canonicalEngineName(mission?.engine);
 }
 
+function formatEngineModel(engineId, engineRoster) {
+  const id = String(engineId || '').trim();
+  if (!id) return '-';
+  const entry = (Array.isArray(engineRoster) ? engineRoster : []).find((row) => row.id === id);
+  if (!entry) return id;
+  const models = Array.isArray(entry.models) ? entry.models.filter(Boolean) : [];
+  if (!models.length) return id;
+  return `${id} (${models.join(', ')})`;
+}
+
+function isTemplateMember(member) {
+  const name = String(member?.name || '').trim();
+  if (name === '<name>') return true;
+  const dir = String(member?.dir || '').trim();
+  return dir.includes('<') || dir.includes('>');
+}
+
+function readMemberNow(member, root) {
+  const nowPath = member?.dir
+    ? path.join(member.dir, 'now.md')
+    : path.join(root, 'atris', 'team', String(member?.name || '').trim(), 'now.md');
+  let text = '';
+  try { text = fs.readFileSync(nowPath, 'utf8'); } catch { return '-'; }
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = String(line || '').trim();
+    if (!trimmed || /^#+\s/.test(trimmed) || /^<!--/.test(trimmed) || /-->$/.test(trimmed)) continue;
+    if (/^---+$/.test(trimmed)) continue;
+    const content = trimmed
+      .replace(/^[-*]\s+/, '')
+      .replace(/^\[[ xX]\]\s+/, '')
+      .trim();
+    if (!content || /^[A-Za-z_-]+:\s/.test(content)) continue;
+    return content;
+  }
+  return '-';
+}
+
+function memberFrontmatterEngine(member) {
+  return String(member?.frontmatter?.engine || '').trim();
+}
+
+function memberAlwaysOn(member) {
+  const raw = member?.frontmatter?.alwayson;
+  if (raw === true) return true;
+  return String(raw || '').trim().toLowerCase() === 'true';
+}
+
+function memberFocus(rawNow, { awake, alwaysOn }) {
+  let focus = rawNow;
+  if (alwaysOn && rawNow === '-') focus = 'always on';
+  if (awake) focus = focus === '-' ? 'always on (live)' : `${focus} (live)`;
+  return focus;
+}
+
+function memberIsActive({ frontmatterEngine, awake }) {
+  // A stale focus line in now.md does not make a member active — only an
+  // assigned engine or live presence does.
+  return Boolean(frontmatterEngine) || awake;
+}
+
+function clipCell(text, max) {
+  const value = String(text || '').trim();
+  if (!max || value.length <= max) return value;
+  if (max <= 0) return '';
+  return value.slice(0, max);
+}
+
+function rosterStatus(entry) {
+  if (entry.status === 'awake') return 'live';
+  if (String(entry.engine || '').trim()) return 'assigned';
+  return 'idle';
+}
+
+function escapeHtml(text) {
+  return String(text || '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
 function collectTeamRoster(deps = {}) {
   const root = deps.root || repoRoot(deps.cwd || process.cwd());
+  const presence = deps.presence || collectTeamPresence(deps);
+  const awake = new Set(presence.members.map((member) => String(member.name || '').trim().toLowerCase()));
+  const engineRoster = deps.engineRoster || readEngineRegistry(root, { persist: false }).engines;
   const engineByOwner = new Map();
   for (const mission of collectMissions(root, deps)) {
     if (!ROSTER_LIVE_MISSION_STATUSES.has(String(mission?.status || '').toLowerCase())) continue;
@@ -99,21 +185,233 @@ function collectTeamRoster(deps = {}) {
     if (owner && engine && !engineByOwner.has(owner)) engineByOwner.set(owner, engine);
   }
   return collectMembers(root, deps)
+    .filter((member) => !isTemplateMember(member))
     .map((member) => {
       const name = String(member?.name || '').trim().toLowerCase();
-      return { name, role: plainRole(member), engine: engineByOwner.get(name) || '' };
+      const missionEngine = engineByOwner.get(name) || '';
+      const frontmatterEngine = memberFrontmatterEngine(member);
+      const alwaysOn = memberAlwaysOn(member);
+      const isAwake = awake.has(name);
+      const rawNow = readMemberNow(member, root);
+      const active = memberIsActive({ frontmatterEngine, awake: isAwake, rawNow });
+      const focus = memberFocus(rawNow, { awake: isAwake, alwaysOn });
+      return {
+        name,
+        role: plainRole(member),
+        engine: frontmatterEngine,
+        mission_engine: missionEngine,
+        engine_model: formatEngineModel(missionEngine, engineRoster),
+        status: isAwake ? 'awake' : 'idle',
+        now: rawNow,
+        focus,
+        active,
+      };
     })
     .filter((entry) => entry.name)
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-function renderTeamRoster(roster) {
-  if (!roster.length) {
+function wrapCommaNames(names, width = 80) {
+  const lines = [];
+  let line = '';
+  for (const name of names) {
+    const candidate = line ? `${line}, ${name}` : name;
+    if (candidate.length > width && line) {
+      lines.push(line);
+      line = name;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.join('\n');
+}
+
+function renderTeamRoster(rosterRows, deps = {}) {
+  if (!rosterRows.length) {
     return 'no team members yet. create one with: atris member create <name> --role="..."';
   }
-  return roster
-    .map((entry) => `${entry.name} - ${entry.role}${entry.engine ? `, on ${entry.engine}` : ''}.`)
-    .join('\n');
+  const activeRows = rosterRows.filter((entry) => entry.active);
+  const restRows = rosterRows.filter((entry) => !entry.active);
+  const termWidth = deps.termWidth || process.stdout.columns || 80;
+  const memberW = Math.max(6, ...activeRows.map((entry) => entry.name.length));
+  const engineW = Math.max(6, ...activeRows.map((entry) => (entry.engine || '-').length));
+  const statusW = 8;
+  const sep = 3;
+  const focusW = Math.max(8, termWidth - memberW - engineW - statusW - sep * 3);
+  const lines = ['active team:'];
+  if (activeRows.length) {
+    for (const entry of activeRows) {
+      const engine = entry.engine || '-';
+      const status = rosterStatus(entry);
+      const focus = clipCell(entry.focus || '-', focusW);
+      lines.push(
+        `${clipCell(entry.name, memberW).padEnd(memberW)} | ${clipCell(engine, engineW).padEnd(engineW)} | ${status.padEnd(statusW)} | ${focus}`,
+      );
+    }
+  } else {
+    lines.push('(none)');
+  }
+  lines.push('');
+  lines.push('rest of the team:');
+  if (restRows.length) {
+    lines.push(wrapCommaNames(restRows.map((entry) => entry.name), termWidth));
+  } else {
+    lines.push('(none)');
+  }
+  return lines.join('\n');
+}
+
+function renderTeamRosterHtml(rosterRows, meta = {}) {
+  const activeRows = rosterRows.filter((entry) => entry.active);
+  const restRows = rosterRows.filter((entry) => !entry.active);
+  const generatedAt = meta.generatedAt || new Date().toISOString();
+  const workspace = meta.workspace || process.cwd();
+
+  const statusDot = (entry) => {
+    const status = rosterStatus(entry);
+    if (status === 'live') return '<span class="dot dot-live" title="live"></span><span class="status-label">live</span>';
+    if (status === 'assigned') return '<span class="dot dot-assigned" title="assigned"></span><span class="status-label">assigned</span>';
+    return '<span class="dot dot-idle" title="idle"></span><span class="status-label">idle</span>';
+  };
+
+  const activeRowsHtml = activeRows.length
+    ? activeRows.map((entry) => `
+        <tr>
+          <td class="col-member">${escapeHtml(entry.name)}</td>
+          <td class="col-engine">${escapeHtml(entry.engine || '-')}</td>
+          <td class="col-status">${statusDot(entry)}</td>
+          <td class="col-focus">${escapeHtml(entry.focus || '-')}</td>
+        </tr>`).join('')
+    : '<tr><td colspan="4" class="empty">(none)</td></tr>';
+
+  const restChipsHtml = restRows.length
+    ? restRows.map((entry) => `<span class="chip">${escapeHtml(entry.name)}</span>`).join('')
+    : '<span class="empty">(none)</span>';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Team board</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
+      "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    color: #1c1917;
+    background: #fafaf9;
+    padding: 16px;
+  }
+  .board { max-width: 1200px; margin: 0 auto; }
+  h2 {
+    font-size: 16px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    padding-bottom: 4px;
+    border-bottom: 2px solid #f59e0b;
+  }
+  section { margin-bottom: 16px; }
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    background: #fff;
+    border-radius: 4px;
+    box-shadow: 0 1px 3px rgba(0,0,0,.08);
+  }
+  th, td {
+    text-align: left;
+    vertical-align: middle;
+    padding: 8px 12px;
+    border-bottom: 1px solid #f5f5f4;
+  }
+  th {
+    font-size: 12px;
+    font-weight: 600;
+    color: #78716c;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+  tr { min-height: 44px; }
+  tr:last-child td { border-bottom: none; }
+  .col-member { white-space: nowrap; }
+  .col-engine { white-space: nowrap; }
+  .col-status { white-space: nowrap; }
+  .col-focus { word-wrap: break-word; overflow-wrap: break-word; }
+  .dot {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    margin-right: 4px;
+    vertical-align: middle;
+  }
+  .dot-live { background: #22c55e; }
+  .dot-assigned { background: #f59e0b; }
+  .dot-idle { background: #a8a29e; }
+  .status-label { font-size: 14px; vertical-align: middle; }
+  .chip-grid {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+  }
+  .chip {
+    display: inline-block;
+    background: #fff;
+    border: 1px solid #e7e5e4;
+    border-radius: 4px;
+    padding: 4px 8px;
+    font-size: 14px;
+    box-shadow: 0 1px 3px rgba(0,0,0,.08);
+  }
+  .empty { color: #78716c; font-style: italic; }
+  footer {
+    margin-top: 16px;
+    font-size: 12px;
+    color: #78716c;
+  }
+</style>
+</head>
+<body>
+<div class="board">
+  <section>
+    <h2>Active team</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>Member</th>
+          <th>Engine</th>
+          <th>Status</th>
+          <th>Focus</th>
+        </tr>
+      </thead>
+      <tbody>${activeRowsHtml}
+      </tbody>
+    </table>
+  </section>
+  <section>
+    <h2>Rest of the team</h2>
+    <div class="chip-grid">${restChipsHtml}</div>
+  </section>
+  <footer>generated ${escapeHtml(generatedAt)} · ${escapeHtml(workspace)}</footer>
+</div>
+</body>
+</html>`;
+}
+
+function writeTeamBoardHtml(rosterRows, deps = {}) {
+  const workspace = deps.cwd || process.cwd();
+  const outPath = path.join(workspace, 'atris', 'team', 'team-board.html');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const html = renderTeamRosterHtml(rosterRows, {
+    workspace,
+    generatedAt: deps.generatedAt || new Date().toISOString(),
+  });
+  fs.writeFileSync(outPath, html, 'utf8');
+  return outPath;
 }
 
 // The pruning pass keeps the team lean like a real company: it flags members
@@ -187,11 +485,11 @@ function renderTeamPrune(report, days = DEFAULT_PRUNE_DAYS) {
 
 function helpText() {
   return [
-    'atris team - one team view: every member, their role, and any engine running their work',
+    'atris team - active members and the rest of the roster',
     'atris team presence - show who is awake and what they are doing',
     'atris team prune - flag members with no recent activity; deletes nothing',
     '',
-    'usage: atris team [roster|presence] [--json]',
+    'usage: atris team [roster|presence] [--json] [--html]',
     'usage: atris team prune [--days N] [--json]',
   ].join('\n');
 }
@@ -223,16 +521,28 @@ function teamCommand(args = [], deps = {}) {
     return 0;
   }
   const rosterArgs = args.filter((arg) => arg !== 'roster');
-  if (args[0] !== 'presence' && rosterArgs.every((arg) => arg === '--json')) {
+  const rosterFlags = new Set(['--json', '--html']);
+  if (args[0] !== 'presence' && rosterArgs.every((arg) => rosterFlags.has(arg))) {
+    const html = rosterArgs.includes('--html');
+    const json = rosterArgs.includes('--json');
+    if (html && json) {
+      (deps.error || process.stderr.write.bind(process.stderr))('usage: atris team [--json] [--html] (not both)\n');
+      return 2;
+    }
     const roster = deps.roster || collectTeamRoster(deps);
-    const output = rosterArgs.includes('--json')
+    if (html) {
+      const outPath = writeTeamBoardHtml(roster, deps);
+      (deps.write || process.stdout.write.bind(process.stdout))(`${outPath}\n`);
+      return 0;
+    }
+    const output = json
       ? JSON.stringify(roster, null, 2)
-      : renderTeamRoster(roster);
+      : renderTeamRoster(roster, deps);
     (deps.write || process.stdout.write.bind(process.stdout))(`${output}\n`);
     return 0;
   }
   if (args[0] !== 'presence' || args.some((arg, index) => index > 0 && arg !== '--json')) {
-    (deps.error || process.stderr.write.bind(process.stderr))('usage: atris team [roster|presence|prune] [--json]\n');
+    (deps.error || process.stderr.write.bind(process.stderr))('usage: atris team [roster|presence|prune] [--json] [--html]\n');
     return 2;
   }
   const presence = deps.presence || collectTeamPresence(deps);
@@ -243,4 +553,10 @@ function teamCommand(args = [], deps = {}) {
   return 0;
 }
 
-module.exports = { collectMissions, collectTasks, collectTeamPresence, collectTeamPrune, collectTeamRoster, renderTeamPrune, renderTeamRoster, teamCommand };
+module.exports = {
+  collectTeamPrune,
+  collectTeamRoster,
+  renderTeamPrune,
+  renderTeamRoster,
+  teamCommand,
+};

package/commands/verify.js

@@ -84,6 +84,7 @@ function verifyWorkspace(cwd, atrisDir) {
     console.log('✗ MAP.md — Issues found');
     mapResult.issues.forEach(issue => console.log(`   • ${issue}`));
   }
+  (mapResult.notes || []).forEach(note => console.log(`   ○ ${note}`));
   console.log('');
 
   // Test status
@@ -215,7 +216,7 @@ function verifyTask(cwd, atrisDir, taskId) {
  */
 function verifyMap(cwd, atrisDir) {
   const mapFile = path.join(atrisDir, 'MAP.md');
-  const result = { valid: false, issues: [], stats: null };
+  const result = { valid: false, issues: [], notes: [], stats: null };
 
   if (!fs.existsSync(mapFile)) {
     result.issues.push('MAP.md does not exist');
@@ -236,6 +237,22 @@ function verifyMap(cwd, atrisDir) {
     return result;
   }
 
+  // Let the repo's own map validator have the final say, when it ships one.
+  // A missing python3 is a skip, not a failure — the CLI has no python dependency.
+  const validator = path.join(cwd, 'scripts', 'validate_map.py');
+  if (fs.existsSync(validator)) {
+    const proc = spawnSync('python3', [validator], { cwd, encoding: 'utf8', env: process.env });
+    if (proc.error) {
+      const reason = proc.error.code === 'ENOENT' ? 'python3 not available' : proc.error.message;
+      result.notes.push(`Skipped scripts/validate_map.py — ${reason}`);
+    } else if ((proc.status ?? 0) !== 0) {
+      const detail = firstOutputLine(proc.stderr) || firstOutputLine(proc.stdout) || `exit ${proc.status}`;
+      result.issues.push(`scripts/validate_map.py failed: ${detail}`);
+    } else {
+      result.notes.push('scripts/validate_map.py passed');
+    }
+  }
+
   // Count refs
   const fileRefs = (content.match(/`[^`]+\.(js|ts|py|go|rs|rb|java|md|json)`/g) || []).length;
   const lineRefs = (content.match(/:\d+`?/g) || []).length;
@@ -250,6 +267,11 @@ function verifyMap(cwd, atrisDir) {
   return result;
 }
 
+function firstOutputLine(text) {
+  if (!text) return '';
+  return String(text).split('\n').map(line => line.trim()).find(line => line.length > 0) || '';
+}
+
 /**
  * Run project tests
  */
@@ -296,6 +318,61 @@ function runTests(cwd) {
   return result;
 }
 
+// Backtick-quoted spans, plus bare tokens that carry at least one slash.
+const MAP_PATH_PATTERN = /`([^`\n]+)`|((?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]*)/g;
+
+/**
+ * Normalize a path-looking token from MAP.md into a repo-relative path.
+ * Returns null for anything that is not usable as a path.
+ */
+function normalizeMapPath(raw) {
+  if (!raw) return null;
+  let value = String(raw).trim();
+  if (!value || /\s/.test(value) || value.includes('://')) return null;
+  value = value.replace(/^\.\//, '').replace(/^\/+/, '');
+  // Sentence punctuation trailing a path in prose, never a trailing slash.
+  value = value.replace(/[),.;:]+$/, '');
+  if (!value || value === '/' || value.split('/').includes('..')) return null;
+  return value;
+}
+
+/**
+ * Split MAP.md into the exact file paths it names and the directory prefixes it covers.
+ * A compact map documents areas, so `backend/routers/` stands in for every file beneath it.
+ */
+function mapCoverage(mapContent, isDirectory = () => false) {
+  const files = new Set();
+  const dirSet = new Set();
+  const seen = new Set();
+  const pattern = new RegExp(MAP_PATH_PATTERN.source, 'g');
+  let match;
+
+  while ((match = pattern.exec(mapContent)) !== null) {
+    const value = normalizeMapPath(match[1] || match[2]);
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+
+    if (value.endsWith('/')) {
+      dirSet.add(value);
+    } else {
+      files.add(value);
+      if (isDirectory(value)) dirSet.add(`${value}/`);
+    }
+  }
+
+  return { files, dirs: [...dirSet] };
+}
+
+/**
+ * A file is documented when the map names it outright or covers the area it lives in.
+ */
+function isPathCovered(file, coverage) {
+  const target = normalizeMapPath(file);
+  if (!target || !coverage) return false;
+  if (coverage.files.has(target)) return true;
+  return coverage.dirs.some((dir) => target.startsWith(dir) && target.length > dir.length);
+}
+
 /**
  * Check if recent git changes are documented in MAP.md
  */
@@ -332,12 +409,25 @@ function checkDocsVsChanges(cwd, atrisDir) {
     significantExtensions.some(ext => f.endsWith(ext))
   );
 
+  if (significantChanges.length === 0) {
+    return result;
+  }
+
+  const isDirectory = (candidate) => {
+    try {
+      return fs.statSync(path.join(cwd, candidate)).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+  const coverage = mapCoverage(mapContent, isDirectory);
+
   for (const file of significantChanges) {
     const basename = path.basename(file);
-    if (!mapContent.includes(basename) && !mapContent.includes(file)) {
-      result.upToDate = false;
-      result.issues.push(`${file} changed but not in MAP.md`);
-    }
+    if (mapContent.includes(basename) || mapContent.includes(file)) continue;
+    if (isPathCovered(file, coverage)) continue;
+    result.upToDate = false;
+    result.issues.push(`${file} changed and its area is not in MAP.md`);
   }
 
   // Limit reported issues
@@ -631,5 +721,8 @@ module.exports = {
   verifyRubric,
   verifyArtifact,
   findTaskInContent,
-  escapeRegExp
+  escapeRegExp,
+  mapCoverage,
+  isPathCovered,
+  normalizeMapPath
 };