@arjunkhera/atlas 0.4.19 → 0.4.21

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -40,6 +40,7 @@ import { afterCommand as testsAfter } from './lib/passes-after.mjs';
 import { upkeepCommand } from './lib/upkeep.mjs';
 import { gateCommand, mergeList } from './lib/gate.mjs';
 import { judgeCommand } from './lib/judge.mjs';
+import { approveCommand } from './lib/approve.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ATLAS_VERSION = packagePackageVersion(PACKAGE_ROOT);
@@ -153,6 +154,7 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
   atlas gate audit --repo <owner/name> --commit <sha>   one commit on the main branch: red when no pull request merged it, or one merged it before its checks were green
   atlas gate check --base <ref> --head <sha>   the gate: judge a pull request with this copy of Atlas; success, owner or red
+      --pr <n> --base-ref <branch>     with --repo: read the comments of the pull request, and let the owner's signed act for this base and head clear owner
       --root <repo>                    the clone that holds both commits (default: this folder); the head is read as git data only
       --body <file>                    the pull request text, for the "behaviour change: no" of a refactor
       --json                           print the answer as JSON
@@ -162,6 +164,17 @@ const HELP = `atlas — the door into a repo's Atlas files
       --branch <name>                  the branch; default origin/HEAD
       --json                           print the answer as JSON
 
+  atlas approve <pr>...                the owner's signed act, on his Mac: show the gate's class and cause for each pull request, then one touch signs every one the gate sent to the owner, and the block goes on each as a comment
+      --repo <owner/name>              the repo; default the repo that atlas.yaml names
+      --key <file>                     the security key; default ~/.ssh/atlas_signing_key, or the key in ~/.config/atlas/signing.json
+      --provider <file>                the security key provider; default /usr/lib/ssh-keychain.dylib on a Mac (Touch ID)
+      --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 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
+
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
   atlas judge run <tasks.md> <id> --out <dir>   one fresh agent does one sealed task, in a clean clone at the sealed commit
@@ -202,7 +215,8 @@ export const FLAGS = Object.freeze({
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
+  approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -451,7 +465,12 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch }, line);
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch }, line);
+}
+
+function approveVerb(chosen) {
+  const flags = { repo: chosen.repo, commit: chosen.commit, item: chosen.item, card: chosen.card, words: chosen.words, pr: chosen.pr, head: chosen.head, decision: chosen.decision, check: chosen.check };
+  return approveCommand({ words: chosen._.slice(1), repo: chosen.repo, root: chosen.root === undefined ? undefined : rootOf(chosen), key: chosen.key, provider: chosen.provider, yes: Boolean(chosen.yes), out: chosen.out, file: chosen.file, signers: chosen.signers, flags }, line);
 }
 
 function judgeVerb(chosen) {
@@ -497,6 +516,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'upkeep': return upkeepVerb(chosen);
     case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(chosen);
+    case 'approve': return approveVerb(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }
 }

package/door/lib/approve.mjs

@@ -0,0 +1,311 @@
+// `atlas approve`: the owner's signed act (roadmap R72, tracker item 0c68a105;
+// design docs/design-docs/signed-act/). It runs on the owner's Mac. One touch
+// of his security key signs a batch.
+//
+//   atlas approve <pr>...          show each pull request with the class and
+//                                  the cause from its gate run, sign the ones
+//                                  the gate sent to the owner, and post the
+//                                  signed block on each
+//   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 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
+//                                  key's own public half: does it need a touch?
+//
+// The signature comes from `ssh-keygen -Y sign` with the owner's security key.
+// A Touch ID key on macOS 26 needs the provider /usr/lib/ssh-keychain.dylib;
+// a hardware key needs an ssh-keygen that reads it. No signing call runs in a
+// test: each one takes `deps`, which a test replaces.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { homedir, tmpdir, platform } from 'node:os';
+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 { GATE_CHECK } from './gate-check.mjs';
+import {
+  ACTS, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, SignedActError,
+} from './signed-act.mjs';
+
+export class ApproveError extends Error {}
+
+const ACTIONS_APP_ID = 15368;
+export const TOUCH_ID_PROVIDER = '/usr/lib/ssh-keychain.dylib';
+export const DEFAULT_KEY = join('.ssh', 'atlas_signing_key');
+// The programs and providers that may sign, by full path only, so a program
+// early on PATH or a provider that an agent wrote cannot see the touch
+// (security review S2). A Homebrew path is writable by the user: the
+// remaining risk is in the design, Security.
+export const SSH_KEYGEN = Object.freeze(['/usr/bin/ssh-keygen', '/opt/homebrew/bin/ssh-keygen', '/usr/local/bin/ssh-keygen']);
+export const PROVIDERS = Object.freeze([TOUCH_ID_PROVIDER, 'internal']);
+
+// No control character, no C1 character and no bidi mark of a remote string
+// reaches the owner's terminal (security review S1).
+export const plainText = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, ' ');
+
+// The key, the provider, the program and the pinned keys: the flags first,
+// then ~/.config/atlas/signing.json, then the defaults. On a Mac with the
+// Touch ID provider, the provider is set. Only a provider and a program from
+// the lists above may sign.
+export function signingSetup({ key, provider, home = homedir(), os = platform(), exists = existsSync } = {}) {
+  let saved = {};
+  const file = join(home, '.config', 'atlas', 'signing.json');
+  if (exists(file)) {
+    try { saved = JSON.parse(readFileSync(file, 'utf8')) ?? {}; } catch { throw new ApproveError(`${file} is not JSON.`); }
+  }
+  const keyPath = typeof key === 'string' ? key : typeof saved.key === 'string' ? saved.key : join(home, DEFAULT_KEY);
+  let chosen = typeof provider === 'string' ? provider : typeof saved.provider === 'string' ? saved.provider : null;
+  if (chosen === null && os === 'darwin' && exists(TOUCH_ID_PROVIDER)) chosen = TOUCH_ID_PROVIDER;
+  if (chosen && !PROVIDERS.includes(chosen)) throw new ApproveError(`the provider ${plainText(chosen)} is not one of ${PROVIDERS.join(', ')}.`);
+  const program = typeof saved.ssh_keygen === 'string' ? saved.ssh_keygen : SSH_KEYGEN.find((path) => exists(path)) ?? SSH_KEYGEN[0];
+  if (!SSH_KEYGEN.includes(program)) throw new ApproveError(`ssh_keygen ${plainText(program)} is not one of ${SSH_KEYGEN.join(', ')}.`);
+  const pinned = Array.isArray(saved.pinned) ? saved.pinned.filter((one) => typeof one === 'string') : [];
+  return { key: resolve(keyPath.replace(/^~(?=\/)/, home)), provider: chosen || null, program, pinned };
+}
+
+// The fingerprints the owner trusts on this Mac: his own key's public half,
+// and the keys he pinned in signing.json.
+export function trustedKeys(setup, read = (path) => readFileSync(path, 'utf8')) {
+  const out = new Set(setup.pinned ?? []);
+  try {
+    const own = parseSigners(`owner ${read(`${setup.key}.pub`).trim()}`).keys[0];
+    if (own) out.add(own.fingerprint);
+  } catch { /* no public half here */ }
+  return out;
+}
+
+// One signature of `payload` with the owner's key. ssh-keygen asks for the
+// touch; its prompt goes to this terminal.
+export function sshSign(payload, { key, provider, program = SSH_KEYGEN[0] }) {
+  const folder = mkdtempSync(join(tmpdir(), 'atlas-approve-'));
+  try {
+    const file = join(folder, 'act.txt');
+    writeFileSync(file, payload);
+    const env = { ...childEnvironment(), ...(provider ? { SSH_SK_PROVIDER: provider } : {}) };
+    const run = spawnSync(program, ['-Y', 'sign', '-n', NAMESPACE, '-f', key, file], { env, stdio: ['inherit', 'inherit', 'inherit'] });
+    if (run.error) throw new ApproveError(`ssh-keygen cannot run: ${run.error.message}`);
+    if (run.status !== 0) throw new ApproveError('ssh-keygen did not sign. Touch the key when it asks, and check the key path.');
+    return readFileSync(`${file}.sig`, 'utf8');
+  } finally { rmSync(folder, { recursive: true, force: true }); }
+}
+
+// Raw text from `gh api`, for a job log.
+export function ghText(path) {
+  return execFileSync('gh', ['api', path], { encoding: 'utf8', env: childEnvironment(), stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+}
+
+async function askYes(question) {
+  if (!process.stdin.isTTY) return false;
+  const reader = createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await reader.question(`${question} [y/N] `)).trim()); } finally { reader.close(); }
+}
+
+const DEPS = { gh: ghApi, text: ghText, sign: sshSign, ask: askYes, now: () => new Date() };
+
+const repoOk = (repo) => typeof repo === 'string' && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
+
+function repoOf({ repo, root }) {
+  if (repo !== undefined && repo !== true) {
+    if (!repoOk(repo)) throw new ApproveError('--repo must be <owner>/<name>.');
+    return repo;
+  }
+  const file = join(resolve(root ?? '.'), 'atlas.yaml');
+  const facts = existsSync(file) ? parseYaml(readFileSync(file, 'utf8')) ?? {} : {};
+  if (!repoOk(facts.repo)) throw new ApproveError('name the repo with --repo <owner>/<name>, or run this in a repo whose atlas.yaml names it.');
+  return facts.repo;
+}
+
+// The lines of a gate job log that say what the gate found. Each log line
+// starts with a time, which goes.
+export function gateLines(log) {
+  const lines = String(log ?? '').split('\n').map((line) => line.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z ?/, '').replace(/\r$/, ''));
+  const rows = lines.filter((line) => /^ {2}(red|owner|signed|note) /.test(line));
+  const verdict = lines.find((line) => /^(RED|OWNER|SUCCESS): /.test(line)) ?? null;
+  return { rows, verdict };
+}
+
+// What the gate said about one pull request at its head: state, class and
+// cause. The gate run is pinned the way `atlas gate ready` pins it, so a head
+// job named "gate" cannot show the owner a false cause (security review S1).
+// The pull request must go into the default branch, and the act names its
+// merge base.
+export function gateResult(deps, repo, pr) {
+  const pull = deps.gh('GET', `repos/${repo}/pulls/${pr}`);
+  if (pull?.state !== 'open') return { pr, state: 'closed', why: `#${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}` };
+  const head = String(pull.head?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(head)) throw new ApproveError(`GitHub gave no head for #${pr}.`);
+  const baseRef = String(pull.base?.ref ?? '');
+  const base = { pr: Number(pr), head, title: plainText(pull.title).slice(0, 120), base_ref: baseRef };
+  const main = String(deps.gh('GET', `repos/${repo}`)?.default_branch ?? '');
+  if (!main || baseRef !== main) return { ...base, state: 'other-base', why: `#${pr} goes into ${plainText(baseRef)}, not the default branch ${plainText(main)}: never signed` };
+  const mergeBase = String(deps.gh('GET', `repos/${repo}/compare/${encodeURIComponent(baseRef)}...${head}`)?.merge_base_commit?.sha ?? '');
+  if (!/^[0-9a-f]{40}$/.test(mergeBase)) throw new ApproveError(`GitHub gave no merge base for #${pr}.`);
+  base.merge_base = mergeBase;
+  const { kept, refused } = pinnedRuns(deps.gh, repo, { pr: Number(pr), sha: head, baseRef, head: pull.head, checks: [GATE_CHECK] });
+  const runs = kept.filter((run) => run.name === GATE_CHECK && run.app?.id === ACTIONS_APP_ID)
+    .sort((a, b) => String(b.started_at ?? '').localeCompare(String(a.started_at ?? '')));
+  base.ignored = refused.length;
+  const run = runs[0];
+  if (!run) return { ...base, state: 'missing', why: `the base gate has not run on this head${refused.length ? `; ${refused.length} other run(s) named gate were ignored` : ''}` };
+  if (run.status !== 'completed') return { ...base, state: 'pending', why: 'the gate is still running on this head' };
+  if (run.conclusion === 'success') return { ...base, state: 'success', why: 'the gate is green: nothing to sign' };
+  let found = { rows: [], verdict: null };
+  try { found = gateLines(deps.text(`repos/${repo}/actions/jobs/${run.id}/logs`)); } catch { /* the log is gone or not ready */ }
+  const rows = found.rows.map((row) => plainText(row).slice(0, 300));
+  const verdict = found.verdict ? plainText(found.verdict).slice(0, 300) : null;
+  if (!verdict) return { ...base, state: 'unknown', why: 'the gate failed and its log names no result; open the run' };
+  if (verdict.startsWith('RED:')) return { ...base, state: 'red', why: verdict, rows };
+  if (verdict.startsWith('OWNER:')) {
+    if (rows.some((row) => /^ {2}owner {2}gate-checks /.test(row))) return { ...base, state: 'job-name', why: 'the head adds a job named like a check; a signed act never clears that', rows };
+    return { ...base, state: 'owner', why: verdict, rows: rows.filter((row) => /^ {2}owner /.test(row)) };
+  }
+  return { ...base, state: 'unknown', why: verdict };
+}
+
+// The owner's signers of a repo, from the key file on one branch.
+export function signersOn(deps, repo, ref) {
+  let file = null;
+  try { file = deps.gh('GET', `repos/${repo}/contents/${SIGNERS_FILE}?ref=${encodeURIComponent(ref)}`); } catch { file = null; }
+  const text = typeof file?.content === 'string' ? Buffer.from(file.content, 'base64').toString('utf8') : '';
+  return parseSigners(text);
+}
+
+// `atlas approve <pr>...`. Exit 0 when each signable pull request got its block.
+export async function approvePulls({ prs, repo, root, key, provider, yes = false }, line, deps = DEPS) {
+  if (!prs.length) throw new ApproveError('name at least one pull request: atlas approve <pr>...');
+  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 name = repoOf({ repo, root });
+  const results = [...new Set(prs.map(Number))].map((pr) => gateResult(deps, name, pr));
+  line(`atlas approve: ${name}, ${results.length} pull request(s). The gate's own words for each:`);
+  for (const one of results) {
+    line(`  #${one.pr}${one.head ? ` at ${one.head.slice(0, 7)}` : ''}${one.base_ref ? ` into ${plainText(one.base_ref)}` : ''}  ${one.state.toUpperCase()}  ${one.title ?? ''}`.trimEnd());
+    line(`      ${one.why}`);
+    for (const row of (one.rows ?? []).slice(0, 8)) line(`    ${row.trim()}`);
+  }
+  const sign = results.filter((one) => one.state === 'owner');
+  if (!sign.length) { line('Nothing to sign: no pull request above waits for the owner.'); return 1; }
+  const skipped = results.length - sign.length;
+  if (skipped) line(`${skipped} pull request(s) above are not signed: only an OWNER result takes the signed act.`);
+  if (!yes && !(await deps.ask(`Sign ${sign.map((one) => `#${one.pr}`).join(', ')} with one touch?`))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  // Every key on each base must be one the owner trusts on this Mac, so a key
+  // that an agent merged shows at the owner's next touch (security review S2).
+  const trusted = (deps.trusted ?? trustedKeys)(setup);
+  for (const ref of new Set(sign.map((one) => one.base_ref))) {
+    const strange = signersOn(deps, name, ref).keys.filter((one) => !trusted.has(one.fingerprint));
+    if (strange.length) {
+      line(`STOP: ${SIGNERS_FILE} on ${plainText(ref)} holds a key that is not yours: ${strange.map((one) => one.fingerprint).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 acts = sign.map((one) => ({ kind: 'merge', repo: name, pr: one.pr, base: one.base_ref, merge_base: one.merge_base, head: one.head }));
+  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 };
+  // Prove the block against the key file of each base before it is posted.
+  for (const ref of new Set(sign.map((one) => one.base_ref))) {
+    const { keys } = signersOn(deps, name, ref);
+    const proof = verifyBlock(block, keys);
+    if (proof.error) { line(`The signature does not count on ${ref}: ${proof.error}`); line(`Nothing was posted. Is your public key in ${SIGNERS_FILE} on ${ref}?`); return 1; }
+    line(`The signature counts on ${ref}: key ${proof.key}, touch ${proof.touched ? 'yes' : 'no'}, verified ${proof.verified ? 'yes' : 'no'}.`);
+  }
+  const text = `${blockText(payload, signature)}\nThe owner signed ${sign.map((one) => `#${one.pr} at ${one.head.slice(0, 7)}`).join(', ')} with \`atlas approve\`. The gate reads this comment and reruns.\n`;
+  for (const one of sign) {
+    deps.gh('POST', `repos/${name}/issues/${one.pr}/comments`, { body: text });
+    line(`  posted on #${one.pr}`);
+  }
+  line('Done. The gate reruns on each comment. Then `atlas gate ready` says whether each one may merge.');
+  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').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.');
+  const need = (flag) => {
+    const value = flags[flag];
+    if (value === undefined || value === true || value === '') throw new ApproveError(`atlas approve act ${kind} needs --${flag}.`);
+    return String(value);
+  };
+  if (kind === 'brake-clear') return { kind, repo: need('repo'), commit: need('commit') };
+  if (kind === 'ready') return { kind, repo: need('repo'), item: need('item') };
+  if (kind === 'lock') return { kind, item: need('item'), card: fingerprint(read(need('card'))) };
+  if (kind === 'decision') return { kind, item: need('item'), words: fingerprint(read(need('words'))) };
+  return { kind, repo: need('repo'), pr: Number(need('pr')), head: need('head'), decision: need('decision'), check: need('check') };
+}
+
+// `atlas approve act <kind>`: one act, one touch; the block goes to --out or
+// to the terminal.
+export async function approveAct({ kind, flags, key, provider, yes = false, out }, line, deps = DEPS) {
+  const act = actFrom(kind, flags);
+  const payload = payloadText([act], deps.now());
+  line('atlas approve: this text will be signed:');
+  for (const each of payload.trimEnd().split('\n')) line(`  ${each}`);
+  if (!yes && !(await deps.ask('Sign it with one touch?'))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  line(`Touch the key now (${setup.key}).`);
+  const text = blockText(payload, deps.sign(payload, setup));
+  if (out && out !== true) { writeFileSync(resolve(out), text); line(`The signed block is in ${out}.`); } else process.stdout.write(text);
+  return 0;
+}
+
+// `atlas approve verify --file <f>`: the blocks of a file against a key file.
+export function approveVerify({ file, signers, root }, line) {
+  if (!file || file === true) throw new ApproveError('atlas approve verify needs --file <block file>.');
+  const keyFile = signers && signers !== true ? resolve(signers) : join(resolve(root ?? '.'), SIGNERS_FILE);
+  if (!existsSync(keyFile)) throw new ApproveError(`there is no key file at ${keyFile}.`);
+  const { keys, refused } = parseSigners(readFileSync(keyFile, 'utf8'));
+  for (const one of refused) line(`  ${keyFile} line ${one.line} does not count: ${one.why}`);
+  const rows = verifyTexts([readFileSync(resolve(file), 'utf8')], keys);
+  if (!rows.length) { line('atlas approve verify: the file holds no signed block.'); return 1; }
+  for (const row of rows) {
+    if (row.error) { line(`  ✗ ${row.error}`); continue; }
+    line(`  ✓ key ${row.key}, signed ${row.signed_at}, touch yes, verified ${row.verified ? 'yes' : 'no'}`);
+    for (const act of row.acts) line(`      ${Object.entries(act).map(([field, value]) => `${field} ${value}`).join(', ')}`);
+  }
+  return rows.some((row) => !row.error) ? 0 : 1;
+}
+
+// `atlas approve key-check`: one touch signs a test text, and the key's own
+// public half verifies it. It says whether the key counts for the gate.
+export async function keyCheck({ key, provider }, line, deps = DEPS) {
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  const publicFile = `${setup.key}.pub`;
+  if (!existsSync(publicFile)) throw new ApproveError(`there is no public key at ${publicFile}.`);
+  const { keys, refused } = parseSigners(`owner ${readFileSync(publicFile, 'utf8').trim()}`);
+  if (!keys.length) { line(`The key does not count: ${refused[0]?.why ?? 'it does not read'}.`); return 1; }
+  const payload = payloadText([{ kind: 'ready', repo: 'atlas/key-check', item: ['00000000', '0000', '0000', '0000', '000000000000'].join('-') }], deps.now());
+  line(`Touch the key now (${setup.key}${setup.provider ? `, provider ${setup.provider}` : ''}).`);
+  const proof = verifyBlock({ payload, signature: deps.sign(payload, setup) }, keys);
+  if (proof.error) { line(`The key does not count: ${proof.error}`); return 1; }
+  // A Touch ID key sets its flags in software, so the flag alone proves no
+  // prompt. Ask the owner (security review S2).
+  if (!(await deps.ask('Did Touch ID or the key ask for your touch just now?'))) { line('The key does not count: it signed with no prompt. Make it again with -t bio (Touch ID), or use a hardware key.'); return 1; }
+  line(`The key counts: ${proof.key}, touch yes, verified ${proof.verified ? 'yes' : 'no'}.`);
+  line(`Its line for ${SIGNERS_FILE}:`);
+  line(`owner ${keys[0].type} ${keys[0].blob.toString('base64')}`);
+  return 0;
+}
+
+// The verb. `words` are the words after "approve"; `flags` are the fields of
+// an act.
+export async function approveCommand({ words = [], repo, root, key, provider, yes = false, out, file, signers, flags = {} }, line, deps = DEPS) {
+  const common = { key, provider, yes };
+  try {
+    if (words[0] === 'act') return await approveAct({ ...common, kind: words[1], flags, out }, 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);
+  } catch (error) {
+    if (error instanceof ApproveError || error instanceof SignedActError) { line(`atlas approve: ${error.message}`); return 2; }
+    throw error;
+  }
+}
+

package/door/lib/gate-check.mjs

@@ -15,7 +15,12 @@
 //   owner    a path or a sign of the owner-only list; a head job named like a
 //            check; a refactor claim (until the review job, roadmap R28); a
 //            file too large to scan; the brake (roadmap R13, brake.mjs)
-//   success  no rule holds the pull request
+//   success  no rule holds the pull request, or the owner signed this head
+//
+// An owner result turns into success when a comment of the pull request holds
+// the owner's signed act for this repo, this pull request and this head
+// (roadmap R72, signed-act.mjs). The key comes from atlas/owner-signers on the
+// base, never from the head.
 //
 // Red wins over owner: the pull request must be fixed before the owner signs.
 // Rules that hold everywhere here:
@@ -29,6 +34,7 @@ import { resolve } from 'node:path';
 import { classify, changedPaths, compile, matcher, fakeSecret } from './owner-only.mjs';
 import { listChanged } from './changed-tests.mjs';
 import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
+import { parseSigners, verifyTexts, findAct, SIGNERS_FILE, BRANCH_FORM } from './signed-act.mjs';
 import { brakeState, undoOf, tripText } from './brake.mjs';
 
 export const VERSION = 1;
@@ -36,7 +42,7 @@ export const GATE_CHECK = 'gate';
 export const GATE_WORKFLOW = '.github/workflows/atlas-gate.yml';
 export const TEST_CHECKS = Object.freeze(['fails-before', 'passes-after']);
 export const RESULTS = Object.freeze(['success', 'owner', 'red']);
-export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act', 'brake']);
+export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act', 'brake', 'signed']);
 export const SIGNED_ACT = "Clears with the owner's signed act: atlas approve <pr> (roadmap R72).";
 // A file over this size is not scanned for secrets, and comes to the owner.
 export const SCAN_LIMIT = 1024 * 1024;
@@ -221,13 +227,15 @@ function testRows({ root, mergeBase, head, body, redMain, rules, undo = null })
 // are red on the merge base: [{ check, green }], where `green` is the newest
 // commit of main on which the check was green. `brake` holds the trips that
 // GitHub gives ({ ci: [...] }, see brake.mjs); false leaves the brake out, as
-// the replay does, because the brake depends on the day of the run.
-export function judge({ root, base, head, body = '', redMain = [], rules = null, brake = {}, now = new Date() }) {
+// the replay does, because the brake depends on the day of the run. `signed`
+// is { repo, pr, baseRef, texts }: the texts are the comments of the pull
+// request, read for a signed act, and baseRef is the name of its base branch.
+export function judge({ root, base, head, body = '', redMain = [], rules = null, brake = {}, now = new Date(), signed = null }) {
   const top = resolve(root);
   const baseSha = commitOf(top, base);
   if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
   const headSha = commitOf(top, head);
-  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null, brake: null };
+  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null, brake: null, signed: null };
   if (!headSha) {
     answer.rows.push({ kind: 'red', class: 'gate', cause: 'the head commit is not readable in this clone' });
     return finish(answer);
@@ -250,9 +258,40 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   answer.rows.push(...jobRows(top, rules ?? mergeBase, headSha, changes));
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
   answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules, undo }));
+  if (signed) signedRows(top, baseSha, headSha, signed, answer);
   return finish(answer);
 }
 
+// Done line 4 of R72: a valid signed act for this head clears each owner row.
+// It never clears red: the pull request must be fixed first. The key file is
+// read from the base commit, so a key that the pull request adds does not count.
+// The act must name this base branch and this merge base too, so a change of
+// the base after the touch does not carry it (security review S1). A head job
+// named like a check is never cleared: the owner's view of the gate could be
+// that job's forgery (security review S1).
+function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer) {
+  if (!answer.rows.some((row) => row.kind === 'owner') || answer.rows.some((row) => row.kind === 'red')) return;
+  const note = (cause) => answer.rows.push({ kind: 'note', class: 'signed', cause });
+  if (texts === null) { note('the comments of the pull request could not be read, so no signed act counts'); return; }
+  if (!BRANCH_FORM.test(String(baseRef ?? ''))) { note('the base branch of the pull request is not named, so no signed act counts'); return; }
+  const { keys, refused } = parseSigners(textAt(root, baseSha, SIGNERS_FILE) ?? '');
+  for (const one of refused.slice(0, 3)) note(`${SIGNERS_FILE} line ${one.line} does not count: ${one.why}`);
+  if (!keys.length) { note(`no owner key in ${SIGNERS_FILE} on the base, so no signed act counts`); return; }
+  note(`${keys.length} owner key(s) in ${SIGNERS_FILE} on the base: ${keys.map((key) => key.fingerprint).join(', ')}`);
+  const verified = verifyTexts(texts, keys);
+  const found = findAct(verified, { kind: 'merge', repo, pr: Number(pr), base: baseRef, merge_base: answer.merge_base, head: headSha });
+  if (!found) {
+    for (const row of verified.filter((each) => each.error).slice(0, 3)) note(`a signed act that does not count: ${row.error}`);
+    if (verified.some((each) => !each.error)) note('a valid signed act names another pull request, base, merge base or head; sign this head');
+    return;
+  }
+  const locked = answer.rows.filter((row) => row.kind === 'owner' && row.class === 'gate-checks');
+  if (locked.length) { note('a signed act never clears a head job named like a check: remove that job'); return; }
+  for (const row of answer.rows) if (row.kind === 'owner') row.kind = 'signed';
+  answer.signed = { key: found.key, signed_at: found.signed_at, verified: found.verified };
+  note(`the owner signed this head with key ${found.key} at ${found.signed_at}`);
+}
+
 // Line 1: while the brake is on, every pull request of the repo comes to the
 // owner, except the exact undo of a trip (line 4).
 function brakeRows(state, undo) {
@@ -281,30 +320,40 @@ const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f]/g, '
 export function renderText(answer) {
   const named = new Set(answer.rows.filter((row) => row.path).map((row) => row.path)).size;
   const out = [`gate: base ${answer.base.slice(0, 7)}, merge base ${String(answer.merge_base ?? '-').slice(0, 7)}, head ${oneLine(answer.head).slice(0, 7)}; ${named} path(s) named`];
-  const order = { red: 0, owner: 1, note: 2 };
+  const order = { red: 0, owner: 1, signed: 2, note: 3 };
   for (const row of [...answer.rows].sort((a, b) => order[a.kind] - order[b.kind])) {
     const where = row.path ? `  ${oneLine(row.path)}${row.line ? `:${row.line}` : ''}` : '';
     out.push(`  ${row.kind.padEnd(6)} ${oneLine(row.class).padEnd(12)}${where}  ${oneLine(row.cause)}`);
   }
   if (answer.result === 'red') out.push(`RED: ${oneLine(answer.rows.find((row) => row.kind === 'red').cause)}. Fix it; red wins over owner.`);
   else if (answer.result === 'owner') out.push(`OWNER: ${oneLine(answer.class)}. ${answer.signed_act}`);
+  else if (answer.signed) out.push('SUCCESS: the owner signed this head.');
   else out.push('SUCCESS: no rule holds this pull request.');
   return out;
 }
 
 // ------------------------------------------------------------------ the command
 
-// `atlas gate check`. `read` gives { redMain } from GitHub when the job runs
-// with --repo. Exit 0 on success, 1 on owner or red, 2 on a usage error.
-export function checkCommand({ root, base, head, body: bodyFile, json = false, summary, output }, line, read = null) {
+// `atlas gate check`. `read` gives the red main checks from GitHub when the
+// job runs with --repo. `comments` gives the comment texts of the pull request
+// when it also runs with --pr, so a signed act can clear owner. Exit 0 on
+// success, 1 on owner or red, 2 on a usage error.
+export function checkCommand({ root, base, head, body: bodyFile, json = false, summary, output, repo = null, pr = null, baseRef = null }, line, read = null, comments = null) {
   try {
     if (!base || base === true) throw Object.assign(new GateCheckError('atlas gate check needs --base <ref>.'), { usage: true });
     if (!head || head === true) throw Object.assign(new GateCheckError('atlas gate check needs --head <sha>.'), { usage: true });
     const body = bodyFile && bodyFile !== true ? readFileSync(resolve(bodyFile), 'utf8') : '';
+    if (pr !== null && pr !== undefined && !/^[1-9][0-9]{0,8}$/.test(String(pr))) throw Object.assign(new GateCheckError('--pr must be a pull request number.'), { usage: true });
     // A reader gives the red main checks, or { redMain, brake } with the brake trips too.
     const got = read ? read() : [];
     const redMain = Array.isArray(got) ? got : got.redMain ?? [];
-    const answer = judge({ root, base, head, body, redMain, brake: Array.isArray(got) ? {} : got.brake ?? {} });
+    let signed = null;
+    if (comments && repo && pr) {
+      let texts = null;
+      try { texts = comments(); } catch { texts = null; }
+      signed = { repo, pr: Number(pr), baseRef: baseRef && baseRef !== true ? String(baseRef) : null, texts };
+    }
+    const answer = judge({ root, base, head, body, redMain, brake: Array.isArray(got) ? {} : got.brake ?? {}, signed });
     const text = renderText(answer);
     if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
     else for (const each of text) line(each);

package/door/lib/gate.mjs

@@ -21,6 +21,7 @@ import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { checkCommand, replayCommand, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
+import { MARKER as SIGNED_MARKER } from './signed-act.mjs';
 import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
@@ -287,7 +288,7 @@ export function jobRefusal(job, check, run) {
 }
 
 // The check runs that may count for this pull request, and the ones refused.
-function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks }) {
+export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks }) {
   const homes = homesAt(gh, repo, baseRef, checks);
   // Every pull request, open or closed, from the head branch into another
   // branch. Read once, when the first run needs it.
@@ -474,6 +475,26 @@ export function redMain({ root, base }, gh, repo, depth = 30) {
   return found;
 }
 
+// The comment texts of one pull request that carry the signed-act marker
+// (roadmap R72). At most ten pages of a hundred, newest kept first, and at most
+// 2 MB of text in all; the gate reads them as data only.
+export function prComments(gh, repo, pr) {
+  const texts = [];
+  for (let page = 1; page <= 10; page += 1) {
+    const rows = gh('GET', `repos/${repo}/issues/${pr}/comments?per_page=100&page=${page}`) ?? [];
+    for (const row of Array.isArray(rows) ? rows : []) if (typeof row?.body === 'string' && row.body.includes(SIGNED_MARKER)) texts.push(row.body);
+    if (!Array.isArray(rows) || rows.length < 100) break;
+  }
+  const kept = [];
+  let bytes = 0;
+  for (const text of texts.reverse()) {
+    bytes += text.length;
+    if (bytes > 2 * 1024 * 1024) break;
+    kept.push(text);
+  }
+  return kept;
+}
+
 // The base workflow files that define a job of one of `names`, read from git.
 function definedAt(git, sha, names) {
   const files = new Set();
@@ -516,11 +537,14 @@ export function brakeRead({ root, base, now = new Date() }, gh, repo, pages = 3)
 }
 
 // `atlas gate apply|ready|audit|check|replay`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, head, body, json = false, summary, output, days, branch, home = homedir() }, line, gh = ghApi) {
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, baseRef, head, body, json = false, summary, output, days, branch, home = homedir() }, line, gh = ghApi) {
   if (!['apply', 'ready', 'audit', 'check', 'replay'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit, check or replay.`);
   // With --repo, check reads the red main checks from GitHub; without, it judges git data alone.
   const named = repo && repo !== true && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
-  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo) } }) : null);
+  if (what === 'check') {
+    const number = /^[1-9][0-9]{0,8}$/.test(String(pr ?? '')) ? Number(pr) : null;
+    return checkCommand({ root, base, head, body, json, summary, output, repo: named ? repo : null, pr: pr === undefined ? null : pr, baseRef: baseRef ?? null }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo) } }) : null, named && number ? () => prComments(gh, repo, number) : null);
+  }
   if (what === 'replay') return replayCommand({ root, days, branch, json }, line);
   if (!named) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
   if (what === 'ready') {