@arjunkhera/atlas 0.4.45 → 0.4.47

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The atlas command: install, upgrade, doctor, check, status, the tooling
-// writer, the kind drift report, the code-read resolver, the STE check, the
+// writer, the code-read resolver, the STE check, the
 // design check and page builder, the tests verbs (the link check and the
 // test kit writer), the upkeep check, and the judge of the fresh-agent test.
 //
@@ -18,7 +18,6 @@ import { spawnSync } from 'node:child_process';
 import { open } from './lib/pull-request.mjs';
 import { write as writeTooling, changes as toolingChanges, ToolingRefusal, CHECK_PATH, WORKFLOW_PATH } from './lib/tooling.mjs';
 import { statusMany, copies } from './lib/status.mjs';
-import { drift, kindsFromRegistry, fileKind } from './lib/kind-drift.mjs';
 import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs';
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
@@ -54,9 +53,8 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas status --root <repo>           is the repo's check current, behind, unknown or missing
       --all                            every Atlas copy in the repo: the check, its workflow, each test kit, each pinned Atlas version
       --json                           print the rows as JSON: type, path, state, have, want, why
-  atlas kind-drift --root <repo> --record-kind <kinds>
-                                       does atlas.yaml agree with the repo record
   atlas check --root <repo>            run the repo shape check here
+      --json                           print the report as JSON, with the counts of parts, procedures and jobs
 
   atlas code-read resolve …            resolve the citations of a code digest
 
@@ -210,8 +208,7 @@ A person merges every file the tooling writer writes.
 export const FLAGS = Object.freeze({
   tooling: { root: 'optional', branch: 'optional', 'replace-unknown': 'switch', workflow: 'switch', 'dry-run': 'switch' },
   status: { root: 'optional', all: 'switch', json: 'switch' },
-  'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
-  check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
+  check: { root: 'optional', repo: 'value', 'fail-on': 'value', json: 'switch' },
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   view: { product: 'value', name: 'value', out: 'value' },
@@ -338,40 +335,6 @@ function copiesCommand(roots, { all, json }) {
   return repos.some((repo) => repo.rows.some((one) => bad.includes(one.state))) ? 1 : 0;
 }
 
-function kindDriftCommand(chosen) {
-  const root = rootOf(chosen);
-  let recordKind = chosen['record-kind'] ?? null;
-  if (!recordKind && chosen.registry) {
-    const kinds = kindsFromRegistry(JSON.parse(readFileSync(resolve(chosen.registry), 'utf8')));
-    const repo = chosen.repo ?? null;
-    recordKind = repo ? kinds[repo] ?? null : null;
-    if (!repo) {
-      // One checkout, so only the registry row that names THIS repo can be
-      // compared. Comparing every row against one root invented drift that was
-      // not there (acceptance review of batch 16, finding S2-6).
-      const here = fileKind(root);
-      if (!here.repo) { line(`${root} has no atlas.yaml, or its atlas.yaml names no repo, so no registry row can be matched to it.`); return 1; }
-      recordKind = kinds[here.repo] ?? null;
-      const others = Object.keys(kinds).filter((id) => id !== here.repo);
-      const report = drift([{ root, recordKind, recordRepo: here.repo }]);
-      for (const row of report.rows) line(`${row.state.toUpperCase().padEnd(10)} ${row.repo}  file=${row.file_kind ?? '-'} record=${row.record_kind ?? '-'}  ${row.why}`);
-      if (!(here.repo in kinds)) line(`The registry holds no row for ${here.repo}. Register it with the repo_add verb.`);
-      if (others.length) line(`Not this checkout, so not read: ${others.join(', ')}. Point --root at each one.`);
-      return report.drifting ? 1 : 0;
-    }
-  }
-  const report = drift([{ root, recordKind }]);
-  for (const row of report.rows) {
-    line(`${row.state.toUpperCase()}  ${row.repo ?? row.root}`);
-    line(`  atlas.yaml   kind ${row.file_kind ?? '(none)'}   spec ${row.spec ?? '(none)'}`);
-    line(`  repo record  kind ${row.record_kind ?? '(not given)'}`);
-    line(`  ${row.why}`);
-  }
-  line('');
-  line('Which of the two is the source is open question O-9. This report picks no winner.');
-  return report.drifting ? 1 : 0;
-}
-
 function steCommand(chosen) {
   const paths = chosen._.slice(1);
   if (!paths.length) throw new Error('give a file or a folder: atlas ste <path> [--share]');
@@ -484,6 +447,12 @@ function checkCommand(chosen) {
   const root = rootOf(chosen);
   const report = scan({ root, repoId: chosen.repo ?? null });
   const decision = verdict(report, chosen['fail-on'] ?? 'error');
+  // The O7 count is one command (roadmap R62 line 6): the report, its counts
+  // of listed parts, procedures and jobs, and the verdict.
+  if (chosen.json) {
+    process.stdout.write(`${JSON.stringify({ ...report, fail_on: chosen['fail-on'] ?? 'error', green: decision.green, why: decision.why }, null, 2)}\n`);
+    return decision.green ? 0 : 1;
+  }
   process.stdout.write(toText(report));
   // A report, never a reason for red: the list is an owner-only key.
   const list = mergeList(root);
@@ -509,7 +478,6 @@ export async function main(argv = process.argv.slice(2)) {
     case 'doctor': return doctor({ packageRoot: PACKAGE_ROOT, options: chosen, line });
     case 'tooling': return toolingCommand(chosen);
     case 'status': return statusCommand(chosen);
-    case 'kind-drift': return kindDriftCommand(chosen);
     case 'check': return checkCommand(chosen);
     case 'ste': return steCommand(chosen);
     case 'design': return designCommand(chosen);

package/door/lib/approve.mjs

@@ -14,6 +14,10 @@
 //                                  for each with one touch, post the block on
 //                                  each pull request, close each audit issue,
 //                                  and print the one message for the lead
+//   atlas approve audit-code <pr>  show the audit-code diff of one merged
+//                                  pull request and its red audit check,
+//                                  sign one accept-code act with one touch,
+//                                  post the block, and print the message
 //   atlas approve verify --file f  verify the blocks of a file against the
 //                                  key file of a repo
 //   atlas approve key-check        sign a test text and verify it with the
@@ -30,10 +34,10 @@ import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
-import { ghApi, pinnedRuns } from './gate.mjs';
+import { ghApi, pinnedRuns, commitAudit } from './gate.mjs';
 import { GATE_CHECK } from './gate-check.mjs';
 import {
-  ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_TEST, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
+  ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, AUDIT_CODE, AUDIT_CODE_TEST, AUDIT_WORKFLOW, auditCodeDiff, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
   preKeyKeys,
 } from './signed-act.mjs';
 
@@ -241,9 +245,8 @@ export async function approvePulls({ prs, repo, root, key, provider, yes = false
 // (R14 line 3), and its filing job then ends red on the merge commit. That red
 // job is the check the owner accepts; the test that his words quote is the
 // kind of the finding (item 0ca9fced, design docs/design-docs/audit-red-sign-off/).
-export { AUDIT_CHECK, AUDIT_TEST };
+export { AUDIT_CHECK, AUDIT_TEST, AUDIT_CODE, AUDIT_WORKFLOW };
 export const AUDIT_ISSUE = /^atlas-job: gate-audit owner-unsigned:([0-9a-f]{40})$/;
-export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
 // The label on an audit issue whose red the owner accepted. The lead closes
 // the issue after the done tool records the acceptance (security review S3).
 export const ACCEPTED_LABEL = 'atlas-accepted';
@@ -257,10 +260,6 @@ export function auditWords(prs, at) {
   return `I accept the ${AUDIT_TEST} audit reds of ${prs.map((pr) => `#${pr}`).join(', ')}, listed at ${new Date(at).toISOString().slice(0, 16)}Z. These pull requests merged without my touch, under my standing approval.`;
 }
 
-// The files whose change lets a merge write its own audit: the audit
-// workflow, the audit and the filer. A merge that changed one is never
-// signed (security review 2, S3).
-export const AUDIT_CODE = Object.freeze([AUDIT_WORKFLOW, 'packages/atlas/door/lib/gate-audit.mjs', 'packages/atlas/door/lib/gate.mjs', 'packages/atlas/door/lib/jobs.mjs', 'packages/atlas/bin/atlas']);
 const AUDIT_ANY = /^atlas-job: gate-audit ([a-z-]+):([0-9a-f]{40})$/;
 
 // The owner keys that the done tool reads for one merge: the keys on its
@@ -274,6 +273,46 @@ function mergeKeys(deps, repo, parent, head) {
   return atParent.filter((key) => atFork.has(key.fingerprint));
 }
 
+// The owner keys for the act of one merge: the keys of mergeKeys, or, for a
+// merge made before the first owner key, the keys at the tip of the default
+// branch within the limits of preKeyKeys (item 65c6c907).
+async function ownerKeys(deps, repo, { parent, head, main }) {
+  const keys = mergeKeys(deps, repo, parent, head);
+  if (keys.length) return { keys };
+  const read = (path) => { try { return deps.gh('GET', path); } catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return null; throw error; } };
+  let first;
+  try { first = await preKeyKeys(read, repo, { parent, branch: main }); } catch (error) { first = { why: `GitHub refused a read of the key file history (${plainText(error?.message ?? error).slice(0, 120)})` }; }
+  return first.keys ? { keys: first.keys, first_key: first.from } : { keys: [], why: first.why };
+}
+
+// Every audit issue of each merge, open or closed, by the kinds of its
+// findings.
+function auditKinds(deps, repo) {
+  const kinds = new Map();
+  for (let page = 1; page <= 10; page += 1) {
+    const rows = deps.gh('GET', `repos/${repo}/issues?state=all&labels=job:gate-audit&per_page=100&page=${page}`) ?? [];
+    for (const one of Array.isArray(rows) ? rows : []) {
+      const hit = AUDIT_ANY.exec(String(one?.title ?? ''));
+      if (hit) kinds.set(hit[2], new Set([...(kinds.get(hit[2]) ?? []), hit[1]]));
+    }
+    if (!Array.isArray(rows) || rows.length < 100) break;
+  }
+  return kinds;
+}
+
+// Why the audit run of a check is not a push run of the audit workflow on
+// the default branch at this merge commit, or null when it is (S3). It
+// answers the job too.
+function auditRunCause(deps, repo, { run, sha, main }) {
+  const job = deps.gh('GET', `repos/${repo}/actions/jobs/${run.id}`);
+  const workflow = job?.run_id ? deps.gh('GET', `repos/${repo}/actions/runs/${job.run_id}`) : null;
+  if (!workflow) return { cause: 'GitHub gave no workflow run for the audit check' };
+  if (workflow.path !== AUDIT_WORKFLOW || workflow.event !== 'push' || workflow.head_branch !== main || workflow.head_sha !== sha) {
+    return { cause: `the audit check is not from a push run of ${AUDIT_WORKFLOW} on ${main} at this merge` };
+  }
+  return { cause: null, job };
+}
+
 // Why the red audit run of one merge is not only "owner-unsigned" for this
 // pull request, or null when it is (security review S1). The run must be a
 // push run of the audit workflow on the default branch at this merge commit
@@ -281,12 +320,8 @@ function mergeKeys(deps, repo, parent, head) {
 // FINDINGS line: the state must be "found", not "broken", and each finding
 // must be owner-unsigned for this merge and this pull request.
 export function auditCause(deps, repo, { run, sha, pr, main }) {
-  const job = deps.gh('GET', `repos/${repo}/actions/jobs/${run.id}`);
-  const workflow = job?.run_id ? deps.gh('GET', `repos/${repo}/actions/runs/${job.run_id}`) : null;
-  if (!workflow) return 'GitHub gave no workflow run for the audit check';
-  if (workflow.path !== AUDIT_WORKFLOW || workflow.event !== 'push' || workflow.head_branch !== main || workflow.head_sha !== sha) {
-    return `the audit check is not from a push run of ${AUDIT_WORKFLOW} on ${main} at this merge`;
-  }
+  const { cause } = auditRunCause(deps, repo, { run, sha, main });
+  if (cause) return cause;
   let log = '';
   try { log = deps.text(`repos/${repo}/actions/jobs/${run.id}/logs`); } catch { return 'the log of the audit check cannot be read'; }
   const lines = String(log ?? '').split('\n').map((one) => one.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z ?/, '').replace(/\r$/, ''));
@@ -324,21 +359,16 @@ export async function auditRow(deps, repo, issue, main, kinds = new Map()) {
   const commit = deps.gh('GET', `repos/${repo}/commits/${sha}`);
   const files = Array.isArray(commit?.files) ? commit.files.map((one) => String(one?.filename ?? '')) : null;
   if (!files) return { ...row, skip: 'GitHub gave no file list of the merge commit' };
-  const own = files.find((path) => AUDIT_CODE.includes(path));
-  if (own) return { ...row, skip: `the merge changed ${own}, so its audit ran its own code: sign it by hand` };
+  const code = auditCodeDiff(commit.files);
+  if (code.unknown) return { ...row, skip: 'GitHub gave no full file list of the merge commit' };
+  if (code.files.length) return { ...row, skip: `the merge changed ${code.files[0]}, so its audit ran its own code: read that diff and sign it with atlas approve audit-code ${row.pr}` };
   const parent = String(commit?.parents?.[0]?.sha ?? '');
   if (!/^[0-9a-f]{40}$/.test(parent)) return { ...row, skip: 'GitHub gave no parent of the merge commit' };
-  let keys = mergeKeys(deps, repo, parent, head);
   // Item 65c6c907: a merge made before the first owner key takes the keys
   // at the tip of the default branch, within the limits of preKeyKeys.
-  let first = null;
-  if (!keys.length) {
-    const read = (path) => { try { return deps.gh('GET', path); } catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return null; throw error; } };
-    try { first = await preKeyKeys(read, repo, { parent, branch: main }); } catch (error) { first = { why: `GitHub refused a read of the key file history (${plainText(error?.message ?? error).slice(0, 120)})` }; }
-    if (first.keys) keys = first.keys;
-  }
-  if (!keys.length) return { ...row, skip: `${SIGNERS_FILE} on the base of this merge holds no owner key, so no act can count: close the issue by hand. No first key counts: ${first?.why ?? 'no reason'}` };
-  return { ...row, run: String(run.id), keys, ...(first?.from ? { first_key: first.from } : {}) };
+  const owner = await ownerKeys(deps, repo, { parent, head, main });
+  if (!owner.keys.length) return { ...row, skip: `${SIGNERS_FILE} on the base of this merge holds no owner key, so no act can count: close the issue by hand. No first key counts: ${owner.why ?? 'no reason'}` };
+  return { ...row, run: String(run.id), keys: owner.keys, ...(owner.first_key ? { first_key: owner.first_key } : {}) };
 }
 
 // `atlas approve audit [<pr>...]`. Exit 0 when each listed red got its act.
@@ -366,15 +396,7 @@ export async function approveAudit({ prs = [], repo, root, key, provider, yes =
   issues.sort((a, b) => Number(a.number) - Number(b.number));
   // Every audit issue of each merge, open or closed: an issue for another
   // finding of the same merge stops its row.
-  const kinds = new Map();
-  for (let page = 1; page <= 10; page += 1) {
-    const rows = deps.gh('GET', `repos/${name}/issues?state=all&labels=job:gate-audit&per_page=100&page=${page}`) ?? [];
-    for (const one of Array.isArray(rows) ? rows : []) {
-      const hit = AUDIT_ANY.exec(String(one?.title ?? ''));
-      if (hit) kinds.set(hit[2], new Set([...(kinds.get(hit[2]) ?? []), hit[1]]));
-    }
-    if (!Array.isArray(rows) || rows.length < 100) break;
-  }
+  const kinds = auditKinds(deps, name);
   line(`  ${issues.length} open audit issue(s) of an owner merge with no touch. Each one can take about 5 seconds.`);
   const rows = [];
   for (const issue of issues) {
@@ -437,11 +459,146 @@ export async function approveAudit({ prs = [], repo, root, key, provider, yes =
   return failed ? 1 : 0;
 }
 
+// ------------------------------------------------------- atlas approve audit-code
+
+// The owner's words for the audit-code red of one merge. The lead records
+// them, word for word, as one decision. They name the pull request as #N,
+// quote the test, and hold the time, as the words of approveAudit do.
+export function auditCodeWords({ pr, sha, files, check }, at) {
+  return `I read the ${AUDIT_CODE_TEST} diff of #${pr} (merge ${sha.slice(0, 7)}): ${files.join(', ')}. I accept its ${AUDIT_CODE_TEST} red of "${check}", listed at ${new Date(at).toISOString().slice(0, 16)}Z.`;
+}
+
+const PASSING = ['success', 'skipped', 'neutral'];
+const RED = ['failure', 'timed_out', 'cancelled', 'action_required', 'startup_failure'];
+
+// The audit of one merge commit with the code of this Mac's Atlas, not the
+// code of the merge. It needs the merge, its head and its parent in the clone
+// at `root`. Returns the findings.
+export function macAudit({ repo, root, sha }) {
+  // The clone must be a clone of this repo, or every commit reads as unread
+  // (security review 2, S2).
+  let origin = '';
+  try { origin = execFileSync('git', ['-C', root, 'remote', 'get-url', 'origin'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { origin = ''; }
+  if (!new RegExp(`^(https://|ssh://git@|git@)github\\.com[:/]${repo.replace(/[.]/g, '\\.')}(\\.git)?$`, 'i').test(origin)) throw new ApproveError(`${root} is not a clone of ${repo}; run the command in the clone`);
+  const found = [];
+  commitAudit({ repo, root, commit: sha, found }, () => {}, ghApi);
+  return found;
+}
+
+// `atlas approve audit-code <pr>` (item f36c6b0f). A merge that changed the
+// audit code ran its own audit, so the batch never signs it. The owner reads
+// the audit-code diff of that one merge here, and one touch signs one
+// accept-code act for its one red audit check. Exit 0 when the act is posted.
+export async function approveAuditCode({ prs = [], repo, root, key, provider, yes = false }, line, deps = DEPS) {
+  if (prs.length !== 1 || !/^[1-9][0-9]{0,8}$/.test(String(prs[0]))) throw new ApproveError('atlas approve audit-code takes one pull request number.');
+  const pr = Number(prs[0]);
+  const name = repoOf({ repo, root });
+  const main = String(deps.gh('GET', `repos/${name}`)?.default_branch ?? '');
+  if (!main) throw new ApproveError(`GitHub gave no default branch of ${name}.`);
+  const pull = deps.gh('GET', `repos/${name}/pulls/${pr}`);
+  const sha = String(pull?.merge_commit_sha ?? '');
+  const head = String(pull?.head?.sha ?? '');
+  if (!pull?.merged_at || !/^[0-9a-f]{40}$/.test(sha) || !/^[0-9a-f]{40}$/.test(head)) throw new ApproveError(`#${pr} is not a merged pull request with a merge commit.`);
+  if (pull.base?.ref !== main) throw new ApproveError(`#${pr} did not merge into ${main}; the push audit runs only there.`);
+  const commit = deps.gh('GET', `repos/${name}/commits/${sha}`);
+  const parent = String(commit?.parents?.[0]?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(parent)) throw new ApproveError('GitHub gave no parent of the merge commit.');
+  // Only a merge commit with two parents lists the whole change of the pull
+  // request against the main branch. A rebase merge lists only its last
+  // commit, so the diff could hide audit code (security review 2, S1).
+  if (!Array.isArray(commit.parents) || commit.parents.length !== 2) throw new ApproveError(`#${pr} did not merge with a merge commit, so its whole diff cannot be shown. Nothing was signed.`);
+  const code = auditCodeDiff(commit?.files);
+  if (code.unknown) throw new ApproveError('GitHub gave no full file list of the merge commit.');
+  if (!code.files.length) throw new ApproveError(`#${pr} changed no audit code. Use atlas approve audit.`);
+  const changed = commit.files.filter((one) => AUDIT_CODE.includes(String(one?.filename ?? '')) || AUDIT_CODE.includes(String(one?.previous_filename ?? '')));
+  const cut = changed.find((one) => typeof one.patch !== 'string' && one.status !== 'removed');
+  if (cut) throw new ApproveError(`GitHub gave no diff of ${plainText(cut.filename)}, so you cannot read it here. Nothing was signed.`);
+  // An audit issue for another finding of this merge stops the act: the
+  // touch accepts the audit-code red only (security review S3 of 0ca9fced).
+  const more = [...(auditKinds(deps, name).get(sha) ?? [])].filter((kind) => kind !== AUDIT_TEST);
+  if (more.length) throw new ApproveError(`another audit issue names this merge: ${more.join(', ')}. Nothing was signed.`);
+  // Every run of each audit check, not only the newest attempt.
+  const all = (deps.gh('GET', `repos/${name}/commits/${sha}/check-runs?filter=all&per_page=100`)?.check_runs ?? []).filter((run) => AUDIT_CHECKS.includes(run?.name));
+  const newest = AUDIT_CHECKS.map((check) => all.filter((run) => run.name === check).sort((a, b) => String(b.started_at ?? '').localeCompare(String(a.started_at ?? '')))[0]).filter(Boolean);
+  const open = newest.find((run) => run.status !== 'completed');
+  if (open) throw new ApproveError(`"${plainText(open.name)}" has not completed on the merge commit. Nothing was signed.`);
+  const red = newest.filter((run) => RED.includes(run.conclusion));
+  const odd = newest.find((run) => !RED.includes(run.conclusion) && !PASSING.includes(run.conclusion));
+  if (odd) throw new ApproveError(`"${plainText(odd.name)}" ended ${plainText(odd.conclusion)}. Nothing was signed.`);
+  if (red.length !== 1) throw new ApproveError(`the merge commit has ${red.length} red audit checks; this command accepts exactly one. Nothing was signed.`);
+  const run = red[0];
+  if (run.app?.id !== ACTIONS_APP_ID || !/^[1-9][0-9]{0,15}$/.test(String(run.id))) throw new ApproveError(`the red "${plainText(run.name)}" is not a GitHub Actions run.`);
+  const pinned = auditRunCause(deps, name, { run, sha, main });
+  if (pinned.cause) throw new ApproveError(`${pinned.cause}. Nothing was signed.`);
+  // The first parent was a main tip of its own push: its push audit ran at
+  // it. So the push of this merge brought this merge commit only, and no
+  // commit past the gate hides under it (security review 2, S1).
+  const before = (deps.gh('GET', `repos/${name}/commits/${parent}/check-runs?filter=all&per_page=100`)?.check_runs ?? [])
+    .filter((one) => AUDIT_CHECKS.includes(one?.name) && one.app?.id === ACTIONS_APP_ID && /^[1-9][0-9]{0,15}$/.test(String(one.id)));
+  if (!before.some((one) => !auditRunCause(deps, name, { run: one, sha: parent, main }).cause)) throw new ApproveError(`the parent ${parent.slice(0, 7)} has no push audit run of its own, so the push of #${pr} may hold more than its merge. Nothing was signed.`);
+  // A force push can put this merge on a parent that drops a later commit
+  // of the main branch. The repo may enforce no branch rule, so the command
+  // reads the force pushes of the branch (security review 3, S2).
+  const forced = deps.gh('GET', `repos/${name}/activity?ref=${encodeURIComponent(`refs/heads/${main}`)}&activity_type=force_push&per_page=100`);
+  if (!Array.isArray(forced)) throw new ApproveError(`GitHub gave no list of the force pushes to ${main}. Nothing was signed.`);
+  if (forced.some((one) => String(one?.after ?? '').toLowerCase() === sha)) throw new ApproveError(`a force push put the merge of #${pr} on ${main}. Nothing was signed.`);
+  // The audit of that run ran the code of this merge, or never ran. So the
+  // Atlas on this Mac audits the merge again with its own code (security
+  // review S2): it must find this owner merge and nothing else.
+  let found;
+  try { found = await (deps.audit ?? macAudit)({ repo: name, root: resolve(root ?? '.'), sha }); }
+  catch (error) { throw new ApproveError(`the audit on this Mac stopped: ${plainText(error?.message ?? error).slice(0, 200)}. Nothing was signed.`); }
+  if (Array.isArray(found) && found.some((one) => one?.pin === 'unread')) throw new ApproveError(`the audit on this Mac could not read the head or the base of #${pr} in this clone. Run git fetch origin pull/${pr}/head, then the command again. Nothing was signed.`);
+  const only = Array.isArray(found) && found.length === 1 && found[0]?.kind === AUDIT_TEST && found[0].sha === sha && Number(found[0].pr) === pr && found[0].key === `${AUDIT_TEST}:${sha}` && found[0].pin === undefined;
+  if (!only) throw new ApproveError(`the audit on this Mac found ${Array.isArray(found) && found.length ? found.map((one) => plainText(one?.key ?? one?.kind)).join(', ') : 'nothing to accept'}, not only ${AUDIT_TEST} for #${pr}. Nothing was signed.`);
+  const owner = await ownerKeys(deps, name, { parent, head, main });
+  if (!owner.keys.length) throw new ApproveError(`${SIGNERS_FILE} holds no owner key that counts for this merge: ${owner.why ?? 'no reason'}.`);
+  line(`atlas approve audit-code: ${name} #${pr} ${plainText(pull.title).slice(0, 120)}`);
+  line(`  merged ${plainText(pull.merged_at)} as ${sha}, head ${head.slice(0, 7)}`);
+  line(`  red: "${plainText(run.name)}" ${plainText(run.conclusion)}, run ${run.id}.`);
+  line(`  The audit on this Mac, with its own code, found only ${AUDIT_TEST} for #${pr}.`);
+  line(`  The merge changed ${commit.files.length} file(s): ${commit.files.map((one) => plainText(one?.filename)).join(', ')}`);
+  if (owner.first_key) line(`  merged before the first owner key: the act counts against the keys at the tip of ${main}, ${owner.first_key.slice(0, 7)}`);
+  line(`Read the audit-code diff of this merge before you touch (${changed.length} file(s)):`);
+  for (const one of changed) {
+    line(`--- ${plainText(one.previous_filename ? `${one.previous_filename} -> ` : '')}${plainText(one.filename)} (${plainText(one.status)})`);
+    for (const each of String(one.patch ?? '').split('\n')) line(`  ${plainText(each)}`);
+  }
+  const words = auditCodeWords({ pr, sha, files: code.files, check: run.name }, deps.now());
+  line('Your words, which the lead records as one decision:');
+  line(`  ${words}`);
+  if (!yes && !(await deps.ask(`You read this diff. Accept the ${AUDIT_CODE_TEST} red of #${pr} with one touch?`))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  const trusted = (deps.trusted ?? trustedKeys)(setup);
+  const strange = owner.keys.filter((one) => !trusted.has(one.fingerprint)).map((one) => one.fingerprint);
+  if (strange.length) {
+    line(`STOP: ${SIGNERS_FILE} holds a key that is not yours: ${strange.join(', ')}.`);
+    line('Nothing was signed. Remove that key in a pull request, or pin it in ~/.config/atlas/signing.json if it is yours.');
+    return 1;
+  }
+  const act = { kind: 'accept-code', repo: name, pr, head, merge: sha, run: String(run.id), diff: code.print, words: wordsFingerprint(words), check: run.name };
+  const payload = payloadText([act], deps.now());
+  line(`Touch the key now (${setup.key}${setup.provider ? `, provider ${setup.provider}` : ''}).`);
+  const signature = deps.sign(payload, setup);
+  const proof = verifyBlock({ payload, signature }, owner.keys);
+  if (proof.error) { line(`The signature does not count for #${pr}: ${proof.error}`); line('Nothing was posted.'); return 1; }
+  const text = `${blockText(payload, signature)}\nThe owner read the ${AUDIT_CODE_TEST} diff of #${pr} and accepts its red with \`atlas approve audit-code\`. His words:\n\n> ${words}\n`;
+  try { deps.gh('POST', `repos/${name}/issues/${pr}/comments`, { body: text }); }
+  catch (error) { line(`#${pr}: GitHub refused the write (${plainText(error?.message ?? error).slice(0, 200)}). Run the command again.`); return 1; }
+  line(`  posted on #${pr}`);
+  line('Now send this one message to the lead, word for word:');
+  line('');
+  line(words);
+  line('');
+  return 0;
+}
+
 // The act that `atlas approve act <kind>` builds from its flags.
 export function actFrom(kind, flags, read = (path) => readFileSync(resolve(path), 'utf8')) {
-  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => each !== 'merge' && each !== 'accept').join(', ')}; a pull request takes atlas approve <pr>.`);
+  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => !['merge', 'accept', 'accept-code'].includes(each)).join(', ')}; a pull request takes atlas approve <pr>.`);
   if (kind === 'merge') throw new ApproveError('a pull request takes atlas approve <pr>, which reads its gate first.');
   if (kind === 'accept') throw new ApproveError('an audit red takes atlas approve audit, which reads the audit issues first.');
+  if (kind === 'accept-code') throw new ApproveError('the audit red of an audit-code merge takes atlas approve audit-code <pr>, which shows its diff first.');
   const need = (flag) => {
     const value = flags[flag];
     if (value === undefined || value === true || value === '') throw new ApproveError(`atlas approve act ${kind} needs --${flag}.`);
@@ -513,6 +670,7 @@ export async function approveCommand({ words = [], repo, root, key, provider, ye
   const common = { key, provider, yes };
   try {
     if (words[0] === 'act') return await approveAct({ ...common, kind: words[1], flags, out }, line, deps);
+    if (words[0] === 'audit-code') return await approveAuditCode({ ...common, prs: words.slice(1), repo, root }, line, deps);
     if (words[0] === 'audit') return await approveAudit({ ...common, prs: words.slice(1), repo, root }, line, deps);
     if (words[0] === 'verify') return approveVerify({ file, signers, root }, line);
     if (words[0] === 'key-check') return await keyCheck(common, line, deps);

package/door/lib/owner-only.mjs

@@ -215,7 +215,7 @@ export function atlasYamlCause(baseText, headText, rules) {
   if (!changed.length) return 'atlas.yaml text changed outside its keys';
   for (const key of changed) {
     if (rules.fixed.includes(key)) return `atlas.yaml key ${key} changed`;
-    if (!rules.add_only.includes(key)) return `atlas.yaml key ${key} changed, and R62 does not list it yet`;
+    if (!rules.add_only.includes(key)) return `atlas.yaml key ${key} changed, and the key list in owner-only.yaml names no rule for it`;
     if (!onlyAdds(a[key], b[key])) return `atlas.yaml key ${key}: an entry was removed, moved or changed`;
   }
   return null;

package/door/lib/signed-act.mjs

@@ -89,6 +89,11 @@ export const ACTS = Object.freeze({
   // S1). It names the fingerprint of the owner's words, not a decision id, so
   // one touch comes before the one message that the lead records.
   accept: { fields: ['repo', 'pr', 'head', 'run', 'words', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) ([1-9][0-9]{0,15}) (${HASH}) ([^\\s].{0,99})` },
+  // The acceptance of the red audit check of one merge that changed the
+  // audit code, made with `atlas approve audit-code` after the owner read
+  // that diff (item f36c6b0f). It names the merge commit and the fingerprint
+  // of its audit-code change, so the touch covers only the diff he read.
+  'accept-code': { fields: ['repo', 'pr', 'head', 'merge', 'run', 'diff', 'words', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) (${SHA}) ([1-9][0-9]{0,15}) (${HASH}) (${HASH}) ([^\\s].{0,99})` },
 });
 
 // The fingerprint that a lock or a decision act names: sha256 of the text,
@@ -105,6 +110,40 @@ export const AUDIT_TEST = 'owner-unsigned';
 // tests, so a release never turns it into a warning (item 9348568f).
 export const AUDIT_CHECKS = Object.freeze(['gate · push audit', AUDIT_CHECK]);
 
+// The files whose change lets a merge write its own audit: every repo file
+// of the gate and audit groups of GATE_FILE_GROUPS in gate-audit.mjs (a test
+// keeps this list a superset), the signed act that the gate reads, and the
+// job file of the audit. `atlas approve audit` never signs a merge that
+// changed one (security review 2 of item 0ca9fced, S3). Such a merge takes
+// an accept-code act instead, and its words quote the test AUDIT_CODE_TEST
+// (item f36c6b0f).
+export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
+export const AUDIT_CODE = Object.freeze([
+  AUDIT_WORKFLOW, '.github/workflows/atlas-gate.yml', '.github/workflows/atlas-jobs.yml',
+  'packages/atlas/bin/atlas', 'packages/atlas/door/cli.mjs', 'packages/atlas/owner-only.yaml', 'packages/atlas/door/jobs/gate-audit.yaml',
+  ...['gate.mjs', 'gate-audit.mjs', 'gate-check.mjs', 'owner-only.mjs', 'jobs.mjs', 'issues.mjs', 'signed-act.mjs'].map((name) => `packages/atlas/door/lib/${name}`),
+  'packages/atlas/shape/check.mjs', 'packages/atlas/work/lib/child-env.mjs',
+]);
+export const AUDIT_CODE_TEST = 'audit-code';
+// GitHub lists at most 300 files of one commit.
+const COMMIT_FILES = 300;
+
+// The audit-code change of one merge commit, from GitHub's file list of that
+// commit: { files, print }, where print is the fingerprint of each changed
+// audit-code file with its state and its blob, or { files: [] } for none. A
+// rename counts by its old name too. A list that is missing or may be cut
+// gives { unknown: true }.
+export function auditCodeDiff(files) {
+  if (!Array.isArray(files) || files.length >= COMMIT_FILES) return { unknown: true };
+  const hits = files.filter((one) => AUDIT_CODE.includes(String(one?.filename ?? '')) || AUDIT_CODE.includes(String(one?.previous_filename ?? '')));
+  if (!hits.length) return { files: [] };
+  const rows = hits.map((one) => `${one.previous_filename ? `${one.previous_filename}>` : ''}${one.filename} ${one.status} ${one.sha ?? '-'}`).sort();
+  // Each file by its name in AUDIT_CODE, never by a new name that a rename
+  // chose, so the words and the refusals hold only names of the list.
+  const named = hits.map((one) => (AUDIT_CODE.includes(String(one.filename)) ? String(one.filename) : String(one.previous_filename)));
+  return { files: [...new Set(named)].sort(), print: fingerprint(rows.join('\n')) };
+}
+
 // The fingerprint that an accept act names: the owner's words with each run
 // of white space made one space, and no space at the ends. A chat can wrap a
 // line or drop a last line end; that does not change the words.

package/door/lib/tooling.mjs

@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, SPECS, SPEC_3, sha256, parseYaml } from '../../shape/check.mjs';
 import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
 import { status } from './status.mjs';
 import { PR_TEMPLATE_PATH } from './upkeep.mjs';
@@ -122,12 +122,43 @@ export function isPackageRepo(root, packageRoot) {
 // refusal that says what to do instead.
 const readWorkflow = (root) => { const full = join(root, WORKFLOW_PATH); return existsSync(full) ? readFileSync(full, 'utf8') : null; };
 
+// The spec 3 lines for a repo whose atlas.yaml is older (roadmap R62). Check
+// version 10 reads spec 3 only, so a copy written into a spec 2 repo would turn
+// its own check red. The lines name the parts this repo already carries: the
+// two entry maps, the index and the two tooling files, plus the rules and a
+// linter config where the repo has them.
+export function specThreeLines(root) {
+  const parts = ['claude-md', 'agents-md'];
+  if (existsSync(join(root, '.claude', 'rules'))) parts.push('rules');
+  parts.push('docs-index', 'check-file', 'gate-workflow');
+  const linters = SPEC_3.files.flatMap((file) => file.parts).find((part) => part.id === 'linters').candidates;
+  if (linters.some((path) => existsSync(join(root, path)))) parts.push('linters');
+  return [`parts: [${parts.join(', ')}]`];
+}
+
+// The spec version atlas.yaml declares, or null when there is no file or it
+// does not read. The check reports those cases itself.
+function declaredSpec(root) {
+  const file = join(root, 'atlas.yaml');
+  if (!existsSync(file)) return null;
+  try { return parseYaml(readFileSync(file, 'utf8'))?.spec ?? null; } catch { return null; }
+}
+
 export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
   const pkg = packagedCheck(packageRoot);
   const own = isPackageRepo(root, packageRoot);
   if (!pkg.latest && !own) {
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
+  const spec = declaredSpec(root);
+  if (spec !== null && !workflowOnly && !SPECS[spec]) {
+    throw new ToolingRefusal([
+      `atlas.yaml is spec ${spec}. Check version ${CHECK_VERSION} reads spec ${Object.keys(SPECS).join(', ')} only.`,
+      'Set spec: 3, remove the kind: line, and add:',
+      ...specThreeLines(root),
+      'Then run atlas tooling again. Nothing was written.',
+    ].join('\n'));
+  }
   const now = status({ root, packageRoot });
   if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !pinnedNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE || workflowKept(root) ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });