@arjunkhera/atlas 0.3.52 → 0.4.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -4,7 +4,7 @@ Atlas sets how a repository is worked on. It is one Claude Code plugin with:
 
 1. **The lead**, `atlas:lead`: the talk rules, the routing and the command
    list. It loads on its own in each session of a repo with `atlas.yaml`.
-   Nobody has to call it.
+   No one has to call it.
 2. **The rulebook**, `atlas:sdlc-task`: start, pause, resume, lock and finish
    one piece of work. Three more skills: `repo-skills` adds a procedure the
    right way, `learnings` turns a miss into one fix, and `feedback` files an

package/door/kit-releases.json

@@ -1,5 +1,5 @@
 {
-  "note": "Every kit of the folder tests/ that a release of Atlas shipped, as the kit hash of its manifest (the sha256 of the sorted lines of path and file hash). The kit of this package is always accepted and need not be listed. When a release changes anything in tests/, add the kit hash of the release before it here. atlas tests check reads this list; git history is never read.",
+  "note": "Every kit of the folder tests/ that a release of Atlas shipped, as the kit hash of its manifest (the sha256 of the sorted lines of path and file hash). The kit of this package is always accepted and need not be listed. When a release changes anything in tests/, add the kit hash of the release before it here. atlas tests check reads this list; git history is never read. Since 24 October 2026 the release picks the version after the merge, so a new row names no first_package. The row of kit 1e62be9a names none either: it was built as 0.3.28, and npm never held 0.3.28.",
   "releases": [
     {
       "kit_sha256": "ae0f32b8c6694fbffb8bdacd8bd919d27c1c1da6281a46779e521dfea2341565",
@@ -22,8 +22,7 @@
       "first_package": "0.3.26"
     },
     {
-      "kit_sha256": "1e62be9a3fb632161c593d44ac7ad404ef04186fe2fbcd108645fbe1559bf860",
-      "first_package": "0.3.28"
+      "kit_sha256": "1e62be9a3fb632161c593d44ac7ad404ef04186fe2fbcd108645fbe1559bf860"
     },
     {
       "kit_sha256": "08c868aa39e6c9f471da2571e9a1d5939932a59856cea9c4176e3173f93454db",

package/door/lib/install.mjs

@@ -14,6 +14,7 @@ import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { readConnection } from '../../work/mcp.mjs';
+import { VERSION_FILES, stampVersion } from './releases.mjs';
 
 export const CATALOG_NAME = 'atlas';
 export const PLUGIN_ID = 'atlas@atlas';
@@ -169,38 +170,95 @@ function filesUnder(root, skip = () => false) {
   return out;
 }
 
-// Is `sha` a commit of the master branch itself? A run's branch name is not
-// enough: a tag named "master" gives a run the same name.
+// Is `sha` in master's history now? A tag named "master" gives a run the
+// branch name too, so the run's branch name is not enough.
 export function onMaster(gh, repo, sha) {
   const compare = gh(['api', '--method', 'GET', `repos/${repo}/compare/${sha}...refs/heads/master`]);
   return ['ahead', 'identical'].includes(compare.status);
 }
 
-// The master run of release.yml that built this version, or null.
-export function findReleaseRun({ gh, repo, version }) {
-  const runs = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/release.yml/runs?event=push&status=success&per_page=100`]).workflow_runs ?? [];
-  for (const run of runs) {
-    if (!/^[0-9a-f]{40}$/.test(run.head_sha ?? '')) continue;
-    let named;
-    try {
-      const file = gh(['api', '--method', 'GET', `repos/${repo}/contents/packages/atlas/package.json?ref=${run.head_sha}`]);
-      named = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8')).version;
-    } catch { continue; }
-    if (named !== version) continue;
-    if (!onMaster(gh, repo, run.head_sha)) continue;
-    return run;
+// Was `sha` once the tip of master, through a merge or a normal push? A commit
+// that reached master only as the second parent of a merge was never the tip,
+// so the run that built it ran on another branch. A force push does not count:
+// with onMaster it would let in code that left master's history. It reads the
+// newest 100 changes of master, the one page this proxy lets through (its
+// next-page links use a path it refuses); an older release is refused.
+const TIP_KINDS = new Set(['pr_merge', 'push', 'merge_queue_merge']);
+export function wasTip(gh, repo, sha) {
+  const rows = gh(['api', '--method', 'GET', `repos/${repo}/activity?ref=refs/heads/master&direction=desc&per_page=100`]);
+  return Array.isArray(rows) && rows.some((row) => row.after === sha && TIP_KINDS.has(row.activity_type));
+}
+
+// The commit that the tag v<version> names, or null. The release job tags the
+// master commit it built (tracker item 339538d3): the commit no longer names
+// the version, because the release picks it after the merge.
+export function tagCommit(gh, repo, version) {
+  // Only "not found" means no tag. Any other failure is GitHub not
+  // answering, and the caller must say so, not refuse on a guess.
+  const read = (path) => {
+    try { return gh(['api', '--method', 'GET', path]).object; } catch (error) {
+      if (/HTTP 404|Not Found/i.test(`${error.stderr ?? ''}${error.message ?? ''}`)) return null;
+      throw error;
+    }
+  };
+  let object = read(`repos/${repo}/git/ref/tags/v${version}`);
+  if (object?.type === 'tag') object = read(`repos/${repo}/git/tags/${object.sha}`);
+  return object?.type === 'commit' && /^[0-9a-f]{40}$/.test(object.sha ?? '') ? object.sha : null;
+}
+
+// The name of the record that a master release run keeps for each version
+// it publishes. Only a run of the tip of master makes one (release.yml). If
+// GitHub stops listing a name once its file expires (90 days), an upgrade to
+// that release is refused, never let through.
+export const recordName = (version, sha256) => `atlas-release-${version}-${sha256}`;
+
+// The release of this version. The tag is only a hint to find the commit: the
+// proof is the record of a successful push run of release.yml on that master
+// commit, which names this version and the sha256 of this exact tarball. The
+// commit must once have been the tip of master. A tag that a person made or
+// moved finds no record, so the upgrade refuses. With no sha256 (a loaded
+// copy has no tarball), any record of this version counts, and the byte
+// compare of every file does the rest.
+export function findRelease({ gh, repo, version, sha256 }) {
+  const commit = tagCommit(gh, repo, version);
+  if (!commit) return { problem: `no tag v${version} names a commit` };
+  if (!onMaster(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which is not on master` };
+  if (!wasTip(gh, repo, commit)) return { problem: `the tag v${version} names commit ${commit.slice(0, 12)}, which was never the tip of master through a merge or a push` };
+  const runs = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/release.yml/runs?event=push&status=success&head_sha=${commit}&per_page=100`]).workflow_runs ?? [];
+  const prefix = recordName(version, '');
+  const named = (name) => (sha256 ? name === recordName(version, sha256) : name.startsWith(prefix) && /^[0-9a-f]{64}$/.test(name.slice(prefix.length)));
+  // A tag named "master" gives a run on another commit the branch name too;
+  // the tip check above rules that out, and these fields rule out the rest.
+  const ours = (row) => row.head_sha === commit && row.event === 'push' && row.head_branch === 'master' && row.path === '.github/workflows/release.yml';
+  for (const run of runs.filter(ours)) {
+    const artifacts = gh(['api', '--method', 'GET', `repos/${repo}/actions/runs/${run.id}/artifacts?per_page=100`]).artifacts ?? [];
+    if (artifacts.some((artifact) => named(artifact.name ?? ''))) return { run, commit };
   }
-  return null;
+  return { problem: `no successful release run on master commit ${commit.slice(0, 12)} recorded ${version}${sha256 ? ' with this tarball' : ''}` };
+}
+
+// The blob ids that the version files of the tarball must have: the files of
+// the commit with the stamp of the target version. So the stamp may change the
+// version line and nothing else.
+export function stampedBlobs({ gh, repo, commit, version }) {
+  const out = new Map();
+  for (const path of VERSION_FILES) {
+    const file = gh(['api', '--method', 'GET', `repos/${repo}/contents/packages/atlas/${path}?ref=${commit}`]);
+    out.set(path, blobSha(Buffer.from(stampVersion(Buffer.from(file.content, 'base64').toString('utf8'), version))));
+  }
+  return out;
 }
 
 // Every file of the tarball must be the file at that commit, and every file of
-// packages/atlas at that commit must be in the tarball.
-export function matchTree({ tree, files }) {
+// packages/atlas at that commit must be in the tarball. `stamped` holds the
+// blob ids that replace the commit's own for the version files.
+export function matchTree({ tree, files, stamped = new Map() }) {
   const wanted = new Map((tree ?? []).filter((row) => row.type === 'blob' && row.path.startsWith('packages/atlas/')).map((row) => [row.path.slice('packages/atlas/'.length), row.sha]));
+  for (const [path, sha] of stamped) if (wanted.has(path)) wanted.set(path, sha);
   const problems = [];
   for (const [path, bytes] of files) {
     if (!wanted.has(path)) problems.push(`${path} is in the tarball and not in the commit`);
-    else if (wanted.get(path) !== blobSha(bytes)) problems.push(`${path} differs from the commit`);
+    else if (wanted.get(path) !== blobSha(bytes)) problems.push(`${path} differs from the commit${stamped.has(path) ? ' with the version stamped' : ''}`);
   }
   for (const path of wanted.keys()) if (!files.has(path)) problems.push(`${path} is in the commit and not in the tarball`);
   return problems;
@@ -222,14 +280,19 @@ export function proveCopy({ packageRoot, exec = defaultExec }) {
     const { version } = packageJson(packageRoot);
     const repo = repoOf(packageRoot);
     const gh = (args) => JSON.parse(exec('gh', args));
-    let run;
-    try { run = findReleaseRun({ gh, repo, version }); } catch (error) { return { state: 'not checked', reason: `GitHub did not answer: ${firstLines(error)}` }; }
-    if (!run) return { state: 'unproven', reason: `no successful release run on a commit of master built ${version}. It may have been published from a branch.` };
+    let release;
+    try { release = findRelease({ gh, repo, version }); } catch (error) { return { state: 'not checked', reason: `GitHub did not answer: ${firstLines(error)}` }; }
+    if (release.problem) return { state: 'unproven', reason: `${release.problem}. It may have been published from a branch.` };
+    const { run, commit } = release;
     let tree;
-    try { tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${run.head_sha}?recursive=1`]).tree; } catch (error) { return { state: 'not checked', reason: `GitHub did not give the file tree: ${firstLines(error)}` }; }
+    let stamped;
+    try {
+      tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${commit}?recursive=1`]).tree;
+      stamped = stampedBlobs({ gh, repo, commit, version });
+    } catch (error) { return { state: 'not checked', reason: `GitHub did not give the files of the commit: ${firstLines(error)}` }; }
     const files = filesUnder(packageRoot, (path) => COPY_MARKER.test(path));
-    const problems = matchTree({ tree, files });
-    const found = { run: run.id, commit: run.head_sha };
+    const problems = matchTree({ tree, files, stamped });
+    const found = { run: run.id, commit };
     return problems.length ? { state: 'differs', ...found, problems: problems.slice(0, 20) } : { state: 'match', ...found, files: files.size };
   } catch (error) {
     return { state: 'not checked', reason: `the proof stopped: ${firstLines(error)}` };
@@ -246,9 +309,6 @@ export async function upgrade({ packageRoot, options = {}, line = console.log, e
   const integrity = exec('npm', ['view', `${name}@${target}`, 'dist.integrity']).trim();
 
   line(`Atlas ${installed} → ${target}`);
-  const run = findReleaseRun({ gh, repo, version: target });
-  if (!run) { line(`Refused: no successful release run on a commit of master built ${target}. It may have been published from a branch.`); return 1; }
-  line(`  built by release run ${run.id}, on master commit ${run.head_sha.slice(0, 12)}`);
 
   const work = mkdtempSync(join(tmpdir(), 'atlas-upgrade-'));
   try {
@@ -257,12 +317,17 @@ export async function upgrade({ packageRoot, options = {}, line = console.log, e
     if (!tarball) throw new Error('npm pack wrote no tarball');
     const bytes = readFileSync(join(work, tarball));
     if (sha512Integrity(bytes) !== integrity) { line('Refused: the tarball does not match the integrity npm records.'); return 1; }
+    const { run, commit, problem } = findRelease({ gh, repo, version: target, sha256: createHash('sha256').update(bytes).digest('hex') });
+    if (problem) { line(`Refused: ${problem}. It may have been published from a branch.`); return 1; }
+    line(`  tag v${target}, recorded by release run ${run.id}, on master commit ${commit.slice(0, 12)}`);
     const unpacked = join(work, 'unpacked');
     mkdirSync(unpacked);
     exec('tar', ['-xzf', join(work, tarball), '-C', unpacked]);
     const files = filesUnder(join(unpacked, 'package'));
-    const tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${run.head_sha}?recursive=1`]).tree;
-    const problems = matchTree({ tree, files });
+    const tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${commit}?recursive=1`]).tree;
+    let stamped;
+    try { stamped = stampedBlobs({ gh, repo, commit, version: target }); } catch (error) { line(`Refused: the version files of that commit cannot take the stamp: ${error.message}`); return 1; }
+    const problems = matchTree({ tree, files, stamped });
     if (problems.length) {
       line('Refused: the tarball is not the commit that run built.');
       for (const problem of problems.slice(0, 20)) line(`  ${problem}`);

package/door/lib/releases.mjs

@@ -15,7 +15,9 @@ export function readReleases(packageRoot) {
   const list = JSON.parse(readFileSync(join(packageRoot, RELEASES_PATH), 'utf8'));
   if (!Array.isArray(list.releases) || !list.releases.length) throw new Error(`${RELEASES_PATH} lists no release`);
   for (const row of list.releases) {
-    if (!Number.isInteger(row.check_version) || !/^[0-9a-f]{64}$/.test(row.sha256 ?? '') || typeof row.first_package !== 'string') {
+    // A row from before 24 October 2026 names its first package. A newer row
+    // names none, because the release picks the version after the merge.
+    if (!Number.isInteger(row.check_version) || !/^[0-9a-f]{64}$/.test(row.sha256 ?? '') || !['string', 'undefined'].includes(typeof row.first_package)) {
       throw new Error(`${RELEASES_PATH} holds a malformed row: ${JSON.stringify(row)}`);
     }
   }
@@ -40,3 +42,18 @@ export function packagedCheck(packageRoot) {
   const fingerprint = sha256(text);
   return { text, sha256: fingerprint, releases, ...placeOf(releases, fingerprint) };
 }
+
+// The release picks the version (tracker item 339538d3). The release job
+// writes the number into these two files of its own checkout, and into nothing
+// else, and never commits it. `atlas upgrade` makes the same stamp on the
+// files of the tagged commit, so the stamp can change the version and nothing
+// more.
+export const VERSION_FILES = Object.freeze(['package.json', '.claude-plugin/plugin.json']);
+const VERSION_LINE = /^ {2}"version": "[^"\n]*"(,?)$/gm;
+
+export function stampVersion(text, version) {
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`"${version}" is not an exact version`);
+  const found = [...text.matchAll(VERSION_LINE)].length;
+  if (found !== 1) throw new Error(`a version file must hold exactly one top-level "version" line, and this one holds ${found}`);
+  return text.replace(VERSION_LINE, (_, comma) => `  "version": "${version}"${comma}`);
+}

package/door/lib/status.mjs

@@ -22,6 +22,10 @@ import { kitHashOf } from '../../tests/link-check.mjs';
 
 export const STATES = Object.freeze(['current', 'behind', 'unknown', 'missing']);
 
+// A row after 24 October 2026 names no package, because the release picks
+// the version after the merge.
+const from = (row) => (row.first_package ? `, first in Atlas ${row.first_package}` : '');
+
 export function status({ root, packageRoot }) {
   const pkg = packagedCheck(packageRoot);
   const latest = pkg.releases[pkg.releases.length - 1];
@@ -35,10 +39,10 @@ export function status({ root, packageRoot }) {
   const { row, latest: isLatest } = placeOf(pkg.releases, fingerprint);
   const copy = { sha256: fingerprint, check_version: row?.check_version ?? checkStamps(text).check_version, first_package: row?.first_package ?? null };
   if (row && isLatest) {
-    return { root, path: CHECK_PATH, state: 'current', packaged, copy, why: `the copy is check version ${row.check_version}, the newest one Atlas has released (first in Atlas ${row.first_package}).` };
+    return { root, path: CHECK_PATH, state: 'current', packaged, copy, why: `the copy is check version ${row.check_version}, the newest one Atlas has released${from(row)}.` };
   }
   if (row) {
-    return { root, path: CHECK_PATH, state: 'behind', packaged, copy, why: `the copy is check version ${row.check_version}, first released in Atlas ${row.first_package}. The newest is check version ${latest.check_version}, from Atlas ${latest.first_package}. "atlas tooling pr" refreshes it.` };
+    return { root, path: CHECK_PATH, state: 'behind', packaged, copy, why: `the copy is check version ${row.check_version}${from(row)}. The newest is check version ${latest.check_version}${from(latest)}. "atlas tooling pr" refreshes it.` };
   }
   return { root, path: CHECK_PATH, state: 'unknown', packaged, copy, why: `the copy's fingerprint, sha256 ${fingerprint.slice(0, 12)}…, is in no release of the check. Someone edited it, or it came from an unreleased package. "atlas tooling pr --replace-unknown" shows the difference and replaces it.` };
 }

package/package.json

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