@arjunkhera/atlas 0.4.22 → 0.4.23

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "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;

package/door/lib/jobs.mjs

@@ -25,6 +25,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../shape/check.mjs';
 import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+import { checkGateFiles, checkGateAudit, checkGateErrors } from './gate-audit.mjs';
+import { commitAudit, ghApi } from './gate.mjs';
 
 export const JOBS_LABEL = 'atlas-job';
 export const HANDED_OVER = 'handed-over';
@@ -107,9 +109,16 @@ export async function checkRedMain({ repo, branch, env }) {
 
 // The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
 // says so in the notes; it never reads `found` from nothing.
-const CHECKS = { 'red-main': checkRedMain };
+// The gate jobs (roadmap R14) read GitHub through `gh`, which the Actions
+// runner holds; their token is the run's own GITHUB_TOKEN.
+const CHECKS = {
+  'red-main': checkRedMain,
+  'gate-files': ({ root, env, fetchImpl }) => checkGateFiles({ root, env, fetchImpl }),
+  'gate-audit': ({ repo, branch, gh }) => checkGateAudit({ repo, branch, gh, audit: commitAudit }),
+  'gate-errors': ({ repo, gh }) => checkGateErrors({ repo, gh }),
+};
 
-export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs() }) {
+export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs(), gh = ghApi, fetchImpl = fetch }) {
   const named = namedJobs(root);
   const notes = [];
   const ran = [];
@@ -123,7 +132,10 @@ export async function jobsCheck({ root, repo, branch = null, env = process.env,
     if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
     try {
       if (!mainBranch) mainBranch = await defaultBranch({ repo, env });
-      const found = (await check({ repo, branch: mainBranch, env })).map((f) => ({ ...f, job: id }));
+      // A check gives its findings, or { findings, notes }.
+      const got = await check({ repo, branch: mainBranch, env, root, gh, fetchImpl });
+      const found = (Array.isArray(got) ? got : got.findings).map((f) => ({ ...f, job: id }));
+      for (const note of Array.isArray(got) ? [] : got.notes ?? []) notes.push(`${id}: ${String(note).slice(0, 300)}`);
       findings.push(...found);
       ran.push({ job: id, state: found.length ? 'found' : 'none' });
     } catch (error) {
@@ -194,13 +206,22 @@ export function jobIssue(finding) {
 export const handedOverStops = (now = Date.now()) => (issue) => (issue.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === HANDED_OVER)
   && Number.isFinite(Date.parse(issue.closed_at)) && now - Date.parse(issue.closed_at) <= HANDED_OVER_DAYS * DAY;
 
+// A job with `handed_over: ignored` never stops on a closed issue: anyone with
+// the shared login can close an issue, so a gate finding comes back while its
+// commit is in the window (roadmap R14).
+export const closedStopsFor = (jobs, now = Date.now()) => (issue) => {
+  const job = (issue.labels ?? []).map((l) => (typeof l === 'string' ? l : l?.name)).find((name) => String(name).startsWith('job:'));
+  if (job && jobs.get(job.slice(4))?.handed_over === 'ignored') return false;
+  return handedOverStops(now)(issue);
+};
+
 export async function fileJobs({ envelope, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, now = Date.now(), jobs = atlasJobs() }) {
   const { findings, dropped } = typedFindings(envelope, jobs);
   if (dropped) line(`dropped ${dropped} finding(s) that are not typed, or that name no Atlas job`);
   if (envelope.state === 'broken') line('the check reads broken, so a check found nothing it can trust. The run ends red.');
   const list = findings.map((f) => ({ key: `${f.job}:${f.key}`, issue: jobIssue(f) }));
   const result = list.length
-    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: handedOverStops(now) })
+    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: closedStopsFor(jobs, now) })
     : (line('no finding: nothing to file.'), { opened: [], skipped: [], deferred: [], failed: [] });
   return { ...result, broken: envelope.state === 'broken' };
 }

package/door/templates/atlas-jobs.yml

@@ -5,7 +5,9 @@ name: atlas-jobs
 # It runs once a day from the default branch, and never on a pull request, so
 # a pull request cannot change what it runs. It has two jobs:
 #   check  reads the repo and the CI runs of the default branch. It holds only
-#          read permissions and the run's own token, and no repo secret.
+#          read permissions and the run's own token, and no repo secret. The
+#          gate jobs (gate-audit, gate-errors) also read pull requests and
+#          check runs, so the job reads those two as well.
 #   file   holds only issues write. It runs Atlas code on the JSON of the
 #          check job, and files one `atlas-job` issue for each new finding.
 # A job does nothing until atlas.yaml names it under `jobs: { atlas: [...] }`.
@@ -28,6 +30,8 @@ jobs:
     permissions:
       contents: read
       actions: read
+      pull-requests: read
+      checks: read
     outputs:
       findings: ${{ steps.check.outputs.findings }}
     steps:

package/door/workflows/atlas-gate-audit.yml

@@ -0,0 +1,128 @@
+name: atlas-gate-audit
+on:
+  push:
+    branches: [master]
+
+# The push audit of the advisory gate (roadmap R14, design
+# docs/design-docs/audit-job/). This plan gives the repo no rulesets, so
+# GitHub merges and takes pushes with no check. This workflow looks at each
+# commit that a push put on the main branch, along the first parent:
+#   1. A commit that no pull request merged is a push past the gate.
+#   2. A force push.
+#   3. A merge made before the required checks of its pull request were
+#      green. A check counts only from a run of the base file that defines it.
+#   4. A gate run that is not from the base copy of atlas-gate.yml.
+# Each finding opens one `atlas-job` issue, and the run ends red. It does not
+# undo the push.
+#
+# It runs the code of the pushed commit, so a push can edit it and hide. The
+# watcher (atlas-jobs.yml) runs the npm copy of Atlas once a day. It audits
+# the commits of the last two days again, and compares these files with the
+# latest release. A test keeps this file byte identical to
+# packages/atlas/door/workflows/atlas-gate-audit.yml.
+#
+# Two jobs, each with only what it needs:
+#   audit  read rights only. It writes the findings as job output.
+#   file   contents: read for the checkout, and issues: write. That is the
+#          only write right of this workflow.
+permissions: {}
+
+concurrency:
+  group: atlas-gate-audit-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  audit:
+    name: gate · push audit
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: read
+      actions: read
+    outputs:
+      findings: ${{ steps.audit.outputs.findings }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Audit each commit of this push
+        id: audit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BEFORE: ${{ github.event.before }}
+          AFTER: ${{ github.event.after }}
+          FORCED: ${{ github.event.forced }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -uo pipefail
+          out="$RUNNER_TEMP/findings.json"
+          # keep FILE [FROM]: add the findings of FROM to FILE, through Atlas code.
+          keep() { node --input-type=module -e 'import { keepFindings } from "./packages/atlas/door/lib/gate-audit.mjs"; import { readFileSync, existsSync } from "node:fs"; const [to, from] = process.argv.slice(1); const have = from && existsSync(from) ? JSON.parse(readFileSync(from, "utf8")) : { findings: [] }; keepFindings(to, have.findings ?? [], { broken: have.state === "broken" });' "$@"; }
+          keep "$out"
+          forced=()
+          if [ "$FORCED" = "true" ]; then forced=(--forced); fi
+          if [ -z "${BEFORE//0/}" ] || [ "$FORCED" = "true" ] || ! git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
+            commits="$AFTER"
+          else
+            commits=$(git rev-list --first-parent --reverse "$BEFORE..$AFTER")
+          fi
+          for sha in $commits; do
+            flag=()
+            if [ "$sha" = "$AFTER" ]; then flag=("${forced[@]}"); fi
+            # GitHub can take a moment to link a fresh merge to its pull
+            # request. So a "no pull request" answer gets one more read, with
+            # a fresh findings file.
+            if ! text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha"); then
+              if grep -q '^RED PUSH' <<<"$text"; then
+                sleep 30
+                rm -f "$out.$sha"
+                text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha")
+              fi
+            fi
+            printf '%s\n' "$text" | tee -a "$GITHUB_STEP_SUMMARY"
+            # A run that wrote no file stopped before it could: mark it broken.
+            if [ -s "$out.$sha" ]; then keep "$out" "$out.$sha"; else echo '{"jobs":1,"state":"broken","findings":[]}' > "$out.$sha"; keep "$out" "$out.$sha"; fi
+          done
+          echo "findings=$(base64 -w0 < "$out")" >> "$GITHUB_OUTPUT"
+
+  file:
+    name: gate · push audit issues
+    needs: audit
+    if: always() && needs.audit.outputs.findings != ''
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: File one issue for each new finding
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          FINDINGS: ${{ needs.audit.outputs.findings }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$FINDINGS" | base64 -d > "$RUNNER_TEMP/findings.json"
+          node packages/atlas/bin/atlas jobs file --findings "$RUNNER_TEMP/findings.json" --repo "$GITHUB_REPOSITORY" | tee -a "$GITHUB_STEP_SUMMARY"
+          state=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).state' "$RUNNER_TEMP/findings.json")
+          if [ "$state" != "none" ]; then
+            echo "::error::the push audit found a break of the gate (state $state). Read the issues it opened."
+            exit 1
+          fi

package/door/workflows/atlas-gate.yml

@@ -0,0 +1,142 @@
+name: atlas-gate
+run-name: "gate #${{ github.event.pull_request.number }} at ${{ github.event.pull_request.head.sha }}"
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+# The gate (roadmap R6, design docs/design-docs/gate-check/). One job, named
+# `gate`, ends as success, or as failure with "owner: class" or "red: reason"
+# in its summary. It judges the pull request by the static rules: the
+# owner-only list, secrets of a known shape, head jobs named like a check, and
+# a test change for product code.
+#
+# It runs on pull_request_target, so GitHub runs this file as the base branch
+# holds it, with the base code. The head is fetched as git objects only and is
+# never checked out, built or run. atlas.yaml comes from the base side only.
+# The title of the run names the pull request and the head; `atlas gate ready`
+# reads it to pin the run (done line 8).
+#
+# The token can only read. No checkout keeps a credential: the one fetch of
+# the head takes the token for that command alone. The job writes two output
+# keys, `result` and `class`, each one word of a fixed set.
+#
+# The signed act (roadmap R72): the gate reads the comments of the pull
+# request, and a valid signature of the owner for this head turns "owner" into
+# success. The key comes from atlas/owner-signers on the base. A new comment
+# with a signed act reruns this run (atlas-gate-signed.yml).
+#
+# Report mode: the gate is not in required_checks yet. It joins the list after
+# the A1 exit test of the overhaul roadmap.
+#
+# The second job, `shape`, is the repo shape check from the base (roadmap R7,
+# design docs/design-docs/shape-check-from-base/). It is the job that
+# `atlas tooling` writes into every repo, word for word, and `atlas status`
+# compares it with the package.
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  checks: read
+  actions: read
+
+concurrency:
+  group: atlas-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.check.outputs.result }}
+      class: ${{ steps.check.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+
+      - name: Read the pull request text from the event
+        run: node -e 'const fs=require("fs");const e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,"utf8"));fs.writeFileSync(process.env.RUNNER_TEMP+"/body.md",String(e.pull_request.body??""))'
+
+      - name: Gate check
+        id: check
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          node packages/atlas/bin/atlas gate check --root . --repo "$GITHUB_REPOSITORY" --base "$GITHUB_SHA" --head "$HEAD_SHA" --pr "$PR" --base-ref "$BASE_REF" --body "$RUNNER_TEMP/body.md" --summary "$GITHUB_STEP_SUMMARY" --output "$GITHUB_OUTPUT"
+
+  shape:
+    name: gate · shape
+    runs-on: ubuntu-latest
+    # The check reads two trees and opens no network. It finishes in seconds
+    # on a small repo. The bound stops a runner being billed until someone
+    # kills it; a run that hits it is red.
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.shape.outputs.result }}
+      class: ${{ steps.shape.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+      - name: Shape check from the base
+        id: shape
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          if [ ! -f .github/atlas/check.mjs ]; then
+            echo "OWNER: first-run: the base has no .github/atlas/check.mjs, so the owner reads the first shape"
+            echo "result=owner" >> "$GITHUB_OUTPUT"
+            echo "class=first-run" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          node .github/atlas/check.mjs --gate --repo "$GITHUB_REPOSITORY" --base-commit "$GITHUB_SHA" --head-commit "$HEAD_SHA"

package/package.json

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

package/work/lib/roundup.mjs

@@ -25,6 +25,29 @@ export const ROUNDUP_READ_VERBS = Object.freeze(['roundup']);
 // stage-2 is the stage 2 item or one of its parts.
 export const STAGE_TAG = /^stage-(\d{1,2})$/;
 export const STUCK_DAYS = 14;
+// Roadmap R14 done line 6: the daily audit runs in the watcher workflow. A
+// repo whose watcher has not run for this long is flagged in part 4.
+export const AUDIT_WORKFLOW = 'atlas-jobs.yml';
+export const AUDIT_STALE_HOURS = 26;
+const HOUR = 3_600_000;
+
+// The newest run of the daily audit in each repo. A repo with no such
+// workflow (GitHub answers 404) has no audit, so it is left out. Any other
+// failure is listed as unread, never as fresh.
+export async function readAudits(repoIds, readGitHub, readAt, staleHours = AUDIT_STALE_HOURS) {
+  const stale = [], unread = [];
+  for (const repo of repoIds) {
+    let runs;
+    try { runs = (await readGitHub(`repos/${repo}/actions/workflows/${AUDIT_WORKFLOW}/runs?per_page=1`))?.workflow_runs; } catch (error) {
+      if (!/\b404\b|Not Found/i.test(String(error?.message ?? error))) unread.push({ repo, reason: oneLine(`the audit runs could not be read: ${error?.message ?? String(error)}`, 200) });
+      continue;
+    }
+    const last = Array.isArray(runs) && runs.length ? runs[0].created_at ?? null : null;
+    const hours = last ? Math.floor((Date.parse(readAt) - Date.parse(last)) / HOUR) : null;
+    if (hours === null || hours >= staleHours) stale.push({ repo, workflow: `.github/workflows/${AUDIT_WORKFLOW}`, last_run_at: last, hours });
+  }
+  return { stale, unread };
+}
 export const TREND_WEEKS = 4;
 const DEFAULT_WINDOW = 7;
 const MAX_WINDOW = 90;
@@ -141,6 +164,7 @@ export function createRoundupVerbs(core) {
       const notMarked = (flight.merged_not_marked ?? []).map((row) => ({ item: row.item, pr: row.pr, title: row.title, days: row.days }));
       const openNoItem = pulls.filter((pull) => pull.state === 'open' && !owner.has(pull.url)).map((pull) => ({ pr: pull.url, title: pull.title, updated_at: pull.updated_at }));
       const longWaits = needRows.filter((row) => row.days_waiting !== null && row.days_waiting >= STUCK_DAYS);
+      const audits = await readAudits(repoIds, readGitHub, readAt);
 
       // 5. Trend, per week; week 1 is the last seven days.
       const weeks = Array.from({ length: TREND_WEEKS }, (_, index) => ({ week: index + 1, from: dayOf(minus(readAt, (index + 1) * 7)), to: dayOf(minus(readAt, index * 7)), merged: 0, delivered: 0, new_items: 0 }));
@@ -150,13 +174,13 @@ export function createRoundupVerbs(core) {
       for (const row of items) bump(row.created_at, 'new_items');
       const oldest = needRows.reduce((max, row) => Math.max(max, row.days_waiting ?? 0), 0);
 
-      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors });
+      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits, weeks, oldest, repoErrors });
       return {
         verb: 'roundup', read_at: readAt, product, window_days: windowDays, since,
         needs_you: needRows,
         where_we_stand: { ladder, lifecycles, active },
         what_moved: { merged, delivered: deliveries, new_items: created },
-        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS },
+        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS, audits_not_run: audits.stale, audits_unread: audits.unread, audit_stale_hours: AUDIT_STALE_HOURS },
         trend: { weeks, open_questions: needRows.length, oldest_question_days: oldest },
         repos_read: repoIds, repo_errors: repoErrors,
         citation: { product, read_at: readAt, items: items.length, repos: repoIds },
@@ -167,7 +191,7 @@ export function createRoundupVerbs(core) {
 }
 
 function render(view) {
-  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors } = view;
+  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits = { stale: [], unread: [] }, weeks, oldest, repoErrors } = view;
   const more = (list) => (list.length > SHOWN ? [`   and ${list.length - SHOWN} more`] : []);
   const out = [`${product} — roundup, ${dayOf(readAt)}`];
 
@@ -195,6 +219,8 @@ function render(view) {
   stuck.push(`   merged, not marked (${notMarked.length})`, ...notMarked.slice(0, SHOWN).map((row) => listLine(row.title, `${row.pr} · ${row.item}`, '     ')));
   stuck.push(`   open pull requests with no item (${openNoItem.length})`, ...openNoItem.slice(0, SHOWN).map((row) => listLine(row.title, row.pr, '     ')));
   stuck.push(`   questions waiting ${STUCK_DAYS} days or more (${longWaits.length})`, ...longWaits.slice(0, SHOWN).map((row) => listLine(row.text, `${row.question} · ${row.days_waiting} days`, '     ')));
+  stuck.push(`   audits with no run in ${AUDIT_STALE_HOURS} hours (${audits.stale.length})`, ...audits.stale.slice(0, SHOWN).map((row) => listLine(row.repo, row.last_run_at ? `last run ${row.last_run_at}, ${row.hours} hours` : 'no run yet', '     ')));
+  for (const row of audits.unread.slice(0, SHOWN)) stuck.push(listLine(row.repo, row.reason, '     '));
   out.push(stuck.join('\n'));
 
   out.push([`5. Trend, per week (week 1 is the last seven days)`,

package/work/mcp.mjs

@@ -206,6 +206,8 @@ export const GITHUB_READS = Object.freeze([
   new RegExp(`^repos/${REPO}/contents/atlas\\.yaml\\?ref=(?:${SHA}|${BRANCH})$`),
   new RegExp(`^repos/${REPO}/releases\\?per_page=\\d{1,3}$`),
   new RegExp(`^repos/${REPO}/compare/${SHA}\\.\\.\\.${TAG}$`),
+  // Roadmap R14 line 6: the newest run of the daily audit, for the roundup.
+  new RegExp(`^repos/${REPO}/actions/workflows/atlas-jobs\\.yml/runs\\?per_page=\\d{1,3}$`),
 ]);
 export function githubReader() {
   return async (path) => {