@arjunkhera/atlas 0.4.40 → 0.4.41

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -173,6 +173,7 @@ const HELP = `atlas — the door into a repo's Atlas files
       --yes                            sign with no question; the key still needs the touch
   atlas approve act <kind>             sign one other act and print its block: brake-clear --repo --commit, ready --repo --item, lock --item --card <file>, decision --item --words <file>, waiver --repo --pr --head --decision --check
       --out <file>                     write the block here; default the terminal
+  atlas approve audit [<pr>...]        the owner's acceptance of the night's audit reds, on his Mac: list each open audit issue of an owner merge that no touch signed, then one touch signs an accept act for each, the block goes on each pull request, each audit issue closes, and it prints the one message for the lead
   atlas approve verify --file <file>   check each signed block of a file against atlas/owner-signers; exit 0 when one counts
       --signers <file>                 the key file; default atlas/owner-signers under --root
   atlas approve key-check              one touch signs a test text, and the key's own public half checks it: does the key count for the gate

package/door/lib/approve.mjs

@@ -9,6 +9,11 @@
 //   atlas approve act <kind> ...   sign one other act: a brake clear, a ready
 //                                  mark, a lock, a decision or a waiver; print
 //                                  the block
+//   atlas approve audit [<pr>...]  list the open audit reds of owner merges
+//                                  that no touch signed, sign one accept act
+//                                  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 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
@@ -28,7 +33,7 @@ import { parseYaml } from '../../shape/check.mjs';
 import { ghApi, pinnedRuns } from './gate.mjs';
 import { GATE_CHECK } from './gate-check.mjs';
 import {
-  ACTS, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, SignedActError,
+  ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_TEST, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
 } from './signed-act.mjs';
 
 export class ApproveError extends Error {}
@@ -229,10 +234,204 @@ export async function approvePulls({ prs, repo, root, key, provider, yes = false
   return 0;
 }
 
+// ------------------------------------------------------------ atlas approve audit
+
+// The push audit opens one issue for each owner merge that no touch signed
+// (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 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';
+const AUDIT_AUTHOR = 'github-actions[bot]';
+
+// The owner's words for one list. The lead records them, word for word, as
+// one decision. Each pull request is named as #N, and the words quote the test.
+// The time of the list makes the words of each list new, so no second
+// decision, in any state, can take the same touch (security review 2, S3).
+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
+// first parent that are also on the merge base of that parent and the head.
+function mergeKeys(deps, repo, parent, head) {
+  const forkPoint = String(deps.gh('GET', `repos/${repo}/compare/${parent}...${head}`)?.merge_base_commit?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(forkPoint)) return [];
+  const atParent = signersOn(deps, repo, parent).keys;
+  if (forkPoint === parent) return atParent;
+  const atFork = new Set(signersOn(deps, repo, forkPoint).keys.map((key) => key.fingerprint));
+  return atParent.filter((key) => atFork.has(key.fingerprint));
+}
+
+// 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
+// (S3). The filing job's log holds the findings it got, as base64 JSON in its
+// 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`;
+  }
+  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$/, ''));
+  const coded = lines.map((one) => /^ {2}FINDINGS: ([A-Za-z0-9+/=]{1,200000})$/.exec(one)?.[1]).filter(Boolean);
+  if (coded.length !== 1) return 'the log of the audit check holds no single FINDINGS line';
+  let envelope;
+  try { envelope = JSON.parse(Buffer.from(coded[0], 'base64').toString('utf8')); } catch { return 'the findings of the audit do not read'; }
+  if (envelope?.state !== 'found') return `the audit state is ${plainText(envelope?.state).slice(0, 20)}, not found: it may have stopped`;
+  const findings = Array.isArray(envelope.findings) ? envelope.findings : [];
+  if (!findings.length) return 'the audit names no finding';
+  const other = findings.find((one) => one?.job !== 'gate-audit' || one.kind !== AUDIT_TEST || one.sha !== sha || Number(one.pr) !== pr || one.pin !== undefined || one.key !== `${AUDIT_TEST}:${sha}`);
+  if (other) return `the audit also found ${plainText(other?.key ?? other?.kind ?? 'a finding').slice(0, 120)}`;
+  return null;
+}
+
+// One open audit issue, read from GitHub: the pull request that made the
+// merge, its head, and the red audit run. `skip` says why it is not signed.
+export function auditRow(deps, repo, issue, main, kinds = new Map()) {
+  const sha = AUDIT_ISSUE.exec(String(issue.title ?? ''))[1];
+  const row = { issue: Number(issue.number), sha };
+  const pull = (deps.gh('GET', `repos/${repo}/commits/${sha}/pulls`) ?? []).find((each) => each?.merged_at && each.merge_commit_sha === sha);
+  if (!pull) return { ...row, skip: 'no pull request merged this commit' };
+  const head = String(pull.head?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(head)) return { ...row, pr: Number(pull.number), skip: 'GitHub gave no head' };
+  Object.assign(row, { pr: Number(pull.number), head, title: plainText(pull.title).slice(0, 120), merged_at: String(pull.merged_at) });
+  const runs = (deps.gh('GET', `repos/${repo}/commits/${sha}/check-runs?per_page=100`)?.check_runs ?? [])
+    .filter((run) => run?.name === AUDIT_CHECK)
+    .sort((a, b) => String(b.started_at ?? '').localeCompare(String(a.started_at ?? '')));
+  const run = runs[0];
+  if (run?.conclusion !== 'failure' || run.app?.id !== ACTIONS_APP_ID || !/^[1-9][0-9]{0,15}$/.test(String(run.id))) return { ...row, skip: `the newest check "${AUDIT_CHECK}" is ${run?.conclusion ?? 'missing'} on the merge commit, not a red GitHub Actions run` };
+  const cause = auditCause(deps, repo, { run, sha, pr: row.pr, main });
+  if (cause) return { ...row, skip: `${cause}: open the run and the other audit issues` };
+  const more = [...(kinds.get(sha) ?? [])].filter((kind) => kind !== AUDIT_TEST);
+  if (more.length) return { ...row, skip: `another audit issue names this merge: ${more.join(', ')}` };
+  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 parent = String(commit?.parents?.[0]?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(parent)) return { ...row, skip: 'GitHub gave no parent of the merge commit' };
+  const keys = mergeKeys(deps, repo, parent, head);
+  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` };
+  return { ...row, run: String(run.id), keys };
+}
+
+// `atlas approve audit [<pr>...]`. Exit 0 when each listed red got its act.
+export async function approveAudit({ prs = [], repo, root, key, provider, yes = false }, line, deps = DEPS) {
+  const bad = prs.find((pr) => !/^[1-9][0-9]{0,8}$/.test(String(pr)));
+  if (bad !== undefined) throw new ApproveError(`"${bad}" is not a pull request number.`);
+  const only = new Set(prs.map(Number));
+  const name = repoOf({ repo, root });
+  line(`atlas approve audit: reading the open audit issues of ${name}.`);
+  const main = String(deps.gh('GET', `repos/${name}`)?.default_branch ?? '');
+  if (!main) throw new ApproveError(`GitHub gave no default branch of ${name}.`);
+  const issues = [];
+  for (let page = 1; page <= 5; page += 1) {
+    const rows = deps.gh('GET', `repos/${name}/issues?state=open&per_page=100&page=${page}`) ?? [];
+    for (const issue of Array.isArray(rows) ? rows : []) {
+      // Only an issue that the audit job opened counts. Anyone can open an
+      // issue with the same title.
+      if (issue?.pull_request || !AUDIT_ISSUE.test(String(issue?.title ?? ''))) continue;
+      if (issue.user?.login !== AUDIT_AUTHOR || issue.user?.type !== 'Bot') { line(`  #${issue.number} is not counted: the audit job did not open it`); continue; }
+      if (!only.size && (issue.labels ?? []).some((label) => (label?.name ?? label) === ACCEPTED_LABEL)) { line(`  #${issue.number} has the label ${ACCEPTED_LABEL}; the lead closes it after the done tool. Name its pull request to sign it again`); continue; }
+      issues.push(issue);
+    }
+    if (!Array.isArray(rows) || rows.length < 100) break;
+  }
+  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;
+  }
+  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) {
+    const row = auditRow(deps, name, issue, main, kinds);
+    if (only.size && !only.has(row.pr)) continue;
+    rows.push(row);
+  }
+  const sign = rows.filter((row) => !row.skip).slice(0, MAX_ACTS);
+  line(`atlas approve audit: ${name}. Each red below merged while the gate sent it to you, and no touch signed it:`);
+  for (const row of rows) {
+    line(`  issue #${row.issue}  ${row.pr ? `#${row.pr}` : row.sha.slice(0, 7)}${row.head ? ` at ${row.head.slice(0, 7)}` : ''}${row.merged_at ? `  merged ${row.merged_at}` : ''}  ${row.skip ? 'NOT SIGNED' : 'SIGN'}  ${row.title ?? ''}`.trimEnd());
+    if (row.skip) line(`      ${row.skip}`);
+  }
+  if (only.size) for (const pr of only) if (!rows.some((row) => row.pr === pr)) line(`  #${pr} has no open audit issue: nothing to accept.`);
+  if (!sign.length) { line('Nothing to sign: no open audit red can take an act.'); return 1; }
+  if (rows.filter((row) => !row.skip).length > sign.length) line(`One touch signs at most ${MAX_ACTS} acts. Run the command again for the rest.`);
+  const words = auditWords(sign.map((row) => row.pr), deps.now());
+  line('Your words, which the lead records as one decision:');
+  line(`  ${words}`);
+  if (!yes && !(await deps.ask(`Accept the audit red of ${sign.map((row) => `#${row.pr}`).join(', ')} with one touch?`))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  // Every key that the done tool reads must be one the owner trusts on this
+  // Mac, as for a merge act (security review S2 of R72).
+  const trusted = (deps.trusted ?? trustedKeys)(setup);
+  const strange = [...new Set(sign.flatMap((row) => row.keys).filter((one) => !trusted.has(one.fingerprint)).map((one) => one.fingerprint))];
+  if (strange.length) {
+    line(`STOP: ${SIGNERS_FILE} on the base of a merge 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 print = wordsFingerprint(words);
+  const acts = sign.map((row) => ({ kind: 'accept', repo: name, pr: row.pr, head: row.head, run: row.run, words: print, check: AUDIT_CHECK }));
+  const payload = payloadText(acts, deps.now());
+  line(`Touch the key now (${setup.key}${setup.provider ? `, provider ${setup.provider}` : ''}).`);
+  const signature = deps.sign(payload, setup);
+  const block = { payload, signature };
+  for (const row of sign) {
+    const proof = verifyBlock(block, row.keys);
+    if (proof.error) { line(`The signature does not count on the base of #${row.pr}: ${proof.error}`); line('Nothing was posted.'); return 1; }
+  }
+  line('The signature counts on the base of each merge.');
+  const text = `${blockText(payload, signature)}\nThe owner accepts the ${AUDIT_TEST} audit red of ${sign.map((row) => `#${row.pr}`).join(', ')} with \`atlas approve audit\`. His words:\n\n> ${words}\n`;
+  let failed = 0;
+  for (const row of sign) {
+    try {
+      deps.gh('POST', `repos/${name}/issues/${row.pr}/comments`, { body: text });
+      deps.gh('POST', `repos/${name}/issues/${row.issue}/comments`, { body: `The owner accepted this red with \`atlas approve audit\`. The signed block is on #${row.pr}. The lead closes this issue after the done tool records the acceptance.` });
+      deps.gh('POST', `repos/${name}/issues/${row.issue}/labels`, { labels: [ACCEPTED_LABEL] });
+      line(`  posted on #${row.pr}, labelled issue #${row.issue} ${ACCEPTED_LABEL}`);
+    } catch (error) {
+      failed += 1;
+      line(`  #${row.pr}: GitHub refused a write (${plainText(error?.message ?? error).slice(0, 200)}). Run the command again for it.`);
+    }
+  }
+  line('Now send this one message to the lead, word for word:');
+  line('');
+  line(words);
+  line('');
+  return failed ? 1 : 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').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) => each !== 'merge' && each !== 'accept').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.');
   const need = (flag) => {
     const value = flags[flag];
     if (value === undefined || value === true || value === '') throw new ApproveError(`atlas approve act ${kind} needs --${flag}.`);
@@ -304,6 +503,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') 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);
     return await approvePulls({ ...common, prs: words, repo, root }, line, deps);

package/door/lib/signed-act.mjs

@@ -83,12 +83,29 @@ export const ACTS = Object.freeze({
   decision: { fields: ['item', 'words'], form: `(${ID}) (${HASH})` },
   // A waiver of one red check on one pull request head (R17 line 6).
   waiver: { fields: ['repo', 'pr', 'head', 'decision', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) (${ID}) ([^\\s].{0,99})` },
+  // The acceptance of one red audit check run on one merged pull request
+  // head, made with `atlas approve audit` (item 0ca9fced). It names the check
+  // run, so a later red of the same check is not accepted (security review
+  // 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 fingerprint that a lock or a decision act names: sha256 of the text,
 // with line ends made plain.
 export const fingerprint = (text) => createHash('sha256').update(String(text).replace(/\r\n?/g, '\n')).digest('hex');
 
+// The one check and the one test that an accept act may accept: the red
+// filing job of the push audit, for an owner merge with no touch (security
+// review S3). The audit job finds; this job opens the issues and ends red.
+export const AUDIT_CHECK = 'gate · push audit issues';
+export const AUDIT_TEST = 'owner-unsigned';
+
+// 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.
+export const wordsFingerprint = (text) => fingerprint(String(text).replace(/\s+/g, ' ').trim());
+
 // One act line from its fields, checked against its form.
 export function actLine(act) {
   const spec = ACTS[act?.kind];

package/package.json

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

@@ -112,7 +112,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 |
+| `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 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 } from '../../door/lib/signed-act.mjs';
+import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct, wordsFingerprint, AUDIT_CHECK, AUDIT_TEST } 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']);
@@ -96,7 +96,7 @@ export function latestCheckRuns(runs) {
       // clears it, and any other later conclusion leaves it standing.
       const superseded = sorted.slice(0, -1).filter((run) => FATAL_CONCLUSIONS.includes(run.conclusion ?? ''))
         .map((run) => ({ conclusion: run.conclusion, url: run.html_url ?? '', completed_at: run.completed_at ?? null }));
-      return { name, conclusion: last.conclusion ?? null, status: last.status ?? null, url: last.html_url ?? '', completed_at: last.completed_at ?? null, attempts: sorted.length, ...(superseded.length ? { superseded_failures: superseded } : {}) };
+      return { name, id: last.id ?? null, conclusion: last.conclusion ?? null, status: last.status ?? null, url: last.html_url ?? '', completed_at: last.completed_at ?? null, attempts: sorted.length, ...(superseded.length ? { superseded_failures: superseded } : {}) };
     })
     .sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -441,7 +441,11 @@ export function createDeliveryVerbs(core) {
   // The act names the repo, the pull request, its head, the decision and the
   // check. The key must be in atlas/owner-signers on the base of the merge,
   // its first parent, so a key that the pull request added does not count.
-  async function signedWaiver(pull, decisionId, check) {
+  // Item 0ca9fced: an accept act from `atlas approve audit` counts too. It
+  // names the fingerprint of the decision's words in place of its id, so the
+  // owner touches once before he sends the words that the lead records.
+  async function signedWaiver(pull, decision, check, testName, decisions) {
+    const decisionId = decision.id;
     const head = String(pull.head_sha ?? '').toLowerCase();
     if (!/^[0-9a-f]{40}$/.test(head)) refuse(`GitHub names no head commit of ${pull.url}, so no signed waiver can match it`);
     const commit = await github(`repos/${pull.repo}/commits/${pull.merge_commit_sha}`);
@@ -467,12 +471,27 @@ export function createDeliveryVerbs(core) {
       if (!Array.isArray(rows) || rows.length < 100) break;
     }
     const verified = verifyTexts(texts, keys);
-    const found = findAct(verified, { kind: 'waiver', repo: pull.repo, pr: pull.number, head, decision: decisionId, check });
+    const words = typeof decision.fields?.text === 'string' ? decision.fields.text : '';
+    let found = findAct(verified, { kind: 'waiver', repo: pull.repo, pr: pull.number, head, decision: decisionId, check });
+    // An accept act takes only the push audit's red of an owner merge
+    // (security review S3). Its words name no decision, so exactly one
+    // standing decision may hold them: a second decision with the same words
+    // 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) {
+      const print = wordsFingerprint(words);
+      found = findAct(verified, { kind: 'accept', repo: pull.repo, pr: pull.number, head, 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`);
+      }
+    }
     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`);
+      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`);
     }
-    return { key: found.key, signed_at: found.signed_at };
+    return { key: found.key, signed_at: found.signed_at, act: found.act.kind, ...(found.act.kind === 'accept' ? { run: String(found.act.run) } : {}) };
   }
 
   async function acceptedRed(value, pulls, item) {
@@ -480,7 +499,7 @@ export function createDeliveryVerbs(core) {
     if (!Array.isArray(value)) refuse('accepted_red must be an array of { pr, check, test, decision_id }');
     if (value.length > MAX_ACCEPTED_RED) refuse(`accepted_red holds at most ${MAX_ACCEPTED_RED} entries`);
     const decisionType = await typeNamed('decision');
-    let replacedIds = null;
+    let replacedIds = null, allDecisions = null;
     const rows = [], seen = new Set();
     for (const entry of value) {
       if (!entry || typeof entry !== 'object' || Array.isArray(entry)) refuse('each accepted_red entry must be an object { pr, check, test, decision_id }');
@@ -512,7 +531,8 @@ export function createDeliveryVerbs(core) {
       if (!ACCEPTING_KINDS.includes(said.kind)) refuse(`decision ${decisionId} is a ${said.kind} record; the owner accepts a red check with a decision or an answer`);
       if (!(Array.isArray(said.items) ? said.items : []).includes(item.id)) refuse(`decision ${decisionId} does not name item ${item.id}; the owner's acceptance is recorded on the item it delivers`);
       // A decision the owner later replaced no longer stands (finding 4).
-      replacedIds ??= new Set((await client.listAllEntities({ type: decisionType.name, state: 'any' })).map((row) => row.fields?.replaces).filter(Boolean));
+      allDecisions ??= await client.listAllEntities({ type: decisionType.name, state: 'any' });
+      replacedIds ??= new Set(allDecisions.map((row) => row.fields?.replaces).filter(Boolean));
       if (replacedIds.has(decision.id)) refuse(`decision ${decisionId} is replaced by a later decision; it no longer stands`);
       const words = typeof said.text === 'string' ? said.text : '';
       const source = typeof said.source === 'string' ? said.source : '';
@@ -522,7 +542,7 @@ export function createDeliveryVerbs(core) {
         || new RegExp(`(?:^|[^A-Za-z0-9_/.-])#${pull.number}(?![0-9])`).test(words);
       if (!namesPull) refuse(`decision ${decisionId} does not name ${pull.url}; the owner's words must name the pull request (its URL or #${pull.number})`);
       if (!words.includes(testName)) refuse(`decision ${decisionId} does not quote the test "${testName}"; the owner's own words must name the exact test`);
-      const waiver = await signedWaiver(pull, decision.id, check);
+      const waiver = await signedWaiver(pull, decision, check, testName, allDecisions);
       rows.push({ pr: pull.url, check, test: testName, decision_id: decision.id, decision_version: decision.version ?? null, waiver, decision });
     }
     return rows;
@@ -688,6 +708,9 @@ export function createDeliveryVerbs(core) {
         for (const row of mine) {
           const run = failed.find((one) => one.name === row.check);
           if (!run) refuse(`accepted_red names check ${row.check} on ${pull.url}, but that check is not red in the merge gate; drop the entry`);
+          // An accept act names the red run the owner's Mac read, so a later
+          // red of the same check is not accepted (security review S1).
+          if (row.waiver.run && String(run.id) !== row.waiver.run) refuse(`the accept act on ${pull.url} names run ${row.waiver.run} of ${row.check}, but the newest red run is ${run.id}; the owner runs atlas approve audit again`);
           const { decision: _record, ...kept } = row;
           acceptedRows.push({ ...kept, conclusion: run.conclusion, run_url: run.url,
             detail: `${row.check} concluded ${run.conclusion} for ${pull.url}. The owner accepted the red test "${row.test}" in decision ${row.decision_id}, and signed the waiver with key ${row.waiver.key}. The gate names the check, not the test, so the verb proved the check level only.` });

package/work/mcp.mjs

@@ -69,7 +69,7 @@ const TOOL_LIST = [
   { name: 'question_ask', description: `Ask the owner one question that blocks work on an item, and say what waiting costs. When: an agent is blocked and cannot decide by itself. The question shows in the "Needs me" view until it is answered. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'text', 'item_id', 'product', 'cost'], properties: { request_id: REQUEST_ID, text: S('The question, in plain words, answerable without opening a source.'), item_id: S('Entity id of the work item the question blocks.'), product: S('Product id of that item.'), cost: S(`What waiting costs. One of: ${COSTS.map((cost) => `${cost} (${COST_MEANING[cost]})`).join('; ')}.`), context: { type: 'object', description: 'What the owner needs to answer without opening a source.', properties: { current_behavior: S('What happens today.'), change: S('What would change.'), affected: { type: 'array', items: { type: 'string' }, description: 'Parts that change.' }, options: { type: 'array', items: { type: 'string' }, description: 'The options, one per entry.' }, consequences: S('What follows from each option.'), sources: { type: 'array', items: { type: 'string' }, description: 'Absolute http or https URLs that back the context.' } } } }, additionalProperties: false } },
   { name: 'question_answer', description: `Record the owner's answer to one open question. One call writes the decision in the owner's words, keeps the rendered answer as a receipt, and closes the question, so the "Needs me" view loses the row. Refuses an unknown question and one that is already answered. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'question_id', 'text', 'date'], properties: { request_id: REQUEST_ID, question_id: S('Entity id of the open question.'), text: S("The owner's answer, verbatim."), date: S('ISO date the owner said it, in the form YYYY-MM-DD.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), kind: S(`One of ${DECISION_KINDS.join(', ')}. Default answer.`), items: { type: 'array', items: { type: 'string' }, description: 'Item ids the decision touches. Default: the question\'s item.' }, priority_order: { type: 'array', items: { type: 'string' }, description: 'Item ids in the order the owner set.' }, replaces: S('Entity id of the decision this one replaces.'), rendered: S('The view text the owner acted on. Default: the question and the answer.'), view: S('Which view the owner read, for example needs-me.') }, additionalProperties: false } },
   { name: 'decision_record', description: `Record what the owner decided outside a question, in their own words. Refuses missing text and a missing date. Pass rendered to keep the view the owner acted on as a receipt in the same call. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'text', 'date'], properties: { request_id: REQUEST_ID, text: S("The owner's words, verbatim."), date: S('ISO date the owner said it.'), source: S('Where the words are on record.'), kind: S(`One of ${DECISION_KINDS.join(', ')}. Default decision.`), product: S('Product id the decision is about.'), items: { type: 'array', items: { type: 'string' }, description: 'Item ids the decision touches.' }, priority_order: { type: 'array', items: { type: 'string' }, description: 'Item ids in the order the owner set.' }, replaces: S('Entity id of the decision this one replaces.'), rendered: S('The view text the owner acted on.'), view: S('Which view the owner read.') }, additionalProperties: false } },
-  { name: 'item_done', description: `Mark an item delivered. What proves it follows the repo kind (amendment A1.7). A service or schema repo gets the three read-only live checks: the deployed commit carries the pull requests, the health endpoint answers, and a functional check scoped to the change passes. Every check is a GET. The merge state of each pull request and the gate runs come from GitHub; the caller supplies none of them, and a red gate (${FATAL_CONCLUSIONS.join(', ')}) refuses the mark. One exception, a last resort for an extraordinary case with no other option: the owner can accept a known red test on one merged pull request. Name it in accepted_red with the decision that records the owner's words; those words must name the pull request and quote the exact test, and one decision accepts one red check. The owner must also sign a waiver act for the repo, the pull request, its head, the decision and the check (atlas approve act waiver) and post the block on the pull request; the key must be in atlas/owner-signers on the base of the merge. The gate names a check, not a test, so the verb proves the check level, and every other red check still refuses the mark. A library repo has no deploy target, so its delivery is proven by the merge and the gate alone: pass no functional, and the product needs no health_url. A schema repo keeps the three checks, because its migration runs after the merge. When atlas.yaml on the base of a merge lists required_checks, each one needs a successful newest GitHub Actions run on the pull request head or on the merge commit; a skipped check and a check that never ran are named apart. When atlas.yaml says live: release, a published release must hold each merge commit, and the mark stores that version; a red run on the merge commit is then a warning on the mark, because the release was built from a later green main. An item with no registered repo, or a repo whose kind was never set, keeps the three checks. The delivering agent calls this; the lead calls it to catch up a delivery made outside a session. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'prs'], properties: { request_id: REQUEST_ID, item_id: S('Item id. The item must be active. Unless every repo it names is a library, its product must carry a health_url.'), prs: { type: 'array', items: { type: 'string' }, description: 'The merged GitHub pull request URLs this delivery shipped. Required: the item\'s own pr links are not read, because a link can be a design or a lock, not a delivery.' }, functional: { type: 'object', required: ['url', 'contains'], description: 'The read-only functional check. Required for a service or schema repo, and refused for a library repo. The verb GETs this URL once. No method, body or headers are accepted.', properties: { url: S('Absolute URL on the product health endpoint\'s origin, under one of the product\'s check_paths, and not the health endpoint itself.'), contains: { type: 'array', items: { type: 'string' }, description: 'Required. Strings the answer must carry, chosen so they exist only because of this change. Only whether each was found is recorded; the answer itself never enters the graph.' }, status: { type: 'number', description: 'Expected HTTP status, 2xx only. Default 200.' } } }, note: S('One line on what was delivered.'), accepted_red: { type: 'array', description: 'Red checks the owner accepted, one entry for each pull request and check. The decision must be a decision or an answer on this item, written by decision_record or question_answer and not replaced. Its words must name the pull request and quote the test. One decision accepts one check on one pull request. A listed check that is not red is refused.', items: { type: 'object', required: ['pr', 'check', 'test', 'decision_id'], additionalProperties: false, properties: { pr: S('One of the prs of this delivery.'), check: S('The name of the red check run in the merge gate, for example "test".'), test: S('The exact name of the red test, as the owner\'s words quote it.'), decision_id: S('The decision that records the owner\'s acceptance.') } } } }, additionalProperties: false } },
+  { name: 'item_done', description: `Mark an item delivered. What proves it follows the repo kind (amendment A1.7). A service or schema repo gets the three read-only live checks: the deployed commit carries the pull requests, the health endpoint answers, and a functional check scoped to the change passes. Every check is a GET. The merge state of each pull request and the gate runs come from GitHub; the caller supplies none of them, and a red gate (${FATAL_CONCLUSIONS.join(', ')}) refuses the mark. One exception, a last resort for an extraordinary case with no other option: the owner can accept a known red test on one merged pull request. Name it in accepted_red with the decision that records the owner's words; those words must name the pull request and quote the exact test, and one decision accepts one red check. The owner must also sign a waiver act for the repo, the pull request, its head, the decision and the check (atlas approve act waiver) and post the block on the pull request; for the push audit red of an owner merge, the accept act that atlas approve audit posts counts too, when the decision's words are the words it printed; the key must be in atlas/owner-signers on the base of the merge. The gate names a check, not a test, so the verb proves the check level, and every other red check still refuses the mark. A library repo has no deploy target, so its delivery is proven by the merge and the gate alone: pass no functional, and the product needs no health_url. A schema repo keeps the three checks, because its migration runs after the merge. When atlas.yaml on the base of a merge lists required_checks, each one needs a successful newest GitHub Actions run on the pull request head or on the merge commit; a skipped check and a check that never ran are named apart. When atlas.yaml says live: release, a published release must hold each merge commit, and the mark stores that version; a red run on the merge commit is then a warning on the mark, because the release was built from a later green main. An item with no registered repo, or a repo whose kind was never set, keeps the three checks. The delivering agent calls this; the lead calls it to catch up a delivery made outside a session. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'prs'], properties: { request_id: REQUEST_ID, item_id: S('Item id. The item must be active. Unless every repo it names is a library, its product must carry a health_url.'), prs: { type: 'array', items: { type: 'string' }, description: 'The merged GitHub pull request URLs this delivery shipped. Required: the item\'s own pr links are not read, because a link can be a design or a lock, not a delivery.' }, functional: { type: 'object', required: ['url', 'contains'], description: 'The read-only functional check. Required for a service or schema repo, and refused for a library repo. The verb GETs this URL once. No method, body or headers are accepted.', properties: { url: S('Absolute URL on the product health endpoint\'s origin, under one of the product\'s check_paths, and not the health endpoint itself.'), contains: { type: 'array', items: { type: 'string' }, description: 'Required. Strings the answer must carry, chosen so they exist only because of this change. Only whether each was found is recorded; the answer itself never enters the graph.' }, status: { type: 'number', description: 'Expected HTTP status, 2xx only. Default 200.' } } }, note: S('One line on what was delivered.'), accepted_red: { type: 'array', description: 'Red checks the owner accepted, one entry for each pull request and check. The decision must be a decision or an answer on this item, written by decision_record or question_answer and not replaced. Its words must name the pull request and quote the test. One decision accepts one check on one pull request. A listed check that is not red is refused.', items: { type: 'object', required: ['pr', 'check', 'test', 'decision_id'], additionalProperties: false, properties: { pr: S('One of the prs of this delivery.'), check: S('The name of the red check run in the merge gate, for example "test".'), test: S('The exact name of the red test, as the owner\'s words quote it.'), decision_id: S('The decision that records the owner\'s acceptance.') } } } }, additionalProperties: false } },
   { name: 'item_reopen', description: `Reopen a delivered item: the lifecycle goes back to active and a reopen mark is appended, citing the failed check by URL. The delivery mark is never erased; the reopen points at it with the corrects relation. The owner, or the lead in this session, calls it. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason', 'failed_check'], properties: { request_id: REQUEST_ID, item_id: S('Item id carrying at least one delivery mark.'), reason: S('Why it is reopened, in plain words.'), failed_check: S('Absolute URL of the check that failed: a CI run, a monitor, an issue.'), corrects: S('Mark id of the delivery this reopen corrects. Default: the item\'s latest delivery mark.') }, additionalProperties: false } },
   { name: 'in_flight', description: 'Answer "what are we working on, and what changed since a date?". Active items per product, ordered by the owner\'s current priority decision first, when it carries an order, then by days since the last change with the latest on top, and the days shown on each row. Each row says what the item waits on. Movement is read from the marks and from each registered repo\'s recent pull requests: the item\'s own pr links, plus any pull request whose title, body or branch names the item id. Merged pull requests with no delivery mark are listed as "merged, not marked". A legacy seal reads as a delivery mark with verdict "legacy". Computed at read time and never stored. Scope: read, every role.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Adds what was delivered since then.') }, additionalProperties: false } },
   { name: 'needs_me', description: 'Answer "what needs me?": every open question on a proposed, active or paused item, per product, ordered by what waiting costs. A row on an item that is not active names its lifecycle. Each row is three lines, the question, the item and the cost, with the context folded under it. Computed at read time and never stored. Scope: read, every role. Pass the row text back as rendered when the owner answers.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.') }, additionalProperties: false } },