@arjunkhera/atlas 0.4.26 → 0.4.28

package/.claude-plugin/plugin.json

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

package/door/lib/gate-check.mjs

@@ -22,12 +22,14 @@
 // An owner result turns into success when a comment of the pull request holds
 // the owner's signed act for this repo, this pull request and this head
 // (roadmap R72, signed-act.mjs). The key comes from atlas/owner-signers on the
-// base, never from the head.
+// base, never from the head. An act for an older head carries to this head
+// when the new commits only merge the base in with no conflict (item 34b554e7).
 //
 // Red wins over owner: the pull request must be fixed before the owner signs.
 // Rules that hold everywhere here:
-// 1. The owner-only list and atlas.yaml come from the merge base, never from
-//    the head (owner-only.mjs reads them there).
+// 1. The owner-only list, atlas.yaml and the guarded workflows come from the
+//    base commit, never from the head and never from the merge base, which
+//    an agent can pick (item d56a9c03).
 // 2. Nothing of the head runs. Every read is a git object.
 // 3. It fails closed: a head or a merge base that git cannot read is red.
 import { spawnSync } from 'node:child_process';
@@ -205,7 +207,7 @@ export function saysNoBehaviourChange(body) {
   return !/^#/.test(first) && /^no\b/i.test(first);
 }
 
-// Product code sits under the `product_paths:` of atlas.yaml at the merge base
+// Product code sits under the `product_paths:` of atlas.yaml at the base
 // (roadmap R4 line 5). It is not a doc by the rule of fails-before, and not a
 // markdown file: a unit test cannot test skill text yet (roadmap R2 line 4).
 // A repo with no such key keeps the other two rules alone.
@@ -230,7 +232,7 @@ export function coveredFiles(root, green, mergeBase) {
 // for the files that main changed since that check was last green.
 function testRows({ root, mergeBase, head, body, redMain, rules, undo = null }) {
   const list = listChanged({ root, base: mergeBase, head });
-  const product = list.other_paths.filter(productTest(root, rules ?? mergeBase));
+  const product = list.other_paths.filter(productTest(root, rules));
   if (!product.length) return [];
   // The exact undo of a change that tripped the brake puts main back as it
   // was before that change, so it needs no new test (roadmap R13 line 4).
@@ -292,11 +294,16 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
     answer.brake = { on: state.on, until: state.until, days: state.days, trips: state.trips, undo: undo?.culprit ?? null };
     answer.rows.push(...brakeRows(state, undo));
   }
-  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));
+  // The rules come from the base commit, never from the merge base. An agent
+  // picks the merge base when it picks where its branch starts, also a middle
+  // commit of a merged pull request that weakened the list and then took the
+  // change back (item d56a9c03). The diff stays merge base to head.
+  const ruleRef = rules ?? baseSha;
+  for (const row of classify({ root: top, base: mergeBase, head: headSha, rules: ruleRef }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
+  answer.rows.push(...jobRows(top, ruleRef, 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 }));
+  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules: ruleRef, undo }));
   if (signed) signedRows(top, baseSha, headSha, signed, answer);
   return finish(answer);
 }
@@ -318,17 +325,106 @@ function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer
   if (!keys.length) { note(`no owner key in ${SIGNERS_FILE} on the base, so no signed act counts`); return; }
   note(`${keys.length} owner key(s) in ${SIGNERS_FILE} on the base: ${keys.map((key) => key.fingerprint).join(', ')}`);
   const verified = verifyTexts(texts, keys);
-  const found = findAct(verified, { kind: 'merge', repo, pr: Number(pr), base: baseRef, merge_base: answer.merge_base, head: headSha });
+  let found = findAct(verified, { kind: 'merge', repo, pr: Number(pr), base: baseRef, merge_base: answer.merge_base, head: headSha });
+  let carried = null;
+  if (!found) {
+    carried = carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answer);
+    if (carried?.found) found = carried.found;
+  }
   if (!found) {
     for (const row of verified.filter((each) => each.error).slice(0, 3)) note(`a signed act that does not count: ${row.error}`);
+    if (carried?.why) note(`a signed act for an older head does not carry: ${carried.why}`);
     if (verified.some((each) => !each.error)) note('a valid signed act names another pull request, base, merge base or head; sign this head');
     return;
   }
   const locked = answer.rows.filter((row) => row.kind === 'owner' && row.class === 'gate-checks');
   if (locked.length) { note('a signed act never clears a head job named like a check: remove that job'); return; }
   for (const row of answer.rows) if (row.kind === 'owner') row.kind = 'signed';
-  answer.signed = { key: found.key, signed_at: found.signed_at, verified: found.verified };
-  note(`the owner signed this head with key ${found.key} at ${found.signed_at}`);
+  answer.signed = { key: found.key, signed_at: found.signed_at, verified: found.verified, ...(carried?.found ? { carried_from: found.act.head } : {}) };
+  if (carried?.found) note(`the owner signed head ${found.act.head.slice(0, 7)} with key ${found.key} at ${found.signed_at}; this head only adds ${carried.merges} clean merge(s) of the base`);
+  else note(`the owner signed this head with key ${found.key} at ${found.signed_at}`);
+}
+
+// At most this many new commits between a signed head and this head.
+export const CARRY_LIMIT = 20;
+// At most this many signed heads are tried, so copies of one block cost little.
+export const CARRY_TRIES = 3;
+const contains = (root, older, newer) => spawnSync('git', [MERGE_BASE, '--is-ancestor', '--end-of-options', older, newer], { cwd: root }).status === 0;
+
+// Tracker item 34b554e7: a signed act survives a clean merge of the base. A
+// batch of signed pull requests merges one at a time, so each next one is
+// behind and must merge the base in, which makes a new head. The act for the
+// old head H0 carries to this head H only when all of these hold:
+// 1. The act names this repo, this pull request and this base branch.
+// 2. H0 is in the history of H, and the merge base of the act is in the
+//    history of the merge base now: the base only moved forward.
+// 3. Each commit in H that is not in H0 and not in the base is a merge with
+//    two parents. Its second parent was a tip of the base branch after the
+//    touch: a first-parent commit of the base after the signed merge base. Its tree is the tree that
+//    git makes for a merge of its two parents with no conflict. So no commit
+//    adds a line that the owner did not see, and a conflict fix needs a new touch.
+//    A clean merge brings in only what the base already holds, so the pull
+//    request changes no path now that it did not change at H0.
+// 4. The brake is not on: an act signed before a brake never clears it.
+// 5. Only the newest touch on this pull request carries, so a rollback to a
+//    head that the owner moved past does not clear.
+// It fails closed: a commit or a merge that git cannot read stops the carry.
+function carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answer) {
+  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+  // Every valid merge act of this pull request, on any base branch and head.
+  const mine = [];
+  for (const row of verified) {
+    if (row.error) continue;
+    for (const act of row.acts) if (act.kind === 'merge' && same(act.repo, repo) && Number(act.pr) === Number(pr)) mine.push({ act, signed_at: row.signed_at, key: row.key, verified: row.verified });
+  }
+  if (!mine.length) return null;
+  // Only the newest touch carries. An older act names a head that the owner
+  // moved past, so a rollback to it must not clear (security review finding 2).
+  const newest = mine.reduce((top, one) => (one.signed_at > top ? one.signed_at : top), '');
+  const seen = new Set();
+  const candidates = mine.filter((one) => {
+    const id = `${one.act.base} ${one.act.merge_base} ${one.act.head}`;
+    if (one.signed_at !== newest || one.act.base !== baseRef || one.act.head === headSha || seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  }).slice(0, CARRY_TRIES);
+  if (!candidates.length) return { why: 'the newest signed act of this pull request names another base branch or head' };
+  if (answer.rows.some((row) => row.kind === 'owner' && row.class === 'brake')) return { why: 'the brake is on, so the owner signs this head' };
+  let why = null;
+  for (const one of candidates) {
+    const result = carryOne(root, baseSha, headSha, answer.merge_base, one.act);
+    if (result.merges) return { found: one, merges: result.merges };
+    why ??= result.why;
+  }
+  return { why: `${why} (${candidates.length} signed head(s) tried)` };
+}
+
+// git with no replace objects and no system config, so the merge that the
+// gate makes depends on the commits alone.
+const PINNED = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' };
+
+function carryOne(root, baseSha, headSha, mergeBase, act) {
+  const old = commitOf(root, act.head);
+  if (old !== act.head) return { why: `the signed head ${act.head.slice(0, 7)} is not a commit in this clone` };
+  if (commitOf(root, act.merge_base) !== act.merge_base) return { why: `the signed merge base ${act.merge_base.slice(0, 7)} is not a commit in this clone` };
+  if (!contains(root, old, headSha)) return { why: `the signed head ${old.slice(0, 7)} is not in the history of this head` };
+  if (!contains(root, act.merge_base, mergeBase)) return { why: 'the base did not only move forward since the touch' };
+  const shas = (git(root, ['rev-list', `--max-count=${CARRY_LIMIT + 1}`, headSha, `^${old}`, `^${baseSha}`], { allowFail: true }) ?? '').split('\n').filter(Boolean);
+  if (!shas.length) return { why: 'this head adds no merge of the base' };
+  if (shas.length > CARRY_LIMIT) return { why: `this head adds more than ${CARRY_LIMIT} commits` };
+  // The tips that the base branch held since the touch: its first-parent
+  // commits after the signed merge base. A merge may bring in only one of
+  // them, never a middle commit of a merged pull request (finding 3).
+  const tips = new Set((git(root, ['rev-list', '--first-parent', baseSha, `^${act.merge_base}`], { allowFail: true }) ?? '').split('\n').filter(Boolean));
+  for (const sha of shas) {
+    const [tree, ...parents] = (git(root, ['show', '-s', '--format=%T %P', sha], { allowFail: true }) ?? '').trim().split(' ');
+    if (parents.length !== 2) return { why: `commit ${sha.slice(0, 7)} is not a merge of two parents` };
+    if (!tips.has(parents[1])) return { why: `merge ${sha.slice(0, 7)} brings in ${parents[1].slice(0, 7)}, which was never a tip of the base after the touch` };
+    const made = spawnSync('git', ['-c', 'merge.renames=true', '-c', 'merge.conflictStyle=merge', 'merge-tree', '--write-tree', '--no-messages', '--end-of-options', parents[0], parents[1]], { cwd: root, encoding: 'utf8', env: PINNED, timeout: 30_000 });
+    if (made.status !== 0) return { why: `merge ${sha.slice(0, 7)} has a conflict, so its fix needs a new touch` };
+    if (made.stdout.split('\n')[0].trim() !== tree) return { why: `merge ${sha.slice(0, 7)} changes more than a clean merge of its parents` };
+  }
+  return { merges: shas.length };
 }
 
 // Line 1: while the brake is on, every pull request of the repo comes to the
@@ -366,6 +462,7 @@ export function renderText(answer) {
   }
   if (answer.result === 'red') out.push(`RED: ${oneLine(answer.rows.find((row) => row.kind === 'red').cause)}. Fix it; red wins over owner.`);
   else if (answer.result === 'owner') out.push(`OWNER: ${oneLine(answer.class)}. ${answer.signed_act}`);
+  else if (answer.signed?.carried_from) out.push(`SUCCESS: the owner signed head ${oneLine(answer.signed.carried_from).slice(0, 7)}, and this head only merges in the base.`);
   else if (answer.signed) out.push('SUCCESS: the owner signed this head.');
   else out.push('SUCCESS: no rule holds this pull request.');
   return out;

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/package.json

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