@arjunkhera/atlas 0.4.22 → 0.4.24

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -153,7 +153,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       On a GitHub plan with no rulesets, apply changes nothing and reports advisory mode.
   atlas gate ready --repo <owner/name> --pr <n>   may this pull request merge: every required check green on its head
   atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
-  atlas gate audit --repo <owner/name> --commit <sha>   one commit on the main branch: red when no pull request merged it, or one merged it before its checks were green
+  atlas gate audit --repo <owner/name> --commit <sha> [--forced] [--findings <file>]   one commit on the main branch: red when no pull request merged it, one merged it before its checks were green, or a gate run is not from the base workflow
+  atlas gate audit --repo <owner/name> --errors [--findings <file>]   red when the gate errored on 3 pull requests in a row
   atlas gate check --base <ref> --head <sha>   the gate: judge a pull request with this copy of Atlas; success, owner or red
       --pr <n> --base-ref <branch>     with --repo: read the comments of the pull request, and let the owner's signed act for this base and head clear owner
       --root <repo>                    the clone that holds both commits (default: this folder); the head is read as git data only
@@ -216,7 +217,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', last: 'value', base: 'value' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
   approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: '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' },
@@ -466,7 +467,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, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch }, 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, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch, errors: Boolean(chosen.errors), forced: Boolean(chosen.forced), findings: chosen.findings }, line);
 }
 
 function approveVerb(chosen) {

package/door/jobs/gate-audit.yaml

@@ -0,0 +1,16 @@
+# An Atlas job of the audit (roadmap R14). The watcher runs it from the npm
+# copy of Atlas, over the first-parent commits of the main branch in the last
+# two days. The push audit (`.github/workflows/atlas-gate-audit.yml`) files
+# the same findings, with the same keys, so one break opens one issue.
+#
+# kind is one of: push (no pull request merged it), force-push,
+# merge-before-green, gate-copy (a gate run not from the base workflow file).
+# A closed issue does not stop a new one while its commit is in the window:
+# anyone with the shared login can close or hand over an issue.
+title: Each commit on the main branch came through the gate
+when: gate-audit
+needs: [gate]
+act: atlas:gate-audit
+may: owner
+handed_over: ignored
+fields: [kind, sha, pr, run_id, pin, checks]

package/door/jobs/gate-errors.yaml

@@ -0,0 +1,11 @@
+# An Atlas job of the audit (roadmap R14). The watcher reads the newest gate
+# run of each pull request. When the gate ended with an error, not a result,
+# on three pull requests in a row, that is one finding. Its key is the oldest
+# run of the streak, so a fourth error opens no second issue.
+title: The gate gives a result
+when: gate-errors
+needs: [gate]
+act: atlas:gate-errors
+may: owner
+handed_over: ignored
+fields: [count, runs, prs]

package/door/jobs/gate-files.yaml

@@ -0,0 +1,13 @@
+# An Atlas job of the audit (roadmap R14). The watcher compares the gate
+# files, the audit files and the merge-door hook of the main branch with the
+# latest npm release. On a push, GitHub runs the pushed copy of a workflow,
+# so a push that edits the audit hides from its own run. This job runs from
+# the npm copy of Atlas, and finds it. It runs in the Atlas source repo only,
+# until `atlas tooling` writes the gate workflows into other repos.
+title: The gate files on the main branch are the released files
+when: gate-files
+needs: [gate]
+act: atlas:gate-files
+may: owner
+handed_over: ignored
+fields: [group, paths, count, release]

package/door/lib/gate-audit.mjs

@@ -0,0 +1,303 @@
+// The audit job (roadmap R14, design docs/design-docs/audit-job/). With no
+// GitHub Pro, GitHub stops no bad merge (decision dd90d8e8). So the audit
+// finds each break of the gate after it lands, and each finding becomes one
+// `atlas-job` issue through `atlas jobs file`.
+//
+//   1. The commit audit (gate.mjs) records a push past the gate, a force push,
+//      a merge before green, and a gate run that is not from the base copy of
+//      its workflow (done lines 1 and 2). This file holds the gate run check.
+//   2. `gateErrors`: three pull requests in a row whose newest gate run ended
+//      with no result (done line 5).
+//   3. `checkGateFiles`: the watcher job `gate-files`. It compares the gate
+//      files, the audit files and the merge-door hook with the latest npm
+//      release (done line 4). It runs from the npm copy of Atlas, so an edit of
+//      the audit workflow cannot hide from it.
+//
+// A finding holds typed fields only: SHAs, numbers, run ids, paths and short
+// codes. No text of a pull request or of a check run reaches an issue.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { dirname, join, resolve } from 'node:path';
+
+export const AUDIT_JOB = 'gate-audit';
+export const ERRORS_JOB = 'gate-errors';
+export const FILES_JOB = 'gate-files';
+export const GATE_STEP = 'Gate check';
+export const GATE_ERROR_TITLE = 'atlas gate error';
+export const ERROR_STREAK = 3;
+export const PACKAGE_NAME = '@arjunkhera/atlas';
+
+// A check name becomes a short code: letters, digits and hyphens only.
+export const slug = (name) => String(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'check';
+
+// The pin that a refused gate run broke, as a short code. The words come from
+// `refusal` in gate.mjs.
+export function pinCode(why) {
+  const text = String(why ?? '');
+  if (/^no workflow run/.test(text)) return 'no-run';
+  if (/not a base file/.test(text)) return 'file';
+  if (/^from the event/.test(text)) return 'event';
+  if (/^of another head commit/.test(text)) return 'head';
+  if (/^of another pull request or head/.test(text)) return 'title';
+  if (/^not of #/.test(text)) return 'pull';
+  if (/^also of a pull request|head branch also had/.test(text)) return 'side';
+  if (/no head branch/.test(text)) return 'no-branch';
+  return 'other';
+}
+
+// ------------------------------------------------------------ the findings file
+
+// The findings file is the envelope of `atlas jobs check`, so `atlas jobs file`
+// reads it as it reads the watcher's. Each audit call adds its findings. A call
+// that stopped with an error marks it broken, and the file job ends red.
+export function keepFindings(file, found = [], { broken = false } = {}) {
+  const path = resolve(file);
+  let envelope = { jobs: 1, state: 'none', ran: [], notes: [], findings: [] };
+  if (existsSync(path)) {
+    try {
+      const have = JSON.parse(readFileSync(path, 'utf8'));
+      if (have?.jobs === 1 && Array.isArray(have.findings)) envelope = { ...envelope, ...have };
+    } catch { envelope.state = 'broken'; }
+  }
+  const keys = new Set(envelope.findings.map((f) => `${f.job}:${f.key}`));
+  for (const f of found) if (!keys.has(`${f.job}:${f.key}`)) { keys.add(`${f.job}:${f.key}`); envelope.findings.push(f); }
+  if (broken || envelope.state === 'broken') envelope.state = 'broken';
+  else envelope.state = envelope.findings.length ? 'found' : 'none';
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(envelope, null, 2)}\n`);
+  return envelope;
+}
+
+// ------------------------------------------------------------ line 5: gate errors
+
+const TITLE = /^gate #(\d{1,9}) at ([0-9a-f]{40})$/;
+const SKIPPED = new Set(['cancelled', 'skipped', 'action_required', 'stale']);
+
+// Did one finished gate run end with a result (success, owner or red), or
+// with an error? An error is a run that timed out or never started, a failed
+// step before the check, or a check that stopped and wrote the error note.
+// A failed check with no note is a result: runs from before the note have
+// none, so they never read as errors.
+export function gateRunState(gh, repo, run) {
+  if (run.conclusion === 'success') return 'result';
+  if (run.conclusion === 'timed_out' || run.conclusion === 'startup_failure') return 'error';
+  if (run.conclusion !== 'failure') return 'result';
+  const job = (gh('GET', `repos/${repo}/actions/runs/${run.id}/jobs`)?.jobs ?? []).find((each) => each.name === 'gate');
+  if (!job) return 'error';
+  const failed = (job.steps ?? []).find((step) => step.conclusion === 'failure');
+  if (failed && failed.name !== GATE_STEP) return 'error';
+  const notes = gh('GET', `repos/${repo}/check-runs/${job.id}/annotations`) ?? [];
+  return (Array.isArray(notes) ? notes : []).some((note) => note?.title === GATE_ERROR_TITLE) ? 'error' : 'result';
+}
+
+// `atlas gate audit --errors`: the newest gate run of each pull request, newest
+// first. When the first `streak` of them all ended with an error, that is one
+// finding. Its key is the oldest run of the streak, so a fourth error keeps
+// the key and opens no second issue.
+export function gateErrors({ repo, found = [] }, line, gh, streak = ERROR_STREAK) {
+  const runs = gh('GET', `repos/${repo}/actions/workflows/atlas-gate.yml/runs?event=pull_request_target&status=completed&per_page=100`)?.workflow_runs ?? [];
+  const newest = new Map();
+  for (const run of runs) {
+    const title = TITLE.exec(String(run?.display_title ?? ''));
+    if (!title || SKIPPED.has(run.conclusion) || run.status !== 'completed') continue;
+    const have = newest.get(title[1]);
+    if (!have || Date.parse(run.created_at) > Date.parse(have.created_at)) newest.set(title[1], { ...run, pr: Number(title[1]) });
+  }
+  const order = [...newest.values()].sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at));
+  const errors = [];
+  for (const run of order) {
+    if (gateRunState(gh, repo, run) !== 'error') break;
+    errors.push(run);
+  }
+  if (errors.length < streak) {
+    line(`- atlas gate audit: the newest gate run of ${order.length ? `#${order[0].pr}` : 'no pull request'} ${errors.length ? `and ${errors.length - 1} more ended with an error; fewer than ${streak} in a row` : 'ended with a result'}.`);
+    return 0;
+  }
+  const shown = errors.slice(0, 10);
+  line(`- ✗ the gate errored on ${errors.length} pull request(s) in a row: ${shown.map((run) => `#${run.pr} run ${run.id}`).join(', ')}`);
+  line('GATE ERRORS: the gate gives no result. Look at its runs now.');
+  const oldest = errors.at(-1);
+  found.push({ job: ERRORS_JOB, key: `streak-${oldest.id}`, count: errors.length, runs: shown.map((run) => run.id).join('+'), prs: shown.map((run) => run.pr).join('+') });
+  return 1;
+}
+
+// ------------------------------------------------------------ line 4: the files
+
+// Each group: the path in the repo, and the path in the npm package. The
+// workflows ship as copies in door/workflows/, which a test keeps byte
+// identical to the repo copies. So a change to a gate workflow is a package
+// change, and it releases.
+export const GATE_FILE_GROUPS = Object.freeze([
+  { group: 'gate', files: [
+    ['.github/workflows/atlas-gate.yml', 'door/workflows/atlas-gate.yml'],
+    ['packages/atlas/door/lib/gate.mjs', 'door/lib/gate.mjs'],
+    ['packages/atlas/door/lib/gate-check.mjs', 'door/lib/gate-check.mjs'],
+    ['packages/atlas/door/lib/owner-only.mjs', 'door/lib/owner-only.mjs'],
+    ['packages/atlas/owner-only.yaml', 'owner-only.yaml'],
+  ] },
+  { group: 'audit', files: [
+    ['.github/workflows/atlas-gate-audit.yml', 'door/workflows/atlas-gate-audit.yml'],
+    ['packages/atlas/door/lib/gate-audit.mjs', 'door/lib/gate-audit.mjs'],
+    ['packages/atlas/door/lib/jobs.mjs', 'door/lib/jobs.mjs'],
+    ['packages/atlas/door/lib/issues.mjs', 'door/lib/issues.mjs'],
+    ['packages/atlas/door/cli.mjs', 'door/cli.mjs'],
+    ['packages/atlas/bin/atlas', 'bin/atlas'],
+    ['packages/atlas/shape/check.mjs', 'shape/check.mjs'],
+    ['packages/atlas/work/lib/child-env.mjs', 'work/lib/child-env.mjs'],
+  ] },
+  { group: 'door-hook', files: [
+    ['packages/atlas/hooks/door.mjs', 'hooks/door.mjs'],
+    ['packages/atlas/hooks/hooks.json', 'hooks/hooks.json'],
+  ] },
+]);
+
+// The files of an npm tarball (gzip of a ustar archive), by their path under
+// `package/`. It reads plain files only, and the long names of pax and GNU.
+export const MAX_TARBALL = 50 * 1024 * 1024;
+export function untar(gz, wanted = null) {
+  const bytes = gunzipSync(gz, { maxOutputLength: MAX_TARBALL });
+  const files = new Map();
+  const text = (block, start, length) => block.subarray(start, start + length).toString('utf8').replace(/\0[\s\S]*$/, '');
+  let at = 0;
+  let long = null;
+  while (at + 512 <= bytes.length) {
+    const head = bytes.subarray(at, at + 512);
+    if (head.every((byte) => byte === 0)) break;
+    const size = parseInt(text(head, 124, 12).trim() || '0', 8);
+    if (!Number.isFinite(size) || size < 0) throw new Error('the tarball has a bad header');
+    const type = head[156] === 0 ? '0' : String.fromCharCode(head[156]);
+    const prefix = text(head, 345, 155);
+    let name = prefix ? `${prefix}/${text(head, 0, 100)}` : text(head, 0, 100);
+    const body = bytes.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'x') { const path = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8')); long = path ? path[1] : null; continue; }
+    if (type === 'L') { long = body.toString('utf8').replace(/\0[\s\S]*$/, ''); continue; }
+    if (long) { name = long; long = null; }
+    // Plain files only: no link, no path that climbs out, and only the named paths when a list is given.
+    const path = name.replace(/^\.\//, '').replace(/^package\//, '');
+    if ((type === '0' || type === '7') && !path.split('/').includes('..') && (!wanted || wanted.has(path))) files.set(path, Buffer.from(body));
+  }
+  return files;
+}
+
+export const integrityOf = (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+
+function registryBase(env) {
+  const text = String(env.ATLAS_NPM_REGISTRY || 'https://registry.npmjs.org');
+  let url;
+  try { url = new URL(text); } catch { throw Object.assign(new Error('ATLAS_NPM_REGISTRY is not a URL'), { usage: true }); }
+  const local = url.hostname === '127.0.0.1' || url.hostname === 'localhost';
+  if (!(url.protocol === 'https:' || (url.protocol === 'http:' && local))) throw Object.assign(new Error('ATLAS_NPM_REGISTRY must be https'), { usage: true });
+  return url;
+}
+
+// The latest release on npm: its version and its files. The tarball must come
+// from the registry's own origin and match the sha512 that npm records.
+export async function latestRelease({ env = process.env, fetchImpl = fetch, wanted = null } = {}) {
+  const base = registryBase(env);
+  const meta = await fetchImpl(new URL(`${base.pathname.replace(/\/$/, '')}/${PACKAGE_NAME.replace('/', '%2f')}/latest`, base), { redirect: 'error' });
+  if (!meta.ok) throw new Error(`npm answered ${meta.status} when the latest release was read`);
+  const doc = await meta.json();
+  const version = String(doc?.version ?? '');
+  const tarball = String(doc?.dist?.tarball ?? '');
+  const integrity = String(doc?.dist?.integrity ?? '');
+  if (!/^\d+\.\d+\.\d+$/.test(version) || !/^sha512-/.test(integrity)) throw new Error('npm gave no version or integrity for the latest release');
+  let url;
+  try { url = new URL(tarball); } catch { throw new Error('npm gave no tarball URL'); }
+  if (url.origin !== base.origin) throw new Error('the tarball is not on the registry origin');
+  const got = await fetchImpl(url, { redirect: 'error' });
+  if (!got.ok) throw new Error(`npm answered ${got.status} when the tarball was read`);
+  const bytes = Buffer.from(await got.arrayBuffer());
+  if (bytes.length > MAX_TARBALL) throw new Error('the tarball is too large');
+  if (integrityOf(bytes) !== integrity) throw new Error(`the tarball of ${version} does not match the integrity npm records`);
+  return { version, files: untar(bytes, wanted) };
+}
+
+// The Atlas source repo: its package folder holds the package that ships.
+export function isAtlasSource(root) {
+  try { return JSON.parse(readFileSync(join(root, 'packages/atlas/package.json'), 'utf8'))?.name === PACKAGE_NAME; } catch { return false; }
+}
+
+// The paths of each group that differ from the release. A file that is
+// missing on either side differs.
+export function compareGroups(root, files, groups = GATE_FILE_GROUPS) {
+  const out = [];
+  for (const { group, files: pairs } of groups) {
+    const differ = [];
+    for (const [repoPath, packagePath] of pairs) {
+      const mine = join(root, repoPath);
+      const theirs = files.get(packagePath);
+      if (!existsSync(mine) || !theirs || !readFileSync(mine).equals(theirs)) differ.push(repoPath);
+    }
+    if (differ.length) out.push({ group, paths: differ });
+  }
+  return out;
+}
+
+// The watcher check of the job `gate-files`. A finding names the files by
+// their last part, so the field stays short; the run log names the full paths.
+export async function checkGateFiles({ root, env = process.env, fetchImpl = fetch }) {
+  if (!root || !isAtlasSource(root)) {
+    return { findings: [], notes: ['this repo is not the Atlas source; its gate files come with `atlas tooling` later (roadmap R7 line 5)'] };
+  }
+  const wanted = new Set(GATE_FILE_GROUPS.flatMap(({ files }) => files.map(([, path]) => path)));
+  const { version, files } = await latestRelease({ env, fetchImpl, wanted });
+  const groups = compareGroups(root, files);
+  // The key holds a hash of the repo bytes that differ, so a second edit of
+  // the same group opens its own issue.
+  const hashOf = (paths) => createHash('sha256').update(paths.map((path) => (existsSync(join(root, path)) ? readFileSync(join(root, path)) : Buffer.from(`missing:${path}`))).reduce((all, one) => Buffer.concat([all, one]), Buffer.alloc(0))).digest('hex').slice(0, 12);
+  const findings = groups.map(({ group, paths }) => ({ job: FILES_JOB, key: `${group}-${hashOf(paths)}`, group, paths: paths.map((path) => path.split('/').at(-1)).join('+'), count: paths.length, release: version }));
+  return { findings, notes: [`compared with ${PACKAGE_NAME}@${version}`, ...groups.map(({ group, paths }) => `${group} differs: ${paths.join(', ')}`)] };
+}
+
+// ------------------------------------------------------------ the daily audit
+
+export const AUDIT_DAYS = 2;
+export const MAX_COMMITS = 100;
+
+// The first-parent commits of the branch in the last `days` days, newest
+// first, read from GitHub. The watcher runs from the npm copy of Atlas, so a
+// push that edits the repo's own audit cannot change this walk.
+export function windowCommits(gh, repo, branch, since, max = MAX_COMMITS) {
+  const out = [];
+  let commit = gh('GET', `repos/${repo}/commits/${encodeURIComponent(branch)}`);
+  while (commit?.sha && out.length < max) {
+    const at = commit.commit?.committer?.date ?? commit.commit?.author?.date;
+    if (!at || at < since) break;
+    out.push(commit.sha);
+    const parent = commit.parents?.[0]?.sha;
+    commit = parent ? gh('GET', `repos/${repo}/commits/${parent}`) : null;
+  }
+  return out;
+}
+
+// The force pushes to the branch in the window, from the activity of its ref.
+export function forcePushes(gh, repo, branch, since) {
+  const rows = gh('GET', `repos/${repo}/activity?ref=${encodeURIComponent(`refs/heads/${branch}`)}&activity_type=force_push&per_page=100`) ?? [];
+  return (Array.isArray(rows) ? rows : []).filter((row) => /^[0-9a-f]{40}$/.test(String(row?.after ?? '')) && String(row?.timestamp ?? '') >= since);
+}
+
+// The watcher check of the job `gate-audit`: the commit audit of this Atlas
+// copy over the window, and each force push. `audit` is commitAudit, passed
+// in so this file needs no import of gate.mjs.
+export function checkGateAudit({ repo, branch, gh, audit, now = new Date(), days = AUDIT_DAYS }) {
+  const since = new Date(now.getTime() - days * 864e5).toISOString();
+  const found = [];
+  const notes = [];
+  const forced = new Set(forcePushes(gh, repo, branch, since).map((row) => row.after));
+  const commits = windowCommits(gh, repo, branch, since);
+  for (const sha of commits) audit({ repo, commit: sha, forced: forced.has(sha), found }, (text) => { if (/^- ✗/.test(text)) notes.push(text.slice(2, 300)); }, gh);
+  // A force push whose new tip is no longer on the branch still counts.
+  for (const sha of forced) if (!commits.includes(sha)) found.push({ job: AUDIT_JOB, key: `force-push:${sha}`, kind: 'force-push', sha });
+  notes.unshift(`audited ${commits.length} commit(s) of ${branch} since ${since.slice(0, 16)}Z, and ${forced.size} force push(es)`);
+  return { findings: found, notes };
+}
+
+// The watcher check of the job `gate-errors`.
+export function checkGateErrors({ repo, gh }) {
+  const found = [];
+  const notes = [];
+  gateErrors({ repo, found }, (text) => notes.push(text.replace(/^- /, '').slice(0, 300)), gh);
+  return { findings: found, notes };
+}

package/door/lib/gate-check.mjs

@@ -363,6 +363,10 @@ export function checkCommand({ root, base, head, body: bodyFile, json = false, s
     return answer.result === 'success' ? 0 : 1;
   } catch (error) {
     line(`gate check: ${error.message}`);
+    // In the gate workflow (it passes --output), an error leaves a note with a
+    // fixed title. The audit reads it to tell an error from a result (roadmap
+    // R14 done line 5).
+    if (output && output !== true) line('::error title=atlas gate error::the gate check stopped before a result. Read the log of this step.');
     return error.usage ? 2 : 1;
   }
 }

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 { keepFindings, gateErrors, pinCode, slug, AUDIT_JOB } from './gate-audit.mjs';
 import { MARKER as SIGNED_MARKER } from './signed-act.mjs';
 import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
 
@@ -248,7 +249,10 @@ export const gateRunTitle = (pr, sha) => `gate #${pr} at ${sha}`;
 // name this pull request and this head. The probe of 26 October (done line
 // 15, atlas#211) showed that its run and its check run sit on the head commit,
 // like the others.
-export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [] }) {
+// The audit reads a merged pull request. GitHub then lists no pull request
+// on its runs, so with `audit` the two pull request pins are left out; the
+// file, the event, the head and the title still hold.
+export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [], audit = false }) {
   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`;
   const event = name === GATE_CHECK ? 'pull_request_target' : 'pull_request';
@@ -256,11 +260,11 @@ export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [] }
   if (run.head_sha !== sha) return 'of another head commit';
   if (name === GATE_CHECK && run.display_title !== gateRunTitle(pr, sha)) return 'of another pull request or head';
   const pulls = run.pull_requests ?? [];
-  if (!pulls.some((each) => Number(each.number) === Number(pr) && each.base?.ref === baseRef)) return `not of #${pr} into ${baseRef}`;
+  if (!audit && !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'}`;
+  if (!audit && 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'}`;
   // GitHub builds that list when it is read, from the open pull requests of
   // the head branch. Once a side pull request closes, its run names only this
   // one. So no run counts when the head branch ever had a pull request into
@@ -287,30 +291,59 @@ export function jobRefusal(job, check, run) {
   return null;
 }
 
-// The check runs that may count for this pull request, and the ones refused.
-export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks }) {
-  const homes = homesAt(gh, repo, baseRef, checks);
-  // Every pull request, open or closed, from the head branch into another
-  // branch. Read once, when the first run needs it.
+// Every pull request, open or closed, from the head branch into another
+// branch. Read once, and only when a gate run needs it.
+function sidesOf(gh, repo, head, baseRef) {
   let sideList;
-  const sides = () => {
+  return () => {
     if (sideList !== undefined) return sideList;
     const owner = head?.repo?.owner?.login ?? head?.user?.login;
     if (!head?.ref || !owner) return (sideList = null);
     const all = gh('GET', `repos/${repo}/pulls?head=${encodeURIComponent(`${owner}:${head.ref}`)}&state=all&per_page=100`) ?? [];
     return (sideList = all.filter((each) => each.base?.ref !== baseRef));
   };
+}
+
+// The workflow run of each check suite, read once.
+function suiteRuns(gh, repo) {
   const suites = new Map();
-  const runOf = (id) => {
+  return (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);
   };
+}
+
+// R14 done line 2: each gate run on the head of a merged pull request must
+// come from the base copy of the gate workflow, on pull_request_target, with
+// the title that names this pull request and head. Returns the refused runs.
+export function gateCopyRefusals(gh, repo, pull) {
+  const sha = pull.head?.sha;
+  const baseRef = pull.base?.ref;
+  const homes = new Map([[GATE_CHECK, new Set([GATE_WORKFLOW])]]);
+  const sides = sidesOf(gh, repo, pull.head, baseRef);
+  const runOf = suiteRuns(gh, repo);
+  const refused = [];
+  for (const check of checkRuns(gh, repo, sha)) {
+    if (check.name !== GATE_CHECK || check.app?.id !== ACTIONS_APP_ID) continue;
+    const run = runOf(check.check_suite?.id);
+    const why = refusal(run, { name: GATE_CHECK, pr: pull.number, sha, baseRef, homes, sides, audit: true })
+      ?? jobRefusal(check.id === undefined ? null : gh('GET', `repos/${repo}/actions/jobs/${check.id}`), check, run);
+    if (why) refused.push({ run: run?.id ?? null, why });
+  }
+  return refused;
+}
+
+// The check runs that may count for this pull request, and the ones refused.
+export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks, homesRef = baseRef, audit = false }) {
+  const homes = homesAt(gh, repo, homesRef, checks);
+  const sides = sidesOf(gh, repo, head, baseRef);
+  const runOf = suiteRuns(gh, repo);
   const kept = [];
   const refused = [];
   for (const check of checkRuns(gh, repo, sha)) {
     if (!checks.includes(check.name) || check.app?.id !== ACTIONS_APP_ID) continue;
     const run = runOf(check.check_suite?.id);
-    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides })
+    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides, audit })
       ?? jobRefusal(check.id === undefined ? null : gh('GET', `repos/${repo}/actions/jobs/${check.id}`), check, run);
     if (why) refused.push({ name: check.name, why }); else kept.push(check);
   }
@@ -389,8 +422,23 @@ export function keepReady({ repo, pr, sha, code, home = homedir(), now = new Dat
 
 // `atlas gate audit --since <date>`: each pull request merged since the date
 // whose required checks were not all green at the moment of the merge.
-export function auditCommand({ repo, since, commit }, line, gh = ghApi) {
-  if (commit !== undefined) return commitAudit({ repo, commit }, line, gh);
+export function auditCommand({ repo, since, commit, errors = false, forced = false, findings }, line, gh = ghApi) {
+  // R14: with --findings, each finding also goes into the file, and `atlas
+  // jobs file` opens one issue for each. A call that stops with an error
+  // marks the file broken, so the file job ends red.
+  const found = [];
+  const keep = (broken = false) => { if (findings && findings !== true) keepFindings(findings, found, { broken }); };
+  try {
+    let code;
+    if (errors) code = gateErrors({ repo, found }, line, gh);
+    else if (commit !== undefined) code = commitAudit({ repo, commit, forced, found }, line, gh);
+    else code = sinceAudit({ repo, since }, line, gh);
+    keep();
+    return code;
+  } catch (error) { keep(true); throw error; }
+}
+
+function sinceAudit({ repo, since }, line, gh) {
   const from = since && since !== true ? since : new Date(Date.now() - 864e5).toISOString().slice(0, 10);
   if (Number.isNaN(Date.parse(from))) throw new GateError(`--since must be a date, not "${from}".`);
   const closed = gh('GET', `repos/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100`) ?? [];
@@ -420,34 +468,55 @@ export function auditCommand({ repo, since, commit }, line, gh = ghApi) {
 
 // `atlas gate audit --commit <sha>`: one commit that reached the main branch.
 // The push job runs it on each push. A commit is good when a pull request
-// merged it after that pull request's required checks were green. A commit
-// that no pull request merged was pushed past the gate, so it is red.
-function commitAudit({ repo, commit }, line, gh) {
+// merged it after that pull request's required checks were green, and each
+// gate run of that pull request came from the base copy of the gate
+// workflow. A commit that no pull request merged was pushed past the gate, so
+// it is red. With --forced, the push that brought it was a force push.
+export function commitAudit({ repo, commit, forced = false, found = [] }, line, gh) {
   if (!commit || commit === true || !/^[0-9a-f]{7,40}$/i.test(String(commit))) throw new GateError('--commit needs a commit SHA.');
   // GitHub expands a short SHA, and names the first parent: the main branch
   // just before this commit, whose atlas.yaml held the gate at that moment.
-  const found = gh('GET', `repos/${repo}/commits/${commit}`);
-  const sha = found?.sha;
+  const fetched = gh('GET', `repos/${repo}/commits/${commit}`);
+  const sha = fetched?.sha;
   if (!sha) throw new GateError(`there is no commit ${commit} in ${repo}.`);
+  let red = false;
+  if (forced) {
+    red = true;
+    line(`- ✗ ${sha.slice(0, 7)} came to the main branch with a force push.`);
+    found.push({ job: AUDIT_JOB, key: `force-push:${sha}`, kind: 'force-push', sha });
+  }
   const pull = (gh('GET', `repos/${repo}/commits/${sha}/pulls`) ?? []).find((each) => each.merged_at && each.merge_commit_sha === sha);
   if (!pull) {
     line(`- ✗ ${sha.slice(0, 7)} reached the main branch with no pull request: a push past the gate.`);
     line('RED PUSH: look at it now; the main branch may hold an untested change.');
+    found.push({ job: AUDIT_JOB, key: `push:${sha}`, kind: 'push', sha });
     return 1;
   }
-  const parent = found.parents?.[0]?.sha ?? pull.base.sha;
+  for (const one of gateCopyRefusals(gh, repo, pull)) {
+    red = true;
+    line(`- ✗ #${pull.number}: a gate run is not from the base copy of ${GATE_WORKFLOW}: run ${one.run ?? 'none'} ${one.why}`);
+    found.push({ job: AUDIT_JOB, key: `gate-copy:${sha}`, kind: 'gate-copy', sha, pr: Number(pull.number), ...(one.run ? { run_id: Number(one.run) } : {}), pin: pinCode(one.why) });
+  }
+  const parent = fetched.parents?.[0]?.sha ?? pull.base.sha;
   let checks;
   try { checks = checksAt(gh, repo, parent); } catch (error) {
     if (!(error instanceof GateError)) throw error;
     line(`- atlas gate audit: ${sha.slice(0, 7)} is the merge of #${pull.number}; atlas.yaml before it listed no required_checks, so nothing to audit.`);
-    return 0;
+    return red ? 1 : 0;
   }
-  const bad = checkStates(checks, checkRuns(gh, repo, pull.head.sha), pull.merged_at).filter((row) => row.state !== 'green');
+  // A required check counts only from a run of a base file that defines it,
+  // as `atlas gate ready` reads it. So a head workflow with a job named like
+  // a required check does not make a merge look green.
+  const { kept, refused } = pinnedRuns(gh, repo, { pr: pull.number, sha: pull.head.sha, baseRef: pull.base?.ref, head: pull.head, checks, homesRef: parent, audit: true });
+  const bad = checkStates(checks, kept, pull.merged_at).filter((row) => row.state !== 'green');
   if (bad.length) {
     line(`- ✗ #${pull.number} merged ${pull.merged_at} before its checks were green: ${bad.map((row) => `${row.name} ${row.state}`).join(', ')}`);
+    for (const one of refused) line(`  - ignored  a run of ${one.name}: ${one.why}`);
     line('RED MERGES: 1. Look at it now; the main branch may hold an untested change.');
+    found.push({ job: AUDIT_JOB, key: `merge-before-green:${sha}`, kind: 'merge-before-green', sha, pr: Number(pull.number), checks: bad.map((row) => slug(row.name)).join('+').slice(0, 200) });
     return 1;
   }
+  if (red) return 1;
   line(`- atlas gate audit: ${sha.slice(0, 7)} is the merge of #${pull.number}, after its ${checks.length} required check(s) were green.`);
   return 0;
 }
@@ -537,7 +606,7 @@ export function brakeRead({ root, base, now = new Date() }, gh, repo, pages = 3)
 }
 
 // `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, baseRef, head, body, json = false, summary, output, days, branch, home = homedir() }, line, gh = ghApi) {
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, baseRef, head, body, json = false, summary, output, days, branch, errors = false, forced = false, findings, 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));
@@ -560,7 +629,7 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
     }
     return code;
   }
-  if (what === 'audit') return auditCommand({ repo, since, commit }, line, gh);
+  if (what === 'audit') return auditCommand({ repo, since, commit, errors, forced, findings }, line, gh);
   if (off && on) throw new GateError('pick --off or --on, not both.');
   const mode = off ? 'off' : on ? 'on' : 'apply';
   const facts = mode === 'apply' ? gateFacts(root) : null;