@arjunkhera/atlas 0.4.13 → 0.4.15

package/.claude-plugin/plugin.json

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

package/door/lib/brake.mjs

@@ -0,0 +1,193 @@
+// The brake (roadmap R13, tracker item dbf54f67; design
+// docs/design-docs/brake/). After a bad merge, every pull request of the repo
+// goes to the owner for 7 days. The gate reads the brake from the base side;
+// nothing stores it.
+//
+//   brakeFacts(text)                                   the brake settings of atlas.yaml
+//   windowCommits(root, base, since)                   the first-parent commits of main in the window
+//   revertTrips(root, commits)                         line 1: a revert of a change that main held
+//   ciTrips({ commits, runs, homes, ... }, jobsOf)     lines 2 and 3: a red main that a rerun confirmed, a failed live check
+//   brakeState({ root, base, now, ci })                the trips, and the date the brake ends
+//   undoOf(root, mergeBase, head, trips)               line 4: the trip that this head undoes exactly, or null
+//
+// The brake works per repo (line 5): it reads only the history and the runs
+// of the repo that the gate judges. One signed act of the owner ends it early
+// (line 6, roadmap R72); that act does not exist yet.
+import { spawnSync } from 'node:child_process';
+import { parseYaml } from '../../shape/check.mjs';
+
+export const BRAKE_DAYS = 7;
+// A job that ends like this failed. A cancelled or skipped job did not.
+export const FAILED = Object.freeze(['failure', 'timed_out']);
+// How far back the read looks for a first-parent commit, at most. A window
+// that holds more fails closed.
+const MAX_COMMITS = 500;
+// A job that never started, as when the Actions billing stops, has no steps
+// and no runner. It proves nothing about the code, so it never trips.
+export const ran = (job) => Array.isArray(job?.steps) && job.steps.length > 0;
+
+export class BrakeError extends Error {}
+
+function git(root, args, { input, allowFail = false } = {}) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', input, maxBuffer: 256 * 1024 * 1024 });
+  if (r.error) throw new BrakeError(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) {
+    if (allowFail) return null;
+    throw new BrakeError(`git ${args.join(' ')} failed: ${String(r.stderr || r.stdout || '').trim().split('\n')[0]}`);
+  }
+  return r.stdout;
+}
+
+const fullSha = (root, ref) => (git(root, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { allowFail: true }) ?? '').trim();
+// git's word for the ancestor test, joined so the package names no ancestry verb (test/package D9).
+const MERGE_BASE = ['merge', 'base'].join('-');
+const holds = (root, ancestor, ref) => spawnSync('git', [MERGE_BASE, '--is-ancestor', ancestor, ref], { cwd: root }).status === 0;
+
+// The brake settings of one atlas.yaml text, as the base holds it. The key
+// `brake:` is on the fixed list of the owner-only floor, so only the owner
+// changes it.
+//   brake:
+//     days: 7              how long one trip holds, 1 to 30
+//     live_checks: [deploy] the jobs of a push run that are the live check, for live: deploy
+export function brakeFacts(text) {
+  let facts;
+  try { facts = parseYaml(text ?? '') ?? {}; } catch { facts = {}; }
+  const brake = facts.brake && typeof facts.brake === 'object' ? facts.brake : {};
+  const days = Number.isInteger(brake.days) && brake.days >= 1 && brake.days <= 30 ? brake.days : BRAKE_DAYS;
+  const liveChecks = Array.isArray(brake.live_checks) ? brake.live_checks.map(String) : [];
+  const checks = Array.isArray(facts.required_checks) ? facts.required_checks.map(String) : [];
+  return { days, live: String(facts.live ?? ''), liveChecks, checks };
+}
+
+// The first-parent commits of the base whose commit time is in the window,
+// newest first. Each one is a merge of a pull request, or a push. One commit
+// with an odd date does not end the walk: it reads all of the newest 500.
+export function windowCommits(root, base, since) {
+  const out = git(root, ['log', '--first-parent', `--max-count=${MAX_COMMITS}`, '--format=%H %cI %P', base, '--']) ?? '';
+  const lines = out.split('\n').filter(Boolean);
+  const rows = [];
+  for (const line of lines) {
+    const [sha, time, ...parents] = line.split(' ');
+    if (!(Date.parse(time) >= since.getTime())) continue;
+    rows.push({ sha, time: new Date(Date.parse(time)).toISOString(), parents });
+  }
+  if (lines.length === MAX_COMMITS && rows.some((row) => row.sha === lines.at(-1).split(' ')[0])) throw new BrakeError(`more than ${MAX_COMMITS} commits of main are in the brake window; the read stops here.`);
+  return rows;
+}
+
+const REVERTS = /This reverts commit ([0-9a-f]{7,40})/g;
+
+// Line 1: a commit that a first-parent commit brought to main, and that says
+// "This reverts commit X", where main held X before. A pull request that
+// reverts its own commit before its merge does not trip it: main never held
+// that commit. GitHub's revert button, `git revert` and a squash of either
+// all write that line. The message is all the read trusts, so a revert trip
+// gives no undo: a false line can only send work to the owner. The revert on
+// main is the undo already.
+export function revertTrips(root, commits) {
+  const trips = [];
+  for (const commit of commits) {
+    const first = commit.parents[0];
+    if (!first) continue;
+    const out = git(root, ['log', '--format=%H%x00%B%x1e', `${first}..${commit.sha}`, '--']) ?? '';
+    for (const entry of out.split('\x1e')) {
+      const [sha, message = ''] = entry.replace(/^\n/, '').split('\x00');
+      if (!sha) continue;
+      for (const hit of message.matchAll(REVERTS)) {
+        const culprit = fullSha(root, hit[1]);
+        if (!culprit || !holds(root, culprit, first)) continue;
+        if (trips.some((trip) => trip.culprit === culprit)) continue;
+        trips.push({ cause: 'revert', sha: commit.sha, time: commit.time, culprit, revert: sha, undoable: false });
+      }
+    }
+  }
+  return trips;
+}
+
+// Lines 2 and 3, from the push runs of the main branch. `runs` are workflow
+// runs as GitHub lists them; `jobsOf(runId, attempt)` gives the jobs of one
+// attempt. `homes` are the base workflow files that define a required check.
+// A required check trips when it failed in try 1 and in try 2: the rerun job
+// of the main branch makes try 2. A later green try does not clear it. A red
+// first try with no rerun trips nothing; the red-main watcher of atlas-jobs
+// files an issue for it. A live check trips on its first failure, because a rerun would deploy again.
+export function ciTrips({ commits, runs, homes, checks, live = '', liveChecks = [] }, jobsOf) {
+  const inWindow = new Map(commits.map((commit) => [commit.sha, commit]));
+  const required = new Set(checks);
+  const liveSet = new Set(live === 'deploy' ? liveChecks : []);
+  const trips = [];
+  const seen = new Set();
+  const add = (trip) => {
+    const key = `${trip.cause} ${trip.sha} ${trip.check}`;
+    if (!seen.has(key)) { seen.add(key); trips.push(trip); }
+  };
+  for (const run of runs ?? []) {
+    const commit = inWindow.get(run.head_sha);
+    if (!commit || run.event !== 'push' || run.status !== 'completed') continue;
+    const attempt = Number(run.run_attempt ?? 1);
+    const failedIn = (n) => new Set((jobsOf(run.id, n) ?? []).filter((job) => FAILED.includes(job.conclusion) && ran(job)).map((job) => String(job.name)));
+    if (liveSet.size && FAILED.includes(run.conclusion)) {
+      for (const name of failedIn(attempt)) if (liveSet.has(name)) add({ cause: 'live', sha: commit.sha, time: commit.time, culprit: commit.sha, check: name });
+    }
+    if (!homes.has(run.path)) continue;
+    if (attempt >= 2) {
+      const second = failedIn(2);
+      if (!second.size) continue;
+      const first = failedIn(1);
+      // The time of the confirmation, when try 2 is the newest try.
+      const seen = attempt === 2 && run.updated_at ? new Date(Date.parse(run.updated_at)).toISOString() : commit.time;
+      for (const name of second) if (required.has(name) && first.has(name)) add({ cause: 'red-main', sha: commit.sha, time: seen > commit.time ? seen : commit.time, culprit: commit.sha, check: name });
+    }
+  }
+  return trips;
+}
+
+// The brake of the repo at the base commit. `ci` holds the trips of lines 2
+// and 3, which the gate reads from GitHub; with no GitHub read it is empty.
+export function brakeState({ root, base, now = new Date(), ci = [] }) {
+  const sha = fullSha(root, base);
+  if (!sha) throw new BrakeError(`the base "${base}" is not a commit in this repo.`);
+  const facts = brakeFacts(git(root, ['show', `${sha}:atlas.yaml`], { allowFail: true }));
+  const since = new Date(now.getTime() - facts.days * 864e5);
+  const commits = windowCommits(root, sha, since);
+  // A time after now, from an odd commit date, counts as now.
+  const stamp = now.toISOString();
+  const trips = [...revertTrips(root, commits), ...ci].map((trip) => (trip.time > stamp ? { ...trip, time: stamp } : trip)).sort((a, b) => b.time.localeCompare(a.time));
+  const until = trips.length ? new Date(Date.parse(trips[0].time) + facts.days * 864e5).toISOString() : null;
+  return { on: trips.length > 0, days: facts.days, since: since.toISOString(), until, trips };
+}
+
+// The patch id of a diff, or null for an empty diff. --verbatim keeps every
+// space, so a change of indent is a different patch.
+function patchId(root, from, to) {
+  const diff = git(root, ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '--full-index', '--binary', from, to, '--']) ?? '';
+  if (!diff.trim()) return null;
+  const out = (git(root, ['patch-id', '--verbatim'], { input: diff }) ?? '').trim();
+  return out.split(/\s+/)[0] || null;
+}
+
+// Line 4: the trip whose change this head takes back exactly, or null. The
+// change of the head, from the merge base, must be the reverse of the
+// culprit's change against its first parent. Any other line makes it a new
+// change, which the brake holds.
+export function undoOf(root, mergeBase, head, trips) {
+  if (!trips.length) return null;
+  const mine = patchId(root, mergeBase, head);
+  if (!mine) return null;
+  for (const trip of trips) {
+    if (trip.undoable === false) continue;
+    const parent = fullSha(root, `${trip.culprit}^1`);
+    if (parent && patchId(root, trip.culprit, parent) === mine) return trip;
+  }
+  return null;
+}
+
+const short = (sha) => String(sha ?? '').slice(0, 7);
+
+// One line for a trip, for the gate summary.
+export function tripText(trip) {
+  if (trip.cause === 'revert') return `revert of ${short(trip.culprit)} by ${short(trip.revert)}, on main at ${short(trip.sha)} (${trip.time.slice(0, 10)})`;
+  if (trip.cause === 'red-main') return `"${trip.check}" red on ${short(trip.sha)} after one rerun (${trip.time.slice(0, 10)})`;
+  return `the live check "${trip.check}" failed after ${short(trip.sha)} (${trip.time.slice(0, 10)})`;
+}
+

package/door/lib/gate-check.mjs

@@ -6,7 +6,7 @@
 //
 //   judge({ root, base, head, body, redMain })   the answer, from git data
 //   renderText(answer)                           the lines of the job summary
-//   checkCommand(options, line, read)            the command; `read` gives the red main checks
+//   checkCommand(options, line, read)            the command; `read` gives the red main checks and the brake trips
 //
 // The answer is success, owner or red:
 //
@@ -14,7 +14,7 @@
 //            case added or changed; a head that git cannot read
 //   owner    a path or a sign of the owner-only list; a head job named like a
 //            check; a refactor claim (until the review job, roadmap R28); a
-//            file too large to scan
+//            file too large to scan; the brake (roadmap R13, brake.mjs)
 //   success  no rule holds the pull request
 //
 // Red wins over owner: the pull request must be fixed before the owner signs.
@@ -29,13 +29,14 @@ import { resolve } from 'node:path';
 import { classify, changedPaths, compile, matcher } from './owner-only.mjs';
 import { listChanged } from './changed-tests.mjs';
 import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
+import { brakeState, undoOf, tripText } from './brake.mjs';
 
 export const VERSION = 1;
 export const GATE_CHECK = 'gate';
 export const GATE_WORKFLOW = '.github/workflows/atlas-gate.yml';
 export const TEST_CHECKS = Object.freeze(['fails-before', 'passes-after']);
 export const RESULTS = Object.freeze(['success', 'owner', 'red']);
-export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act']);
+export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act', 'brake']);
 export const SIGNED_ACT = "Clears with the owner's signed act: atlas approve <pr> (roadmap R72).";
 // A file over this size is not scanned for secrets, and comes to the owner.
 export const SCAN_LIMIT = 1024 * 1024;
@@ -185,10 +186,13 @@ export function coveredFiles(root, green, mergeBase) {
 // Line 6: new product code needs a new or changed test case, and fails-before
 // proves it. Line 7: a fix of a red main check that changes no test is exempt
 // for the files that main changed since that check was last green.
-function testRows({ root, mergeBase, head, body, redMain, rules }) {
+function testRows({ root, mergeBase, head, body, redMain, rules, undo = null }) {
   const list = listChanged({ root, base: mergeBase, head });
   const product = list.other_paths.filter(productTest(root, rules ?? mergeBase));
   if (!product.length) return [];
+  // The exact undo of a change that tripped the brake puts main back as it
+  // was before that change, so it needs no new test (roadmap R13 line 4).
+  if (undo) return [{ kind: 'note', class: 'tests', cause: `the exact undo of ${undo.culprit.slice(0, 7)} needs no new test case` }];
   const cases = list.rows.filter((row) => CASE_GROUPS.has(row.group) && row.status !== 'removed');
   if (cases.length) return [{ kind: 'note', class: 'tests', cause: `${new Set(cases.map((row) => row.path)).size} test file(s) added or changed; fails-before proves them` }];
   const anyTest = list.rows.length > 0;
@@ -215,13 +219,15 @@ function testRows({ root, mergeBase, head, body, redMain, rules }) {
 
 // The answer for one pull request. `redMain` lists the required checks that
 // are red on the merge base: [{ check, green }], where `green` is the newest
-// commit of main on which the check was green.
-export function judge({ root, base, head, body = '', redMain = [], rules = null }) {
+// commit of main on which the check was green. `brake` holds the trips that
+// GitHub gives ({ ci: [...] }, see brake.mjs); false leaves the brake out, as
+// the replay does, because the brake depends on the day of the run.
+export function judge({ root, base, head, body = '', redMain = [], rules = null, brake = {}, now = new Date() }) {
   const top = resolve(root);
   const baseSha = commitOf(top, base);
   if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
   const headSha = commitOf(top, head);
-  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null };
+  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null, brake: null };
   if (!headSha) {
     answer.rows.push({ kind: 'red', class: 'gate', cause: 'the head commit is not readable in this clone' });
     return finish(answer);
@@ -233,13 +239,30 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null
   }
   answer.merge_base = mergeBase;
   const changes = changedPaths(top, mergeBase, headSha);
+  let undo = null;
+  if (brake !== false) {
+    const state = brakeState({ root: top, base: baseSha, now, ci: brake?.ci ?? [] });
+    undo = undoOf(top, mergeBase, headSha, state.trips);
+    answer.brake = { on: state.on, until: state.until, days: state.days, trips: state.trips, undo: undo?.culprit ?? null };
+    answer.rows.push(...brakeRows(state, undo));
+  }
   for (const row of classify({ root: top, base: mergeBase, head: headSha, rules }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
   answer.rows.push(...jobRows(top, rules ?? mergeBase, headSha, changes));
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
-  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules }));
+  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules, undo }));
   return finish(answer);
 }
 
+// Line 1: while the brake is on, every pull request of the repo comes to the
+// owner, except the exact undo of a trip (line 4).
+function brakeRows(state, undo) {
+  if (!state.on) return [];
+  const newest = state.trips[0];
+  const more = state.trips.length > 1 ? `; ${state.trips.length} trips in ${state.days} days` : '';
+  if (undo) return [{ kind: 'note', class: 'brake', cause: `the exact undo of ${undo.culprit.slice(0, 7)}, which tripped the brake: ${tripText(undo)}` }];
+  return [{ kind: 'owner', class: 'brake', cause: `the brake is on until ${state.until.slice(0, 16).replace('T', ' ')} UTC: ${tripText(newest)}${more}` }];
+}
+
 function finish(answer) {
   const red = answer.rows.filter((row) => row.kind === 'red');
   const owner = answer.rows.filter((row) => row.kind === 'owner');
@@ -278,8 +301,10 @@ export function checkCommand({ root, base, head, body: bodyFile, json = false, s
     if (!base || base === true) throw Object.assign(new GateCheckError('atlas gate check needs --base <ref>.'), { usage: true });
     if (!head || head === true) throw Object.assign(new GateCheckError('atlas gate check needs --head <sha>.'), { usage: true });
     const body = bodyFile && bodyFile !== true ? readFileSync(resolve(bodyFile), 'utf8') : '';
-    const redMain = read ? read() : [];
-    const answer = judge({ root, base, head, body, redMain });
+    // A reader gives the red main checks, or { redMain, brake } with the brake trips too.
+    const got = read ? read() : [];
+    const redMain = Array.isArray(got) ? got : got.redMain ?? [];
+    const answer = judge({ root, base, head, body, redMain, brake: Array.isArray(got) ? {} : got.brake ?? {} });
     const text = renderText(answer);
     if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
     else for (const each of text) line(each);
@@ -311,7 +336,7 @@ export function replay({ root, days = 30, branch = null, now = new Date() }) {
   for (const entry of shas) {
     const [sha, parent] = entry.split(' ');
     if (!parent) continue;
-    const answer = judge({ root: top, base: parent, head: sha, rules: tip });
+    const answer = judge({ root: top, base: parent, head: sha, rules: tip, brake: false });
     const list = listChanged({ root: top, base: parent, head: sha });
     const oldTest = list.rows.some((row) => CASE_GROUPS.has(row.group) && row.status !== 'added');
     rows.push({

package/door/lib/gate.mjs

@@ -21,6 +21,7 @@ import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { checkCommand, replayCommand, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
+import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
 export const TAG_RULESET = 'atlas release tags';
@@ -293,6 +294,23 @@ function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks }) {
   return { kept, refused };
 }
 
+// The push runs of the base files that define a required or a live check,
+// since `since`. Three full pages fail closed.
+function pushRuns(gh, repo, { files, since, pages = 3 }) {
+  const created = encodeURIComponent(`>=${since.toISOString().slice(0, 10)}`);
+  const runs = [];
+  for (const path of files) {
+    const file = path.split('/').pop();
+    for (let page = 1; ; page += 1) {
+      if (page > pages) throw new BrakeError(`more than ${pages * 100} push runs of ${path} in the brake window; the read stops here.`);
+      const got = gh('GET', `repos/${repo}/actions/workflows/${encodeURIComponent(file)}/runs?event=push&status=completed&created=${created}&per_page=100&page=${page}`)?.workflow_runs ?? [];
+      runs.push(...got.filter((run) => run.path === path || String(run.path ?? '').startsWith(`${path}@`)).map((run) => ({ ...run, path })));
+      if (got.length < 100) break;
+    }
+  }
+  return runs;
+}
+
 // `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, answer }, line, gh = ghApi) {
@@ -427,12 +445,53 @@ export function redMain({ root, base }, gh, repo, depth = 30) {
   return found;
 }
 
+// The base workflow files that define a job of one of `names`, read from git.
+function definedAt(git, sha, names) {
+  const files = new Set();
+  if (!names.length) return files;
+  const listing = (() => { try { return git(['ls-tree', '-r', '--name-only', sha, '--', '.github/workflows/']); } catch { return ''; } })();
+  for (const path of listing.split('\n').filter((each) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(each))) {
+    let text = '';
+    try { text = git(['show', `${sha}:${path}`]); } catch { continue; }
+    if ((jobNames(text) ?? []).some((name) => names.includes(name))) files.add(path);
+  }
+  return files;
+}
+
+// The brake trips that only GitHub knows (roadmap R13 lines 2 and 3): a
+// required check that failed twice on a commit of main, and a failed live
+// check. The gate job reads them with its read-only token. It reads the push
+// runs of the base files that define those jobs, in the brake window. A base
+// with no such file makes no call.
+export function brakeRead({ root, base, now = new Date() }, gh, repo, pages = 3) {
+  const git = (args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  const sha = git(['rev-parse', '--verify', '--end-of-options', `${base}^{commit}`]);
+  let text = '';
+  try { text = git(['show', `${sha}:atlas.yaml`]); } catch { return []; }
+  const facts = brakeFacts(text);
+  const checks = facts.checks.filter((name) => name !== GATE_CHECK);
+  const liveChecks = facts.live === 'deploy' ? facts.liveChecks : [];
+  const homes = definedAt(git, sha, checks);
+  const files = new Set([...homes, ...definedAt(git, sha, liveChecks)]);
+  if (!files.size) return [];
+  const since = new Date(now.getTime() - facts.days * 864e5);
+  const commits = windowCommits(root, sha, since);
+  if (!commits.length) return [];
+  const runs = pushRuns(gh, repo, { files, since, pages });
+  const jobsOf = (id, attempt) => {
+    const jobs = gh('GET', `repos/${repo}/actions/runs/${id}/attempts/${attempt}/jobs?per_page=100`)?.jobs ?? [];
+    if (jobs.length >= 100) throw new BrakeError(`run ${id} has 100 jobs or more; the read stops here.`);
+    return jobs;
+  };
+  return ciTrips({ commits, runs, homes, checks, live: facts.live, liveChecks }, jobsOf);
+}
+
 // `atlas gate apply|ready|audit|check|replay`. Returns the exit code.
 export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, head, body, json = false, summary, output, days, branch, home = homedir() }, line, gh = ghApi) {
   if (!['apply', 'ready', 'audit', 'check', 'replay'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit, check or replay.`);
   // With --repo, check reads the red main checks from GitHub; without, it judges git data alone.
   const named = repo && repo !== true && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
-  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line, named ? () => redMain({ root, base }, gh, repo) : null);
+  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo) } }) : null);
   if (what === 'replay') return replayCommand({ root, days, branch, json }, line);
   if (!named) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
   if (what === 'ready') {

package/door/lib/upkeep.mjs

@@ -16,8 +16,7 @@
 // 4. Doc sources (roadmap R39, lib/doc-sources.mjs). Each doc and each
 //    procedure names its code, or why it names none, and each named path
 //    exists. With --event, each doc whose code the pull request changes is
-//    updated in it, or marked "still true" in its text. Until the replay of
-//    R39 line 3 is read, that last rule only reports (TOUCHED_DOCS_GATE).
+//    updated in it, or marked "still true" in its text (TOUCHED_DOCS_GATE).
 //
 // It reads the tree and the event file, and writes nothing.
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
@@ -25,9 +24,11 @@ import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
 
-// R39 line 4 gates only after the replay of line 3. False: a touched doc with
-// no update and no mark is a note, not a finding.
-export const TOUCHED_DOCS_GATE = false;
+// R39 line 4 gates only after the replay of line 3. The replay of the last 30
+// merges (atlas#225): rule "file" pulled in 81 docs over 24 merges, 58 not
+// updated; rule "line" pulled in none. So rule "file" gates. False makes a
+// touched doc with no update and no mark a note, not a finding.
+export const TOUCHED_DOCS_GATE = true;
 
 const INDEX = 'docs/index.md';
 const SKIP_DIRS = new Set(['node_modules', 'archive', 'fixtures']);

package/package.json

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