@arjunkhera/atlas 0.4.20 → 0.4.22

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "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);
@@ -140,6 +141,7 @@ const HELP = `atlas — the door into a repo's Atlas files
 
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, and in a pull request its tracker item
   atlas upkeep replay --root <repo>    what the doc-sources rule would have asked of the last merges; writes nothing
+  atlas upkeep procedures --root <repo>  run the procedure steps marked atlas-run; --base <ref> runs only the procedures a change touches
       --last <n>                       how many merges on the first-parent line; default 30
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
@@ -153,6 +155,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 +165,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
@@ -201,8 +215,9 @@ export const FLAGS = Object.freeze({
   view: { product: 'value', name: 'value', out: 'value' },
   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' },
+  upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
+  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' },
@@ -447,11 +462,16 @@ function jobsVerb(chosen) {
 }
 
 function upkeepVerb(chosen) {
-  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last }, rootOf(chosen), line);
+  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last, base: chosen.base }, rootOf(chosen), line);
 }
 
 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 +517,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') {

package/door/lib/procedure-steps.mjs

@@ -0,0 +1,122 @@
+// CI runs the procedures (roadmap R40, item 38b2a0fe). Target design 4.6: CI
+// runs each procedure step that a clean machine can run.
+//
+// A procedure marks such a step with a fenced block whose info string holds
+// the tag `atlas-run`:
+//
+//   ```sh atlas-run
+//   npm test
+//   ```
+//
+// A step that needs what a clean machine does not have names it after the
+// tag: `atlas-run needs=secret/NPM_TOKEN` or `atlas-run needs=device/macos`.
+// Such a step is listed as "not run here", never as passed.
+//
+// `atlas upkeep procedures` runs the marked steps of each procedure that
+// atlas.yaml `procedures:` names. With --base, it runs only the procedures a
+// pull request changes: its own folder, or a path its `sources:` names. Each
+// block runs in bash, from the repo root, with `set -euo pipefail`. It reads
+// no repo kind, so a repo with no deploy target uses it unchanged.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fenceOpens, fenceCloses } from './markdown.mjs';
+import { docUnits, covers, changedPaths } from './doc-sources.mjs';
+
+export const TAG = 'atlas-run';
+const SHELLS = new Set(['sh', 'bash', 'shell']);
+const NEEDS = new Set(['secret', 'device', 'network']);
+// The bound on one block. A step that runs longer is a failure. It sits
+// below the 10 minutes of the CI job, so the step fails with a reason.
+export const STEP_TIMEOUT_MS = 8 * 60 * 1000;
+
+// Line 1: the marked steps of one procedure text. Each step is one fenced
+// block. `problems` holds a tag that cannot run as written.
+export function markedSteps(text) {
+  const steps = [];
+  const problems = [];
+  const lines = String(text ?? '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const mark = fenceOpens(lines[i]);
+    if (!mark) continue;
+    const info = lines[i].trim().slice(mark.length).trim().split(/\s+/).filter(Boolean);
+    const start = i;
+    const body = [];
+    for (i += 1; i < lines.length && !fenceCloses(lines[i], mark); i += 1) body.push(lines[i]);
+    if (!info.includes(TAG)) continue;
+    const line = start + 1;
+    const lang = info[0] === TAG ? null : info[0];
+    if (!SHELLS.has(lang)) { problems.push({ line, why: `the block is tagged ${TAG} but its language is ${lang ?? 'missing'}; use sh or bash` }); continue; }
+    if (i >= lines.length) { problems.push({ line, why: 'the block never closes' }); continue; }
+    const needs = [];
+    let bad = null;
+    for (const word of info.slice(info.indexOf(TAG) + 1)) {
+      const m = /^needs=(.+)$/.exec(word);
+      if (!m) { bad = `"${word}" after ${TAG} is not needs=<kind>/<name>`; break; }
+      for (const one of m[1].split(',')) {
+        const [kind, name] = one.split('/');
+        if (!NEEDS.has(kind) || !name) { bad = `"${one}" is not one of ${[...NEEDS].map((k) => `${k}/<name>`).join(', ')}`; break; }
+        needs.push({ kind, name });
+      }
+      if (bad) break;
+    }
+    if (bad) { problems.push({ line, why: bad }); continue; }
+    const script = body.join('\n').trim();
+    if (!script) { problems.push({ line, why: 'the block is empty' }); continue; }
+    steps.push({ line, script, needs });
+  }
+  return { steps, problems };
+}
+
+// The procedures to run. With `changed`, only those a pull request changes:
+// a path in the procedure's folder, or a path its `sources:` names.
+export function proceduresToRun(root, changed = null) {
+  const units = docUnits(root).filter((one) => one.kind === 'procedure');
+  if (changed === null) return units;
+  return units.filter((one) => changed.some((path) => path.startsWith(`${one.unit}/`)
+    || (one.named?.sources ?? []).some((source) => covers(root, source, path))));
+}
+
+const needsText = (needs) => needs.map((one) => `${one.kind} ${one.name}`).join(', ');
+
+// Line 2 and line 3: run each marked step of each chosen procedure. A step
+// that needs a secret, a device or the network is "not run here".
+export function runProcedures(root, { base = null, run = runStep } = {}) {
+  const changed = base === null ? null : changedPaths(root, `${base}...HEAD`);
+  const chosen = proceduresToRun(root, changed);
+  const rows = [];
+  for (const unit of chosen) {
+    const { steps, problems } = markedSteps(readFileSync(join(root, unit.where), 'utf8'));
+    for (const one of problems) rows.push({ procedure: unit.unit, where: `${unit.where}:${one.line}`, state: 'bad tag', why: one.why });
+    if (!steps.length && !problems.length) rows.push({ procedure: unit.unit, where: unit.where, state: 'no step', why: `it marks no step with ${TAG}` });
+    for (const step of steps) {
+      const where = `${unit.where}:${step.line}`;
+      if (step.needs.length) { rows.push({ procedure: unit.unit, where, state: 'not run here', why: `needs ${needsText(step.needs)}` }); continue; }
+      const result = run(root, step.script);
+      rows.push({ procedure: unit.unit, where, state: result.ok ? 'passed' : 'failed', why: result.why, tail: result.tail });
+    }
+  }
+  const red = rows.filter((row) => row.state === 'failed' || row.state === 'bad tag');
+  return { procedures: chosen.map((one) => one.unit), all: changed === null, rows, green: red.length === 0 };
+}
+
+export function runStep(root, script) {
+  const out = spawnSync('bash', ['-c', `set -euo pipefail\n${script}`], { cwd: root, encoding: 'utf8', timeout: STEP_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+  const tail = `${out.stdout ?? ''}${out.stderr ?? ''}`.trimEnd().split('\n').slice(-20).join('\n');
+  if (out.error?.code === 'ETIMEDOUT') return { ok: false, why: `it ran past ${STEP_TIMEOUT_MS / 60000} minutes`, tail };
+  if (out.error) return { ok: false, why: out.error.message, tail };
+  return out.status === 0 ? { ok: true, why: 'exit 0', tail } : { ok: false, why: `exit ${out.status ?? out.signal}`, tail };
+}
+
+// `atlas upkeep procedures`.
+export function proceduresCommand({ base = null, json = false }, root, line) {
+  const out = runProcedures(root, { base });
+  if (json) { process.stdout.write(`${JSON.stringify(out, null, 2)}\n`); return out.green ? 0 : 1; }
+  line(`procedures: ${out.procedures.length} to run${out.all ? '' : ` (the ones this change touches, from ${base})`}${out.procedures.length ? `: ${out.procedures.join(', ')}` : ''}`);
+  for (const row of out.rows) {
+    line(`  ${row.state.padEnd(12)} ${row.where}  ${row.why}`);
+    if (row.state === 'failed' && row.tail) for (const one of row.tail.split('\n')) line(`      | ${one}`);
+  }
+  line(`procedure steps: ${out.green ? 'GREEN' : 'RED'}`);
+  return out.green ? 0 : 1;
+}

package/door/lib/signed-act.mjs

@@ -0,0 +1,332 @@
+// The signed act: the owner's one act that an agent cannot make (roadmap R72,
+// tracker item 0c68a105; design docs/design-docs/signed-act/).
+//
+// Agents work under the owner's own GitHub login, so GitHub cannot tell his
+// act from theirs. The signed act is an SSH signature made with a security
+// key: a hardware key, or a Secure Enclave key that needs Touch ID. The
+// signature carries the "user present" flag of the key, so a valid one proves
+// a touch. This file holds the parts that need no GitHub:
+//
+//   parseSigners(text)            the public keys of atlas/owner-signers
+//   payloadText(acts, signedAt)   the exact text that one touch signs
+//   parseBlocks(text)             the signed blocks in a comment or a file
+//   verifyBlock(block, signers)   the acts of one block, or the reason it fails
+//   findAct(verified, want)       the first verified act that names `want`
+//
+// The verifier reads the SSH signature format (OpenSSH PROTOCOL.sshsig) and
+// the security key form (PROTOCOL.u2f) with node:crypto alone. It runs no
+// program, so the gate job needs nothing but Node.
+//
+// Rules that hold everywhere here:
+// 1. Only a security key counts: sk-ssh-ed25519 or sk-ecdsa-sha2-nistp256.
+//    A plain key can sign with no touch, so it is refused.
+// 2. A signature counts only with the "user present" flag. A key line with
+//    `verify-required` also needs the "user verified" flag.
+// 3. The key must be one of the signers that the caller read from the base.
+// 4. It fails closed: any field that does not read is a refusal.
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+export const NAMESPACE = 'atlas-signed-act';
+export const FORMAT = 'atlas signed act 1';
+export const SIGNERS_FILE = 'atlas/owner-signers';
+export const BEGIN = '-----BEGIN ATLAS SIGNED ACT-----';
+export const END = '-----END ATLAS SIGNED ACT-----';
+const SIG_BEGIN = '-----BEGIN SSH SIGNATURE-----';
+const SIG_END = '-----END SSH SIGNATURE-----';
+export const MARKER = '<!-- atlas:signed-act -->';
+// One touch signs at most this many acts, and a text holds at most this many blocks.
+export const MAX_ACTS = 50;
+export const MAX_BLOCKS = 20;
+const MAX_TEXT = 256 * 1024;
+
+// The two security key types. The names are joined from pieces, so the
+// package holds no text that reads as an email address (test/package D3).
+const AT_OPENSSH = (name) => [name, 'openssh.com'].join('@');
+export const ED25519_SK = AT_OPENSSH('sk-ssh-ed25519');
+export const ECDSA_SK = AT_OPENSSH('sk-ecdsa-sha2-nistp256');
+export const KEY_TYPES = Object.freeze([ED25519_SK, ECDSA_SK]);
+const FLAG_USER_PRESENT = 0x01;
+const FLAG_USER_VERIFIED = 0x04;
+const FLAG_EXTENSIONS = 0x80;
+
+export class SignedActError extends Error {}
+
+// ------------------------------------------------------------------ the acts
+
+const REPO = '[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+';
+const SHA = '[0-9a-f]{40}';
+const ID = '[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}';
+const HASH = '[0-9a-f]{64}';
+const NUMBER = '[1-9][0-9]{0,8}';
+// A branch name: plain characters only, so a line never holds a space.
+const BRANCH = '[A-Za-z0-9._/-]{1,100}';
+export const BRANCH_FORM = new RegExp(`^${BRANCH}$`);
+
+// Each kind of act, its fields, and the exact form of its line. The order of
+// the fields is the order of the words after the kind. A check name can hold
+// spaces, so it is the last field of a waiver and takes the rest of the line.
+export const ACTS = Object.freeze({
+  // A pull request head that the gate sent to the owner (done line 4). It
+  // names the base branch and the merge base too, so a change of the base
+  // after the touch does not carry the act onto a diff the owner never saw
+  // (security review S1, 26 October 2026).
+  merge: { fields: ['repo', 'pr', 'base', 'merge_base', 'head'], form: `(${REPO}) (${NUMBER}) (${BRANCH}) (${SHA}) (${SHA})` },
+  // The end of a brake before its time (R13 line 6). The commit is the one
+  // that set the brake, so one clear never ends a later brake.
+  'brake-clear': { fields: ['repo', 'commit'], form: `(${REPO}) (${SHA})` },
+  // A ready mark for the runner (R25 line 3). It holds no nonce: R25 must
+  // say what stops a replay when an item is reopened, before its reader ships.
+  ready: { fields: ['repo', 'item'], form: `(${REPO}) (${ID})` },
+  // An owner lock: the item and the fingerprint of its card (R27 line 2).
+  lock: { fields: ['item', 'card'], form: `(${ID}) (${HASH})` },
+  // A decision: the item and the fingerprint of the owner's words.
+  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 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');
+
+// One act line from its fields, checked against its form.
+export function actLine(act) {
+  const spec = ACTS[act?.kind];
+  if (!spec) throw new SignedActError(`there is no act "${act?.kind}". Use ${Object.keys(ACTS).join(', ')}.`);
+  const line = `act ${act.kind} ${spec.fields.map((field) => String(act[field] ?? '')).join(' ')}`;
+  if (!new RegExp(`^act ${act.kind} ${spec.form}$`).test(line)) throw new SignedActError(`the ${act.kind} act does not read: ${line.slice(0, 200)}`);
+  return line;
+}
+
+// The exact text that one touch signs. It ends with one line end.
+export function payloadText(acts, signedAt) {
+  if (!Array.isArray(acts) || !acts.length) throw new SignedActError('a signed act names at least one act.');
+  if (acts.length > MAX_ACTS) throw new SignedActError(`one touch signs at most ${MAX_ACTS} acts.`);
+  const at = new Date(signedAt);
+  if (Number.isNaN(at.getTime())) throw new SignedActError('the time of the signature does not read.');
+  return `${[FORMAT, `signed ${at.toISOString()}`, ...acts.map(actLine)].join('\n')}\n`;
+}
+
+// The acts of a payload text, or a refusal. Every line must read.
+export function parsePayload(text) {
+  const lines = String(text).split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  if (lines[0] !== FORMAT) throw new SignedActError(`the first line is not "${FORMAT}".`);
+  const at = /^signed (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/.exec(lines[1] ?? '');
+  if (!at || Number.isNaN(Date.parse(at[1]))) throw new SignedActError('the second line is not "signed <time>".');
+  const rows = lines.slice(2);
+  if (!rows.length) throw new SignedActError('the block names no act.');
+  if (rows.length > MAX_ACTS) throw new SignedActError(`the block names more than ${MAX_ACTS} acts.`);
+  const acts = rows.map((line) => {
+    const kind = /^act ([a-z-]+) /.exec(line)?.[1];
+    const spec = kind && Object.hasOwn(ACTS, kind) ? ACTS[kind] : null;
+    const hit = spec && new RegExp(`^act ${kind} ${spec.form}$`).exec(line);
+    if (!hit) throw new SignedActError(`an act line does not read: ${line.slice(0, 120)}`);
+    const act = { kind };
+    spec.fields.forEach((field, index) => { act[field] = field === 'pr' ? Number(hit[index + 1]) : hit[index + 1]; });
+    return act;
+  });
+  return { signed_at: at[1], acts };
+}
+
+// ------------------------------------------------------------------ the SSH wire form
+
+function reader(buffer) {
+  let at = 0;
+  const need = (n) => { if (at + n > buffer.length) throw new SignedActError('the signature is cut short.'); };
+  return {
+    u8() { need(1); return buffer[at++]; },
+    u32() { need(4); const value = buffer.readUInt32BE(at); at += 4; return value; },
+    raw(n) { need(n); const out = buffer.subarray(at, at + n); at += n; return out; },
+    string() { const n = this.u32(); return this.raw(n); },
+    text() { return this.string().toString('latin1'); },
+    done() { return at === buffer.length; },
+  };
+}
+
+const sshString = (value) => {
+  const body = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'latin1');
+  const size = Buffer.alloc(4);
+  size.writeUInt32BE(body.length);
+  return Buffer.concat([size, body]);
+};
+
+// The node:crypto key of one security key blob, and its application.
+function keyOf(blob) {
+  const read = reader(blob);
+  const type = read.text();
+  if (type === ED25519_SK) {
+    const raw = read.string();
+    const application = read.text();
+    if (raw.length !== 32 || !read.done()) throw new SignedActError('the ed25519 key does not read.');
+    return { type, application, key: createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: raw.toString('base64url') }, format: 'jwk' }) };
+  }
+  if (type === ECDSA_SK) {
+    const curve = read.text();
+    const point = read.string();
+    const application = read.text();
+    if (curve !== 'nistp256' || point.length !== 65 || point[0] !== 4 || !read.done()) throw new SignedActError('the ecdsa key does not read.');
+    return { type, application, key: createPublicKey({ key: { kty: 'EC', crv: 'P-256', x: point.subarray(1, 33).toString('base64url'), y: point.subarray(33).toString('base64url') }, format: 'jwk' }) };
+  }
+  throw new SignedActError(`the key type ${type.slice(0, 60)} is not a security key, so it needs no touch.`);
+}
+
+export const keyFingerprint = (blob) => `SHA256:${createHash('sha256').update(blob).digest('base64').replace(/=+$/, '')}`;
+
+// The keys of an allowed-signers text: one key on each line,
+// `<name> [options] <type> <base64> [comment]`. The one option that counts is
+// `verify-required`. `no-touch-required` and a plain key are refused, with
+// the line number, and the other lines still count.
+export function parseSigners(text) {
+  const keys = [];
+  const refused = [];
+  String(text ?? '').split('\n').forEach((raw, index) => {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) return;
+    const words = line.split(/\s+/);
+    const name = words.shift();
+    let options = '';
+    if (!KEY_TYPES.includes(words[0]) && !/^(ssh-|ecdsa-|sk-)/.test(words[0] ?? '')) options = words.shift() ?? '';
+    const [type, base64] = words;
+    const opts = options ? options.split(',') : [];
+    const why = (reason) => refused.push({ line: index + 1, why: reason });
+    if (opts.some((opt) => opt === 'no-touch-required')) return why('no-touch-required: a signature with no touch proves nothing');
+    const unknown = opts.filter((opt) => opt !== 'verify-required');
+    if (unknown.length) return why(`an option that the gate does not read: ${unknown[0].slice(0, 40)}`);
+    if (!KEY_TYPES.includes(type)) return why(`${String(type).slice(0, 40)} is not a security key`);
+    let blob;
+    try { blob = Buffer.from(base64 ?? '', 'base64'); keyOf(blob); } catch (error) { return why(error.message); }
+    if (blob.toString('base64').replace(/=+$/, '') !== String(base64).replace(/=+$/, '')) return why('the key is not plain base64');
+    keys.push({ name, type, blob, verify_required: opts.includes('verify-required'), fingerprint: keyFingerprint(blob) });
+  });
+  return { keys, refused };
+}
+
+// The parts of an armored SSH signature.
+function sshsigParts(armored) {
+  const body = String(armored).replace(SIG_BEGIN, '').replace(SIG_END, '').replace(/\s+/g, '');
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) throw new SignedActError('the SSH signature is not base64.');
+  const read = reader(Buffer.from(body, 'base64'));
+  if (read.raw(6).toString('latin1') !== 'SSHSIG') throw new SignedActError('the signature does not start with SSHSIG.');
+  if (read.u32() !== 1) throw new SignedActError('the signature is not version 1.');
+  const key = read.string();
+  const namespace = read.text();
+  const reserved = read.string();
+  const hash = read.text();
+  const signature = read.string();
+  if (!read.done()) throw new SignedActError('the signature has data after its end.');
+  return { key, namespace, reserved, hash, signature };
+}
+
+// Verify one SSH signature of `message` against the signers. The answer names
+// the key and the flags, or throws the reason.
+export function verifySignature(message, armored, signers, namespace = NAMESPACE) {
+  const parts = sshsigParts(armored);
+  if (parts.namespace !== namespace) throw new SignedActError(`the signature is for "${parts.namespace.slice(0, 40)}", not "${namespace}".`);
+  if (parts.reserved.length) throw new SignedActError('the reserved field of the signature is not empty.');
+  if (!['sha256', 'sha512'].includes(parts.hash)) throw new SignedActError(`the hash ${parts.hash.slice(0, 20)} is not sha256 or sha512.`);
+  const signer = signers.find((each) => each.blob.equals(parts.key));
+  if (!signer) throw new SignedActError(`the key ${keyFingerprint(parts.key)} is not in ${SIGNERS_FILE} on the base.`);
+  const { type, application, key } = keyOf(signer.blob);
+  // The text that the key signed: PROTOCOL.sshsig, then PROTOCOL.u2f.
+  const signed = Buffer.concat([Buffer.from('SSHSIG', 'latin1'), sshString(namespace), sshString(''), sshString(parts.hash), sshString(createHash(parts.hash).update(message).digest())]);
+  const read = reader(parts.signature);
+  const sigType = read.text();
+  if (sigType !== type) throw new SignedActError(`the signature type ${sigType.slice(0, 60)} does not match the key.`);
+  const inner = read.string();
+  const flags = read.u8();
+  const counter = read.u32();
+  if (!read.done()) throw new SignedActError('the security key signature has data after its end.');
+  if (flags & FLAG_EXTENSIONS) throw new SignedActError('the security key signature carries extensions, which the gate does not read.');
+  const counterBytes = Buffer.alloc(4);
+  counterBytes.writeUInt32BE(counter);
+  const original = Buffer.concat([createHash('sha256').update(application).digest(), Buffer.from([flags]), counterBytes, createHash('sha256').update(signed).digest()]);
+  let good;
+  if (type === ED25519_SK) {
+    if (inner.length !== 64) throw new SignedActError('the ed25519 signature does not read.');
+    good = cryptoVerify(null, original, key, inner);
+  } else {
+    const ecdsa = reader(inner);
+    // A canonical mpint only: no needless leading zero, and never negative.
+    // Nothing relies on one signature per text; ECDSA allows two.
+    const fixed = (n) => {
+      if (!n.length || (n[0] & 0x80) || (n[0] === 0 && (n.length === 1 || !(n[1] & 0x80)))) throw new SignedActError('the ecdsa signature does not read.');
+      const bytes = n[0] === 0 ? n.subarray(1) : n;
+      if (bytes.length > 32) throw new SignedActError('the ecdsa signature does not read.');
+      return Buffer.concat([Buffer.alloc(32 - bytes.length), bytes]);
+    };
+    const r = fixed(ecdsa.string());
+    const s = fixed(ecdsa.string());
+    if (!ecdsa.done()) throw new SignedActError('the ecdsa signature does not read.');
+    good = cryptoVerify('sha256', original, { key, dsaEncoding: 'ieee-p1363' }, Buffer.concat([r, s]));
+  }
+  if (!good) throw new SignedActError('the signature does not match the text.');
+  const touched = Boolean(flags & FLAG_USER_PRESENT);
+  const verified = Boolean(flags & FLAG_USER_VERIFIED);
+  if (!touched) throw new SignedActError('the key made this signature with no touch.');
+  if (signer.verify_required && !verified) throw new SignedActError('the key line says verify-required, and the key did not verify the owner (no Touch ID or PIN).');
+  return { key: signer.fingerprint, name: signer.name, touched, verified, counter };
+}
+
+// ------------------------------------------------------------------ blocks
+
+// The block that a comment or a file carries: the marker, the payload and
+// the signature, in a fence so GitHub shows it as it is.
+export const blockText = (payload, signature) => [MARKER, '```text', BEGIN, payload.replace(/\n$/, ''), END, signature.trim(), '```', ''].join('\n');
+
+// Each signed block of a text: { payload, signature }. Line ends are made
+// plain, so a copy from a page with CR LF still reads. A text with no marker
+// holds no block. The scan is linear: each marker is found once with indexOf.
+export function parseBlocks(text) {
+  const raw = String(text ?? '');
+  if (!raw.includes(MARKER)) return [];
+  const plain = raw.slice(0, MAX_TEXT).replace(/\r\n?/g, '\n');
+  const out = [];
+  let from = 0;
+  while (out.length < MAX_BLOCKS) {
+    const begin = plain.indexOf(`${BEGIN}\n`, from);
+    if (begin < 0) break;
+    const end = plain.indexOf(`\n${END}\n`, begin);
+    if (end < 0) break;
+    const sigStart = end + END.length + 2;
+    const sigEnd = plain.indexOf(SIG_END, sigStart);
+    if (sigEnd < 0) break;
+    from = sigEnd + SIG_END.length;
+    const signature = plain.slice(sigStart, from);
+    if (!signature.startsWith(`${SIG_BEGIN}\n`) || !/^[A-Za-z0-9+/=\n]+$/.test(signature.slice(SIG_BEGIN.length + 1, -SIG_END.length))) continue;
+    out.push({ payload: `${plain.slice(begin + BEGIN.length + 1, end)}\n`, signature });
+  }
+  return out;
+}
+
+// One block, verified: { acts, signed_at, key, verified }, or { error }.
+export function verifyBlock(block, signers) {
+  try {
+    const parsed = parsePayload(block.payload);
+    const proof = verifySignature(Buffer.from(block.payload, 'utf8'), block.signature, signers);
+    return { ...parsed, ...proof };
+  } catch (error) {
+    if (error instanceof SignedActError) return { error: error.message };
+    throw error;
+  }
+}
+
+// Every block of each text, verified. `texts` is a list of strings, such as
+// the comments of a pull request.
+export function verifyTexts(texts, signers) {
+  const rows = [];
+  for (const text of texts) for (const block of parseBlocks(text)) rows.push(verifyBlock(block, signers));
+  return rows;
+}
+
+// The first verified act that matches every field of `want`, with its block.
+// Repo names match with no case, as GitHub does.
+export function findAct(verified, want) {
+  const same = (field, a, b) => (field === 'repo' ? String(a).toLowerCase() === String(b).toLowerCase() : String(a) === String(b));
+  for (const row of verified) {
+    if (row.error) continue;
+    const act = row.acts.find((each) => Object.entries(want).every(([field, value]) => same(field, each[field], value)));
+    if (act) return { act, signed_at: row.signed_at, key: row.key, verified: row.verified };
+  }
+  return null;
+}

package/door/lib/upkeep.mjs

@@ -23,6 +23,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
+import { proceduresCommand } from './procedure-steps.mjs';
 
 // R39 line 4 gates only after the replay of line 3. The replay of the last 30
 // merges (atlas#225): rule "file" pulled in 81 docs over 24 merges, 58 not
@@ -246,9 +247,10 @@ export function upkeepCheck(root, { event = null } = {}) {
   return { green: findings.length === 0, findings, notes: sources.notes, index, dead, item, text, sources };
 }
 
-export function upkeepCommand({ what, event: eventFile, json = false, last }, root, line) {
+export function upkeepCommand({ what, event: eventFile, json = false, last, base }, root, line) {
   if (what === 'replay') return replayCommand({ last, json }, root, line);
-  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, or atlas upkeep replay.`);
+  if (what === 'procedures') return proceduresCommand({ base: base ?? null, json }, root, line);
+  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, atlas upkeep replay or atlas upkeep procedures.`);
   let event = null;
   if (eventFile !== undefined) {
     try { event = JSON.parse(readFileSync(resolve(eventFile), 'utf8')); } catch (error) { throw new Error(`cannot read the event file ${eventFile}: ${error.message}`); }

package/package.json

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

@@ -110,8 +110,9 @@ set. A test keeps the two lists equal.
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `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 the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates |
+| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. 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 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/skills/repo-skills/SKILL.md

@@ -27,19 +27,24 @@ the form the repo already uses for that kind of thing.
    deploy. A rule says how to judge a change. They have different approval
    rules, so split a skill that holds both.
 4. **Write the header Atlas reads,** for a skill file. It names the type,
-   the commands and files, and the code it covers. It says how CI runs
-   it, if CI can. Today the Atlas check reads only `name` and
-   `description`, and finds the skill when `procedures` in `atlas.yaml`
-   names it. Later upkeep checks read the other keys, so keep each true.
-5. **Keep it to this repo.** A step that holds how to work in general
+   the commands and files, and the code it covers in `sources:`. The
+   Atlas check finds the skill when `procedures` in `atlas.yaml` names
+   it. `atlas upkeep check` reads `sources:`.
+5. **Tag each step a clean machine can run.** Put its commands in a
+   fenced block. Open it with ```` ```sh atlas-run ````. CI runs each
+   such block when a pull request changes the skill or its sources. A
+   step that needs a secret, a device or the network gets
+   `needs=secret/<name>`, `needs=device/<name>` or `needs=network/<name>`
+   after the tag. CI lists it as "not run here".
+6. **Keep it to this repo.** A step that holds how to work in general
    belongs in Atlas. Do not put it here. Propose it to Atlas with the
    `atlas:feedback` skill.
-6. **Follow the repo's own rules.** Read its entry file first. Some repos
+7. **Follow the repo's own rules.** Read its entry file first. Some repos
    ask for one area folder for each change, or a status file updated
    when the state changes. Keep to them.
-7. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
+8. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
    a fresh worktree, before you ask for the merge.
-8. **Write the pull request text.** Say what you found, what you kept,
+9. **Write the pull request text.** Say what you found, what you kept,
    and the gap you closed.
 
 ## The header of a skill file
@@ -51,9 +56,8 @@ description: <when to use it, in one or two sentences>
 type: task            # or rule
 names:                # each command and file the steps name
   - <command or path>
-covers:               # the code this skill describes
+sources:              # the code this skill describes
   - <path>
-ci: <how CI runs it, or "cannot run in CI">
 ---
 ```