@arjunkhera/atlas 0.4.15 → 0.4.17

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -267,7 +267,8 @@ function toolingCommand(chosen) {
     if (what !== 'write') throw new Error(`there is no tooling verb "${what}". Use write or pr.`);
     const result = writeTooling(root, PACKAGE_ROOT, { dryRun: Boolean(chosen['dry-run']), replaceUnknown, workflowOnly });
     line(`Atlas ${result.version}, check version ${result.check_version}${result.status ? `; the copy was ${result.status}` : ''}`);
-    for (const row of result.rows) line(`  ${row.state.padEnd(10)} ${row.path}  sha256 ${row.sha256.slice(0, 12)}…`);
+    // A removed file has no bytes, so its row has no sha256 (roadmap R7).
+    for (const row of result.rows) line(`  ${row.state.padEnd(10)} ${row.path}${row.sha256 ? `  sha256 ${row.sha256.slice(0, 12)}…` : ''}`);
     line('');
     line(result.changed
       ? 'The files come from the package. No hand step, and no edit by hand afterwards.'

package/door/lib/doc-sources.mjs

@@ -96,7 +96,6 @@ export function docUnits(root) {
   const units = [];
   const folders = new Set();
   for (const file of markdownFiles(root, 'docs')) {
-    if (file.startsWith('docs/site/')) continue;
     const folder = designFolderOf(root, file);
     if (folder) {
       if (folders.has(folder)) continue;

package/door/lib/kind-drift.mjs

@@ -3,7 +3,7 @@
 // Milestone M2, slice L2 stage one: "The facts helper compares the `kind` in
 // `atlas.yaml` with the `kind` on the repo record and reports drift."
 //
-// The kind decides which of the seven files a repository needs, so the two
+// The kind decides which of the six files a repository needs, so the two
 // copies disagreeing is not a detail. A repo record that says `service` while
 // atlas.yaml says `library` means four required parts read "not applicable" in
 // CI and "required" everywhere else.

package/door/lib/pull-request.mjs

@@ -11,9 +11,9 @@
 // git and GitHub calls sit below it, in one place.
 import { execFileSync } from 'node:child_process';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH } from '../../shape/check.mjs';
 
 // Every change names where it came from, and the set is closed.
 export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'task input']);
@@ -24,6 +24,9 @@ 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']);
+// 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]);
 
 export class ChangeError extends Error {}
 
@@ -38,8 +41,12 @@ export function checkChanges(changes) {
   for (const change of changes) {
     const path = posix.normalize(String(change?.path ?? '')).replace(/^\.\//, '');
     if (!path || path === '.') throw new ChangeError('a change has no path');
-    if (!TOOLING_PATHS.includes(path)) throw new ChangeError(`the tooling writer writes only ${TOOLING_PATHS.join(' and ')}; it refuses "${path}"`);
-    if (typeof change.contents !== 'string') throw new ChangeError(`the change to "${path}" carries no contents`);
+    if (change.remove === true) {
+      if (!TOOLING_REMOVALS.includes(path)) throw new ChangeError(`the tooling writer removes only ${TOOLING_REMOVALS.join(' and ')}; it refuses to remove "${path}"`);
+    } else {
+      if (!TOOLING_PATHS.includes(path)) throw new ChangeError(`the tooling writer writes only ${TOOLING_PATHS.join(' and ')}; it refuses "${path}"`);
+      if (typeof change.contents !== 'string') throw new ChangeError(`the change to "${path}" carries no contents`);
+    }
     const source = change?.provenance?.source;
     if (!PROVENANCE_SOURCES.includes(source)) throw new ChangeError(`the change to "${path}" names no source; every change names one of ${PROVENANCE_SOURCES.join(', ')}`);
     if (!String(change?.provenance?.detail ?? '').trim()) throw new ChangeError(`the change to "${path}" names the source "${source}" and says nothing about it`);
@@ -82,8 +89,11 @@ export function applyChanges(root, changes) {
   const written = [];
   for (const change of changes) {
     const path = join(root, change.path);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, change.contents);
+    if (change.remove === true) rmSync(path, { force: true });
+    else {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, change.contents);
+    }
     written.push(change.path);
   }
   return { written };
@@ -105,7 +115,8 @@ export function open({ root, changes, why, branch, title, base = null, label = T
   if (dryRun) return { repo, branch, title, body, base: onto, written, opened: false };
 
   exec('git', ['checkout', '-b', branch], root);
-  exec('git', ['add', '--', ...written], root);
+  // `git add -A` stages a removed file as well as a written one.
+  exec('git', ['add', '-A', '--', ...written], root);
   exec('git', ['commit', '-m', title, '-m', body], root);
   exec('git', ['push', '-u', 'origin', branch], root);
   // A label that does not exist yet makes `gh pr create` fail, so it is made

package/door/lib/status.mjs

@@ -15,7 +15,7 @@
 // package's list. This runs in a session, with the package on disk.
 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 { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, 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';
@@ -57,8 +57,9 @@ export function statusMany(roots, packageRoot) {
 // 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
+//   workflow  .github/workflows/atlas-gate.yml, by the workflow fingerprint
+//             in each row of that list, or by its shape job; before check
+//             version 6, .github/workflows/atlas-check.yml
 //   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
 //
@@ -92,23 +93,37 @@ function checkRow(root, packageRoot) {
 
 // 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.
+// From check version 6 the workflow is the gate workflow, and a repo may add
+// its own jobs to it, as the Atlas repo does: then its shape job must be the
+// one the package writes. A repo that still has only the old atlas-check.yml
+// is behind (roadmap R7 line 5).
 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.`);
+  const known = (text) => pkg.releases.filter((one) => one.workflow_sha256 === sha256(text));
+  if (!existsSync(full)) {
+    const old = join(root, OLD_WORKFLOW_PATH);
+    if (linkAt(old)) return linked('workflow', OLD_WORKFLOW_PATH, want);
+    if (!existsSync(old)) 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(old, 'utf8'); } catch (error) { return broken('workflow', OLD_WORKFLOW_PATH, want, error); }
+    const rows = known(text);
+    if (rows.length) return row('workflow', OLD_WORKFLOW_PATH, 'behind', `workflow of check version ${rows.at(-1).check_version}`, want, `${OLD_WORKFLOW_PATH} runs the head's copy of the check, so a pull request can change its own judge. "atlas tooling pr" writes ${WORKFLOW_PATH} and removes it.`);
+    return row('workflow', OLD_WORKFLOW_PATH, 'unknown', `sha256 ${sha256(text).slice(0, 12)}…`, want, `${OLD_WORKFLOW_PATH} is in no release, and ${WORKFLOW_PATH} does not exist. "atlas tooling pr" shows the difference.`);
+  }
   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 (text === WORKFLOW_TEMPLATE) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'the workflow is the one this package writes.');
+  if (shapeJobOf(text) === SHAPE_JOB_TEXT) return row('workflow', WORKFLOW_PATH, 'current', want, want, 'its shape job is the one this package writes; the file holds other jobs of this repo too.');
+  const rows = known(text);
   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, 'behind', `workflow of check version ${newest.check_version}`, want, `the workflow was first written by Atlas ${rows[0].first_package ?? `check version ${rows[0].check_version}`}. "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.`);
+  return row('workflow', WORKFLOW_PATH, 'unknown', `sha256 ${sha256(text).slice(0, 12)}…`, want, `the workflow is in no release, and its shape job is not the one this package writes. 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

package/door/lib/tooling.mjs

@@ -14,15 +14,27 @@
 // is missing or behind, or unknown with --replace-unknown, and only a check
 // that is the newest row of the release list. The Atlas repo itself may take
 // its own unreleased check, because that is how a new check is made.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
 import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
 import { status } from './status.mjs';
 import { PR_TEMPLATE_PATH } from './upkeep.mjs';
 
-export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+export { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+
+// The gate workflow (roadmap R7 line 5). A repo may keep its own jobs in it, as
+// the Atlas repo does. When its shape job is the one the package writes, the
+// writer keeps the file. The workflow of check versions 1 to 5,
+// atlas-check.yml, ran the head's copy of the check; the writer removes it.
+const workflowKept = (root) => {
+  const full = join(root, WORKFLOW_PATH);
+  if (!existsSync(full)) return false;
+  const text = readFileSync(full, 'utf8');
+  return text !== WORKFLOW_TEMPLATE && shapeJobOf(text) === SHAPE_JOB_TEXT;
+};
+const oldWorkflow = (root) => existsSync(join(root, OLD_WORKFLOW_PATH));
 
 // The watcher of the routines design (roadmap R24). The writer puts it into each
 // repo, with the version of this package as its pin. It refreshes a copy whose pin
@@ -101,8 +113,8 @@ 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)) {
-    throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE ? '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 === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(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) {
     throw new ToolingRefusal(`${now.why}`);
@@ -120,6 +132,7 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
   for (const [path, contents] of Object.entries(wanted)) {
     const full = join(root, path);
     const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
+    if (path === WORKFLOW_PATH && workflowKept(root)) { rows.push({ path, state: 'kept', sha256: sha256(was), was: sha256(was) }); continue; }
     const state = was === null ? 'written' : was === contents ? 'unchanged' : 'refreshed';
     if (state !== 'unchanged' && !dryRun) {
       mkdirSync(dirname(full), { recursive: true });
@@ -127,6 +140,11 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
+  if (oldWorkflow(root)) {
+    const was = readFileSync(join(root, OLD_WORKFLOW_PATH), 'utf8');
+    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);
@@ -165,7 +183,11 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
-    .map((row) => ({
+    .map((row) => (row.state === 'removed' ? {
+      path: row.path,
+      remove: true,
+      provenance: { source: 'repo read', detail: `the workflow of check versions 1 to 5, which runs the head's copy of the check; ${WORKFLOW_PATH} replaces it from check version ${CHECK_VERSION}` },
+    } : {
       path: row.path,
       contents: wanted[row.path],
       provenance: {

package/door/lib/upkeep.mjs

@@ -119,7 +119,7 @@ export function docsIndex(root) {
     if (path.startsWith('docs/')) listed.add(path);
   }
   const unlisted = markdownFiles(root, 'docs').filter((path) => {
-    if (path === INDEX || path.startsWith('docs/site/') || listed.has(path)) return false;
+    if (path === INDEX || listed.has(path)) return false;
     const folder = designFolderOf(root, path);
     return !(folder && listed.has(`${folder}/design.yaml`));
   });

package/package.json

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