@arjunkhera/atlas 0.4.35 → 0.4.37

package/.claude-plugin/plugin.json

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

package/door/lib/gate.mjs

@@ -252,7 +252,7 @@ export const gateRunTitle = (pr, sha) => `gate #${pr} at ${sha}`;
 // The audit reads a merged pull request. GitHub then lists no pull request
 // on its runs, so with `audit` the two pull request pins are left out; the
 // file, the event, the head and the title still hold.
-export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [], audit = false }) {
+export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [], audit = false, baseChanged = () => '' }) {
   if (!run) return 'no workflow run';
   if (!homes.get(name)?.has(run.path)) return `from ${run.path ?? 'no file'}, not a base file that defines the check`;
   const event = name === GATE_CHECK ? 'pull_request_target' : 'pull_request';
@@ -272,6 +272,12 @@ export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [],
   const side = sides();
   if (side === null) return 'no head branch to check for side pull requests';
   if (side.length) return `the head branch also had #${side[0].number} into ${side[0].base?.ref ?? 'another branch'}`;
+  // A pull request can change its base. A run made while it pointed at a side
+  // branch used that branch's file, and the lists above no longer show it. So
+  // a run made before the last base change does not count (item 490bd791).
+  const changed = baseChanged();
+  if (changed === null) return `no events of #${pr} to check for a base change`;
+  if (changed && !(String(run.created_at ?? '') > changed)) return `made before the base of #${pr} last changed (${changed})`;
   return null;
 }
 
@@ -291,6 +297,77 @@ export function jobRefusal(job, check, run) {
   return null;
 }
 
+// Every event of one pull request, oldest first, or null when GitHub gives
+// none or more pages than `pages`. The newest event sits on the last page.
+function eventsOf(gh, repo, pr, pages = 10) {
+  const all = [];
+  for (let page = 1; page <= pages; page += 1) {
+    const got = gh('GET', `repos/${repo}/issues/${pr}/events?per_page=100&page=${page}`);
+    if (!Array.isArray(got)) return null;
+    all.push(...got);
+    if (got.length < 100) return all;
+  }
+  return null;
+}
+
+// The merge lock (item a638ce35). Two pull requests, each READY on the same
+// main tip, can merge seconds apart and turn the main branch red together
+// (atlas#214 and atlas#215). So a READY takes a lock: the label MERGE_LABEL
+// on its pull request. A lock lives LOCK_MS from its label event, a minute
+// longer than a READY file, or until its pull request closes. A label makes
+// no ref and starts no workflow. Times come from GitHub, not the local clock.
+export const MERGE_LABEL = 'atlas-merging';
+export const LOCK_MS = 11 * 60 * 1000;
+
+// The newest event that put the label on or took it off, or null. GitHub
+// lists the events oldest first.
+const labelEvents = (events) => events
+  .filter((each) => (each?.event === 'labeled' || each?.event === 'unlabeled') && each.label?.name === MERGE_LABEL);
+const lastLabelEvent = (events) => labelEvents(events).at(-1) ?? null;
+
+// `lock.on` says whether the pull request carries the label now.
+export function dropLock(gh, repo, pull, lock) {
+  if (!lock.on) return;
+  gh('DELETE', `repos/${repo}/issues/${pull.number}/labels/${MERGE_LABEL}`);
+  lock.on = false;
+}
+
+// Take the lock for `pull`. Returns null when it holds the lock, or why not;
+// the caller then takes the label off. Each caller puts its label on first,
+// then reads the others. Of two live labels, the older one wins, and the
+// lower number breaks a tie. So of two ready calls in the same seconds,
+// exactly one keeps its label.
+export function takeLock(gh, repo, pull, lock) {
+  // GitHub can show its events late, and an old label event would make this
+  // lock look older. Events only grow, so the label events are counted first:
+  // the read after must hold each new one, and the newest must put it on.
+  const before = eventsOf(gh, repo, pull.number);
+  if (!before) return { why: `GitHub gave no events of #${pull.number}` };
+  const made = lock.on ? 2 : 1;
+  // A new label event restarts the lock, so an old label comes off first.
+  dropLock(gh, repo, pull, lock);
+  gh('POST', `repos/${repo}/issues/${pull.number}/labels`, { labels: [MERGE_LABEL] });
+  lock.on = true;
+  const mine = eventsOf(gh, repo, pull.number);
+  const last = mine && lastLabelEvent(mine);
+  if (!mine || labelEvents(mine).length < labelEvents(before).length + made || last?.event !== 'labeled') return { why: `GitHub does not show the new label event on #${pull.number} yet` };
+  const at = String(last.created_at ?? '');
+  const held = gh('GET', `repos/${repo}/issues?labels=${MERGE_LABEL}&state=open&per_page=100`);
+  if (!Array.isArray(held)) return { why: 'GitHub gave no list of locked pull requests' };
+  for (const other of held) {
+    if (!other?.pull_request || Number(other.number) === Number(pull.number)) continue;
+    const events = eventsOf(gh, repo, other.number);
+    const theirs = events && lastLabelEvent(events);
+    if (!theirs) return { why: `GitHub shows no label event on #${other.number}`, pr: other.number };
+    // The list can be late too: a label already taken off holds no lock.
+    if (theirs.event !== 'labeled') continue;
+    const since = String(theirs.created_at ?? '');
+    if (Date.parse(at) - Date.parse(since) >= LOCK_MS) continue;
+    if (since < at || (since === at && Number(other.number) < Number(pull.number))) return { why: `#${other.number} holds the merge lock since ${since}`, pr: other.number };
+  }
+  return null;
+}
+
 // Every pull request, open or closed, from the head branch into another
 // branch. Read once, and only when a gate run needs it.
 function sidesOf(gh, repo, head, baseRef) {
@@ -304,6 +381,18 @@ function sidesOf(gh, repo, head, baseRef) {
   };
 }
 
+// The time of the last base change of one pull request, '' for none, or
+// null when GitHub gives no events. Read once, when the first run needs it.
+function baseChangedOf(gh, repo, pr) {
+  let changedAt;
+  return () => {
+    if (changedAt !== undefined) return changedAt;
+    const events = eventsOf(gh, repo, pr);
+    if (!events) return (changedAt = null);
+    return (changedAt = events.filter((each) => each?.event === 'base_ref_changed').map((each) => String(each.created_at ?? '')).sort().pop() ?? '');
+  };
+}
+
 // The workflow run of each check suite, read once.
 function suiteRuns(gh, repo) {
   const suites = new Map();
@@ -337,13 +426,14 @@ export function gateCopyRefusals(gh, repo, pull) {
 export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks, homesRef = baseRef, audit = false }) {
   const homes = homesAt(gh, repo, homesRef, checks);
   const sides = sidesOf(gh, repo, head, baseRef);
+  const baseChanged = audit ? () => '' : baseChangedOf(gh, repo, pr);
   const runOf = suiteRuns(gh, repo);
   const kept = [];
   const refused = [];
   for (const check of checkRuns(gh, repo, sha)) {
     if (!checks.includes(check.name) || check.app?.id !== ACTIONS_APP_ID) continue;
     const run = runOf(check.check_suite?.id);
-    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides, audit })
+    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides, audit, baseChanged })
       ?? jobRefusal(check.id === undefined ? null : gh('GET', `repos/${repo}/actions/jobs/${check.id}`), check, run);
     if (why) refused.push({ name: check.name, why }); else kept.push(check);
   }
@@ -374,6 +464,20 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   const pull = gh('GET', `repos/${repo}/pulls/${pr}`);
   if (answer && typeof pull?.head?.sha === 'string') answer.sha = pull.head.sha;
   if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
+  // Any answer but READY, an error too, takes the merge label off.
+  const lock = { on: (pull.labels ?? []).some((each) => each?.name === MERGE_LABEL) };
+  let code;
+  try {
+    code = readyOpen({ repo, pr, pull, lock }, line, gh);
+    return code;
+  } finally {
+    if (code !== 0) {
+      try { dropLock(gh, repo, pull, lock); } catch (error) { if (code !== undefined) throw error; }
+    }
+  }
+}
+
+function readyOpen({ repo, pr, pull, lock }, line, gh) {
   const sha = pull.head.sha;
   let checks;
   try { checks = checksAt(gh, repo, pull.base.ref); } catch (error) {
@@ -395,7 +499,19 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   if (!(behind >= 0)) throw new GateError(`GitHub gave no compare of ${pull.base.ref} and ${sha.slice(0, 7)}.`);
   line(`  ${behind === 0 ? '✓' : '✗'} ${(behind === 0 ? 'current' : 'behind').padEnd(8)} ${behind === 0 ? `the head holds every commit of ${pull.base.ref}` : `${pull.base.ref} has ${behind} commit(s) that the head does not hold`}`);
   const green = rows.every((row) => row.state === 'green');
-  if (green && behind === 0) { line('READY: every required check is green, on top of the current main branch. Merge with a merge commit, at this head.'); return 0; }
+  if (green && behind === 0) {
+    const held = takeLock(gh, repo, pull, lock);
+    if (held) {
+      line(`  ✗ locked   ${held.why}`);
+      line(held.pr
+        ? `NOT READY: do not merge. Wait for #${held.pr} to merge or for its lock to end (${LOCK_MS / 60000} min). Then merge ${pull.base.ref} in if it moved, and run ready again.`
+        : 'NOT READY: do not merge. The merge lock could not be read; run ready again.');
+      return 1;
+    }
+    line(`  ✓ lock     this pull request holds the merge lock (label ${MERGE_LABEL}) for ${LOCK_MS / 60000} min`);
+    line('READY: every required check is green, on top of the current main branch. Merge with a merge commit, at this head.');
+    return 0;
+  }
   line(behind > 0
     ? `NOT READY: do not merge. Merge ${pull.base.ref} in, wait for green, then run ready again.`
     : 'NOT READY: do not merge. Wait for a pending check; fix a red or missing one.');

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/workflows/atlas-upkeep.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/workflows/atlas-procedures.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

@@ -47,8 +47,14 @@ export const PACKAGE_JOBS_SOURCE = 'door/templates/atlas-jobs.yml';
 // 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 tagged procedure steps on each pull request that changes a skill
+// (roadmap R40). The same pin rule holds. The Atlas repo runs these steps in
+// its own package gates job, so the writer never writes this file there.
+export const PROCEDURES_PATH = '.github/workflows/atlas-procedures.yml';
+export const PACKAGE_PROCEDURES_SOURCE = 'door/templates/atlas-procedures.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 PINNED = Object.freeze([[JOBS_PATH, PACKAGE_JOBS_SOURCE], [UPKEEP_PATH, PACKAGE_UPKEEP_SOURCE], [PROCEDURES_PATH, PACKAGE_PROCEDURES_SOURCE]]);
+const pinnedFor = (root, packageRoot) => (isPackageRepo(root, packageRoot) ? PINNED.filter(([path]) => path !== PROCEDURES_PATH) : PINNED);
 const VERSION_SLOT = '__ATLAS_VERSION__';
 function packagedPinned(packageRoot, source) {
   const full = join(packageRoot, source);
@@ -56,6 +62,7 @@ function packagedPinned(packageRoot, source) {
 }
 export const packagedJobsWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_JOBS_SOURCE);
 export const packagedUpkeepWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_UPKEEP_SOURCE);
+export const packagedProceduresWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_PROCEDURES_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 one pinned workflow.
@@ -69,7 +76,7 @@ function pinnedState(root, packageRoot, path, source) {
   const have = pinOf(was);
   return have && older(have, pinOf(wanted)) ? 'refreshed' : 'kept';
 }
-const pinnedNeedWrite = (root, packageRoot) => PINNED.some(([path, source]) => ['written', 'refreshed'].includes(pinnedState(root, packageRoot, path, source)));
+const pinnedNeedWrite = (root, packageRoot) => pinnedFor(root, packageRoot).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.
@@ -154,7 +161,7 @@ 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) });
   }
-  for (const [path, source] of workflowOnly ? [] : PINNED) {
+  for (const [path, source] of workflowOnly ? [] : pinnedFor(root, packageRoot)) {
     const state = pinnedState(root, packageRoot, path, source);
     if (state === null) continue;
     const contents = packagedPinned(packageRoot, source);
@@ -190,7 +197,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), [UPKEEP_PATH]: packagedUpkeepWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
+  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [UPKEEP_PATH]: packagedUpkeepWorkflow(packageRoot), [PROCEDURES_PATH]: packagedProceduresWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => (row.state === 'removed' ? {
@@ -206,8 +213,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 || row.path === UPKEEP_PATH
-              ? `written from ${row.path === JOBS_PATH ? PACKAGE_JOBS_SOURCE : PACKAGE_UPKEEP_SOURCE}, with its pin set to Atlas ${version}`
+            : PINNED.some(([path]) => path === row.path)
+              ? `written from ${PINNED.find(([path]) => path === row.path)[1]}, with its pin set to Atlas ${version}`
               : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));

package/door/templates/atlas-procedures.yml

@@ -0,0 +1,53 @@
+name: atlas-procedures
+# The Atlas procedure steps (roadmap R40). `atlas tooling` wrote this file from
+# the Atlas package; do not edit it by hand.
+#
+# A procedure is a skill that atlas.yaml names under `procedures:`. A step a
+# clean machine can run sits in a fenced block tagged `atlas-run`. This job
+# runs those blocks for each procedure that a pull request changes: the
+# procedure folder, or a path its `sources:` names. A block tagged
+# `needs=secret/<name>`, `needs=device/<name>` or `needs=network/<name>` is
+# listed "not run here".
+#
+# The path filter starts the job only when a skill or atlas.yaml changes, so
+# most pull requests start nothing. A change to a path that a procedure names
+# in `sources:` alone does not start it; the upkeep check lists that procedure
+# instead. The steps run the code of the pull request, so the job holds a
+# token that can only read and no repo 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 of Atlas itself.
+on:
+  pull_request:
+    paths:
+      - ".claude/skills/**"
+      - "atlas.yaml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: atlas-procedures-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  procedures:
+    name: procedures · tagged steps
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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: Run the tagged steps of each procedure this pull request changes
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          cd "$RUNNER_TEMP"
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ upkeep procedures --root "$GITHUB_WORKSPACE" --base "origin/$BASE_REF" | tee -a "$GITHUB_STEP_SUMMARY"

package/package.json

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