@arjunkhera/atlas 0.4.25 → 0.4.27

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "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/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/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/lib/pull-request.mjs

@@ -23,7 +23,7 @@ export const TOOLING_LABEL = 'atlas-helper';
 
 // The only files the tooling writer may write: the check, its workflow, and
 // the pull request template when the repo has none.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/pull_request_template.md']);
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/workflows/atlas-upkeep.yml', '.github/pull_request_template.md']);
 // The only files the tooling writer may remove: the workflow of check versions
 // 1 to 5, which the gate workflow replaces (roadmap R7).
 export const TOOLING_REMOVALS = Object.freeze([OLD_WORKFLOW_PATH]);

package/door/lib/tooling.mjs

@@ -42,25 +42,34 @@ const oldWorkflow = (root) => existsSync(join(root, OLD_WORKFLOW_PATH));
 // repo backwards, and never replaces a hand edit at the same version.
 export const JOBS_PATH = '.github/workflows/atlas-jobs.yml';
 export const PACKAGE_JOBS_SOURCE = 'door/templates/atlas-jobs.yml';
+// The upkeep check on each pull request (roadmap R41). The same pin rule holds.
+// The Atlas repo keeps its own atlas-upkeep.yml, which runs the package of
+// master and has no pin, so the writer keeps it and Atlas runs one upkeep job.
+export const UPKEEP_PATH = '.github/workflows/atlas-upkeep.yml';
+export const PACKAGE_UPKEEP_SOURCE = 'door/templates/atlas-upkeep.yml';
+// The workflows the writer pins, in the order of its rows.
+const PINNED = Object.freeze([[JOBS_PATH, PACKAGE_JOBS_SOURCE], [UPKEEP_PATH, PACKAGE_UPKEEP_SOURCE]]);
 const VERSION_SLOT = '__ATLAS_VERSION__';
-export function packagedJobsWorkflow(packageRoot) {
-  const full = join(packageRoot, PACKAGE_JOBS_SOURCE);
+function packagedPinned(packageRoot, source) {
+  const full = join(packageRoot, source);
   return existsSync(full) ? readFileSync(full, 'utf8').split(VERSION_SLOT).join(packagePackageVersion(packageRoot)) : null;
 }
-const jobsPin = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
+export const packagedJobsWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_JOBS_SOURCE);
+export const packagedUpkeepWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_UPKEEP_SOURCE);
+const pinOf = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
 const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
-// written, refreshed, unchanged or kept: what the writer does with the watcher.
-function jobsState(root, packageRoot) {
-  const wanted = packagedJobsWorkflow(packageRoot);
+// written, refreshed, unchanged or kept: what the writer does with one pinned workflow.
+function pinnedState(root, packageRoot, path, source) {
+  const wanted = packagedPinned(packageRoot, source);
   if (wanted === null) return null;
-  const full = join(root, JOBS_PATH);
+  const full = join(root, path);
   if (!existsSync(full)) return 'written';
   const was = readFileSync(full, 'utf8');
   if (was === wanted) return 'unchanged';
-  const have = jobsPin(was);
-  return have && older(have, jobsPin(wanted)) ? 'refreshed' : 'kept';
+  const have = pinOf(was);
+  return have && older(have, pinOf(wanted)) ? 'refreshed' : 'kept';
 }
-const jobsNeedWrite = (root, packageRoot) => ['written', 'refreshed'].includes(jobsState(root, packageRoot));
+const pinnedNeedWrite = (root, packageRoot) => PINNED.some(([path, source]) => ['written', 'refreshed'].includes(pinnedState(root, packageRoot, path, source)));
 
 // The pull request template (roadmap R8). The writer puts it into a repo that
 // has none, and never replaces a template the repo keeps.
@@ -113,7 +122,7 @@ export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOn
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
   const now = status({ root, packageRoot });
-  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !pinnedNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE || workflowKept(root) ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });
   }
   if (now.state === 'unknown' && !replaceUnknown && !own) {
@@ -145,16 +154,17 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     if (!dryRun) rmSync(join(root, OLD_WORKFLOW_PATH));
     rows.push({ path: OLD_WORKFLOW_PATH, state: 'removed', sha256: null, was: sha256(was) });
   }
-  const jobs = workflowOnly ? null : jobsState(root, packageRoot);
-  if (jobs !== null) {
-    const contents = packagedJobsWorkflow(packageRoot);
-    const full = join(root, JOBS_PATH);
+  for (const [path, source] of workflowOnly ? [] : PINNED) {
+    const state = pinnedState(root, packageRoot, path, source);
+    if (state === null) continue;
+    const contents = packagedPinned(packageRoot, source);
+    const full = join(root, path);
     const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
-    if ((jobs === 'written' || jobs === 'refreshed') && !dryRun) {
+    if ((state === 'written' || state === 'refreshed') && !dryRun) {
       mkdirSync(dirname(full), { recursive: true });
       writeFileSync(full, contents);
     }
-    rows.push({ path: JOBS_PATH, state: jobs, sha256: sha256(jobs === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
+    rows.push({ path, state, sha256: sha256(state === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
   }
   const template = workflowOnly ? null : packagedTemplate(packageRoot);
   if (template !== null) {
@@ -180,7 +190,7 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
     throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
+  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [UPKEEP_PATH]: packagedUpkeepWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => (row.state === 'removed' ? {
@@ -196,8 +206,8 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
           : row.path === PR_TEMPLATE_PATH
             ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
-            : row.path === JOBS_PATH
-              ? `written from ${PACKAGE_JOBS_SOURCE}, with its pin set to Atlas ${version}`
+            : row.path === JOBS_PATH || row.path === UPKEEP_PATH
+              ? `written from ${row.path === JOBS_PATH ? PACKAGE_JOBS_SOURCE : PACKAGE_UPKEEP_SOURCE}, with its pin set to Atlas ${version}`
               : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));

package/door/templates/atlas-upkeep.yml

@@ -0,0 +1,45 @@
+name: atlas-upkeep
+# The Atlas upkeep check on each pull request: plain code, no model and no
+# secret. `atlas tooling` wrote this file from the Atlas package; do not edit
+# it by hand. A newer Atlas moves the pin below when `atlas tooling pr` runs.
+#
+# It stops drift at its source: the docs index lists each doc, every doc link
+# resolves, each doc names its code, and the pull request names its tracker
+# item, or says "no item:" and a reason. A repo with no docs/ folder passes
+# the index part with one line.
+#
+# It runs a pinned Atlas release from npm, never code of the pull request. It
+# runs on pull_request, not pull_request_target, so it holds only a read token
+# and no secret, also for a pull request from a fork. npx runs outside the
+# checkout, so an .npmrc in the pull request cannot pick the registry.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: atlas-upkeep-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  upkeep:
+    name: docs · upkeep check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Upkeep check
+        run: |
+          set -euo pipefail
+          cd "$RUNNER_TEMP"
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ upkeep check --root "$GITHUB_WORKSPACE" --event "$GITHUB_EVENT_PATH" | tee -a "$GITHUB_STEP_SUMMARY"

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.25",
+  "version": "0.4.27",
   "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"
     }
   ]