@arjunkhera/atlas 0.4.14 → 0.4.16

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -267,7 +267,8 @@ function toolingCommand(chosen) {
     if (what !== 'write') throw new Error(`there is no tooling verb "${what}". Use write or pr.`);
     const result = writeTooling(root, PACKAGE_ROOT, { dryRun: Boolean(chosen['dry-run']), replaceUnknown, workflowOnly });
     line(`Atlas ${result.version}, check version ${result.check_version}${result.status ? `; the copy was ${result.status}` : ''}`);
-    for (const row of result.rows) line(`  ${row.state.padEnd(10)} ${row.path}  sha256 ${row.sha256.slice(0, 12)}…`);
+    // A removed file has no bytes, so its row has no sha256 (roadmap R7).
+    for (const row of result.rows) line(`  ${row.state.padEnd(10)} ${row.path}${row.sha256 ? `  sha256 ${row.sha256.slice(0, 12)}…` : ''}`);
     line('');
     line(result.changed
       ? 'The files come from the package. No hand step, and no edit by hand afterwards.'

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/pull-request.mjs

@@ -11,9 +11,9 @@
 // git and GitHub calls sit below it, in one place.
 import { execFileSync } from 'node:child_process';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH } from '../../shape/check.mjs';
 
 // Every change names where it came from, and the set is closed.
 export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'task input']);
@@ -24,6 +24,9 @@ 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/workflows/atlas-jobs.yml', '.github/pull_request_template.md']);
+// The only files the tooling writer may remove: the workflow of check versions
+// 1 to 5, which the gate workflow replaces (roadmap R7).
+export const TOOLING_REMOVALS = Object.freeze([OLD_WORKFLOW_PATH]);
 
 export class ChangeError extends Error {}
 
@@ -38,8 +41,12 @@ export function checkChanges(changes) {
   for (const change of changes) {
     const path = posix.normalize(String(change?.path ?? '')).replace(/^\.\//, '');
     if (!path || path === '.') throw new ChangeError('a change has no path');
-    if (!TOOLING_PATHS.includes(path)) throw new ChangeError(`the tooling writer writes only ${TOOLING_PATHS.join(' and ')}; it refuses "${path}"`);
-    if (typeof change.contents !== 'string') throw new ChangeError(`the change to "${path}" carries no contents`);
+    if (change.remove === true) {
+      if (!TOOLING_REMOVALS.includes(path)) throw new ChangeError(`the tooling writer removes only ${TOOLING_REMOVALS.join(' and ')}; it refuses to remove "${path}"`);
+    } else {
+      if (!TOOLING_PATHS.includes(path)) throw new ChangeError(`the tooling writer writes only ${TOOLING_PATHS.join(' and ')}; it refuses "${path}"`);
+      if (typeof change.contents !== 'string') throw new ChangeError(`the change to "${path}" carries no contents`);
+    }
     const source = change?.provenance?.source;
     if (!PROVENANCE_SOURCES.includes(source)) throw new ChangeError(`the change to "${path}" names no source; every change names one of ${PROVENANCE_SOURCES.join(', ')}`);
     if (!String(change?.provenance?.detail ?? '').trim()) throw new ChangeError(`the change to "${path}" names the source "${source}" and says nothing about it`);
@@ -82,8 +89,11 @@ export function applyChanges(root, changes) {
   const written = [];
   for (const change of changes) {
     const path = join(root, change.path);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, change.contents);
+    if (change.remove === true) rmSync(path, { force: true });
+    else {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, change.contents);
+    }
     written.push(change.path);
   }
   return { written };
@@ -105,7 +115,8 @@ export function open({ root, changes, why, branch, title, base = null, label = T
   if (dryRun) return { repo, branch, title, body, base: onto, written, opened: false };
 
   exec('git', ['checkout', '-b', branch], root);
-  exec('git', ['add', '--', ...written], root);
+  // `git add -A` stages a removed file as well as a written one.
+  exec('git', ['add', '-A', '--', ...written], root);
   exec('git', ['commit', '-m', title, '-m', body], root);
   exec('git', ['push', '-u', 'origin', branch], root);
   // A label that does not exist yet makes `gh pr create` fail, so it is made

package/door/lib/status.mjs

@@ -15,7 +15,7 @@
 // package's list. This runs in a session, with the package on disk.
 import { readFileSync, existsSync, readdirSync, lstatSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, checkStamps, sha256 } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, checkStamps, sha256 } from '../../shape/check.mjs';
 import { packagedCheck, placeOf, packagePackageVersion } from './releases.mjs';
 import { currentKitHash, KIT_RELEASES_FILE, KIT_TARGET, MANIFEST } from './tests.mjs';
 import { kitHashOf } from '../../tests/link-check.mjs';
@@ -57,8 +57,9 @@ export function statusMany(roots, packageRoot) {
 // R19, slice 0 of the routines design). The check is one copy of four types:
 //
 //   check     .github/atlas/check.mjs, by the release list of the check
-//   workflow  .github/workflows/atlas-check.yml, by the workflow fingerprint
-//             in each row of that list
+//   workflow  .github/workflows/atlas-gate.yml, by the workflow fingerprint
+//             in each row of that list, or by its shape job; before check
+//             version 6, .github/workflows/atlas-check.yml
 //   kit       each <area>/test/atlas/, by its manifest and the kit list
 //   pin       an Atlas version written in a workflow, a script or package.json
 //
@@ -92,23 +93,37 @@ function checkRow(root, packageRoot) {
 
 // The workflow is written with the check, from the WORKFLOW_TEMPLATE of that
 // check. Each row of the release list keeps the fingerprint of its template.
+// From check version 6 the workflow is the gate workflow, and a repo may add
+// its own jobs to it, as the Atlas repo does: then its shape job must be the
+// one the package writes. A repo that still has only the old atlas-check.yml
+// is behind (roadmap R7 line 5).
 function workflowRow(root, packageRoot) {
   const pkg = packagedCheck(packageRoot);
   const version = checkStamps(pkg.text).check_version;
   const want = `workflow of check version ${version}`;
   const full = join(root, WORKFLOW_PATH);
   if (linkAt(full)) return linked('workflow', WORKFLOW_PATH, want);
-  if (!existsSync(full)) return row('workflow', WORKFLOW_PATH, 'missing', null, want, `${WORKFLOW_PATH} does not exist in this repo, so its check never runs in CI. "atlas tooling pr" adds it.`);
+  const known = (text) => pkg.releases.filter((one) => one.workflow_sha256 === sha256(text));
+  if (!existsSync(full)) {
+    const old = join(root, OLD_WORKFLOW_PATH);
+    if (linkAt(old)) return linked('workflow', OLD_WORKFLOW_PATH, want);
+    if (!existsSync(old)) return row('workflow', WORKFLOW_PATH, 'missing', null, want, `${WORKFLOW_PATH} does not exist in this repo, so its check never runs in CI. "atlas tooling pr" adds it.`);
+    let text;
+    try { text = readFileSync(old, 'utf8'); } catch (error) { return broken('workflow', OLD_WORKFLOW_PATH, want, error); }
+    const rows = known(text);
+    if (rows.length) return row('workflow', OLD_WORKFLOW_PATH, 'behind', `workflow of check version ${rows.at(-1).check_version}`, want, `${OLD_WORKFLOW_PATH} runs the head's copy of the check, so a pull request can change its own judge. "atlas tooling pr" writes ${WORKFLOW_PATH} and removes it.`);
+    return row('workflow', OLD_WORKFLOW_PATH, 'unknown', `sha256 ${sha256(text).slice(0, 12)}…`, want, `${OLD_WORKFLOW_PATH} is in no release, and ${WORKFLOW_PATH} does not exist. "atlas tooling pr" shows the difference.`);
+  }
   let text;
   try { text = readFileSync(full, 'utf8'); } catch (error) { return broken('workflow', WORKFLOW_PATH, want, error); }
-  const fingerprint = sha256(text);
-  if (fingerprint === sha256(WORKFLOW_TEMPLATE)) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'the workflow is the one this package writes.');
-  const rows = pkg.releases.filter((one) => one.workflow_sha256 === fingerprint);
+  if (text === WORKFLOW_TEMPLATE) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'the workflow is the one this package writes.');
+  if (shapeJobOf(text) === SHAPE_JOB_TEXT) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'its shape job is the one this package writes; the file holds other jobs of this repo too.');
+  const rows = known(text);
   if (rows.length) {
     const newest = rows.at(-1);
-    return row('workflow', WORKFLOW_PATH, 'behind', `workflow of check version ${newest.check_version}`, want, `the workflow was first written by Atlas ${rows[0].first_package}. "atlas tooling pr --workflow" refreshes it.`);
+    return row('workflow', WORKFLOW_PATH, 'behind', `workflow of check version ${newest.check_version}`, want, `the workflow was first written by Atlas ${rows[0].first_package ?? `check version ${rows[0].check_version}`}. "atlas tooling pr --workflow" refreshes it.`);
   }
-  return row('workflow', WORKFLOW_PATH, 'unknown', `sha256 ${fingerprint.slice(0, 12)}…`, want, `the workflow is in no release. Someone edited it, or it came from an unreleased package. "atlas tooling pr" shows the difference.`);
+  return row('workflow', WORKFLOW_PATH, 'unknown', `sha256 ${sha256(text).slice(0, 12)}…`, want, `the workflow is in no release, and its shape job is not the one this package writes. Someone edited it, or it came from an unreleased package. "atlas tooling pr" shows the difference.`);
 }
 
 // A walk never follows a link and never enters node_modules or .git. The

package/door/lib/tooling.mjs

@@ -14,15 +14,27 @@
 // is missing or behind, or unknown with --replace-unknown, and only a check
 // that is the newest row of the release list. The Atlas repo itself may take
 // its own unreleased check, because that is how a new check is made.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
 import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
 import { status } from './status.mjs';
 import { PR_TEMPLATE_PATH } from './upkeep.mjs';
 
-export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+export { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+
+// The gate workflow (roadmap R7 line 5). A repo may keep its own jobs in it, as
+// the Atlas repo does. When its shape job is the one the package writes, the
+// writer keeps the file. The workflow of check versions 1 to 5,
+// atlas-check.yml, ran the head's copy of the check; the writer removes it.
+const workflowKept = (root) => {
+  const full = join(root, WORKFLOW_PATH);
+  if (!existsSync(full)) return false;
+  const text = readFileSync(full, 'utf8');
+  return text !== WORKFLOW_TEMPLATE && shapeJobOf(text) === SHAPE_JOB_TEXT;
+};
+const oldWorkflow = (root) => existsSync(join(root, OLD_WORKFLOW_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
@@ -101,8 +113,8 @@ 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) && !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 === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
+    throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE || workflowKept(root) ? '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) {
     throw new ToolingRefusal(`${now.why}`);
@@ -120,6 +132,7 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
   for (const [path, contents] of Object.entries(wanted)) {
     const full = join(root, path);
     const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
+    if (path === WORKFLOW_PATH && workflowKept(root)) { rows.push({ path, state: 'kept', sha256: sha256(was), was: sha256(was) }); continue; }
     const state = was === null ? 'written' : was === contents ? 'unchanged' : 'refreshed';
     if (state !== 'unchanged' && !dryRun) {
       mkdirSync(dirname(full), { recursive: true });
@@ -127,6 +140,11 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
+  if (oldWorkflow(root)) {
+    const was = readFileSync(join(root, OLD_WORKFLOW_PATH), 'utf8');
+    if (!dryRun) rmSync(join(root, OLD_WORKFLOW_PATH));
+    rows.push({ path: OLD_WORKFLOW_PATH, state: 'removed', sha256: null, was: sha256(was) });
+  }
   const jobs = workflowOnly ? null : jobsState(root, packageRoot);
   if (jobs !== null) {
     const contents = packagedJobsWorkflow(packageRoot);
@@ -165,7 +183,11 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   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) => ({
+    .map((row) => (row.state === 'removed' ? {
+      path: row.path,
+      remove: true,
+      provenance: { source: 'repo read', detail: `the workflow of check versions 1 to 5, which runs the head's copy of the check; ${WORKFLOW_PATH} replaces it from check version ${CHECK_VERSION}` },
+    } : {
       path: row.path,
       contents: wanted[row.path],
       provenance: {

package/package.json

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