@arjunkhera/atlas 0.4.9 → 0.4.11

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -155,6 +155,10 @@ const HELP = `atlas — the door into a repo's Atlas files
       --body <file>                    the pull request text, for the "behaviour change: no" of a refactor
       --json                           print the answer as JSON
       --summary <file> --output <file> append the text to a job summary, and result= and class= to an output file
+  atlas gate replay [--days 30]        the static rules of the gate over the first-parent commits of the main branch; the owner share. Writes nothing
+      --root <repo>                    the clone to read (default: this folder)
+      --branch <name>                  the branch; default origin/HEAD
+      --json                           print the answer as JSON
 
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
@@ -196,7 +200,7 @@ export const FLAGS = Object.freeze({
   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', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -437,7 +441,7 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output }, line);
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch }, line);
 }
 
 function judgeVerb(chosen) {

package/door/lib/fails-before.mjs

@@ -268,7 +268,7 @@ export const commandOf = (runner, file, report) => (runner === 'node'
 // A fresh tree of `sha` at `tree`, from git archive: no .git of the repo, so a test cannot read which
 // commit it is. gitTree then gives it a .git of its own.
 export function freshTree(top, tree, sha) {
-  rmSync(tree, { recursive: true, force: true });
+  rmSync(tree, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
   mkdirSync(tree, { recursive: true });
   const archive = spawnSync('git', ['archive', '--format=tar', sha], { cwd: top, maxBuffer: 1024 * 1024 * 1024 });
   if (archive.status !== 0) throw new Error(`git archive failed: ${String(archive.stderr).trim()}`);
@@ -328,7 +328,9 @@ export function runSide({ top, changed, plans, side, work = join(tmpdir(), 'atla
       out.files[p.path] = { command, cases, why };
     }
   } finally {
-    rmSync(tree, { recursive: true, force: true });
+    // A process that a test left behind can still write in the tree for a
+    // moment; Node then retries the remove (atlas#209: ENOTEMPTY in CI).
+    rmSync(tree, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
   }
   return out;
 }
@@ -343,7 +345,7 @@ export function combine(prepared, oldRun, newRun) {
   const answer = { fails_before: VERSION, base: changed.base, merge_base: changed.merge_base, head: changed.head, product_changed: productChanged, red: false, proven_count: 0, files: files.map((f) => ({ ...f })), cases: [], env: null, runs: null };
   if (!productChanged || !plans.length) {
     for (const p of plans) for (const c of p.picked) answer.cases.push({ path: p.path, name: c.name, change: c.change, before: null, after: null, result: c.duplicate ? 'duplicate' : 'not proven' });
-    return finish(answer);
+    return finish(answer, nothingProven(prepared, answer));
   }
   if (oldRun?.side !== 'old' || newRun?.side !== 'new') throw new Error('give one run file of the side old and one of the side new');
   for (const run of [oldRun, newRun]) {
@@ -373,7 +375,18 @@ export function combine(prepared, oldRun, newRun) {
       answer.cases.push({ path: p.path, name: c.name, change: c.change, before, after, result: c.duplicate ? 'duplicate' : resultOf(before, after) });
     }
   }
-  return finish(answer);
+  return finish(answer, nothingProven(prepared, answer));
+}
+
+// Roadmap R6 done line 6: product code changed, the pull request changed a
+// unit test file that runs here, and yet no case runs, such as a change of
+// spaces in a case. The gate counts that file as a test change, so this check
+// says red. A pull request whose only test change is a scenario file, or a
+// file with no runner here, gets its proof elsewhere: the planted-fault
+// procedure.
+function nothingProven({ changed, productChanged }, answer) {
+  if (!productChanged || answer.cases.length) return false;
+  return changed.rows.some((r) => r.group === 'unit-test' && r.status !== 'removed' && runnerOf(r.path));
 }
 
 // Both runs, one after the other, then the answer. For a local run.
@@ -385,9 +398,10 @@ export function failsBefore({ root, base, head = 'HEAD', list = null, work = joi
   return combine(prepared, oldRun, newRun);
 }
 
-function finish(answer) {
+function finish(answer, nothing = false) {
   answer.cases.sort((x, y) => (x.path === y.path ? String(x.name).localeCompare(String(y.name)) : x.path < y.path ? -1 : 1));
-  answer.red = answer.cases.some((c) => RED_RESULTS.includes(c.result));
+  answer.nothing_proven = nothing;
+  answer.red = nothing || answer.cases.some((c) => RED_RESULTS.includes(c.result));
   answer.proven_count = answer.cases.filter((c) => c.result === 'proven').length;
   return answer;
 }
@@ -403,6 +417,7 @@ export function renderText(a) {
   for (const f of a.files.filter((x) => x.result === 'ran' && x.why)) out.push(`  note           ${oneLine(f.path)}  ${oneLine(f.why)}`);
   const red = a.cases.filter((c) => RED_RESULTS.includes(c.result));
   if (red.length) out.push(`RED: ${red.length} case(s): ${[...new Set(red.map((c) => c.result))].join(', ')}. A case that passes on the old code cannot catch this change.`);
+  else if (a.nothing_proven) out.push('RED: nothing proven. Product code changed and a test file changed, but no new or changed case runs. Add or change a test case.');
   else if (!a.product_changed) out.push('GREEN: no product code changed, so the new cases are not proven.');
   else if (a.product_changed && !a.cases.length) out.push('GREEN: product code changed, and no new or changed case runs. Nothing is proven.');
   else out.push(`GREEN: no red case. Green does not mean proven: ${a.proven_count} proven, ${a.cases.length - a.proven_count} not proven.`);

package/door/lib/gate-check.mjs

@@ -185,9 +185,9 @@ 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 }) {
+function testRows({ root, mergeBase, head, body, redMain, rules }) {
   const list = listChanged({ root, base: mergeBase, head });
-  const product = list.other_paths.filter(productTest(root, mergeBase));
+  const product = list.other_paths.filter(productTest(root, rules ?? mergeBase));
   if (!product.length) return [];
   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` }];
@@ -216,7 +216,7 @@ function testRows({ root, mergeBase, head, body, redMain }) {
 // 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 = [] }) {
+export function judge({ root, base, head, body = '', redMain = [], rules = null }) {
   const top = resolve(root);
   const baseSha = commitOf(top, base);
   if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
@@ -233,10 +233,10 @@ export function judge({ root, base, head, body = '', redMain = [] }) {
   }
   answer.merge_base = mergeBase;
   const changes = changedPaths(top, mergeBase, headSha);
-  for (const row of classify({ root: top, base: mergeBase, head: headSha }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
-  answer.rows.push(...jobRows(top, mergeBase, headSha, changes));
+  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 }));
+  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules }));
   return finish(answer);
 }
 
@@ -292,3 +292,82 @@ export function checkCommand({ root, base, head, body: bodyFile, json = false, s
     return error.usage ? 2 : 1;
   }
 }
+
+// ------------------------------------------------------------------ the replay
+
+// `atlas gate replay`: the static rules over the first-parent commits of a
+// branch in the last `days` days (done line 13). It writes nothing. The test
+// checks cannot be replayed, so it also counts the commits that changed an
+// old test: passes-after could add those to the owner share.
+export function replay({ root, days = 30, branch = null, now = new Date() }) {
+  const top = resolve(root);
+  const ref = branch ?? ([(git(top, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { allowFail: true }) ?? '').trim(), 'origin/main', 'origin/master'].find((name) => name && commitOf(top, name)) || 'HEAD');
+  if (!commitOf(top, ref)) throw new GateCheckError(`there is no branch "${ref}" in this clone.`);
+  const tip = commitOf(top, ref);
+  const since = new Date(now.getTime() - days * 864e5).toISOString();
+  const shas = (git(top, ['log', '--first-parent', `--since=${since}`, '--format=%H %P', ref]) ?? '').split('\n').filter(Boolean);
+  const facts = parseYaml(textAt(top, ref, 'atlas.yaml') ?? '') ?? {};
+  const rows = [];
+  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 list = listChanged({ root: top, base: parent, head: sha });
+    const oldTest = list.rows.some((row) => CASE_GROUPS.has(row.group) && row.status !== 'added');
+    rows.push({
+      sha, result: answer.result,
+      owner: answer.rows.some((row) => row.kind === 'owner'),
+      red: answer.rows.some((row) => row.kind === 'red'),
+      old_test: oldTest,
+      causes: [...new Set(answer.rows.filter((row) => row.kind !== 'note').map((row) => `${row.kind}: ${row.class}: ${causeKey(row)}`))],
+    });
+  }
+  const count = (test) => rows.filter(test).length;
+  const share = (n) => (rows.length ? Math.round((n / rows.length) * 100) : 0);
+  const causes = new Map();
+  for (const row of rows) for (const cause of row.causes) causes.set(cause, (causes.get(cause) ?? 0) + 1);
+  return {
+    gate_replay: VERSION, branch: ref, since, commits: rows.length,
+    meaningful: Array.isArray(facts.product_paths),
+    owner: count((row) => row.owner), red: count((row) => row.red), success: count((row) => row.result === 'success'),
+    owner_share: share(count((row) => row.owner)),
+    old_test_share: share(count((row) => row.old_test)),
+    old_test_only_share: share(count((row) => row.old_test && !row.owner)),
+    causes: [...causes].sort((a, b) => b[1] - a[1]).map(([cause, n]) => ({ cause, commits: n })),
+    rows,
+  };
+}
+
+// One cause for the count: a list or floor rule keeps its rule, and a path
+// cause keeps its folder, so one rule counts once over many files.
+function causeKey(row) {
+  if (/^(list|floor|sign): /.test(row.cause)) return row.cause.replace(/ \(.*\)$/, '');
+  if (row.class === 'secret') return row.cause;
+  if (row.class === 'unlisted') return 'outside product_paths';
+  return row.cause.replace(/: .*$/, '').replace(/ src\/\S+| \S+\/\S+/g, '');
+}
+
+export function renderReplay(answer) {
+  const out = [`gate replay: ${answer.commits} first-parent commit(s) of ${answer.branch} since ${answer.since.slice(0, 10)}, by the list at ${answer.branch}`];
+  if (!answer.meaningful) out.push('  NOT MEANINGFUL: atlas.yaml lists no product_paths, so every path comes to the owner.');
+  out.push(`  owner share (path and sign rules): ${answer.owner_share}% (${answer.owner} of ${answer.commits})`);
+  out.push(`  changed an old test, where passes-after decides: ${answer.old_test_share}%; of those, not owner by path: ${answer.old_test_only_share}%`);
+  out.push(`  red: ${answer.red}, success: ${answer.success}`);
+  out.push('  causes, by commits:');
+  for (const each of answer.causes.slice(0, 12)) out.push(`    ${String(each.commits).padStart(4)}  ${oneLine(each.cause)}`);
+  return out;
+}
+
+export function replayCommand({ root, days, branch, json = false }, line) {
+  try {
+    const n = days === undefined || days === true ? 30 : Number(days);
+    if (!Number.isInteger(n) || n < 1 || n > 365) throw Object.assign(new GateCheckError('--days must be a whole number from 1 to 365.'), { usage: true });
+    const answer = replay({ root, days: n, branch: branch && branch !== true ? branch : null });
+    if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+    else for (const each of renderReplay(answer)) line(each);
+    return 0;
+  } catch (error) {
+    line(`gate replay: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/gate.mjs

@@ -20,7 +20,7 @@ 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';
-import { checkCommand } from './gate-check.mjs';
+import { checkCommand, replayCommand, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
 export const TAG_RULESET = 'atlas release tags';
@@ -195,6 +195,85 @@ function checksAt(gh, repo, ref) {
 const checkRuns = (gh, repo, sha) => gh('GET', `repos/${repo}/commits/${sha}/check-runs?per_page=100`)?.check_runs ?? [];
 const checkLine = (row) => `  ${row.state === 'green' ? '✓' : '✗'} ${row.state.padEnd(8)} ${row.name}${row.conclusion && row.state === 'red' ? ` (${row.conclusion})` : ''}`;
 
+// The base files that define each required check (roadmap R6 done line 8).
+// A check counts only from a workflow run of one of its files, as the base
+// branch holds them. The gate always comes from its own file.
+function homesAt(gh, repo, ref, checks) {
+  const homes = new Map(checks.map((name) => [name, new Set()]));
+  const listing = gh('GET', `repos/${repo}/contents/.github/workflows?ref=${encodeURIComponent(ref)}`);
+  for (const entry of Array.isArray(listing) ? listing : []) {
+    if (entry?.type !== 'file' || !/\.ya?ml$/.test(entry.name ?? '')) continue;
+    const file = gh('GET', `repos/${repo}/contents/${entry.path}?ref=${encodeURIComponent(ref)}`);
+    if (typeof file?.content !== 'string') continue;
+    for (const name of jobNames(Buffer.from(file.content, 'base64').toString('utf8')) ?? []) if (homes.has(name)) homes.get(name).add(entry.path);
+  }
+  if (homes.has(GATE_CHECK)) homes.set(GATE_CHECK, new Set([GATE_WORKFLOW]));
+  return homes;
+}
+
+// The title that the gate workflow gives each run (its `run-name`). The base
+// file sets it, so a pull request cannot write it.
+export const gateRunTitle = (pr, sha) => `gate #${pr} at ${sha}`;
+
+// Why one workflow run cannot carry a required check of this pull request,
+// or null when it can. The run must come from a base file that defines the
+// check, from a pull request event, on this head, for this pull request into
+// its base branch.
+export function refusal(run, { name, pr, sha, baseRef, homes }) {
+  if (!run) return 'no workflow run';
+  if (!homes.get(name)?.has(run.path)) return `from ${run.path ?? 'no file'}, not a base file that defines the check`;
+  if (run.event !== 'pull_request') return `from the event ${run.event}`;
+  if (run.head_sha !== sha) return 'of another head commit';
+  const pulls = run.pull_requests ?? [];
+  if (!pulls.some((each) => Number(each.number) === Number(pr) && each.base?.ref === baseRef)) return `not of #${pr} into ${baseRef}`;
+  // GitHub lists every open pull request with this head, so a run made for a
+  // pull request into a side branch can also name this one. Such a run used
+  // the side branch's file, so it does not count.
+  if (pulls.some((each) => each.base?.ref !== baseRef)) return `also of a pull request into ${pulls.find((each) => each.base?.ref !== baseRef).base?.ref ?? 'another branch'}`;
+  return null;
+}
+
+// The same for a run of the gate. It runs on pull_request_target, so it sits
+// on a commit of the base branch, not on the head. Its title names the pull
+// request and the head; the run must come from the base branch and its file.
+export function gateRefusal(run, { pr, sha, baseRef, onBase }) {
+  if (run.path !== GATE_WORKFLOW) return `from ${run.path ?? 'no file'}, not ${GATE_WORKFLOW}`;
+  if (run.event !== 'pull_request_target') return `from the event ${run.event}`;
+  if (run.display_title !== gateRunTitle(pr, sha)) return 'of another pull request or head';
+  if (run.head_branch !== baseRef) return `from the branch ${run.head_branch}, not ${baseRef}`;
+  if (!onBase(run.head_sha)) return `from a commit that is not on ${baseRef}`;
+  return null;
+}
+
+// The check runs that may count for this pull request, and the ones refused.
+function pinnedRuns(gh, repo, { pr, sha, baseRef, checks }) {
+  const homes = homesAt(gh, repo, baseRef, checks);
+  const suites = new Map();
+  const runOf = (id) => {
+    if (!suites.has(id)) suites.set(id, id ? (gh('GET', `repos/${repo}/actions/runs?check_suite_id=${id}`)?.workflow_runs ?? [])[0] ?? null : null);
+    return suites.get(id);
+  };
+  const kept = [];
+  const refused = [];
+  for (const check of checkRuns(gh, repo, sha)) {
+    if (!checks.includes(check.name) || check.name === GATE_CHECK || check.app?.id !== ACTIONS_APP_ID) continue;
+    const why = refusal(runOf(check.check_suite?.id), { name: check.name, pr, sha, baseRef, homes });
+    if (why) refused.push({ name: check.name, why }); else kept.push(check);
+  }
+  if (checks.includes(GATE_CHECK)) {
+    const onBase = (commit) => ['ahead', 'identical'].includes(gh('GET', `repos/${repo}/compare/${commit}...${encodeURIComponent(baseRef)}`)?.status);
+    const runs = gh('GET', `repos/${repo}/actions/workflows/${GATE_WORKFLOW.split('/').pop()}/runs?event=pull_request_target&per_page=100`)?.workflow_runs ?? [];
+    for (const run of runs.filter((each) => each.display_title === gateRunTitle(pr, sha))) {
+      const why = gateRefusal(run, { pr, sha, baseRef, onBase });
+      if (why) { refused.push({ name: GATE_CHECK, why }); continue; }
+      for (const job of gh('GET', `repos/${repo}/actions/runs/${run.id}/jobs`)?.jobs ?? []) {
+        if (job.name === GATE_CHECK) kept.push({ ...job, app: { id: ACTIONS_APP_ID } });
+      }
+    }
+  }
+  return { kept, refused };
+}
+
 // `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) {
@@ -204,9 +283,12 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   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);
-  const rows = checkStates(checks, checkRuns(gh, repo, sha));
+  const { kept, refused } = pinnedRuns(gh, repo, { pr, sha, baseRef: pull.base.ref, checks });
+  const rows = checkStates(checks, kept);
   line(`atlas gate ready: #${pr} at ${sha.slice(0, 7)}, ${checks.length} required check(s) from atlas.yaml on ${pull.base.ref}.`);
   for (const row of rows) line(checkLine(row));
+  // A refused run names its check and the pin it broke, never a text of the run.
+  for (const one of refused) line(`  - ignored  a run of ${one.name}: ${one.why}`);
   // Checks that ran on an old base prove nothing about the merge: two pull
   // requests, each green alone, can turn the main branch red together (atlas#188).
   const behind = Number(gh('GET', `repos/${repo}/compare/${encodeURIComponent(pull.base.ref)}...${sha}`)?.behind_by ?? NaN);
@@ -303,11 +385,37 @@ function commitAudit({ repo, commit }, line, gh) {
   return 0;
 }
 
-// `atlas gate apply|ready|audit|check`. 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, home = homedir() }, line, gh = ghApi) {
-  if (!['apply', 'ready', 'audit', 'check'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit or check.`);
-  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line);
-  if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
+// The required checks that are red on the base commit, each with the newest
+// first-parent commit before it where that check was green (done line 7). The
+// gate job reads them with its read-only token. It walks back at most
+// `depth` commits; a check with no green commit in reach is left out.
+export function redMain({ root, base }, gh, repo, depth = 30) {
+  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 checks;
+  try { checks = factsOf(git(['show', `${sha}:atlas.yaml`])).checks.filter((name) => name !== GATE_CHECK); } catch { return []; }
+  const red = checkStates(checks, checkRuns(gh, repo, sha)).filter((row) => row.state === 'red').map((row) => row.name);
+  if (!red.length) return [];
+  const older = git(['rev-list', '--first-parent', `--max-count=${depth}`, `${sha}^`]).split('\n').filter(Boolean);
+  const found = [];
+  let left = red;
+  for (const commit of older) {
+    if (!left.length) break;
+    const states = checkStates(left, checkRuns(gh, repo, commit));
+    for (const row of states.filter((each) => each.state === 'green')) found.push({ check: row.name, green: commit });
+    left = left.filter((name) => !found.some((each) => each.check === name));
+  }
+  return found;
+}
+
+// `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 === 'replay') return replayCommand({ root, days, branch, json }, line);
+  if (!named) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
   if (what === 'ready') {
     const answer = {};
     let code = 1;

package/door/lib/owner-only.mjs

@@ -496,8 +496,11 @@ const newest = (paths) => paths.reduce((best, path) => (best === null || newer(p
 
 // ------------------------------------------------------------------ classify
 
-export function classify({ root, base, head, classes = loadClasses() }) {
-  const { rules, product, tree: baseTree } = rulesAt({ root, ref: base, classes });
+// `rules` names the commit whose list holds; the default is the base. The
+// gate replay passes today's main branch, to ask what today's list would do.
+export function classify({ root, base, head, rules: rulesRef = null, classes = loadClasses() }) {
+  const { rules, product, tree } = rulesAt({ root, ref: rulesRef ?? base, classes });
+  const baseTree = rulesRef ? treeAt(root, base) : tree;
   const headTree = treeAt(root, head);
   const changes = changedPaths(root, base, head);
   const rows = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "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

@@ -111,7 +111,7 @@ set. A test keeps the two lists equal.
 | `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 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, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `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 |
 
 A person merges every file that `atlas tooling` writes.