@arjunkhera/atlas 0.3.49 → 0.3.51

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -17,7 +17,7 @@ import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { open } from './lib/pull-request.mjs';
 import { write as writeTooling, changes as toolingChanges, ToolingRefusal, CHECK_PATH, WORKFLOW_PATH } from './lib/tooling.mjs';
-import { status, statusMany } from './lib/status.mjs';
+import { statusMany, copies } from './lib/status.mjs';
 import { drift, kindsFromRegistry, fileKind } from './lib/kind-drift.mjs';
 import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs';
 import { packagePackageVersion } from './lib/releases.mjs';
@@ -50,6 +50,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       --replace-unknown                also replace a copy that is in no release
       --workflow                       rewrite only the workflow, for a repo whose check is current
   atlas status --root <repo>           is the repo's check current, behind, unknown or missing
+      --all                            every Atlas copy in the repo: the check, its workflow, each test kit, each pinned Atlas version
+      --json                           print the rows as JSON: type, path, state, have, want, why
   atlas kind-drift --root <repo> --record-kind <kinds>
                                        does atlas.yaml agree with the repo record
   atlas check --root <repo>            run the repo shape check here
@@ -135,6 +137,9 @@ const HELP = `atlas — the door into a repo's Atlas files
       --root <repo>                    the checkout to read atlas.yaml from (default: this folder)
       --dry-run                        print each call; change nothing
       --off | --on                     break glass: turn both rulesets off, or back on
+      On a GitHub plan with no rulesets, apply changes nothing and reports advisory mode.
+  atlas gate ready --repo <owner/name> --pr <n>   may this pull request merge: every required check green on its head
+  atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
 
   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
@@ -167,7 +172,7 @@ A person merges every file the tooling writer writes.
 // skipped the privacy filter and printed GREEN (review of PR #107).
 export const FLAGS = Object.freeze({
   tooling: { root: 'optional', branch: 'optional', 'replace-unknown': 'switch', workflow: 'switch', 'dry-run': 'switch' },
-  status: { root: 'optional' },
+  status: { root: 'optional', all: 'switch', json: 'switch' },
   'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
   check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
   ste: { share: 'switch', terms: 'value' },
@@ -175,7 +180,7 @@ 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' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: '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' },
@@ -250,6 +255,7 @@ function toolingCommand(chosen) {
 
 function statusCommand(chosen) {
   const roots = chosen._.slice(1).length ? chosen._.slice(1).map((one) => resolve(one)) : [rootOf(chosen)];
+  if (chosen.all || chosen.json) return copiesCommand(roots, { all: Boolean(chosen.all), json: Boolean(chosen.json) });
   const rows = statusMany(roots, PACKAGE_ROOT);
   for (const row of rows) {
     line(`${row.state.toUpperCase().padEnd(8)} ${row.root}`);
@@ -262,6 +268,29 @@ function statusCommand(chosen) {
   return rows.some((row) => row.state === 'behind') ? 1 : 0;
 }
 
+// One row for each Atlas copy (roadmap item R19). Exit 1 when a copy is
+// behind or broken, so a watcher can act on the exit alone.
+function copiesCommand(roots, { all, json }) {
+  const repos = roots.map((root) => copies({ root, packageRoot: PACKAGE_ROOT, all }));
+  const decided = `Decided by the release lists in Atlas ${ATLAS_VERSION}, never by git history or the network.`;
+  if (json) {
+    line(JSON.stringify({ atlas: ATLAS_VERSION, decided_by: decided, repos }, null, 2));
+  } else {
+    for (const repo of repos) {
+      line(repo.root);
+      for (const one of repo.rows) {
+        line(`  ${one.state.toUpperCase().padEnd(8)} ${one.type.padEnd(8)} ${one.path}`);
+        line(`           have ${one.have ?? '—'} · want ${one.want}`);
+        if (one.state !== 'current' || one.have !== one.want) line(`           ${one.why}`);
+      }
+      line('');
+    }
+    line(decided);
+  }
+  const bad = all ? ['behind', 'broken'] : ['behind'];
+  return repos.some((repo) => repo.rows.some((one) => bad.includes(one.state))) ? 1 : 0;
+}
+
 function kindDriftCommand(chosen) {
   const root = rootOf(chosen);
   let recordKind = chosen['record-kind'] ?? null;
@@ -388,7 +417,7 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on) }, 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 }, line);
 }
 
 function judgeVerb(chosen) {

package/door/lib/gate.mjs

@@ -6,6 +6,12 @@
 //   2. "atlas release tags" on v* tags: no update, no delete.
 // The bypass list stays empty. --off and --on are the break glass.
 //
+// A private repo on a free GitHub plan gets no rulesets (owner, 24 October
+// 2026: "ignore pro and assume going with that check in place"). There the
+// gate is advisory: apply changes nothing and says so, `atlas gate ready`
+// says if one pull request may merge, and `atlas gate audit` names each merge
+// that came before its checks were green (design docs/design-docs/gate-advisory/).
+//
 // The plan is built by pure functions, so a test reads it without GitHub. The
 // gh calls sit in one place, behind `gh`, which a test replaces.
 import { execFileSync } from 'node:child_process';
@@ -26,7 +32,11 @@ export class GateError extends Error {}
 export function gateFacts(root) {
   const path = join(root, 'atlas.yaml');
   if (!existsSync(path)) throw new GateError(`there is no atlas.yaml in ${root}. Nothing was changed.`);
-  const facts = parseYaml(readFileSync(path, 'utf8')) ?? {};
+  return factsOf(readFileSync(path, 'utf8'));
+}
+
+function factsOf(text) {
+  const facts = parseYaml(text) ?? {};
   const checks = facts.required_checks;
   if (!Array.isArray(checks) || checks.length === 0 || checks.some((name) => typeof name !== 'string' || !name.trim())) {
     throw new GateError('atlas.yaml lists no required_checks. Nothing was changed.');
@@ -141,20 +151,100 @@ export function compare(wanted, got) {
 export function ghApi(method, path, body) {
   const args = ['api', '--method', method, path, '-H', 'Accept: application/vnd.github+json'];
   if (body !== undefined) args.push('--input', '-');
-  const out = execFileSync('gh', args, { encoding: 'utf8', input: body === undefined ? undefined : JSON.stringify(body), env: childEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] });
+  const out = execFileSync('gh', args, { encoding: 'utf8', input: body === undefined ? undefined : JSON.stringify(body), env: childEnvironment(), stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
   return out.trim() ? JSON.parse(out) : null;
 }
 
+// GitHub's answer when the repo's plan has no rulesets.
+const PLAN_REFUSAL = /Upgrade to GitHub Pro|make this repository public/i;
+export const ADVISORY = 'advisory mode: the checks run on each pull request, but GitHub does not block a merge on this plan. Merge only when "atlas gate ready" says READY.';
+
 const explain = (error) => {
   const text = `${error.stderr ?? ''}${error.message ?? ''}`;
   if (/HTTP 403|Upgrade to GitHub Pro|403/.test(text)) return 'GitHub refused the ruleset (403). A private repo needs GitHub Pro for rulesets, and only a repo admin may set one.';
   return text.trim().split('\n').slice(-3).join(' ');
 };
 
-// `atlas gate apply`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false }, line, gh = ghApi) {
-  if (what !== 'apply') throw new GateError(`there is no gate verb "${what ?? ''}". Use apply.`);
-  if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError('atlas gate apply needs --repo <owner/name>.');
+// The state of each required check on one commit, from its GitHub Actions
+// check runs. `at` is a time: a run that ended after it does not count.
+// A check is green only when its newest run from GitHub Actions ended in success.
+export function checkStates(checks, runs, at = null) {
+  return checks.map((name) => {
+    const mine = (runs ?? [])
+      .filter((run) => run.name === name && run.app?.id === ACTIONS_APP_ID)
+      .filter((run) => at === null || (run.started_at ?? run.completed_at ?? '') <= at)
+      .sort((a, b) => String(b.started_at ?? '').localeCompare(String(a.started_at ?? '')));
+    const newest = mine[0];
+    if (!newest) return { name, state: 'missing' };
+    if (newest.status !== 'completed' || (at !== null && (newest.completed_at ?? '') > at)) return { name, state: 'pending' };
+    return { name, state: newest.conclusion === 'success' ? 'green' : 'red', conclusion: newest.conclusion };
+  });
+}
+
+// The required checks as atlas.yaml listed them at one commit on GitHub. Ready
+// reads the base branch, so a pull request cannot drop its own red check, and
+// audit reads the base of each merge, so a later rename gives no false alarm.
+function checksAt(gh, repo, ref) {
+  const file = gh('GET', `repos/${repo}/contents/atlas.yaml?ref=${encodeURIComponent(ref)}`);
+  if (typeof file?.content !== 'string') throw new GateError(`there is no atlas.yaml in ${repo} at ${ref}.`);
+  return factsOf(Buffer.from(file.content, 'base64').toString('utf8')).checks;
+}
+
+const checkRuns = (gh, repo, sha) => gh('GET', `repos/${repo}/commits/${sha}/check-runs?per_page=100`)?.check_runs ?? [];
+const checkLine = (row) => `  ${row.state === 'green' ? '✓' : '✗'} ${row.state.padEnd(8)} ${row.name}${row.conclusion && row.state === 'red' ? ` (${row.conclusion})` : ''}`;
+
+// `atlas gate ready --pr <n>`: may this pull request merge now? Exit 0 when
+// every required check is green on its head commit, 1 when not.
+export function readyCommand({ repo, pr }, line, gh = ghApi) {
+  if (!pr || pr === true || !/^\d+$/.test(String(pr))) throw new GateError('atlas gate ready needs --pr <number>.');
+  const pull = gh('GET', `repos/${repo}/pulls/${pr}`);
+  if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
+  const sha = pull.head.sha;
+  const checks = checksAt(gh, repo, pull.base.ref);
+  const rows = checkStates(checks, checkRuns(gh, repo, sha));
+  line(`atlas gate ready: #${pr} at ${sha.slice(0, 7)}, ${checks.length} required check(s) from atlas.yaml on ${pull.base.ref}.`);
+  for (const row of rows) line(checkLine(row));
+  const ready = rows.every((row) => row.state === 'green');
+  line(ready ? 'READY: every required check is green. Merge with a merge commit, at this head.' : 'NOT READY: do not merge. Wait for a pending check; fix a red or missing one.');
+  return ready ? 0 : 1;
+}
+
+// `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 }, line, gh = ghApi) {
+  const from = since && since !== true ? since : new Date(Date.now() - 864e5).toISOString().slice(0, 10);
+  if (Number.isNaN(Date.parse(from))) throw new GateError(`--since must be a date, not "${from}".`);
+  const closed = gh('GET', `repos/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100`) ?? [];
+  const merged = closed.filter((pull) => pull.merged_at && pull.merged_at >= new Date(from).toISOString());
+  line(`atlas gate audit: ${merged.length} pull request(s) merged into ${repo} since ${from}.`);
+  if (closed.length >= 100 && (closed.at(-1)?.updated_at ?? '') >= new Date(from).toISOString()) line('  (only the 100 closed pull requests updated last were read; give a later --since to read all of them)');
+  const lists = new Map();
+  const checksOf = (sha) => {
+    if (!lists.has(sha)) { try { lists.set(sha, checksAt(gh, repo, sha)); } catch (error) { if (!(error instanceof GateError)) throw error; lists.set(sha, null); } }
+    return lists.get(sha);
+  };
+  let red = 0;
+  let ungated = 0;
+  for (const pull of merged) {
+    const checks = checksOf(pull.base.sha);
+    if (!checks) { ungated += 1; continue; }
+    const rows = checkStates(checks, checkRuns(gh, repo, pull.head.sha), pull.merged_at);
+    const bad = rows.filter((row) => row.state !== 'green');
+    if (!bad.length) continue;
+    red += 1;
+    line(`  ✗ #${pull.number} merged ${pull.merged_at} before its checks were green: ${bad.map((row) => `${row.name} ${row.state}`).join(', ')}`);
+  }
+  if (ungated) line(`  (${ungated} merge(s) had a base whose atlas.yaml listed no required_checks; nothing to audit there)`);
+  line(red ? `RED MERGES: ${red}. Look at each one now; the main branch may hold an untested change.` : 'every merge came after its required checks were green.');
+  return red ? 1 : 0;
+}
+
+// `atlas gate apply|ready|audit`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since }, line, gh = ghApi) {
+  if (!['apply', 'ready', 'audit'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready or audit.`);
+  if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
+  if (what === 'ready') return readyCommand({ repo, pr }, line, gh);
+  if (what === 'audit') return auditCommand({ repo, since }, 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;
@@ -163,6 +253,11 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
   line(`GET    repos/${repo}/rulesets`);
   let existing;
   try { existing = gh('GET', `repos/${repo}/rulesets`) ?? []; } catch (error) {
+    if (mode === 'apply' && PLAN_REFUSAL.test(`${error.stderr ?? ''}${error.message ?? ''}`)) {
+      line(`atlas gate apply: ${ADVISORY}`);
+      line('Nothing was changed. Auto-merge stays off: with no ruleset, GitHub would merge at once, before the checks end.');
+      return 0;
+    }
     if (!dryRun) { line(`atlas gate apply: ${explain(error)} Nothing was changed.`); return 1; }
     line(`       (the read failed: ${explain(error)} The plan below assumes no ruleset exists.)`);
     existing = [];

package/door/lib/status.mjs

@@ -13,10 +13,12 @@
 //
 // CI never makes this judgement. A check with no network cannot learn the
 // package's list. This runs in a session, with the package on disk.
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { CHECK_PATH, checkStamps, sha256 } from '../../shape/check.mjs';
-import { packagedCheck, placeOf } from './releases.mjs';
+import { readFileSync, existsSync, readdirSync, lstatSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, checkStamps, sha256 } from '../../shape/check.mjs';
+import { packagedCheck, placeOf, packagePackageVersion } from './releases.mjs';
+import { currentKitHash, KIT_RELEASES_FILE, KIT_TARGET, MANIFEST } from './tests.mjs';
+import { kitHashOf } from '../../tests/link-check.mjs';
 
 export const STATES = Object.freeze(['current', 'behind', 'unknown', 'missing']);
 
@@ -45,3 +47,220 @@ export function status({ root, packageRoot }) {
 export function statusMany(roots, packageRoot) {
   return roots.map((root) => { try { return status({ root, packageRoot }); } catch (error) { return { root, state: 'unknown', why: error.message, packaged: null, copy: null }; } });
 }
+
+// ---------------------------------------------------------------------------
+// Every Atlas copy in a repository, and the age of each one (roadmap item
+// R19, slice 0 of the routines design). The check is one copy of four types:
+//
+//   check     .github/atlas/check.mjs, by the release list of the check
+//   workflow  .github/workflows/atlas-check.yml, by the workflow fingerprint
+//             in each row of that list
+//   kit       each <area>/test/atlas/, by its manifest and the kit list
+//   pin       an Atlas version written in a workflow, a script or package.json
+//
+// Each row has have, want and state. A copy that cannot be read is broken,
+// never missing. Like the check alone, every answer comes from the lists this
+// package carries, never from git history or the network.
+export const COPY_STATES = Object.freeze(['current', 'behind', 'unknown', 'missing', 'broken']);
+export const COPY_TYPES = Object.freeze(['check', 'workflow', 'kit', 'pin']);
+
+const posix = (path) => path.split(sep).join('/');
+const SKIP = new Set(['node_modules', '.git']);
+const MAX_DEPTH = 8;
+const MAX_PIN_FILE = 512 * 1024;
+
+const row = (type, path, state, have, want, why) => ({ type, path, state, have, want, why });
+const broken = (type, path, want, error) => row(type, path, 'broken', null, want, `it cannot be read: ${error.message}`);
+// A link is never read. A link at a copy's path, even one that points
+// nowhere, is a copy that cannot be read: broken, never missing.
+const linkAt = (full) => { try { return lstatSync(full).isSymbolicLink(); } catch { return false; } };
+const linked = (type, path, want) => row(type, path, 'broken', null, want, `${path} is a link. Atlas never reads a copy through a link. Replace it with a plain file or folder.`);
+
+function checkRow(root, packageRoot) {
+  const pkg = packagedCheck(packageRoot);
+  const want = `check version ${checkStamps(pkg.text).check_version}`;
+  if (linkAt(join(root, CHECK_PATH))) return linked('check', CHECK_PATH, want);
+  let answer;
+  try { answer = status({ root, packageRoot }); } catch (error) { return broken('check', CHECK_PATH, want, error); }
+  const have = answer.copy ? (answer.state === 'unknown' ? `sha256 ${answer.copy.sha256.slice(0, 12)}…` : `check version ${answer.copy.check_version}`) : null;
+  return row('check', CHECK_PATH, answer.state, have, want, answer.why);
+}
+
+// The workflow is written with the check, from the WORKFLOW_TEMPLATE of that
+// check. Each row of the release list keeps the fingerprint of its template.
+function workflowRow(root, packageRoot) {
+  const pkg = packagedCheck(packageRoot);
+  const version = checkStamps(pkg.text).check_version;
+  const want = `workflow of check version ${version}`;
+  const full = join(root, WORKFLOW_PATH);
+  if (linkAt(full)) return linked('workflow', WORKFLOW_PATH, want);
+  if (!existsSync(full)) return row('workflow', WORKFLOW_PATH, 'missing', null, want, `${WORKFLOW_PATH} does not exist in this repo, so its check never runs in CI. "atlas tooling pr" adds it.`);
+  let text;
+  try { text = readFileSync(full, 'utf8'); } catch (error) { return broken('workflow', WORKFLOW_PATH, want, error); }
+  const fingerprint = sha256(text);
+  if (fingerprint === sha256(WORKFLOW_TEMPLATE)) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'the workflow is the one this package writes.');
+  const rows = pkg.releases.filter((one) => one.workflow_sha256 === fingerprint);
+  if (rows.length) {
+    const newest = rows.at(-1);
+    return row('workflow', WORKFLOW_PATH, 'behind', `workflow of check version ${newest.check_version}`, want, `the workflow was first written by Atlas ${rows[0].first_package}. "atlas tooling pr --workflow" refreshes it.`);
+  }
+  return row('workflow', WORKFLOW_PATH, 'unknown', `sha256 ${fingerprint.slice(0, 12)}…`, want, `the workflow is in no release. Someone edited it, or it came from an unreleased package. "atlas tooling pr" shows the difference.`);
+}
+
+// A walk never follows a link and never enters node_modules or .git. The
+// visit sees a link as a link, and says which other folders it enters: it
+// returns false to stop.
+function walk(dir, visit, depth = 0) {
+  if (depth > MAX_DEPTH) return;
+  let names;
+  try { names = readdirSync(dir).sort(); } catch { return; }
+  for (const name of names) {
+    if (SKIP.has(name)) continue;
+    const full = join(dir, name);
+    let stat;
+    try { stat = lstatSync(full); } catch { continue; }
+    if (visit(full, name, stat) === false) continue;
+    if (stat.isDirectory()) walk(full, visit, depth + 1);
+  }
+}
+
+// Each <area>/test/atlas/ folder, where "atlas tests write" puts the kit. A
+// dot folder holds no area: the check's base tree is one.
+function kitFolders(root) {
+  const found = [];
+  const [parent, leaf] = KIT_TARGET.split('/');
+  walk(root, (full, name, stat) => {
+    const isKit = name === leaf && full.split(sep).at(-2) === parent;
+    if (isKit && stat.isSymbolicLink()) { found.push(full); return false; }
+    if (!stat.isDirectory() || name.startsWith('.')) return false;
+    if (isKit) { found.push(full); return false; }
+    return true;
+  });
+  return found;
+}
+
+function kitFilesOnDisk(dir, prefix = '') {
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (name === '__pycache__') continue;
+    const full = join(dir, name);
+    const stat = lstatSync(full);
+    if (stat.isDirectory()) out.push(...kitFilesOnDisk(full, `${prefix}${name}/`));
+    else out.push({ path: `${prefix}${name}`, full, link: stat.isSymbolicLink() });
+  }
+  return out;
+}
+
+function kitRow(root, dir, ctx) {
+  const path = `${posix(relative(root, dir))}/`;
+  const area = posix(relative(root, join(dir, '..', '..'))) || '.';
+  const want = `kit of Atlas ${ctx.version}`;
+  const refresh = `"atlas tests write --root ${area}" refreshes it.`;
+  if (linkAt(dir)) return linked('kit', path, want);
+  try {
+    const manifestPath = join(dir, MANIFEST);
+    if (!existsSync(manifestPath)) return row('kit', path, 'broken', null, want, `the kit has no ${MANIFEST}, so its age cannot be read. ${refresh}`);
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); } catch { return row('kit', path, 'broken', null, want, `${MANIFEST} is not JSON, so the kit's age cannot be read. ${refresh}`); }
+    const listed = manifest?.files;
+    if (!listed || typeof listed !== 'object' || Array.isArray(listed)) return row('kit', path, 'broken', null, want, `${MANIFEST} lists no files, so the kit's age cannot be read. ${refresh}`);
+    const have = `kit of Atlas ${typeof manifest.atlas === 'string' ? manifest.atlas : '?'}`;
+    const onDisk = kitFilesOnDisk(dir).filter((one) => one.path !== MANIFEST);
+    const edited = [];
+    for (const one of onDisk) {
+      if (one.link || !Object.hasOwn(listed, one.path) || sha256(readFileSync(one.full)) !== listed[one.path]) edited.push(one.path);
+    }
+    const present = new Set(onDisk.map((one) => one.path));
+    for (const listedPath of Object.keys(listed)) if (!present.has(listedPath)) edited.push(listedPath);
+    if (edited.length) return row('kit', path, 'unknown', have, want, `${edited.length} file(s) differ from ${MANIFEST}: ${edited.slice(0, 3).join(', ')}. Someone edited the kit. ${refresh}`);
+    const hash = kitHashOf(listed);
+    if (hash === ctx.kitHash) return row('kit', path, 'current', have, want, `the kit is the one this package ships${have === want ? '' : '; only its version label is older'}.`);
+    const first = ctx.kitReleases.get(hash);
+    if (first) return row('kit', path, 'behind', have, want, `the kit was first shipped in Atlas ${first}. ${refresh}`);
+    return row('kit', path, 'unknown', have, want, `the kit is in no release. It came from an unreleased package, or someone edited its ${MANIFEST}. ${refresh}`);
+  } catch (error) {
+    return broken('kit', path, want, error);
+  }
+}
+
+// A version number compared part by part: -1, 0 or 1.
+function compare(a, b) {
+  const [x, y] = [a, b].map((one) => one.split('.').map(Number));
+  for (let index = 0; index < 3; index += 1) if (x[index] !== y[index]) return x[index] < y[index] ? -1 : 1;
+  return 0;
+}
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+
+// The places a repo writes an Atlas version: the workflows and actions under
+// .github/, the scripts under scripts/, and package.json. A tag such as
+// "latest", or a version held in a variable, is no pin.
+function pinFiles(root) {
+  const files = [];
+  for (const top of ['.github', 'scripts']) {
+    const dir = join(root, top);
+    if (!existsSync(dir)) continue;
+    walk(dir, (full, name, stat) => {
+      if (stat.isFile() && stat.size <= MAX_PIN_FILE && posix(relative(root, full)) !== CHECK_PATH) files.push(full);
+      return stat.isDirectory();
+    });
+  }
+  const manifest = join(root, 'package.json');
+  if (existsSync(manifest)) files.push(manifest);
+  return files;
+}
+
+function pinRows(root, ctx) {
+  const name = escape(ctx.name);
+  const patterns = [
+    new RegExp(`${name}@(\\d+\\.\\d+\\.\\d+)\\b`, 'g'),
+    new RegExp(`"${name}"\\s*:\\s*"[~^=]?(\\d+\\.\\d+\\.\\d+)"`, 'g'),
+    /\bATLAS_VERSION\s*[:=]\s*["']?(\d+\.\d+\.\d+)\b/g,
+  ];
+  const rows = [];
+  for (const full of pinFiles(root)) {
+    const file = posix(relative(root, full));
+    let text;
+    try { text = readFileSync(full, 'utf8'); } catch (error) { rows.push(broken('pin', file, ctx.version, error)); continue; }
+    text.split('\n').forEach((line, index) => {
+      const seen = new Set();
+      for (const pattern of patterns) {
+        for (const match of line.matchAll(pattern)) {
+          if (seen.has(match[1])) continue;
+          seen.add(match[1]);
+          const at = `${file}:${index + 1}`;
+          const order = compare(match[1], ctx.version);
+          if (order === 0) rows.push(row('pin', at, 'current', match[1], ctx.version, 'the pin names the version of this package.'));
+          else if (order < 0) rows.push(row('pin', at, 'behind', match[1], ctx.version, `the pin names Atlas ${match[1]}, and this package is ${ctx.version}. Move the pin in this line.`));
+          else rows.push(row('pin', at, 'unknown', match[1], ctx.version, `the pin names Atlas ${match[1]}, which is newer than this package. Upgrade Atlas to judge it.`));
+        }
+      }
+    });
+  }
+  return rows;
+}
+
+function kitReleases(packageRoot) {
+  const file = join(packageRoot, KIT_RELEASES_FILE);
+  if (!existsSync(file)) return new Map();
+  return new Map((JSON.parse(readFileSync(file, 'utf8')).releases ?? []).map((one) => [String(one.kit_sha256), String(one.first_package)]));
+}
+
+// One row for each Atlas copy in the repository. With all false, only the
+// check, which is what "atlas status" answered before --all.
+export function copies({ root, packageRoot, all = true }) {
+  const version = packagePackageVersion(packageRoot);
+  const rows = [checkRow(root, packageRoot)];
+  if (all) {
+    const ctx = {
+      version,
+      name: JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).name,
+      kitHash: currentKitHash(packageRoot),
+      kitReleases: kitReleases(packageRoot),
+    };
+    rows.push(workflowRow(root, packageRoot));
+    for (const dir of kitFolders(root)) rows.push(kitRow(root, dir, ctx));
+    rows.push(...pinRows(root, ctx));
+  }
+  return { root, atlas: version, rows };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.49",
+  "version": "0.3.51",
   "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/releases.json

@@ -1,30 +1,35 @@
 {
-  "note": "Every copy of shape/check.mjs a release of Atlas has shipped. The last row is the check this package ships. atlas status reads this list; git history is never read.",
+  "note": "Every copy of shape/check.mjs a release of Atlas has shipped. The last row is the check this package ships. workflow_sha256 is the fingerprint of the workflow that check writes (its WORKFLOW_TEMPLATE). atlas status reads this list; git history is never read.",
   "releases": [
     {
       "check_version": 1,
       "sha256": "3dfd659a7533c51dce11bd0e2d7a9312f041c5955d45ac3cc67d3e29d328b5d2",
-      "first_package": "0.1.1"
+      "first_package": "0.1.1",
+      "workflow_sha256": "a463b58c30d5d7b1de27b5c7c145dd86d6ea58356ab83d9e6ddc62705902299e"
     },
     {
       "check_version": 2,
       "sha256": "a4bc5ab8c75be8f216d460df9233670f5ba4ed9d853236f6b55a7f0d10dfe293",
-      "first_package": "0.2.0"
+      "first_package": "0.2.0",
+      "workflow_sha256": "b333b57c016791e2b77f983f6fe70c9aaf50f5f6fca28b7b9ca84c222dd7b7e1"
     },
     {
       "check_version": 3,
       "sha256": "0184db66fd5d5061c21ee7d2d88395b5bac64ab1308e02e06781e6015f3d7608",
-      "first_package": "0.3.0"
+      "first_package": "0.3.0",
+      "workflow_sha256": "b69efaac2a3e52368ae5e7d7a33e1c88c6c7a7efa6fc1846844f79f9432ecd7d"
     },
     {
       "check_version": 4,
       "sha256": "3357ea247694634c3535998368683eceffaf863221dee5fec9e43a03042afb95",
-      "first_package": "0.3.36"
+      "first_package": "0.3.36",
+      "workflow_sha256": "b69efaac2a3e52368ae5e7d7a33e1c88c6c7a7efa6fc1846844f79f9432ecd7d"
     },
     {
       "check_version": 5,
       "sha256": "8f36633fe693ebf7a7cc0f7237d49eb4720f67d371d4758d556bab51965ec334",
-      "first_package": "0.3.48"
+      "first_package": "0.3.48",
+      "workflow_sha256": "b69efaac2a3e52368ae5e7d7a33e1c88c6c7a7efa6fc1846844f79f9432ecd7d"
     }
   ]
 }

package/skills/lead/SKILL.md

@@ -96,7 +96,7 @@ set. A test keeps the two lists equal.
 | `atlas upgrade` | When the owner asks to upgrade Atlas. Call the `atlas_upgrade` tool instead: the Bash sandbox blocks this command. Run the command by hand only where that tool is missing. In a cloud session, call the tool with `check: true` at the first reply, as section 7 says |
 | `atlas doctor` | When Atlas seems missing or broken in a session |
 | `atlas check` | Before you ask for a merge in a repo that has the shape check |
-| `atlas status` | To learn whether a repo's check is current or behind |
+| `atlas status` | To learn whether a repo's check is current or behind. `atlas status --all --json <repo>` lists each Atlas copy in a repo, with have, want and state |
 | `atlas tooling` | When `atlas status` says behind; `pr` opens the pull request |
 | `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
 | `atlas code-read` | To resolve the citations of a code digest |
@@ -105,7 +105,7 @@ 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 upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
-| `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 |
+| `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. `audit` in the daily upkeep run |
 | `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/sdlc-task/SKILL.md

@@ -144,6 +144,15 @@ A lock is the owner's approval of a short design.
    posts its own proof comment. When it returns a comment file instead,
    post that file unchanged. Never edit that comment. Ask the owner for the
    merge only after the proof is there, and show the proof first.
+8. **Merge only on green.** On a plan with no rulesets, GitHub blocks
+   nothing, so this step is the gate (owner, 24 October 2026).
+   1. Right before the merge, run `atlas gate` with the verb `ready`,
+      `--repo` and `--pr`.
+   2. A pending check: wait for it. A red or missing check: fix it.
+   3. Merge only when it prints READY. Name the head SHA that it read in
+      the merge call, so a later push cannot slip in.
+   4. Where the verb `apply` set the rulesets, the branch rule holds the
+      merge. Turn on auto-merge there, and never press merge.
 
 ## pause
 

package/skills/upkeep/SKILL.md

@@ -65,6 +65,10 @@ Pass the product to every read. Show no other product.
 4. **Read only, report only.** Call `sweep_check` and `needs_me` for the
    product. Put any mismatch, and any question older than seven days, in the
    report. Do not act on them.
+5. **Red merges.** When `atlas.yaml` lists `required_checks`, run
+   `atlas gate` with the verb `audit`, `--repo` and `--since` set to
+   yesterday's date. Put each merge it names in the report, under "Left for
+   the owner", with its pull request. Do not revert it.
 
 If the tracker cannot be reached, skip this half and say so.
 
@@ -106,7 +110,7 @@ Upkeep <date> · Atlas <version>
 Marked: <n> (<item ids and pull requests>)
 Next steps fixed: <n> · Comments: <n> · Issues closed: <n>
 Docs: <n> fixes, <merged #n | open #n, why | none>
-Left for the owner: <sweep mismatch, old questions, unclear links, or none>
+Left for the owner: <red merges, sweep mismatch, old questions, unclear links, or none>
 ```
 
 ## Example