@arjunkhera/atlas 0.4.2 → 0.4.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/cli.mjs

@@ -33,6 +33,7 @@ import { verdictCommand as testsVerdict, namedCommand as testsNamed, rerunComman
 import { runKept } from '../tests/kept.mjs';
 import { sweepCommand as testsSweep, coversCommand as testsCovers } from '../tests/sweep.mjs';
 import { issuesCommand as testsIssues } from './lib/issues.mjs';
+import { jobsCommand } from './lib/jobs.mjs';
 import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
 import { afterCommand as testsAfter } from './lib/passes-after.mjs';
@@ -129,6 +130,14 @@ const HELP = `atlas — the door into a repo's Atlas files
       --tests <dir>                    the test folder of the area; default test. The test files are in <dir>/scenarios
       --evidence <dir>                 where the evidence files are; default <area>/test/evidence
 
+  atlas jobs check --root <repo> --repo <owner/name>   the watcher: run the check of each Atlas job that atlas.yaml names; findings as JSON
+      --branch <name>                  the default branch; default GitHub's answer
+      --out <file>                     write the JSON here; default the terminal
+  atlas jobs file --findings <file> --repo <owner/name>   open one atlas-job issue for each new finding of a jobs check; never closes one
+      --max <n>                        open at most n issues in one run; default 10. The rest are listed, and the exit is 1
+      --dry-run                        print what it would open; change nothing
+                                       The token is only GITHUB_TOKEN. The atlas-jobs workflow runs both, once a day
+
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, and in a pull request its tracker item
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
@@ -180,6 +189,7 @@ export const FLAGS = Object.freeze({
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
+  jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
@@ -413,6 +423,10 @@ async function testsCommand(chosen) {
   throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, changed, before, after, sweep, covers, kept, issues or rerun.`);
 }
 
+function jobsVerb(chosen) {
+  return jobsCommand({ what: chosen._[1], root: rootOf(chosen), repo: chosen.repo, branch: chosen.branch, out: chosen.out, findings: chosen.findings, max: chosen.max, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+}
+
 function upkeepVerb(chosen) {
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json) }, rootOf(chosen), line);
 }
@@ -457,6 +471,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'design': return designCommand(chosen);
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
+    case 'jobs': return jobsVerb(chosen);
     case 'upkeep': return upkeepVerb(chosen);
     case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(chosen);

package/door/jobs/red-main.yaml

@@ -0,0 +1,15 @@
+# An Atlas job (the routines design, records part). A job does nothing until a
+# repo names it in its atlas.yaml:
+#
+#   jobs:
+#     atlas: [red-main]
+#
+# The check is Atlas code (door/lib/jobs.mjs). It reads the runs of the main
+# branch only, never a run from a fork. `fields` are the typed fields that a
+# finding of this job may hold. Atlas code drops every other field.
+title: The newest CI run on the main branch passes
+when: red-main
+needs: [tests]
+act: atlas:red-main
+may: pull-request
+fields: [workflow, run_id, head_sha, conclusion]

package/door/kit-releases.json

@@ -47,6 +47,10 @@
     {
       "kit_sha256": "8d6ae3c4dede74bafe292a992de3ef650e5c5566fb282081a9de23b8d30d9025",
       "first_package": "0.3.39"
+    },
+    {
+      "kit_sha256": "41d64800daf644174dd1daef1c95ccc2ca7a8460dbe3e36bcf2625d05fb0479e",
+      "first_package": "0.3.42"
     }
   ]
 }

package/door/lib/gate.mjs

@@ -15,8 +15,9 @@
 // The plan is built by pure functions, so a test reads it without GitHub. The
 // gh calls sit in one place, behind `gh`, which a test replaces.
 import { execFileSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 
@@ -195,9 +196,10 @@ const checkLine = (row) => `  ${row.state === 'green' ? '✓' : '✗'} ${row.sta
 
 // `atlas gate ready --pr <n>`: may this pull request merge now? Exit 0 when
 // every required check is green on its head commit, 1 when not.
-export function readyCommand({ repo, pr }, line, gh = ghApi) {
+export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   if (!pr || pr === true || !/^\d+$/.test(String(pr))) throw new GateError('atlas gate ready needs --pr <number>.');
   const pull = gh('GET', `repos/${repo}/pulls/${pr}`);
+  if (answer && typeof pull?.head?.sha === 'string') answer.sha = pull.head.sha;
   if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
   const sha = pull.head.sha;
   const checks = checksAt(gh, repo, pull.base.ref);
@@ -209,6 +211,24 @@ export function readyCommand({ repo, pr }, line, gh = ghApi) {
   return ready ? 0 : 1;
 }
 
+// The merge door hook (packages/atlas/hooks/door.mjs) reads this file before
+// a merge. It holds the last READY of one pull request: the repo, the number,
+// the head commit and the time. Any answer but READY removes the file, so an
+// old READY never outlives a newer NOT READY. The hook keeps its own copy of
+// the path, because its bytes are pinned.
+export const readyFile = (repo, pr, home = homedir()) => join(home, '.config', 'atlas', 'gate-ready', ...repo.toLowerCase().split('/'), String(pr));
+
+export function keepReady({ repo, pr, sha, code, home = homedir(), now = new Date() }) {
+  if (repo.split('/').some((part) => /^\.+$/.test(part))) return null;
+  const path = readyFile(repo, pr, home);
+  if (code !== 0 || !/^[0-9a-f]{40}$/i.test(String(sha ?? ''))) { rmSync(path, { force: true }); return null; }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify({ repo: repo.toLowerCase(), pr: Number(pr), sha: sha.toLowerCase(), at: now.toISOString() })}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+  return path;
+}
+
 // `atlas gate audit --since <date>`: each pull request merged since the date
 // whose required checks were not all green at the moment of the merge.
 export function auditCommand({ repo, since, commit }, line, gh = ghApi) {
@@ -275,10 +295,22 @@ function commitAudit({ repo, commit }, line, gh) {
 }
 
 // `atlas gate apply|ready|audit`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit }, line, gh = ghApi) {
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, home = homedir() }, line, gh = ghApi) {
   if (!['apply', 'ready', 'audit'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready or audit.`);
   if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
-  if (what === 'ready') return readyCommand({ repo, pr }, line, gh);
+  if (what === 'ready') {
+    const answer = {};
+    let code = 1;
+    try { code = readyCommand({ repo, pr, answer }, line, gh); } finally {
+      if (/^\d+$/.test(String(pr ?? ''))) {
+        try {
+          const kept = keepReady({ repo, pr, sha: answer.sha, code, home });
+          if (kept) line(`The merge door may merge #${pr} at this head for ten minutes.`);
+        } catch (error) { line(`The merge door could not keep this answer (${error.code ?? error.message}), so it will refuse the merge. Run ready again outside the sandbox.`); }
+      }
+    }
+    return code;
+  }
   if (what === 'audit') return auditCommand({ repo, since, commit }, line, gh);
   if (off && on) throw new GateError('pick --off or --on, not both.');
   const mode = off ? 'off' : on ? 'on' : 'apply';

package/door/lib/issues.mjs

@@ -22,7 +22,7 @@ import { resolve } from 'node:path';
 import { LABEL } from '../../tests/sweep.mjs';
 
 const usage = (message) => Object.assign(new Error(message), { usage: true });
-const TOKEN_SHAPE = /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|\b[0-9a-f]{40}\b)/;
+export const TOKEN_SHAPE = /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|\b[0-9a-f]{40}\b)/;
 const SEGMENT = /^[A-Za-z0-9_.-]+$/;
 const PAGE = 100;
 export const DEFAULT_BOT = 'github-actions[bot]';
@@ -43,7 +43,7 @@ export function apiBase(env) {
   return text.replace(/\/+$/, '');
 }
 
-async function api(base, key, method, path, body) {
+export async function api(base, key, method, path, body) {
   const response = await fetch(`${base}${path}`, {
     method,
     headers: {
@@ -63,6 +63,12 @@ async function api(base, key, method, path, body) {
 
 export const LABEL_COLOR = 'c5def5';
 export const LABEL_TEXT = 'Opened by the daily sweep of the scenario tests (atlas tests sweep)';
+// Each label an issue may carry, and its line. A label with no line here gets a plain one.
+const LABEL_TEXTS = {
+  [LABEL]: LABEL_TEXT,
+  'atlas-job': 'Opened by the Atlas watcher (atlas-jobs.yml); a runner acts on it',
+};
+const labelText = (label) => LABEL_TEXTS[label] ?? (label.startsWith('job:') ? `The Atlas job ${label.slice(4)}` : 'Opened by Atlas');
 
 // The label must exist before the first issue: a token that may only write issues may not create a label by
 // naming it in an issue. GET the label; on 404, create it. A 422 means it exists by now (a race), which is fine.
@@ -72,7 +78,7 @@ async function ensureLabel(base, key, repo, label, line) {
   const have = await api(base, key, 'GET', `/repos/${repo}/labels/${name}`);
   if (have.ok) return;
   if (have.status !== 404) { line(`label  GitHub answered ${have.status} when the label ${label} was read; going on`); return; }
-  const made = await api(base, key, 'POST', `/repos/${repo}/labels`, { name: label, color: LABEL_COLOR, description: LABEL_TEXT });
+  const made = await api(base, key, 'POST', `/repos/${repo}/labels`, { name: label, color: LABEL_COLOR, description: labelText(label) });
   if (made.ok || made.status === 422) line(`label  ${made.ok ? 'created' : 'already exists'}: ${label}`);
   else line(`label  GitHub answered ${made.status} when the label ${label} was created; going on`);
 }
@@ -99,42 +105,50 @@ export function readFindings(text) {
   return data.findings;
 }
 
-// An issue of the bot that holds the marker and stops a new one.
-const stops = (issue, marker, bot) => !issue.pull_request
+// An issue of the bot that holds the marker and stops a new one. `closedStops` says which closed issue
+// still stops one: for the sweep, one closed as not_planned.
+const sweepClosedStops = (issue) => issue.state_reason === 'not_planned';
+const stops = (issue, marker, bot, closedStops) => !issue.pull_request
   && issue.user?.login === bot
   && typeof issue.body === 'string' && issue.body.includes(marker)
-  && (issue.state === 'open' || (issue.state === 'closed' && issue.state_reason === 'not_planned'));
+  && (issue.state === 'open' || (issue.state === 'closed' && closedStops(issue)));
 
-export async function openIssues({ findings, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line }) {
+// `label` is the label whose issues are read for markers: the sweep's own by default. Every label of a
+// finding is made before its first issue, and the issue must carry `label`.
+export async function openIssues({ findings, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, label = LABEL, closedStops = sweepClosedStops }) {
   const base = apiBase(env);
   const key = env.GITHUB_TOKEN || '';
   let known = [];
   if (!dryRun || key) {
     if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
-    known = await labelled(base, key, repo, LABEL);
+    known = await labelled(base, key, repo, label);
   } else line('dry run with no GITHUB_TOKEN: the existing issues are not read, so every finding shows as new.');
   const opened = [];
   const skipped = [];
   const deferred = [];
   const failed = [];
   const seen = new Set();
-  let labelEnsured = false;
+  const ensured = new Set();
   for (const f of findings) {
     const { title, body, marker, labels } = f.issue;
-    const hit = known.find((i) => stops(i, marker, bot));
+    const hit = known.find((i) => stops(i, marker, bot, closedStops));
     if (hit || seen.has(marker)) { skipped.push(f.key); line(`skip   ${f.key}: ${hit ? `issue #${hit.number} (${hit.state}) of ${bot} holds the marker` : 'a finding of this file has the same marker'}`); continue; }
     seen.add(marker);
     if (opened.length >= max) { deferred.push(f.key); line(`later  ${f.key}: the limit of ${max} issue(s) for one run is reached`); continue; }
     const cut = String(title).slice(0, 200);
     if (dryRun) { opened.push(f.key); line(`would open   ${f.key}: ${cut}  [${labels.join(', ')}]`); continue; }
     try {
-      if (!labelEnsured) { labelEnsured = true; await ensureLabel(base, key, repo, LABEL, line); }
+      for (const name of [label, ...labels]) {
+        if (ensured.has(name)) continue;
+        ensured.add(name);
+        await ensureLabel(base, key, repo, name, line);
+      }
       const r = await api(base, key, 'POST', `/repos/${repo}/issues`, { title: cut, body, labels });
       if (!r.ok) throw new Error(`GitHub answered ${r.status}`);
       opened.push(f.key);
       line(`opened #${r.data?.number ?? '?'}  ${f.key}: ${cut}${r.data?.html_url ? `  ${r.data.html_url}` : ''}`);
-      const has = (r.data?.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === LABEL);
-      if (!has) { failed.push(f.key); line(`label  ${f.key}: the new issue does not carry the label ${LABEL}; the token may not create labels. Create the label by hand.`); }
+      const has = (r.data?.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === label);
+      if (!has) { failed.push(f.key); line(`label  ${f.key}: the new issue does not carry the label ${label}; the token may not create labels. Create the label by hand.`); }
     } catch (error) {
       failed.push(f.key);
       line(`failed ${f.key}: ${String(error.message).split(key).join('(token)')}`);

package/door/lib/jobs.mjs

@@ -0,0 +1,241 @@
+// `atlas jobs check` and `atlas jobs file`: the watcher of the routines design
+// (its records and security parts).
+//
+//   atlas jobs check --root <repo> --repo <owner/name> [--branch <name>] [--out <file>]
+//   atlas jobs file --findings <file> --repo <owner/name> [--max <n>] [--dry-run]
+//
+// The workflow `.github/workflows/atlas-jobs.yml` runs both, from the default branch, once a day.
+// `atlas tooling` writes it from door/templates/atlas-jobs.yml.
+//
+//   check  reads `jobs: { atlas: [...] }` from atlas.yaml and runs the check of each Atlas job it
+//          names. It reads; it writes no issue. Its job in the workflow holds read permissions only.
+//   file   reads the JSON of the check, keeps the typed fields of each finding and drops the rest, and
+//          opens one `atlas-job` issue for each new finding, through openIssues (issues.mjs).
+//
+// The check envelope (records part, "The check envelope"):
+//   { "jobs": 1, "state": "none" | "found" | "broken", "findings": [ { "job", "key", <typed fields> } ] }
+// A finding holds ids, paths, versions and numbers only. No prose reaches an issue: every line of an
+// issue is Atlas code, and the finding goes into it as one JSON block.
+//
+// A finding is new when no issue of the bot holds its marker, except for one that is closed. A closed
+// issue with the label `handed-over` still stops a new one for 30 days: the runner gave the finding to
+// the tracker. The token is only GITHUB_TOKEN, as for `atlas tests issues`.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../shape/check.mjs';
+import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+
+export const JOBS_LABEL = 'atlas-job';
+export const HANDED_OVER = 'handed-over';
+export const HANDED_OVER_DAYS = 30;
+export const JOBS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'jobs');
+export const ENVELOPE = 1;
+export const STATES = Object.freeze(['none', 'found', 'broken']);
+export const MAX_FINDINGS = 50;
+
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+const DAY = 24 * 60 * 60 * 1000;
+
+// A job id, a key, and each typed value. A value is an id, a path, a version or a number: no space and
+// no prose. A key may hold a path, so it takes a slash and a dot.
+const JOB_ID = /^[a-z][a-z0-9-]{0,40}$/;
+const KEY = /^[A-Za-z0-9._/:@+-]{1,200}$/;
+const VALUE = /^[A-Za-z0-9._/:@+-]{1,200}$/;
+const FIELD = /^[a-z][a-z0-9_]{0,40}$/;
+
+// ---------------------------------------------------------------- the Atlas jobs
+
+// Every Atlas job of this package: door/jobs/<id>.yaml.
+export function atlasJobs(dir = JOBS_DIR) {
+  const out = new Map();
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir).sort()) {
+    if (!name.endsWith('.yaml')) continue;
+    const id = name.slice(0, -'.yaml'.length);
+    const job = parseYaml(readFileSync(join(dir, name), 'utf8')) ?? {};
+    out.set(id, { id, ...job, fields: Array.isArray(job.fields) ? job.fields.map(String).filter((f) => FIELD.test(f)) : [] });
+  }
+  return out;
+}
+
+// The Atlas jobs that the repo's atlas.yaml names, read from the checkout of the default branch.
+export function namedJobs(root) {
+  const file = join(root, 'atlas.yaml');
+  if (!existsSync(file)) throw usage(`there is no atlas.yaml in ${root}`);
+  const facts = parseYaml(readFileSync(file, 'utf8')) ?? {};
+  const named = facts.jobs?.atlas;
+  if (named === undefined || named === null) return [];
+  if (!Array.isArray(named)) throw usage('jobs.atlas in atlas.yaml must be a list of job ids');
+  return named.map(String);
+}
+
+// ---------------------------------------------------------------- the check of red-main
+
+// A red run: it ended and did not pass. A cancelled run is not red: a newer push cancels an older run.
+const RED = new Set(['failure', 'timed_out', 'startup_failure']);
+
+// The newest finished run of each workflow on the default branch, from a push to this repo. A run of a
+// pull request, a schedule, or a fork is never read: its event is not push, or its head repo is another.
+export function newestMainRuns(runs, { repo, branch }) {
+  const newest = new Map();
+  for (const run of runs) {
+    if (run?.event !== 'push' || run?.head_branch !== branch || run?.status !== 'completed') continue;
+    if (run?.head_repository?.full_name !== repo || run?.repository?.full_name !== repo) continue;
+    const path = String(run.path ?? '').replace(/@.*$/, '');
+    if (!path || !VALUE.test(path)) continue;
+    const have = newest.get(path);
+    if (!have || Date.parse(run.created_at) > Date.parse(have.created_at)) newest.set(path, run);
+  }
+  return newest;
+}
+
+export async function checkRedMain({ repo, branch, env }) {
+  const base = apiBase(env);
+  const key = env.GITHUB_TOKEN || '';
+  if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
+  const query = `branch=${encodeURIComponent(branch)}&event=push&status=completed&per_page=100`;
+  const r = await api(base, key, 'GET', `/repos/${repo}/actions/runs?${query}`);
+  if (!r.ok || !Array.isArray(r.data?.workflow_runs)) throw new Error(`GitHub answered ${r.status} when the runs of ${branch} were listed`);
+  const findings = [];
+  for (const [path, run] of [...newestMainRuns(r.data.workflow_runs, { repo, branch })].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!RED.has(run.conclusion)) continue;
+    findings.push({ job: 'red-main', key: path, workflow: path, run_id: Number(run.id), head_sha: String(run.head_sha), conclusion: String(run.conclusion) });
+  }
+  return findings;
+}
+
+// The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
+// says so in the notes; it never reads `found` from nothing.
+const CHECKS = { 'red-main': checkRedMain };
+
+export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs() }) {
+  const named = namedJobs(root);
+  const notes = [];
+  const ran = [];
+  const findings = [];
+  let state = 'none';
+  let mainBranch = branch;
+  for (const id of named) {
+    const job = jobs.get(id);
+    if (!job) { notes.push(`${JOB_ID.test(id) ? id : '(a bad id)'}: no Atlas job has this id`); continue; }
+    const check = CHECKS[job.when];
+    if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
+    try {
+      if (!mainBranch) mainBranch = await defaultBranch({ repo, env });
+      const found = (await check({ repo, branch: mainBranch, env })).map((f) => ({ ...f, job: id }));
+      findings.push(...found);
+      ran.push({ job: id, state: found.length ? 'found' : 'none' });
+    } catch (error) {
+      if (error.usage) throw error;
+      // The message never holds the token: it is built from fixed words and statuses.
+      ran.push({ job: id, state: 'broken' });
+      notes.push(`${id}: broken: ${String(error.message).split(env.GITHUB_TOKEN || '\u0000').join('(token)')}`);
+    }
+  }
+  if (ran.some((one) => one.state === 'broken')) state = 'broken';
+  else if (findings.length) state = 'found';
+  return { jobs: ENVELOPE, repo, branch: mainBranch, state, ran, notes, findings };
+}
+
+async function defaultBranch({ repo, env }) {
+  const r = await api(apiBase(env), env.GITHUB_TOKEN || '', 'GET', `/repos/${repo}`);
+  const name = r.data?.default_branch;
+  if (!r.ok || typeof name !== 'string' || !VALUE.test(name)) throw new Error(`GitHub answered ${r.status} when the default branch was read`);
+  return name;
+}
+
+// ---------------------------------------------------------------- the file job
+
+// Keep a finding only when its job is an Atlas job, its key is typed, and it has at least one field.
+// Keep only the fields that the job lists, and only typed values. Count what is dropped.
+export function typedFindings(envelope, jobs = atlasJobs()) {
+  if (!envelope || envelope.jobs !== ENVELOPE || !STATES.includes(envelope.state) || !Array.isArray(envelope.findings)) {
+    throw usage('the findings file is not the output of `atlas jobs check`');
+  }
+  const kept = [];
+  let dropped = 0;
+  for (const f of envelope.findings.slice(0, MAX_FINDINGS)) {
+    const job = jobs.get(String(f?.job));
+    if (!job || !KEY.test(String(f?.key ?? ''))) { dropped += 1; continue; }
+    const one = { job: job.id, key: String(f.key) };
+    for (const field of job.fields) {
+      const value = f[field];
+      if (typeof value === 'number' && Number.isFinite(value)) one[field] = value;
+      else if (typeof value === 'string' && VALUE.test(value)) one[field] = value;
+    }
+    kept.push(one);
+  }
+  dropped += Math.max(0, envelope.findings.length - MAX_FINDINGS);
+  return { findings: kept, dropped };
+}
+
+// An HTML comment may not hold two hyphens in a row, so the marker spells them another way.
+export const jobMarker = (job, key) => `<!-- atlas-job:${job}:${String(key).replace(/--/g, '-~')} -->`;
+
+// The issue of one finding (records part, "The atlas-job issue").
+export function jobIssue(finding) {
+  const marker = jobMarker(finding.job, finding.key);
+  const body = [
+    `The Atlas watcher found this in the job \`${finding.job}\`. Atlas code wrote this issue. It holds typed fields only.`,
+    '',
+    '```json',
+    JSON.stringify(finding, null, 2),
+    '```',
+    '',
+    'A runner acts on it later. The watcher never edits or closes this issue.',
+    '',
+    marker,
+  ].join('\n');
+  return { title: `atlas-job: ${finding.job} ${finding.key}`.slice(0, 200), body, labels: [JOBS_LABEL, `job:${finding.job}`], marker };
+}
+
+// A closed issue stops a new one only when the runner handed it over in the last 30 days.
+export const handedOverStops = (now = Date.now()) => (issue) => (issue.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === HANDED_OVER)
+  && Number.isFinite(Date.parse(issue.closed_at)) && now - Date.parse(issue.closed_at) <= HANDED_OVER_DAYS * DAY;
+
+export async function fileJobs({ envelope, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, now = Date.now(), jobs = atlasJobs() }) {
+  const { findings, dropped } = typedFindings(envelope, jobs);
+  if (dropped) line(`dropped ${dropped} finding(s) that are not typed, or that name no Atlas job`);
+  if (envelope.state === 'broken') line('the check reads broken, so a check found nothing it can trust. The run ends red.');
+  const list = findings.map((f) => ({ key: `${f.job}:${f.key}`, issue: jobIssue(f) }));
+  const result = list.length
+    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: handedOverStops(now) })
+    : (line('no finding: nothing to file.'), { opened: [], skipped: [], deferred: [], failed: [] });
+  return { ...result, broken: envelope.state === 'broken' };
+}
+
+// ---------------------------------------------------------------- the command
+
+export async function jobsCommand({ what, root, repo, branch, out, findings, max, dryRun = false, bot, args = [] }, line, env = process.env) {
+  try {
+    if ([...args, findings, repo, out, branch].some((a) => typeof a === 'string' && TOKEN_SHAPE.test(a))) throw usage('a token must never be an argument; put it in GITHUB_TOKEN');
+    if (!repoOk(repo)) throw usage('give the repo as --repo <owner/name>');
+    if (what === 'check') {
+      if (branch !== undefined && (typeof branch !== 'string' || !VALUE.test(branch))) throw usage('--branch must name a branch');
+      const result = await jobsCheck({ root, repo, branch: branch ?? null, env });
+      const json = `${JSON.stringify(result, null, 2)}\n`;
+      if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(resolve(out), json); }
+      line(`jobs check: ${result.state}. ${result.ran.length} job(s) ran, ${result.findings.length} finding(s).${out ? ` Written to ${out}.` : ''}`);
+      for (const one of result.ran) line(`  ${one.job}: ${one.state}`);
+      for (const note of result.notes) line(`  note: ${note}`);
+      if (!out) line(json.trimEnd());
+      return result.state === 'broken' ? 1 : 0;
+    }
+    if (what === 'file') {
+      if (!findings) throw usage('give the check file: --findings <file>');
+      const limit = max === undefined ? DEFAULT_MAX : Number(max);
+      if (!Number.isInteger(limit) || limit < 0) throw usage('--max must be a whole number, 0 or more');
+      const file = resolve(findings);
+      if (!existsSync(file)) throw usage(`the findings file ${file} does not exist`);
+      let envelope;
+      try { envelope = JSON.parse(readFileSync(file, 'utf8')); } catch { throw usage('the findings file is not JSON'); }
+      const r = await fileJobs({ envelope, repo, dryRun: Boolean(dryRun), max: limit, bot: bot || DEFAULT_BOT, env, line });
+      return r.broken || r.deferred.length || r.failed.length ? 1 : 0;
+    }
+    throw usage(`there is no jobs verb "${what ?? ''}". Use check or file.`);
+  } catch (error) {
+    line(`jobs: ${String(error.message).split(env.GITHUB_TOKEN || '\u0000').join('(token)')}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/pull-request.mjs

@@ -23,7 +23,7 @@ export const TOOLING_LABEL = 'atlas-helper';
 
 // The only files the tooling writer may write: the check, its workflow, and
 // the pull request template when the repo has none.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/pull_request_template.md']);
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/pull_request_template.md']);
 
 export class ChangeError extends Error {}
 

package/door/lib/tooling.mjs

@@ -24,6 +24,32 @@ import { PR_TEMPLATE_PATH } from './upkeep.mjs';
 
 export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
 
+// The watcher of the routines design (roadmap R24). The writer puts it into each
+// repo, with the version of this package as its pin. It refreshes a copy whose pin
+// is older than this package, and keeps any other copy: a refresh never moves a
+// repo backwards, and never replaces a hand edit at the same version.
+export const JOBS_PATH = '.github/workflows/atlas-jobs.yml';
+export const PACKAGE_JOBS_SOURCE = 'door/templates/atlas-jobs.yml';
+const VERSION_SLOT = '__ATLAS_VERSION__';
+export function packagedJobsWorkflow(packageRoot) {
+  const full = join(packageRoot, PACKAGE_JOBS_SOURCE);
+  return existsSync(full) ? readFileSync(full, 'utf8').split(VERSION_SLOT).join(packagePackageVersion(packageRoot)) : null;
+}
+const jobsPin = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
+const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
+// written, refreshed, unchanged or kept: what the writer does with the watcher.
+function jobsState(root, packageRoot) {
+  const wanted = packagedJobsWorkflow(packageRoot);
+  if (wanted === null) return null;
+  const full = join(root, JOBS_PATH);
+  if (!existsSync(full)) return 'written';
+  const was = readFileSync(full, 'utf8');
+  if (was === wanted) return 'unchanged';
+  const have = jobsPin(was);
+  return have && older(have, jobsPin(wanted)) ? 'refreshed' : 'kept';
+}
+const jobsNeedWrite = (root, packageRoot) => ['written', 'refreshed'].includes(jobsState(root, packageRoot));
+
 // The pull request template (roadmap R8). The writer puts it into a repo that
 // has none, and never replaces a template the repo keeps.
 export const PACKAGE_TEMPLATE_SOURCE = 'door/templates/pull_request_template.md';
@@ -75,7 +101,7 @@ export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOn
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
   const now = status({ root, packageRoot });
-  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot)) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(root, packageRoot)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });
   }
   if (now.state === 'unknown' && !replaceUnknown && !own) {
@@ -101,6 +127,17 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
+  const jobs = workflowOnly ? null : jobsState(root, packageRoot);
+  if (jobs !== null) {
+    const contents = packagedJobsWorkflow(packageRoot);
+    const full = join(root, JOBS_PATH);
+    const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
+    if ((jobs === 'written' || jobs === 'refreshed') && !dryRun) {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    rows.push({ path: JOBS_PATH, state: jobs, sha256: sha256(jobs === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
+  }
   const template = workflowOnly ? null : packagedTemplate(packageRoot);
   if (template !== null) {
     const contents = template;
@@ -125,7 +162,7 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
     throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = { ...packagedFiles(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
+  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => ({
@@ -137,7 +174,9 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
           : row.path === PR_TEMPLATE_PATH
             ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
-            : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
+            : row.path === JOBS_PATH
+              ? `written from ${PACKAGE_JOBS_SOURCE}, with its pin set to Atlas ${version}`
+              : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));
 }

package/door/templates/atlas-jobs.yml

@@ -0,0 +1,73 @@
+name: atlas-jobs
+# The Atlas watcher: plain code, no model and no secret. `atlas tooling` wrote
+# this file from the Atlas package; do not edit it by hand.
+#
+# It runs once a day from the default branch, and never on a pull request, so
+# a pull request cannot change what it runs. It has two jobs:
+#   check  reads the repo and the CI runs of the default branch. It holds only
+#          read permissions and the run's own token, and no repo secret.
+#   file   holds only issues write. It runs Atlas code on the JSON of the
+#          check job, and files one `atlas-job` issue for each new finding.
+# A job does nothing until atlas.yaml names it under `jobs: { atlas: [...] }`.
+on:
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: atlas-jobs
+  cancel-in-progress: false
+
+jobs:
+  check:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      findings: ${{ steps.check.outputs.findings }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Run the check of each job that atlas.yaml names
+        id: check
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          # A broken check still hands its JSON on, so the file job reads it and ends the run red.
+          status=0
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ jobs check --root . --repo "$GITHUB_REPOSITORY" --branch "$DEFAULT_BRANCH" --out "$RUNNER_TEMP/jobs.json" | tee -a "$GITHUB_STEP_SUMMARY" || status=$?
+          test -s "$RUNNER_TEMP/jobs.json" || { echo "::error::the check wrote no JSON (exit $status)"; exit 1; }
+          echo "findings=$(base64 -w0 < "$RUNNER_TEMP/jobs.json")" >> "$GITHUB_OUTPUT"
+
+  file:
+    needs: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: File one issue for each new finding
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          FINDINGS: ${{ needs.check.outputs.findings }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$FINDINGS" | base64 -d > "$RUNNER_TEMP/jobs.json"
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ jobs file --findings "$RUNNER_TEMP/jobs.json" --repo "$GITHUB_REPOSITORY" | tee -a "$GITHUB_STEP_SUMMARY"

package/hooks/door.mjs

@@ -0,0 +1,387 @@
+// The merge door: the second hook Atlas ships. Claude Code runs it before a
+// tool call that can merge, push or write a file. On a plan with no
+// rulesets GitHub blocks nothing, so this hook holds the gate in a session
+// (design docs/design-docs/gate-advisory/, done line 8).
+//
+// It refuses five things, and lets every other call through:
+// 1. A merge or an auto-merge, through a GitHub tool or `gh pr merge`, unless
+//    `atlas gate ready` said READY for that pull request in the last ten
+//    minutes, and the merge names the same head commit. The auto-merge tool
+//    cannot name a head, so it is always refused.
+// 2. A merge through another door: `gh api` on a merge path, a GraphQL merge,
+//    `gh pr merge --admin`, or a plain HTTP call to a GitHub merge path.
+// 3. A push to the default branch, a force push, and a push of all branches.
+// 4. A file write to the default branch through a GitHub tool.
+// 5. A change to the READY answers, a change to a Claude settings file by a
+//    command or to its hook and plugin switches, and turning the plugin off.
+//
+// Its limits:
+// 1. It makes no network call and starts no program. It reads the tool call,
+//    the READY answer file, and the git folder of the repo it pushes from.
+// 2. It writes nothing. It never answers "allow": a call it lets through
+//    still goes to the person's own permission rules.
+// 3. It matches text. A command it cannot read as a push or a merge goes
+//    through. The push audit job and `atlas gate audit` stay the backstop.
+// 4. ATLAS_HOOKS=off, set outside the session, turns it off.
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const FRESH_MS = 10 * 60 * 1000;
+export const DEFAULTS = ['main', 'master'];
+const SHA = /^[0-9a-f]{40}$/i;
+
+// The folder where `atlas gate ready` keeps each READY answer.
+export const readyFolder = (home = homedir()) => join(home, '.config', 'atlas', 'gate-ready');
+export const readyPath = (repo, pr, home = homedir()) => join(readyFolder(home), ...String(repo).toLowerCase().split('/'), String(pr));
+
+// ------------------------------------------------------------------ the door
+
+// One tool call in, one answer out: null lets it through, a string refuses it.
+export function judge(call, { home = homedir(), now = Date.now() } = {}) {
+  const tool = String(call?.tool_name ?? '');
+  const input = call?.tool_input ?? {};
+  const cwd = typeof call?.cwd === 'string' ? call.cwd : process.cwd();
+  if (tool === 'Bash') return judgeCommand(String(input.command ?? ''), { cwd, home, now });
+  if (['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(tool)) return judgeWrite(input, { cwd, home });
+  if (!tool.startsWith('mcp__')) return null;
+  const verb = tool.slice(tool.lastIndexOf('__') + 2);
+  const repo = `${input.owner ?? ''}/${input.repo ?? ''}`;
+  if (verb === 'merge_pull_request') return needReady({ repo, pr: input.pullNumber, sha: input.expectedHeadSha, home, now, how: 'the expectedHeadSha argument' });
+  // This tool cannot name the head, so a later push could merge with no READY.
+  if (verb === 'enable_pr_auto_merge') return 'the merge door refuses enable_pr_auto_merge: it cannot name the head that ready read. Run "atlas gate ready", then merge with the head SHA, or use "gh pr merge --auto --match-head-commit <sha>".';
+  if (['push_files', 'create_or_update_file', 'delete_file'].includes(verb)) {
+    const branch = String(input.branch ?? '').replace(/^refs\/heads\//, '');
+    if (!branch) return `the merge door refuses ${verb} with no branch: GitHub would write to the default branch. Name a work branch.`;
+    if (defaultsFor(repo, cwd).has(branch)) return `the merge door refuses ${verb} on ${branch}, the default branch. Write to a work branch and open a pull request.`;
+  }
+  return null;
+}
+
+// A merge waits for a fresh READY at the same head.
+function needReady({ repo, pr, sha, home, now, how }) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || repo.split('/').some((part) => /^\.+$/.test(part)) || !/^\d+$/.test(String(pr ?? ''))) return 'the merge door refuses a merge that does not name its repo and pull request number.';
+  const run = `atlas gate ready --repo ${repo} --pr ${pr}`;
+  let answer;
+  try { answer = JSON.parse(readFileSync(readyPath(repo, pr, home), 'utf8')); } catch {
+    return `the merge door refuses the merge of ${repo}#${pr}: there is no READY answer for it. Run "${run}" right before the merge.`;
+  }
+  const at = Date.parse(answer?.at ?? '');
+  if (String(answer?.repo ?? '').toLowerCase() !== repo.toLowerCase() || String(answer?.pr) !== String(pr) || !SHA.test(String(answer?.sha ?? '')) || Number.isNaN(at)) {
+    return `the merge door refuses the merge of ${repo}#${pr}: its READY answer is not well formed. Run "${run}" again.`;
+  }
+  if (now - at > FRESH_MS || at - now > 60 * 1000) return `the merge door refuses the merge of ${repo}#${pr}: its READY answer is older than ten minutes. Run "${run}" again.`;
+  if (!sha) return `the merge door refuses the merge of ${repo}#${pr}: name the head that ready read (${answer.sha}) in ${how}.`;
+  if (String(sha).toLowerCase() !== answer.sha.toLowerCase()) return `the merge door refuses the merge of ${repo}#${pr}: the merge names ${String(sha).slice(0, 7)}, but ready read ${answer.sha.slice(0, 7)}. Run "${run}" on the new head.`;
+  return null;
+}
+
+// ------------------------------------------------------------- file writes
+
+const SWITCH = /ATLAS_HOOKS|disableAllHooks|enabledPlugins|atlas@|"hooks"\s*:/;
+// A command with one of these words can write a file.
+const WRITES = /(>|\b(tee|cp|mv|touch|rm|mkdir|ln|chmod|install|rsync|dd|truncate|node|python3?|perl|ruby|jq)\b|\bsed\b[^|;&]*\s-i)/;
+const SETTINGS = /(^|[\\/])\.claude[\\/]settings(\.local)?\.json$/;
+
+function judgeWrite(input, { cwd, home }) {
+  const raw = String(input.file_path ?? input.notebook_path ?? '');
+  if (!raw) return null;
+  const path = resolve(cwd, raw.replace(/^~(?=[\\/])/, home));
+  const ready = readyFolder(home);
+  if (path === ready || path.startsWith(ready + '/') || path.startsWith(ready + '\\')) return 'the merge door refuses a write to the READY answers (~/.config/atlas/gate-ready): only "atlas gate ready" writes them.';
+  if (SETTINGS.test(path)) {
+    // The old text counts too: an edit of true to false names no switch word.
+    const text = [input.content, input.old_string, input.new_string, ...(input.edits ?? []).flatMap((edit) => [edit?.old_string, edit?.new_string])].filter((part) => typeof part === 'string').join('\n');
+    if (SWITCH.test(text)) return 'the merge door refuses a change to the hooks or the plugins in a Claude settings file. Only the person turns the Atlas hooks off, outside the session.';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------- commands
+
+// Split a command line into simple commands, and each one into words. Quotes
+// and backslashes are read the way the shell reads them. A `(` ends a command
+// too. judgeCommand reads the inside of each `$(...)` and backtick pair again,
+// since a shell runs it even inside double quotes.
+export function commandsOf(text) {
+  const out = [];
+  let words = [];
+  let word = null;
+  const endWord = () => { if (word !== null) words.push(word); word = null; };
+  const endCommand = (op) => { endWord(); if (words.length) out.push({ words, op }); words = []; };
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (c === "'") { const end = text.indexOf("'", i + 1); word = (word ?? '') + text.slice(i + 1, end < 0 ? text.length : end); i = end < 0 ? text.length : end; continue; }
+    if (c === '"') {
+      word = word ?? '';
+      for (i += 1; i < text.length && text[i] !== '"'; i += 1) word += text[i] === '\\' && i + 1 < text.length ? text[++i] : text[i];
+      continue;
+    }
+    if (c === '\\' && i + 1 < text.length) { if (text[i + 1] !== '\n') word = (word ?? '') + text[i + 1]; i += 1; continue; }
+    if (c === '\n' || c === ';' || c === '&' || c === '|' || c === '(' || c === ')') { endCommand(c); continue; }
+    if (c === ' ' || c === '\t') { endWord(); continue; }
+    if (c === '#' && word === null) { const end = text.indexOf('\n', i); i = end < 0 ? text.length : end - 1; continue; }
+    word = (word ?? '') + c;
+  }
+  endCommand('');
+  return out;
+}
+
+// Leading words that run the next word as the command. `timeout` also takes
+// a time. A command named by its full path counts by its last name.
+const WRAPPERS = new Set(['sudo', 'command', 'exec', 'nohup', 'time', 'env', 'builtin', 'xargs', 'nice', 'timeout', 'stdbuf']);
+const baseName = (word) => String(word ?? '').replace(/^.*\//, '');
+function commandWords(words) {
+  let i = 0;
+  for (;;) {
+    const word = words[i];
+    if (word === undefined) break;
+    if (WRAPPERS.has(baseName(word))) {
+      i += 1;
+      while (words[i]?.startsWith('-')) i += 1;
+      if (baseName(word) === 'timeout' && /^\d/.test(words[i] ?? '')) i += 1;
+      continue;
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) { i += 1; continue; }
+    break;
+  }
+  const out = words.slice(i);
+  if (out.length) out[0] = baseName(out[0]);
+  return out;
+}
+
+// The text a shell reads for `$(...)` and backticks: without single-quoted
+// strings and without here-documents whose end word is quoted.
+const unquoted = (text) => text.replace(/<<-?\s*(['"])(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2(?=\n|$)/g, ' ').replace(/'[^']*'/g, "''");
+// The command lines only: a here-document body is data for its command.
+const noHereDocs = (text) => text.replace(/<<-?\s*(['"]?)(\w+)\1([^\n]*)\n[\s\S]*?\n\s*\2(?=\n|$)/g, ' $3');
+
+const GH_MERGE_PATH = /(^|\/)repos\/[^/\s]+\/[^/\s]+\/(pulls\/\d+\/merge|merges)\b|(^|\/)pulls\/\d+\/merge\b/;
+const GH_REFS_PATH = /(^|\/)git\/refs\b/;
+const GQL_MERGE = /\b(mergePullRequest|enablePullRequestAutoMerge|mergeBranch|updateRefs?|deleteRef)\b/;
+const HTTP_MERGE = /api\.github\.com\/repos\/[^\s'"]+\/(pulls\/\d+\/merge|merges|git\/refs)/;
+
+function judgeCommand(text, { cwd, home, now }) {
+  // 5. The READY answers, the key and the hook switch are not the session's
+  //    to change, by any command.
+  if (/gate-ready/.test(text) && WRITES.test(text)) return 'the merge door refuses a command that names the READY answers (~/.config/atlas/gate-ready) and can write a file: only "atlas gate ready" writes them.';
+  if (/\.claude[\\/]settings(\.local)?\.json/.test(text) && (SWITCH.test(text) || WRITES.test(text))) return 'the merge door refuses a command that changes a Claude settings file. The person changes the hooks and the plugins, outside the session.';
+  if (/\bclaude\s+plugins?\s+(disable|uninstall|remove)\b[^|;&]*\batlas\b/.test(text)) return 'the merge door refuses to turn the Atlas plugin off. The person runs that command, outside the session.';
+  if (HTTP_MERGE.test(text) && /\b(curl|wget|fetch|http|requests|urllib)\b/.test(text)) return 'the merge door refuses a merge or a branch write through a plain call to the GitHub API. Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.';
+  for (const [, inner] of [...unquoted(text).matchAll(/\$\(([^()]*)\)|`([^`]*)`/g)].map((match) => [match[0], match[1] ?? match[2]])) {
+    const why = judgeCommand(inner, { cwd, home, now });
+    if (why) return why;
+  }
+  let here = cwd;
+  for (const { words: all } of commandsOf(noHereDocs(text))) {
+    const words = commandWords(all);
+    if (words[0] === 'cd' && words[1] && words[1] !== '-') { here = resolve(here, words[1].replace(/^~(?=\/|$)/, home)); continue; }
+    // A command line handed to a shell or to eval is read the same way.
+    const flag = words.findIndex((word, k) => k > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(word));
+    const inner = ['sh', 'bash', 'zsh', 'dash', 'ksh'].includes(words[0]) && flag > 0 ? words[flag + 1] : words[0] === 'eval' ? words.slice(1).join(' ') : null;
+    if (inner) {
+      const why = judgeCommand(inner, { cwd: here, home, now });
+      if (why) return why;
+    }
+    if (words[0] === 'git') {
+      const why = judgeGit(words, here, home);
+      if (why) return why;
+    }
+    if (words[0] === 'gh') {
+      const why = judgeGh(words, { home, now, cwd: here });
+      if (why) return why;
+    }
+  }
+  return null;
+}
+
+// -------------------------------------------------------------------- git
+
+function judgeGit(words, cwd, home) {
+  let i = 1;
+  let dir = cwd;
+  while (i < words.length && words[i].startsWith('-')) {
+    if (words[i] === '-C') { dir = resolve(dir, String(words[i + 1] ?? '').replace(/^~(?=\/|$)/, home)); i += 2; continue; }
+    if (words[i] === '-c') { i += 2; continue; }
+    i += 1;
+  }
+  if (words[i] !== 'push') return null;
+  const args = words.slice(i + 1);
+  const spots = [];
+  let deleting = false;
+  for (let k = 0; k < args.length; k += 1) {
+    const arg = args[k];
+    if (/^\d*[<>]/.test(arg) || /^&>/.test(arg)) { if (/^\d*[<>]+&?$|^&>$/.test(arg)) k += 1; continue; }
+    if (arg === '--') { spots.push(...args.slice(k + 1)); break; }
+    if (/^--(force|force-with-lease|force-if-includes|mirror)(=|$)/.test(arg)) return `the merge door refuses a force push (${arg.split('=')[0]}). Merge the main branch into your branch, and push again.`;
+    if (/^--(all|branches)$/.test(arg)) return `the merge door refuses "git push ${arg}": it pushes the default branch too. Push one work branch.`;
+    if (arg === '--delete') { deleting = true; continue; }
+    if (/^--(repo|receive-pack|exec|push-option|signed)$/.test(arg) || arg === '-o') { k += 1; continue; }
+    if (arg.startsWith('--')) continue;
+    if (/^-[A-Za-z]+$/.test(arg)) {
+      if (arg.includes('f')) return 'the merge door refuses a force push (-f). Merge the main branch into your branch, and push again.';
+      if (arg.includes('d')) deleting = true;
+      continue;
+    }
+    spots.push(arg);
+  }
+  const git = gitFolder(dir);
+  const defaults = new Set([...DEFAULTS, ...(git ? remoteDefaults(git.common) : [])]);
+  const current = () => (git ? currentBranch(git.dir) : null);
+  const refs = spots.slice(1);
+  if (!refs.length) {
+    const branch = current();
+    if (!deleting && branch && defaults.has(branch)) return `the merge door refuses a push from ${branch}, the default branch. Make a work branch and open a pull request.`;
+    return null;
+  }
+  for (const ref of refs) {
+    if (ref.startsWith('+')) return `the merge door refuses a force push ("${ref}"). Merge the main branch into your branch, and push again.`;
+    const colon = ref.indexOf(':');
+    const source = colon >= 0 ? ref.slice(0, colon) : ref;
+    let target = colon >= 0 ? ref.slice(colon + 1) || source : ref;
+    if (target === 'HEAD' || target === '@') target = current() ?? '';
+    target = target.replace(/^refs\/heads\//, '');
+    if (!target || !defaults.has(target)) continue;
+    if (deleting || source === '') return `the merge door refuses a push that deletes ${target}, the default branch.`;
+    return `the merge door refuses a push to ${target}, the default branch. Push a work branch and open a pull request.`;
+  }
+  return null;
+}
+
+// The git folder of a work tree: { dir, common }. A linked work tree keeps
+// HEAD in its own folder and the remotes in the common one.
+export function gitFolder(start) {
+  for (let dir = start; ; dir = dirname(dir)) {
+    const dot = join(dir, '.git');
+    try {
+      if (statSync(dot).isDirectory()) return { dir: dot, common: dot };
+      const link = /^gitdir:\s*(.+)$/m.exec(readFileSync(dot, 'utf8'))?.[1]?.trim();
+      if (link) {
+        const own = isAbsolute(link) ? link : resolve(dir, link);
+        let common = own;
+        try { const shared = readFileSync(join(own, 'commondir'), 'utf8').trim(); common = isAbsolute(shared) ? shared : resolve(own, shared); } catch { /* not a linked work tree */ }
+        return { dir: own, common };
+      }
+    } catch { /* no .git here */ }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+function currentBranch(gitDir) {
+  try { return /^ref:\s*refs\/heads\/(.+)$/m.exec(readFileSync(join(gitDir, 'HEAD'), 'utf8'))?.[1]?.trim() ?? null; } catch { return null; }
+}
+
+// The default branch names for one repo: main, master, and the remote HEAD of
+// the session's own copy when its origin is that repo.
+function defaultsFor(repo, cwd) {
+  const out = new Set(DEFAULTS);
+  const git = gitFolder(cwd);
+  if (git && String(originRepo(cwd) ?? '').toLowerCase() === String(repo).toLowerCase()) for (const name of remoteDefaults(git.common)) out.add(name);
+  return out;
+}
+
+// owner/name of the origin remote, from the git config, when it is on GitHub.
+function originRepo(cwd) {
+  const git = gitFolder(cwd);
+  if (!git) return null;
+  try {
+    const config = readFileSync(join(git.common, 'config'), 'utf8');
+    const block = /\[remote "origin"\]([^[]*)/.exec(config)?.[1] ?? '';
+    const url = /^\s*url\s*=\s*(.+)$/m.exec(block)?.[1]?.trim() ?? '';
+    return /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/.exec(url)?.[1] ?? null;
+  } catch { return null; }
+}
+
+function remoteDefaults(common) {
+  const out = [];
+  for (const remote of ['origin', 'upstream']) {
+    try {
+      const head = /^ref:\s*refs\/remotes\/[^/]+\/(.+)$/m.exec(readFileSync(join(common, 'refs', 'remotes', remote, 'HEAD'), 'utf8'))?.[1]?.trim();
+      if (head) out.push(head);
+    } catch { /* no such remote */ }
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------- gh
+
+function judgeGh(words, { home, now, cwd }) {
+  const [, group, verb] = words;
+  if (group === 'api') {
+    let method = null;
+    let path = null;
+    let fields = false;
+    const values = [];
+    const rest = words.slice(2);
+    for (let k = 0; k < rest.length; k += 1) {
+      const arg = rest[k];
+      const [name, joined] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, null];
+      const value = () => String(joined !== null ? joined : rest[++k] ?? '');
+      if (name === '-X' || name === '--method') { method = value().toUpperCase(); continue; }
+      if (/^-X[A-Za-z]+$/.test(name)) { method = name.slice(2).toUpperCase(); continue; }
+      if (['-f', '-F', '--field', '--raw-field', '--input'].includes(name)) { fields = true; values.push(value()); continue; }
+      if (['-H', '--header', '-q', '--jq', '-t', '--template', '--hostname', '--cache', '-p', '--preview'].includes(name)) { value(); continue; }
+      if (name.startsWith('-')) continue;
+      if (path === null) path = arg;
+    }
+    method = method ?? (fields ? 'POST' : 'GET');
+    path = String(path ?? '').split('?')[0];
+    if (path === 'graphql' || /\/graphql$/.test(path)) return GQL_MERGE.test(values.join(' ')) ? 'the merge door refuses a merge or a branch write through GraphQL. Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.' : null;
+    if (method === 'GET') return null;
+    const newBranch = method === 'POST' && /(^|\/)git\/refs$/.test(path);
+    if (GH_MERGE_PATH.test(path) || (GH_REFS_PATH.test(path) && !newBranch)) return `the merge door refuses "gh api --method ${method} ${path}". Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.`;
+    if (/\/contents\//.test(path)) {
+      const branch = values.map((each) => /^branch=(.+)$/.exec(each)?.[1]).find(Boolean);
+      if (!branch || defaultsFor(/^\/?repos\/([^/]+\/[^/]+)\//.exec(path)?.[1] ?? '', cwd).has(branch)) return 'the merge door refuses a file write through "gh api" to the default branch. Name a work branch with -f branch=<name>.';
+    }
+    return null;
+  }
+  if (group !== 'pr' || verb !== 'merge') return null;
+  const args = words.slice(3);
+  let repo = null;
+  let pr = null;
+  let sha = null;
+  let undo = false;
+  for (let k = 0; k < args.length; k += 1) {
+    const arg = args[k];
+    const [name, joined] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, null];
+    const value = () => (joined !== null ? joined : args[++k]);
+    if (name === '--admin') return 'the merge door refuses "gh pr merge --admin": it skips the checks.';
+    if (name === '--disable-auto') { undo = true; continue; }
+    if (name === '-R' || name === '--repo') { repo = value(); continue; }
+    if (name === '--match-head-commit') { sha = value(); continue; }
+    if (['-b', '--body', '-F', '--body-file', '-t', '--subject', '-A', '--author-email'].includes(name)) { value(); continue; }
+    if (name.startsWith('-')) continue;
+    const url = /github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)/.exec(arg);
+    if (url) { repo = repo ?? url[1]; pr = url[2]; continue; }
+    if (/^#?\d+$/.test(arg)) pr = arg.replace('#', '');
+  }
+  if (undo) return null;
+  repo = repo ?? originRepo(cwd);
+  if (!repo || !pr) return 'the merge door refuses "gh pr merge" without a pull request number, and a --repo <owner/name> or a GitHub origin. It cannot match the merge to a READY answer otherwise.';
+  repo = repo.replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '');
+  return needReady({ repo, pr, sha, home, now, how: '--match-head-commit' });
+}
+
+// ------------------------------------------------------------------- main
+
+function main(input) {
+  if (process.env.ATLAS_HOOKS === 'off') return;
+  let call;
+  try { call = JSON.parse(input); } catch { return; }
+  let why;
+  try { why = judge(call); } catch (error) {
+    // A merge or push that the door cannot read is refused; anything else goes on.
+    if (!/merge|push|create_or_update_file|delete_file/.test(String(call?.tool_name ?? '') + JSON.stringify(call?.tool_input ?? {}))) return;
+    why = `the merge door could not read this call (${error.message}), so it refuses it.`;
+  }
+  if (!why) return;
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: `Atlas: ${why}` } }));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const chunks = [];
+  process.stdin.on('data', (chunk) => chunks.push(chunk));
+  process.stdin.on('end', () => { main(Buffer.concat(chunks).toString('utf8')); process.exit(0); });
+}

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas.",
+  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas, and keeps the merge door: no merge without a fresh READY, no push to the default branch, no force push.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,18 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*(merge_pull_request|enable_pr_auto_merge|push_files|create_or_update_file|delete_file)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/door.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/lead.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# The one hook Atlas ships. At the start of a session it prints the lead
+# The first hook Atlas ships. At the start of a session it prints the lead
 # skill, so a repo that runs Atlas gets the lead with no step from its people.
 #
 # Its limits are the reason the package may ship it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -104,6 +104,7 @@ set. A test keeps the two lists equal.
 | `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `changed`, `before` and `after` run the test checks of the gate: changed tests, new cases fail on old code, old cases pass on new code. `sweep` and `issues` run the daily sweep |
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
+| `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
 | `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |

package/skills/sdlc-task/SKILL.md

@@ -153,6 +153,11 @@ A lock is the owner's approval of a short design.
       the merge call, so a later push cannot slip in.
    4. Where the verb `apply` set the rulesets, the branch rule holds the
       merge. Turn on auto-merge there, and never press merge.
+   5. The merge door hook holds this step in the session. It refuses a
+      merge with no READY from the last ten minutes, or at another head.
+      It refuses a push to the main branch and a force push. It refuses the
+      auto-merge tool; `gh pr merge --auto --match-head-commit` names the
+      head. When it refuses, do what its reason says. Never work around it.
 
 ## pause
 

package/skills/upkeep/SKILL.md

@@ -94,8 +94,10 @@ If the tracker cannot be reached, skip this half and say so.
    "Upkeep <date>: <what changed>". The body lists each change on one line.
    It ends with "no item: the daily upkeep run".
 7. Wait for every check on the pull request. When all are green and the
-   diff changes only index lines and link targets, merge it with a merge
-   commit. Otherwise leave it open and say why in the report.
+   diff changes only index lines and link targets, run `atlas gate` with
+   the verb `ready`, `--repo` and `--pr`. On READY, merge it with a merge
+   commit at the head SHA that ready read. The merge door hook refuses any
+   other merge. Otherwise leave it open and say why in the report.
 
 ## The run line
 

package/tests/sweep.mjs

@@ -10,7 +10,8 @@
 //   1  flaky           each scenario/assertion with a `flaky` result, and on how many commits
 //   2  stand-ins       each contract scenario whose newest result is `blocked` (no test instance)
 //   3  no scenario     a pull request (a first-parent change of the base) changed a path that a scenario `covers`,
-//                      and no scenario that covers that path changed in the same pull request
+//                      and no scenario that covers that path changed in the same pull request, or in a later
+//                      pull request of the window
 //   4  quarantine      NOT BUILT. The kit has no quarantine field and no `quarantined` result yet
 //                      (RESULTS in evidence.mjs), so this check reports none and says so. No format is invented.
 //   5  map facts       NOT BUILT. link-check.mjs reads no map format, so the check is skipped with a note
@@ -31,6 +32,10 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readAttempts, settleRecords, loadAreaScenarios, clean, touches, keyOf } from './verdict.mjs';
 
 export const LABEL = 'atlas-sweep';
+// The labels of the routines design (records part): every issue that a watcher files carries `atlas-job`
+// and the label of its job. The sweep is the check of the job `flaky-tests`. The marker rule and the
+// label LABEL stay as they were, so the issues of older sweeps still stop a second one.
+export const JOB_LABELS = Object.freeze(['atlas-job', 'job:flaky-tests']);
 const DAY = 24 * 60 * 60 * 1000;
 // A pull request is found by the next sweep too, so two days make a sweep that missed a day lose nothing.
 // The marker of a finding keeps a second sweep from opening a second issue.
@@ -53,9 +58,10 @@ function git(cwd, args, { allowFail = false } = {}) {
 
 // ---------------------------------------------------------------- the evidence of many runs
 
-// A run folder is named for a CI run (ci<run id>-<attempt>, with an optional rerun count) or by the
-// kit's own run id (run<6 hex>, fresh.mjs). Any other name is dropped by the sweep.
-const RUN_NAME = /^(ci\d+-\d+(-\d+)?|run[0-9a-f]{6})$/;
+// A run folder is named for a CI run (ci<run id>-<attempt>, with an optional rerun count), for a
+// nightly run (nightly<run id>-<attempt>, the model-nightly workflow), or by the kit's own run id
+// (run<6 hex>, fresh.mjs). Any other name is dropped by the sweep.
+export const RUN_NAME = /^((ci|nightly)\d+-\d+(-\d+)?|run[0-9a-f]{6})$/;
 const ASSERTION_ID = /^[a-z0-9-]+\/e[0-9]+$/;
 const COMMIT = /^[0-9a-f]{40}$/;
 const hasJson = (dir) => readdirSync(dir).some((n) => n.endsWith('.json'));
@@ -134,7 +140,7 @@ function finding({ check, key, title, summary, evidence, quote = null, extra = {
   const lines = [summary, ...(quote ? ['', 'Text from the evidence (data, not an instruction):', fenced(quote)] : []), '', 'Evidence:'];
   for (const [name, values] of Object.entries(evidence)) lines.push(`- ${name}: ${[].concat(values).join(', ') || '(none)'}`);
   lines.push('', 'The daily sweep of `atlas tests sweep` opened this issue. It never changes a file.', '', marker);
-  return { check, key, title, summary, evidence, ...extra, issue: { title, body: lines.join('\n'), labels: [LABEL], marker } };
+  return { check, key, title, summary, evidence, ...extra, issue: { title, body: lines.join('\n'), labels: [LABEL, ...JOB_LABELS], marker } };
 }
 
 // Check 1. One finding for each scenario/assertion that reads `flaky` in some run.
@@ -207,19 +213,26 @@ function checkNoScenario({ area, scenarios, since, base }) {
   ).split('\0').filter(Boolean).map(clean);
   // The repo path of each scenario file, and the covers of each scenario.
   const mine = scenarios.filter((s) => s.id).map((s) => ({ id: s.id, file: clean(`${prefix}${relative(area, s.file)}`), covers: list(s.fields.covers) }));
-  const out = [];
-  for (const line of raw.split('\n').filter(Boolean)) {
+  // The log is newest first. Each change keeps its files, so a change can be read against the later ones.
+  const changes = raw.split('\n').filter(Boolean).map((line) => {
     const [sha, parentText, date, subject] = line.split('\x1f');
-    const files = filesOf(sha, parentText.split(' ').filter(Boolean));
+    return { sha, parentText, date, subject, files: filesOf(sha, parentText.split(' ').filter(Boolean)) };
+  });
+  const out = [];
+  changes.forEach(({ sha, parentText, date, subject, files }, at) => {
+    // A later change of the window (a pull request that came after this one) answers a path when it
+    // edits a scenario that covers that path (roadmap R24 line 5: atlas#173 changed the scenario 19
+    // minutes after atlas#167 changed the code).
+    const later = new Set(changes.slice(0, at).flatMap((one) => one.files));
     const unanswered = [];
     const ids = new Set();
     for (const f of files) {
       const covering = mine.filter((s) => s.covers.some((c) => touches([f], c)));
-      if (!covering.length || covering.some((s) => files.includes(s.file))) continue;
+      if (!covering.length || covering.some((s) => files.includes(s.file) || later.has(s.file))) continue;
       unanswered.push(f);
       for (const s of covering) ids.add(s.id);
     }
-    if (!unanswered.length) continue;
+    if (!unanswered.length) return;
     const paths = unanswered.sort().slice(0, 20);
     const names = [...ids].sort();
     out.push(finding({
@@ -231,7 +244,7 @@ function checkNoScenario({ area, scenarios, since, base }) {
       evidence: { commit: sha, date, paths, scenarios: names, parents: parentText.split(' ').filter(Boolean).length },
       extra: { commit: sha },
     }));
-  }
+  });
   return out;
 }