@arjunkhera/atlas 0.4.24 → 0.4.26

package/.claude-plugin/plugin.json

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

package/door/jobs/gate-audit.yaml

@@ -4,7 +4,9 @@
 # the same findings, with the same keys, so one break opens one issue.
 #
 # kind is one of: push (no pull request merged it), force-push,
-# merge-before-green, gate-copy (a gate run not from the base workflow file).
+# merge-before-green, gate-copy (a gate run not from the base workflow file),
+# owner-unsigned (the gate sends the merge to the owner, and no signed act
+# names its head; the push audit only, because it needs the clone).
 # A closed issue does not stop a new one while its commit is in the window:
 # anyone with the shared login can close or hand over an issue.
 title: Each commit on the main branch came through the gate

package/door/jobs/npm-release.yaml

@@ -0,0 +1,24 @@
+# An Atlas job (the routines design, records part). A job does nothing until a
+# repo names it in its atlas.yaml, with the npm packages it publishes:
+#
+#   jobs:
+#     atlas: [npm-release]
+#     npm: ['@scope/name']
+#
+# It fits a repo that publishes to npm through a release.yml on master that
+# keeps the Atlas release record, as Atlas does. A service, a schema repo or a
+# repo that publishes nothing does not name it.
+#
+# The check is Atlas code (door/lib/jobs.mjs). Each version that npm got in the
+# last 2 days must have the proof that `atlas upgrade` asks for: a successful
+# push run of release.yml on a master commit that recorded that version with
+# the sha256 of its tarball. A branch can publish before any merge (the gate
+# probes, P7), so a version with no such run is a finding. `problem` is a
+# code: no-tag, not-on-master, never-tip or no-record. Only a person can act
+# on it (deprecate the version on npm), so the job may only report.
+title: Each new npm version was published by a release run on master
+when: daily
+needs: []
+act: atlas:npm-release
+may: report
+fields: [package, version, problem, commit]

package/door/lib/gate-check.mjs

@@ -10,8 +10,10 @@
 //
 // The answer is success, owner or red:
 //
-//   red      a secret in an added line; product code that changed with no test
-//            case added or changed; a head that git cannot read
+//   red      a secret in an added line; a private term in an added line or a
+//            path that ships, or no terms when atlas.yaml names shipped
+//            paths; product code that changed with no test case added or
+//            changed; a head that git cannot read
 //   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)
@@ -31,7 +33,8 @@
 import { spawnSync } from 'node:child_process';
 import { readFileSync, appendFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { classify, changedPaths, compile, matcher, fakeSecret } from './owner-only.mjs';
+import { classify, changedPaths, compile, matcher, fakeSecret, repoFacts } from './owner-only.mjs';
+import { MISSING, HIT, fileHits, hidePath, shippedPaths, ships, termsFromEnv } from './private-terms.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';
@@ -115,6 +118,39 @@ export function secretRows(root, base, head, changes) {
   return rows;
 }
 
+// ------------------------------------------------------------------ private terms
+
+// The private-terms rule (roadmap R18, design docs/design-docs/private-terms/).
+// It holds when the base atlas.yaml names `private_terms: { paths }`, the
+// paths that ship in public. `terms` comes from the repo secret. It reads the
+// whole head text of each changed file that ships, binary or not, so a term
+// split over two lines, or already in an old line, is found too. A row names
+// the path, with [hidden] for a term in it, and the line, never the term.
+export function termRows(root, base, head, changes, terms) {
+  const paths = shippedPaths(repoFacts(root, base).facts);
+  if (paths === null) return [];
+  if (!paths.length) return [{ kind: 'red', class: 'private-term', cause: 'atlas.yaml private_terms names no paths' }];
+  if (!terms.length) return [{ kind: 'red', class: 'private-term', cause: MISSING }];
+  const rows = [];
+  for (const change of changes) {
+    if (change.status === 'D' || change.newMode === '160000' || !ships(paths, change.path)) continue;
+    const size = Number((git(root, ['cat-file', '-s', `${head}:${change.path}`], { allowFail: true }) ?? '0').trim());
+    if (size > SCAN_LIMIT) { rows.push({ kind: 'red', class: 'private-term', path: change.path, cause: `${size} bytes: too large to check for private terms` }); continue; }
+    for (const hit of fileHits(change.path, textAt(root, head, change.path) ?? '', terms)) {
+      rows.push({ kind: 'red', class: 'private-term', path: hit.path, ...(hit.line ? { line: hit.line } : {}), cause: hit.line ? `the line ${HIT}` : `the path ${HIT}` });
+    }
+  }
+  rows.push({ kind: 'note', class: 'private-term', cause: `private terms: ${terms.length} term(s), ${rows.length} hit(s)` });
+  return rows;
+}
+
+// The answer with each term hidden in every path and cause, so no row of any
+// rule shows a term in the summary, the log or the JSON.
+export function hideTerms(answer, terms) {
+  if (!terms?.length) return answer;
+  return { ...answer, rows: answer.rows.map((row) => ({ ...row, ...(row.path ? { path: hidePath(row.path, terms) } : {}), cause: hidePath(String(row.cause ?? ''), terms) })) };
+}
+
 // ------------------------------------------------------------------ jobs named like a check
 
 const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/;
@@ -230,7 +266,9 @@ function testRows({ root, mergeBase, head, body, redMain, rules, undo = null })
 // 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 }) {
+// `terms` is the list of private terms, or undefined to skip that rule (the
+// replay, which has no secret).
+export function judge({ root, base, head, body = '', redMain = [], rules = null, brake = {}, now = new Date(), signed = null, terms = undefined }) {
   const top = resolve(root);
   const baseSha = commitOf(top, base);
   if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
@@ -257,6 +295,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   for (const row of classify({ root: top, base: mergeBase, head: headSha, rules }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
   answer.rows.push(...jobRows(top, rules ?? mergeBase, headSha, changes));
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
+  if (terms !== undefined) answer.rows.push(...termRows(top, baseSha, headSha, changes, terms));
   answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules, undo }));
   if (signed) signedRows(top, baseSha, headSha, signed, answer);
   return finish(answer);
@@ -353,7 +392,8 @@ export function checkCommand({ root, base, head, body: bodyFile, json = false, s
       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 { terms } = termsFromEnv();
+    const answer = hideTerms(judge({ root, base, head, body, redMain, brake: Array.isArray(got) ? {} : got.brake ?? {}, signed, terms }), terms);
     const text = renderText(answer);
     if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
     else for (const each of text) line(each);
@@ -362,7 +402,7 @@ export function checkCommand({ root, base, head, body: bodyFile, json = false, s
     if (output && output !== true) appendFileSync(output, `result=${answer.result}\nclass=${/^[a-z-]+$/.test(answer.class ?? '') ? answer.class : 'none'}\n`);
     return answer.result === 'success' ? 0 : 1;
   } catch (error) {
-    line(`gate check: ${error.message}`);
+    line(`gate check: ${hidePath(error.message, termsFromEnv().terms)}`);
     // In the gate workflow (it passes --output), an error leaves a note with a
     // fixed title. The audit reads it to tell an error from a result (roadmap
     // R14 done line 5).

package/door/lib/gate.mjs

@@ -20,7 +20,7 @@ import { homedir } from 'node:os';
 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 { checkCommand, replayCommand, judge, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
 import { keepFindings, gateErrors, pinCode, slug, AUDIT_JOB } from './gate-audit.mjs';
 import { MARKER as SIGNED_MARKER } from './signed-act.mjs';
 import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
@@ -422,7 +422,7 @@ export function keepReady({ repo, pr, sha, code, home = homedir(), now = new Dat
 
 // `atlas gate audit --since <date>`: each pull request merged since the date
 // whose required checks were not all green at the moment of the merge.
-export function auditCommand({ repo, since, commit, errors = false, forced = false, findings }, line, gh = ghApi) {
+export function auditCommand({ repo, root, since, commit, errors = false, forced = false, findings }, line, gh = ghApi) {
   // R14: with --findings, each finding also goes into the file, and `atlas
   // jobs file` opens one issue for each. A call that stops with an error
   // marks the file broken, so the file job ends red.
@@ -431,7 +431,7 @@ export function auditCommand({ repo, since, commit, errors = false, forced = fal
   try {
     let code;
     if (errors) code = gateErrors({ repo, found }, line, gh);
-    else if (commit !== undefined) code = commitAudit({ repo, commit, forced, found }, line, gh);
+    else if (commit !== undefined) code = commitAudit({ repo, root, commit, forced, found }, line, gh);
     else code = sinceAudit({ repo, since }, line, gh);
     keep();
     return code;
@@ -472,7 +472,22 @@ function sinceAudit({ repo, since }, line, gh) {
 // gate run of that pull request came from the base copy of the gate
 // workflow. A commit that no pull request merged was pushed past the gate, so
 // it is red. With --forced, the push that brought it was a force push.
-export function commitAudit({ repo, commit, forced = false, found = [] }, line, gh) {
+// R14 done line 3: a merge that the gate sent to the owner needs the owner's
+// signed act for its head (R72). The audit judges the merged head again with
+// the base commit's rules, at the time of the merge, and reads the signed acts
+// of the pull request. It needs both commits in the clone. Returns 'owner'
+// when no signed act clears it, 'unread' when it cannot judge, else null.
+export function ownerUnsigned({ root, repo, pull, parent }, gh) {
+  const head = pull.head?.sha;
+  const has = (sha) => { try { execFileSync('git', ['-C', root, 'cat-file', '-e', `${sha}^{commit}`], { stdio: 'ignore' }); return true; } catch { return false; } };
+  if (!/^[0-9a-f]{40}$/.test(String(head)) || !/^[0-9a-f]{40}$/.test(String(parent)) || !has(head) || !has(parent)) return 'unread';
+  let texts = null;
+  try { texts = prComments(gh, repo, pull.number); } catch { texts = null; }
+  const answer = judge({ root, base: parent, head, body: String(pull.body ?? ''), now: new Date(pull.merged_at), signed: { repo, pr: Number(pull.number), baseRef: pull.base?.ref ?? null, texts } });
+  return answer.result === 'owner' ? 'owner' : null;
+}
+
+export function commitAudit({ repo, root = null, commit, forced = false, found = [] }, line, gh) {
   if (!commit || commit === true || !/^[0-9a-f]{7,40}$/i.test(String(commit))) throw new GateError('--commit needs a commit SHA.');
   // GitHub expands a short SHA, and names the first parent: the main branch
   // just before this commit, whose atlas.yaml held the gate at that moment.
@@ -498,6 +513,16 @@ export function commitAudit({ repo, commit, forced = false, found = [] }, line,
     found.push({ job: AUDIT_JOB, key: `gate-copy:${sha}`, kind: 'gate-copy', sha, pr: Number(pull.number), ...(one.run ? { run_id: Number(one.run) } : {}), pin: pinCode(one.why) });
   }
   const parent = fetched.parents?.[0]?.sha ?? pull.base.sha;
+  if (root) {
+    const owner = ownerUnsigned({ root, repo, pull, parent }, gh);
+    if (owner) {
+      red = true;
+      line(owner === 'owner'
+        ? `- ✗ #${pull.number} merged while the gate sent it to the owner, and no signed act names its head ${String(pull.head?.sha).slice(0, 7)}.`
+        : `- ✗ #${pull.number}: the head or the base commit is not in this clone, so the audit cannot judge it.`);
+      found.push({ job: AUDIT_JOB, key: `owner-unsigned:${sha}`, kind: 'owner-unsigned', sha, pr: Number(pull.number), ...(owner === 'unread' ? { pin: 'unread' } : {}) });
+    }
+  } else line(`- atlas gate audit: no clone (--root), so the owner check of #${pull.number} did not run.`);
   let checks;
   try { checks = checksAt(gh, repo, parent); } catch (error) {
     if (!(error instanceof GateError)) throw error;
@@ -629,7 +654,7 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
     }
     return code;
   }
-  if (what === 'audit') return auditCommand({ repo, since, commit, errors, forced, findings }, line, gh);
+  if (what === 'audit') return auditCommand({ repo, root, since, commit, errors, forced, findings }, line, gh);
   if (off && on) throw new GateError('pick --off or --on, not both.');
   const mode = off ? 'off' : on ? 'on' : 'apply';
   const facts = mode === 'apply' ? gateFacts(root) : null;

package/door/lib/install.mjs

@@ -218,12 +218,13 @@ export const recordName = (version, sha256) => `atlas-release-${version}-${sha25
 // commit must once have been the tip of master. A tag that a person made or
 // moved finds no record, so the upgrade refuses. With no sha256 (a loaded
 // copy has no tarball), any record of this version counts, and the byte
-// compare of every file does the rest.
+// compare of every file does the rest. A refusal carries a `code` too, for
+// the npm-release job of the watcher (jobs.mjs).
 export function findRelease({ gh, repo, version, sha256 }) {
   const commit = tagCommit(gh, repo, version);
-  if (!commit) return { problem: `no tag v${version} names a commit` };
-  if (!onMaster(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which is not on master` };
-  if (!wasTip(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which was never the tip of master through a merge or a push` };
+  if (!commit) return { code: 'no-tag', problem: `no tag v${version} names a commit` };
+  if (!onMaster(gh, repo, commit)) return { code: 'not-on-master', commit, problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which is not on master` };
+  if (!wasTip(gh, repo, commit)) return { code: 'never-tip', commit, problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which was never the tip of master through a merge or a push` };
   const runs = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/release.yml/runs?event=push&status=success&head_sha=${commit}&per_page=100`]).workflow_runs ?? [];
   const prefix = recordName(version, '');
   const named = (name) => (sha256 ? name === recordName(version, sha256) : name.startsWith(prefix) && /^[0-9a-f]{64}$/.test(name.slice(prefix.length)));
@@ -234,7 +235,7 @@ export function findRelease({ gh, repo, version, sha256 }) {
     const artifacts = gh(['api', '--method', 'GET', `repos/${repo}/actions/runs/${run.id}/artifacts?per_page=100`]).artifacts ?? [];
     if (artifacts.some((artifact) => named(artifact.name ?? ''))) return { run, commit };
   }
-  return { problem: `no successful release run on master commit ${commit.slice(0, 12)} recorded ${version}${sha256 ? ' with this tarball' : ''}` };
+  return { code: 'no-record', commit, problem: `no successful release run on master commit ${commit.slice(0, 12)} recorded ${version}${sha256 ? ' with this tarball' : ''}` };
 }
 
 // The blob ids that the version files of the tarball must have: the files of

package/door/lib/jobs.mjs

@@ -24,7 +24,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../shape/check.mjs';
+import { createHash } from 'node:crypto';
 import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+import { findRelease, sha512Integrity } from './install.mjs';
 import { checkGateFiles, checkGateAudit, checkGateErrors } from './gate-audit.mjs';
 import { commitAudit, ghApi } from './gate.mjs';
 
@@ -107,7 +109,100 @@ export async function checkRedMain({ repo, branch, env }) {
   return findings;
 }
 
-// The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
+// ---------------------------------------------------------------- the check of npm-release
+
+// A branch of the repo can run its own release.yml and publish to npm before any merge (the gate
+// probes, P7). So each version that npm got in the last NPM_DAYS days must have the proof that
+// `atlas upgrade` asks for: a successful push run of release.yml on a master commit that recorded
+// this version with the sha256 of this exact tarball (findRelease, install.mjs). The watcher runs
+// once a day, so two days cover one missed run. A longer window reaches versions from before the
+// release record existed (Atlas 0.4.0), and the tip proof reads only the newest 100 changes of master.
+export const NPM_DAYS = 2;
+export const NPM_MAX = 50;
+const PACKAGE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+// The npm packages that atlas.yaml names under `jobs: { npm: [...] }`.
+export function npmPackages(root) {
+  const facts = parseYaml(readFileSync(join(root, 'atlas.yaml'), 'utf8')) ?? {};
+  const named = facts.jobs?.npm;
+  if (!Array.isArray(named) || !named.length) throw new Error('atlas.yaml names no package under jobs.npm');
+  const bad = named.map(String).find((name) => !PACKAGE.test(name));
+  if (bad !== undefined) throw new Error('jobs.npm in atlas.yaml holds a name that is not an npm package name');
+  return named.map(String);
+}
+
+// https, or http for this machine only (a test uses a fake registry on 127.0.0.1).
+function registryBase(env) {
+  const text = String(env.NPM_REGISTRY_URL || 'https://registry.npmjs.org');
+  let url;
+  try { url = new URL(text); } catch { throw usage('NPM_REGISTRY_URL is not a URL'); }
+  const local = url.hostname === '127.0.0.1' || url.hostname === 'localhost';
+  if (!(url.protocol === 'https:' || (url.protocol === 'http:' && local))) throw usage('NPM_REGISTRY_URL must be https (http is allowed only for 127.0.0.1 or localhost)');
+  return url;
+}
+
+// findRelease reads GitHub through a sync `gh`. Here each read is a fetch, so the proof runs again
+// after each read it asked for, until it needs none. Every read is a GET, and the same path gives the
+// same answer, so a replay changes nothing.
+export async function replayRelease({ base, key, repo, version, sha256 }) {
+  const answers = new Map();
+  for (let round = 0; round < 50; round += 1) {
+    try {
+      return findRelease({
+        repo, version, sha256,
+        gh: (args) => {
+          const path = `/${args.at(-1)}`;
+          if (!answers.has(path)) throw Object.assign(new Error('a read is still to come'), { need: path });
+          const answer = answers.get(path);
+          if (answer instanceof Error) throw answer;
+          return answer;
+        },
+      });
+    } catch (error) {
+      if (!error.need) throw error;
+      const r = await api(base, key, 'GET', error.need);
+      if (r.status === 404) answers.set(error.need, Object.assign(new Error('Not Found'), { stderr: 'HTTP 404' }));
+      else if (!r.ok) throw new Error(`GitHub answered ${r.status} when the release of ${version} was read`);
+      else answers.set(error.need, r.data);
+    }
+  }
+  throw new Error(`the release of ${version} needed more than 50 reads`);
+}
+
+export async function checkNpmRelease({ repo, env, root, now = Date.now(), fetchImpl = fetch }) {
+  const base = apiBase(env);
+  const key = env.GITHUB_TOKEN || '';
+  if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
+  const registry = registryBase(env);
+  const findings = [];
+  for (const name of npmPackages(root)) {
+    const response = await fetchImpl(new URL(name.replace('/', '%2F'), `${registry.href.replace(/\/?$/, '/')}`));
+    if (!response.ok) throw new Error(`npm answered ${response.status} when ${name} was read`);
+    const doc = await response.json();
+    // A broken answer must read broken, never none: each version needs a publish time.
+    const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+    if (!object(doc?.versions) || !object(doc?.time)) throw new Error(`npm sent no versions and times for ${name}`);
+    if (Object.keys(doc.versions).some((version) => !Number.isFinite(Date.parse(doc.time[version])))) throw new Error(`npm sent a version of ${name} with no publish time`);
+    const recent = Object.keys(doc.versions).filter((version) => now - Date.parse(doc.time[version]) <= NPM_DAYS * DAY);
+    if (recent.length > NPM_MAX) throw new Error(`npm holds ${recent.length} versions of ${name} from the last ${NPM_DAYS} days, more than ${NPM_MAX}`);
+    for (const version of recent.sort()) {
+      if (!VALUE.test(version)) throw new Error(`npm holds a version of ${name} that is not a plain version`);
+      const dist = doc.versions[version].dist ?? {};
+      const tarball = new URL(String(dist.tarball ?? ''), registry);
+      if (tarball.origin !== registry.origin) throw new Error(`the tarball of ${name}@${version} is not on the registry`);
+      const got = await fetchImpl(tarball);
+      if (!got.ok) throw new Error(`npm answered ${got.status} when the tarball of ${name}@${version} was read`);
+      const bytes = Buffer.from(await got.arrayBuffer());
+      if (sha512Integrity(bytes) !== dist.integrity) throw new Error(`the tarball of ${name}@${version} does not match the integrity npm records`);
+      const release = await replayRelease({ base, key, repo, version, sha256: createHash('sha256').update(bytes).digest('hex') });
+      if (!release.problem) continue;
+      findings.push({ job: 'npm-release', key: `${name}@${version}`, package: name, version, problem: release.code, ...(release.commit ? { commit: release.commit } : {}) });
+    }
+  }
+  return findings;
+}
+
+// The check of each Atlas job, by its id, else by its `when`. A job whose check is not built yet reads `none` and
 // says so in the notes; it never reads `found` from nothing.
 // The gate jobs (roadmap R14) read GitHub through `gh`, which the Actions
 // runner holds; their token is the run's own GITHUB_TOKEN.
@@ -116,6 +211,7 @@ const CHECKS = {
   'gate-files': ({ root, env, fetchImpl }) => checkGateFiles({ root, env, fetchImpl }),
   'gate-audit': ({ repo, branch, gh }) => checkGateAudit({ repo, branch, gh, audit: commitAudit }),
   'gate-errors': ({ repo, gh }) => checkGateErrors({ repo, gh }),
+  'npm-release': checkNpmRelease,
 };
 
 export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs(), gh = ghApi, fetchImpl = fetch }) {
@@ -128,7 +224,7 @@ export async function jobsCheck({ root, repo, branch = null, env = process.env,
   for (const id of named) {
     const job = jobs.get(id);
     if (!job) { notes.push(`${JOB_ID.test(id) ? id : '(a bad id)'}: no Atlas job has this id`); continue; }
-    const check = CHECKS[job.when];
+    const check = CHECKS[job.id] ?? CHECKS[job.when];
     if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
     try {
       if (!mainBranch) mainBranch = await defaultBranch({ repo, env });

package/door/lib/privacy.mjs

@@ -36,15 +36,37 @@ export function loadPrivateTerms({ path = null, home = homedir() } = {}) {
     if (path) throw new Error(`the private terms file ${path} does not exist.`);
     return [];
   }
-  return readFileSync(file, 'utf8').split('\n').map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+  return parseTerms(readFileSync(file, 'utf8'));
+}
+
+// The terms of one terms file's text: one term on each line, and a line that
+// starts with # is a note. The Mac file and the repo secret share this form.
+export function parseTerms(text) {
+  return String(text ?? '').split('\n').map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+}
+
+// Text as the term rules read it: NFKC form, with the marks that do not
+// show (a soft hyphen, the zero-width marks, a byte-order mark) taken out.
+// It keeps every line break, so a line number stays true.
+const INVISIBLE = /[\u00AD\u200B-\u200D\u2060\uFEFF]/g;
+export const termText = (text) => String(text ?? '').normalize('NFKC').replace(INVISIBLE, '');
+
+// One rule for each private term. A term matches only as a whole word, in any
+// case. The words of a term may be split by any run of white space, also a
+// line break, so a wrapped paragraph still matches when the caller reads the
+// whole text.
+export function termRules(terms = []) {
+  return terms.map((term) => {
+    const words = termText(term).split(/\s+/).filter(Boolean).map(escape);
+    return { id: 'private-term', holds: 'One of the owner\'s private terms.', pattern: new RegExp(`(?<![\\p{L}\\p{N}])${words.join('\\s+')}(?![\\p{L}\\p{N}])`, 'iu') };
+  });
 }
 
 // Every rule this filter applies: the secret patterns, the generic patterns,
 // then one rule for each private term.
 export function privacyRules({ terms = [] } = {}) {
   const secrets = secretPatterns().map((pattern, index) => ({ id: `secret-${SECRET_PATTERNS[index].id}`, holds: SECRET_PATTERNS[index].holds, pattern }));
-  const own = terms.map((term) => ({ id: 'private-term', holds: 'One of the owner\'s private terms.', pattern: new RegExp(`(?<![A-Za-z0-9])${escape(term)}(?![A-Za-z0-9])`, 'i') }));
-  return [...secrets, ...PRIVACY_PATTERNS, ...own];
+  return [...secrets, ...PRIVACY_PATTERNS, ...termRules(terms)];
 }
 
 // Each finding names its line and its rule, never the text it matched, so a

package/door/lib/private-terms.mjs

@@ -0,0 +1,65 @@
+// The private-terms check of a public package (roadmap R18, tracker item
+// 437b99c1; design docs/design-docs/private-terms/). The release build runs
+// it on each file of the tarball, and the gate runs it on each added line
+// under the shipped paths of a pull request.
+//
+// The terms come from the repo secret ATLAS_PRIVATE_TERMS, in the form of the
+// owner's terms file. This plan gives a private repo no environments, so any
+// workflow run of this repo can read that secret, on any branch. A fork
+// cannot. The design accepts that: who can push here can already publish.
+//
+// A hit names the path and the line, never the term. A path that holds a
+// term shows [hidden] in its place. The text is read in NFKC form with the
+// marks that do not show taken out, and the words of a term may be split by
+// any white space.
+import { parseTerms, redact, termRules, termText } from './privacy.mjs';
+
+export const TERMS_ENV = 'ATLAS_PRIVATE_TERMS';
+export const MISSING = `the private terms are missing: the repo secret ${TERMS_ENV} is empty`;
+export const HIT = 'holds a private term';
+
+// The terms from the environment. `set` is false when the variable is absent
+// or holds notes only.
+export function termsFromEnv(env = process.env) {
+  const terms = parseTerms(env[TERMS_ENV]);
+  return { set: terms.length > 0, terms };
+}
+
+// The text with each term replaced by [hidden]. Text with no term comes back
+// as it was.
+export function hidePath(text, terms) {
+  if (!terms?.length) return text;
+  const clean = termText(text);
+  const hidden = redact(clean, { rules: termRules(terms) }).replace(/\[hidden: private-term\]/g, '[hidden]');
+  return hidden === clean ? text : hidden;
+}
+
+// The hits of one file: { path, line } for the first line of each match, and
+// { path, line: null } when the path holds a term. `path` is already hidden.
+// The whole text is read at once, so a term split over two lines still
+// matches.
+export function fileHits(path, text, terms) {
+  const rules = termRules(terms);
+  const shown = hidePath(path, terms);
+  const hits = [];
+  if (rules.some((rule) => rule.pattern.test(termText(path)))) hits.push({ path: shown, line: null });
+  const body = termText(text);
+  const lines = new Set();
+  for (const rule of rules) {
+    const all = new RegExp(rule.pattern.source, `${rule.pattern.flags}g`);
+    for (const match of body.matchAll(all)) lines.add(body.slice(0, match.index).split('\n').length);
+  }
+  for (const line of [...lines].sort((a, b) => a - b)) hits.push({ path: shown, line });
+  return hits;
+}
+
+// The shipped paths that atlas.yaml names under private_terms.paths, or null
+// when the key is not there.
+export function shippedPaths(facts) {
+  const entry = facts?.private_terms;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  const paths = Array.isArray(entry.paths) ? entry.paths.filter((path) => typeof path === 'string' && path) : [];
+  return paths;
+}
+
+export const ships = (paths, path) => paths.some((prefix) => (prefix.endsWith('/') ? path.startsWith(prefix) : path === prefix || path.startsWith(`${prefix}/`)));

package/door/workflows/atlas-gate-audit.yml

@@ -12,6 +12,8 @@ on:
 #   3. A merge made before the required checks of its pull request were
 #      green. A check counts only from a run of the base file that defines it.
 #   4. A gate run that is not from the base copy of atlas-gate.yml.
+#   5. A merge that the gate sends to the owner, with no signed act of the
+#      owner for its head (R72). The audit judges the head again from git.
 # Each finding opens one `atlas-job` issue, and the run ends red. It does not
 # undo the push.
 #

package/door/workflows/atlas-gate.yml

@@ -81,6 +81,8 @@ jobs:
       - name: Read the pull request text from the event
         run: node -e 'const fs=require("fs");const e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,"utf8"));fs.writeFileSync(process.env.RUNNER_TEMP+"/body.md",String(e.pull_request.body??""))'
 
+      # Only this step gets the private terms (roadmap R18). It runs the base
+      # code, and reads the head as git data.
       - name: Gate check
         id: check
         env:
@@ -88,6 +90,7 @@ jobs:
           BASE_REF: ${{ github.event.pull_request.base.ref }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           GH_TOKEN: ${{ github.token }}
+          ATLAS_PRIVATE_TERMS: ${{ secrets.ATLAS_PRIVATE_TERMS }}
         run: |
           set -euo pipefail
           node packages/atlas/bin/atlas gate check --root . --repo "$GITHUB_REPOSITORY" --base "$GITHUB_SHA" --head "$HEAD_SHA" --pr "$PR" --base-ref "$BASE_REF" --body "$RUNNER_TEMP/body.md" --summary "$GITHUB_STEP_SUMMARY" --output "$GITHUB_OUTPUT"

package/package.json

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

package/shape/check.mjs

@@ -38,7 +38,7 @@ export const sha256 = (text) => createHash('sha256').update(String(text ?? ''),
 // Whether a copy is current or behind is not decided here. CI has no package
 // and no network. The session verb decides it, from the release list that
 // ships beside this file in the package, shape/releases.json.
-export const CHECK_VERSION = 7;
+export const CHECK_VERSION = 8;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -1232,6 +1232,22 @@ function workflowStructure(document) {
   return out;
 }
 
+// The shape check takes no secret. The rule reads the job that runs the check
+// and the workflow-wide env, which every job gets. Another job of the same file
+// may give one step a secret: the gate step gets the private terms (roadmap
+// R18), and it runs the base code too. When the file cannot be read, or no job
+// runs the check, the rule reads the whole text.
+function readsSecret(text) {
+  const READS = /\bsecrets\./;
+  let document = null;
+  try { document = parseYaml(text); } catch { return READS.test(text); }
+  const jobs = document?.jobs && typeof document.jobs === 'object' ? Object.values(document.jobs) : [];
+  const job = jobs.find((candidate) => (Array.isArray(candidate?.steps) ? candidate.steps : [])
+    .some((step) => typeof step?.run === 'string' && step.run.includes(GATE_RUNNER.runs)));
+  if (!job) return READS.test(text);
+  return READS.test(JSON.stringify(job)) || READS.test(JSON.stringify(document.env ?? null));
+}
+
 function checkWorkflow(context, part) {
   const text = readText(context.root, part.path);
   if (text === null || !text.trim()) return result(part, 'empty', [`${part.path} is missing or holds nothing`]);
@@ -1254,7 +1270,7 @@ function checkWorkflow(context, part) {
   // a block map and a flow map for both permissions and steps, so read both
   // spellings or a workflow can widen itself past the check (review R-3).
   for (const grant of writeGrants(text)) findings.push(`the workflow grants ${grant}; this check needs read access only`);
-  if (/\bsecrets\./.test(text)) findings.push('the workflow reads a repository secret; this check takes none');
+  if (readsSecret(text)) findings.push('the workflow reads a repository secret; this check takes none');
   const unpinned = [...text.matchAll(/uses[ \t]*:[ \t]*["']?([^\s,}\]"']+)/g)]
     .map(([, value]) => value)
     .filter((value) => !value.startsWith('./'))

package/shape/releases.json

@@ -40,6 +40,12 @@
     {
       "check_version": 7,
       "sha256": "b29fdb036170419b9f0642ef0ca7da45a80ff53492421eb57beaf157df13d057",
+      "first_package": "0.4.17",
+      "workflow_sha256": "fcddebef030e6564f97e1a5fb81c8ad1b3084ebef9622167c6565698312dcdd7"
+    },
+    {
+      "check_version": 8,
+      "sha256": "8cf521f6e8f89ae65a257c521c583281e0c3c27ef968b4bd96eb336a8d095795",
       "workflow_sha256": "fcddebef030e6564f97e1a5fb81c8ad1b3084ebef9622167c6565698312dcdd7"
     }
   ]