@arjunkhera/atlas 0.4.46 → 0.4.47

package/.claude-plugin/plugin.json

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

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/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/package.json

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

package/skills/lead/SKILL.md

@@ -114,7 +114,7 @@ set. A test keeps the two lists equal.
 | `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
 | `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names and stale pages. In a pull request it also reads the tracker item, the changed designs, and STE on the changed lines. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
-| `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`; record its printed words as one decision for `item_done`, then close each issue |
+| `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`, and `audit-code <pr>` per audit-code merge; record its words as one decision, then close each issue |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 
 A person merges every file that `atlas tooling` writes.

package/work/lib/delivery.mjs

@@ -16,7 +16,7 @@ import { refuse, text, isoDate, url, stringList, sha256, repoKinds, LIVE_KINDS }
 import { oneLine, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine, blockersOf, blocksOf, blockedPhrase, waitsShown } from './questions.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { ACTIONS_APP_ID } from '../../door/lib/gate.mjs';
-import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct, wordsFingerprint, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, preKeyKeys } from '../../door/lib/signed-act.mjs';
+import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct, wordsFingerprint, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, AUDIT_CODE_TEST, auditCodeDiff, preKeyKeys } from '../../door/lib/signed-act.mjs';
 
 export const DELIVERY_WRITE_VERBS = Object.freeze(['item_done', 'item_reopen']);
 export const DELIVERY_READ_VERBS = Object.freeze(['in_flight']);
@@ -467,8 +467,22 @@ export function createDeliveryVerbs(core) {
     // act for the push audit red may count, against the keys at the tip of
     // the default branch (preKeyKeys in signed-act.mjs holds the limits). The
     // audit runs only on the default branch, so the merge must be into it.
+    // Item f36c6b0f: the red audit check of a merge that changed the audit
+    // code takes only an accept-code act, which names the merge and the
+    // fingerprint of its audit-code change. An accept act never takes such
+    // a merge: the batch of atlas approve audit does not show its diff.
+    const auditRed = check === AUDIT_CHECK && testName === AUDIT_TEST;
+    const codeRed = AUDIT_CHECKS.includes(check) && testName === AUDIT_CODE_TEST;
+    let code = null;
+    if (auditRed || codeRed) {
+      code = auditCodeDiff(commit?.files);
+      if (code.unknown) refuse(`GitHub gave no full file list of the merge commit of ${pull.url}, so no accept act can be checked`);
+      if (auditRed && code.files.length) refuse(`${pull.url} changed the audit code (${code.files.join(', ')}), so an accept act does not count; the owner reads that diff and signs with atlas approve audit-code ${pull.number}, and the test is "${AUDIT_CODE_TEST}"`);
+      if (codeRed && (!Array.isArray(commit?.parents) || commit.parents.length !== 2)) refuse(`${pull.url} did not merge with a merge commit, so its audit-code diff is not its whole change; an accept-code act does not count`);
+      if (codeRed && !code.files.length) refuse(`${pull.url} changed no audit code, so the test "${AUDIT_CODE_TEST}" does not apply; the owner signs with atlas approve audit`);
+    }
     let prekey = null;
-    if (!keys.length && check === AUDIT_CHECK && testName === AUDIT_TEST) {
+    if (!keys.length && (auditRed || codeRed)) {
       const main = (await github(`repos/${pull.repo}`))?.default_branch;
       prekey = typeof main === 'string' && main === pull.base
         ? await preKeyKeys(githubOrNull, pull.repo, { parent, branch: main })
@@ -491,9 +505,11 @@ export function createDeliveryVerbs(core) {
     // cannot carry the touch to items the owner never named (review S2). The
     // words hold the time of the list, and a decision in any state counts,
     // so a replaced decision cannot hand the touch on (review 2, S3).
-    if (!found && words.trim() && check === AUDIT_CHECK && testName === AUDIT_TEST) {
+    if (!found && words.trim() && (auditRed || codeRed)) {
       const print = wordsFingerprint(words);
-      found = findAct(verified, { kind: 'accept', repo: pull.repo, pr: pull.number, head, words: print, check });
+      found = auditRed
+        ? findAct(verified, { kind: 'accept', repo: pull.repo, pr: pull.number, head, words: print, check })
+        : findAct(verified, { kind: 'accept-code', repo: pull.repo, pr: pull.number, head, merge: String(pull.merge_commit_sha).toLowerCase(), diff: code.print, words: print, check });
       if (found) {
         const same = decisions.filter((row) => typeof row.fields?.text === 'string' && wordsFingerprint(row.fields.text) === print);
         if (same.length !== 1 || same[0].id !== decisionId) refuse(`the accept act on ${pull.url} matches the words of ${same.length} decisions; exactly one decision, in any state, may hold the words the owner signed`);
@@ -501,9 +517,9 @@ export function createDeliveryVerbs(core) {
     }
     if (!found) {
       const why = verified.find((row) => row.error)?.error;
-      refuse(`accepted_red needs the owner's signed waiver on ${pull.url} for check ${check}, head ${head.slice(0, 12)} and decision ${decisionId}; none counts${why ? ` (a block was refused: ${why})` : ''}. The owner runs: atlas approve act waiver, and posts the block on the pull request; or, for an audit red, atlas approve audit, and the decision holds the words it printed`);
+      refuse(`accepted_red needs the owner's signed waiver on ${pull.url} for check ${check}, head ${head.slice(0, 12)} and decision ${decisionId}; none counts${why ? ` (a block was refused: ${why})` : ''}. The owner runs: atlas approve act waiver, and posts the block on the pull request; or, for an audit red, atlas approve audit (atlas approve audit-code <pr> for a merge that changed the audit code), and the decision holds the words it printed`);
     }
-    return { key: found.key, signed_at: found.signed_at, act: found.act.kind, ...(found.act.kind === 'accept' ? { run: String(found.act.run) } : {}), ...(prekey?.from ? { first_key: prekey.from } : {}) };
+    return { key: found.key, signed_at: found.signed_at, act: found.act.kind, ...(['accept', 'accept-code'].includes(found.act.kind) ? { run: String(found.act.run) } : {}), ...(prekey?.from ? { first_key: prekey.from } : {}) };
   }
 
   async function acceptedRed(value, pulls, item) {