@arjunkhera/atlas 0.4.15 → 0.4.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "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/check.mjs

@@ -7,7 +7,9 @@
 // reader, the secret patterns and the report. It imports Node builtins only.
 //
 // What it reads: the checkout it is pointed at, and nothing else. It opens no
-// network. It holds no token. It writes nothing back into the repo.
+// network. It holds no token. It writes nothing back into the repo. In gate
+// mode only, it reads git objects with the git binary, and writes two trees
+// into a temp folder outside the checkout.
 //
 // What it reports: one state per part of the seven files. Five states: filled,
 // empty, stale, not applicable, no extractor. It leads with the count of
@@ -18,10 +20,12 @@
 //
 // Authority: the Atlas M2 study, design page D1 with its
 // D7 amendment; the Atlas architecture review, build order B1.
-import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, appendFileSync } from 'node:fs';
-import { join, resolve, relative, posix } from 'node:path';
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, appendFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { join, resolve, relative, posix, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
 
 // node:crypto is a builtin, so the check still imports nothing but builtins.
 export const sha256 = (text) => createHash('sha256').update(String(text ?? ''), 'utf8').digest('hex');
@@ -34,7 +38,7 @@ export const sha256 = (text) => createHash('sha256').update(String(text ?? ''),
 // Whether a copy is current or behind is not decided here. CI has no package
 // and no network. The session verb decides it, from the release list that
 // ships beside this file in the package, shape/releases.json.
-export const CHECK_VERSION = 5;
+export const CHECK_VERSION = 6;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -417,8 +421,8 @@ export const SPEC_1 = {
       "parts": [
         {
           "id": "atlas-check",
-          "path": ".github/workflows/atlas-check.yml",
-          "holds": "The one workflow that runs .github/atlas/check.mjs, the check file in this repo.",
+          "path": ".github/workflows/atlas-gate.yml",
+          "holds": "The gate workflow. Its shape job runs the base copy of .github/atlas/check.mjs over the merge base and the head of each pull request.",
           "kind": {
             "service": "required",
             "library": "required",
@@ -640,64 +644,135 @@ export function canaryMisses() {
 }
 
 // ---------------------------------------------------------------------------
-// The workflow that runs this file. A person copies it into a repo today. The
-// tooling helper of slice L2 writes it from here. It runs on pull_request, it
-// reads the contents, it takes no secret, and it pins its one action by commit
-// SHA (design review finding R11).
+// The workflow that runs this file: the gate (roadmap R7, design
+// docs/design-docs/shape-check-from-base/ in the Atlas repo). The tooling
+// writer puts it into each repo from here. It runs on pull_request_target, so
+// GitHub takes it from the base branch, and the check that judges a pull
+// request is the base copy. It reads the head as git objects only, it holds a
+// read token, and it pins its one action by commit SHA (design review finding
+// R11).
+//
+// Check version 6 moved the check here from the old atlas-check.yml, which ran
+// on pull_request with the head's copy of this file. A pull request could edit
+// the check to print GREEN, and the check only warned that a person merges it.
 // ---------------------------------------------------------------------------
 
-export const WORKFLOW_PATH = '.github/workflows/atlas-check.yml';
+export const WORKFLOW_PATH = '.github/workflows/atlas-gate.yml';
+// The workflow of check versions 1 to 5. The tooling writer removes it.
+export const OLD_WORKFLOW_PATH = '.github/workflows/atlas-check.yml';
 export const CHECK_PATH = '.github/atlas/check.mjs';
 
-// Where the workflow puts the base tree. `walk` and `symlinks` skip every entry
-// whose name starts with a dot, and every other read names an exact path, so no
-// scanner ever reaches into it.
+// Where a run by hand, or an old workflow, puts the base tree. `walk` and
+// `symlinks` skip every entry whose name starts with a dot, and every other
+// read names an exact path, so no scanner ever reaches into it.
 export const BASE_DIR = '.atlas-base';
 
-export const WORKFLOW_TEMPLATE = `# The Atlas repo shape check, in this repo's own CI.
-#
-# It reads the seven files this repo carries, named in atlas.yaml and under
-# atlas/, and reports one state per part: filled, empty, stale, not applicable,
-# or no extractor. It reads this repo only. It takes no secret and opens no
-# network, so it runs on a pull request with read access to the contents.
+// The two trees of the gate, under the runner's temp folder, outside the
+// checkout. Each is written from git objects, and loses every link.
+export const GATE_TREES = Object.freeze({ base: 'atlas-base', head: 'atlas-head' });
+
+// The job and the check name. The name says the job runs the shape rule
+// only, so no reader takes it for the full gate, which keeps the name `gate`
+// (roadmap R76). A repo may add jobs to this file; the shape job must stay as
+// Atlas writes it, and `atlas status` compares that job.
+export const SHAPE_JOB = 'shape';
+export const SHAPE_CHECK = 'gate · shape';
+
+export const WORKFLOW_HEADER = `# The Atlas gate workflow, in this repo's own CI. Its shape job is the repo
+# shape check, judged from the base.
 #
-# The check is ${CHECK_PATH} in this repo. It needs no package and no
-# install. Atlas writes both files; do not edit them by hand.
+# It runs on pull_request_target, so GitHub runs this file as the base branch
+# holds it. The job checks out the base and runs the base copy of
+# ${CHECK_PATH}. It fetches the head as git objects only, and runs none of it.
 #
-# It reports in the docs lane. It never fails a code merge.
+# The check writes two trees from git objects, the merge base and the head, in
+# the runner's temp folder, and scores them side by side. No attribute of a
+# tree applies, and no link is written. The no-loss rule says red when a part
+# that the base had is taken away. It says owner when only the owner may
+# approve the change, such as a change to the check or to this file.
 #
-# The second checkout is the no-loss rule's base tree. The check scores the base
-# commit and the head commit side by side, and it goes red when a part the base
-# already had is taken away. The base tree lands in ${BASE_DIR}, whose name
-# starts with a dot, so no scanner walks into it. If that checkout fails there
-# is nothing to compare, so the step may fail and the check says so and does not
-# gate.
+# The token can only read. No checkout keeps a credential: the one fetch of
+# the head takes the token for that command alone. The check step holds no
+# token. The job writes two output keys, result and class.
 #
-# Design: the Atlas architecture record, sections 5.2, 6 and rule 7.
-name: atlas-check
+# Atlas writes this file and ${CHECK_PATH}; do not edit the shape job by hand.
+# Design: docs/design-docs/shape-check-from-base/ in the Atlas repo.
+name: atlas-gate
+run-name: "gate #\${{ github.event.pull_request.number }} at \${{ github.event.pull_request.head.sha }}"
 on:
-  pull_request:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
 permissions:
   contents: read
+concurrency:
+  group: atlas-gate-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
 jobs:
-  repo-shape:
-    name: docs · repo shape
+`;
+
+export const SHAPE_JOB_TEXT = `  ${SHAPE_JOB}:
+    name: ${SHAPE_CHECK}
     runs-on: ubuntu-latest
-    # The check reads two directory trees and opens no network. It finishes in
-    # seconds. The bound stops a runner being billed until someone kills it.
-    timeout-minutes: 5
+    # The check reads two trees and opens no network. It finishes in seconds
+    # on a small repo. The bound stops a runner being billed until someone
+    # kills it; a run that hits it is red.
+    timeout-minutes: 10
+    outputs:
+      result: \${{ steps.shape.outputs.result }}
+      class: \${{ steps.shape.outputs.class }}
     steps:
-      # actions/checkout v4.3.1
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
-      - name: the base commit, for the no-loss rule
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
-        continue-on-error: true
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: \${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
         with:
-          ref: \${{ github.event.pull_request.base.sha }}
-          path: ${BASE_DIR}
-      - run: node ${CHECK_PATH} --base ${BASE_DIR} --base-sha \${{ github.event.pull_request.base.sha }}
+          node-version: "22.22.0"
+      - name: Fetch the head as objects only
+        env:
+          PR: \${{ github.event.pull_request.number }}
+          HEAD_SHA: \${{ github.event.pull_request.head.sha }}
+          TOKEN: \${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+      - name: Shape check from the base
+        id: shape
+        env:
+          HEAD_SHA: \${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          if [ ! -f ${CHECK_PATH} ]; then
+            echo "OWNER: first-run: the base has no ${CHECK_PATH}, so the owner reads the first shape"
+            echo "result=owner" >> "$GITHUB_OUTPUT"
+            echo "class=first-run" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          node ${CHECK_PATH} --gate --repo "$GITHUB_REPOSITORY" --base-commit "$GITHUB_SHA" --head-commit "$HEAD_SHA"
 `;
 
+export const WORKFLOW_TEMPLATE = `${WORKFLOW_HEADER}${SHAPE_JOB_TEXT}`;
+
+// The shape job of a workflow text: from its key line to the next job key or
+// the end. `atlas status` compares it with SHAPE_JOB_TEXT.
+export function shapeJobOf(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const start = lines.indexOf(`  ${SHAPE_JOB}:`);
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length && !/^ {2}\S/.test(lines[end]) && !/^\S/.test(lines[end])) end += 1;
+  return `${lines.slice(start, end).join('\n').replace(/\n+$/, '')}\n`;
+}
+
 // ---------------------------------------------------------------------------
 // The YAML reader. Atlas ships no dependency, so the check reads the subset of
 // YAML that atlas.yaml, the section files and a SKILL.md front matter block
@@ -1013,21 +1088,29 @@ function checkPathRules(context, part) {
     if (!list.length) { bad.push(`${file} has no paths: key`); continue; }
     for (const pattern of list) {
       const base = String(pattern).split(/[*?[]/)[0].replace(/\/+$/, '');
+      if (base && !insideRepo(context.root, base)) { bad.push(`${file} names a path outside the repo`); continue; }
       if (base && !existsSync(join(context.root, base))) bad.push(`${file} names ${pattern}, which does not exist`);
     }
   }
   return bad.length ? result(part, 'stale', bad.slice(0, MAX_LISTED)) : result(part, 'filled', [`${files.length} rule file(s)`]);
 }
 
+const SKILL_NAME = /^(?!\.\.?$)[A-Za-z0-9._-]{1,100}$/;
+
 function checkProcedure(context, part) {
   const named = context.facts?.procedures?.[part.procedure];
   if (named === undefined) return result(part, 'empty', [`atlas.yaml has no procedures entry for ${part.procedure}`]);
   if (named === null || named === '') return result(part, 'empty', [`atlas.yaml sets procedures.${part.procedure} to null: the repo has no skill for it yet`]);
+  // A skill name is one folder name. A slash, a dot pair or a control
+  // character would let atlas.yaml point the check outside the skills folder,
+  // or outside the tree it scores (security review of roadmap R7).
+  if (!SKILL_NAME.test(String(named))) return result(part, 'stale', [`atlas.yaml names a skill for ${part.procedure} that is not one folder name`]);
   const skill = posix.join('.claude/skills', String(named), 'SKILL.md');
-  if (!isFile(context.root, skill)) return result(part, 'stale', [`atlas.yaml names skill "${named}", and ${skill} does not exist`]);
+  const at = { ...part, path: skill };
+  if (!isFile(context.root, skill)) return result(at, 'stale', [`atlas.yaml names skill "${named}", and ${skill} does not exist`]);
   const front = frontMatter(readText(context.root, skill) ?? '');
-  if (!front?.name || !front?.description) return result(part, 'stale', [`${skill} has no name or no description in its front matter`]);
-  return result(part, 'filled', [skill]);
+  if (!front?.name || !front?.description) return result(at, 'stale', [`${skill} has no name or no description in its front matter`]);
+  return result(at, 'filled', [skill]);
 }
 
 // `scan` reports a missing or unreadable atlas.yaml as an error and returns
@@ -1221,6 +1304,9 @@ function writeGrants(text) {
 // A workflow this function cannot read is a finding, not a pass. That is the
 // safe direction: the check says it cannot confirm the job runs, instead of
 // saying the job is fine.
+// The step that runs the shape check, and the flags it must pass.
+const GATE_RUNNER = Object.freeze({ runs: `node ${CHECK_PATH} `, flags: ['--gate', '--base-commit', '--head-commit'] });
+
 function workflowStructure(document) {
   const out = [];
   const jobs = document?.jobs;
@@ -1230,9 +1316,9 @@ function workflowStructure(document) {
   // the pull requests that change the files it guards, and the pull request
   // still reads green, because a job that never ran reports nothing (P13).
   const on = document.on;
-  const trigger = on && typeof on === 'object' && !Array.isArray(on) ? on.pull_request : null;
+  const trigger = on && typeof on === 'object' && !Array.isArray(on) ? on.pull_request_target : null;
   if (trigger && typeof trigger === 'object' && !Array.isArray(trigger)) {
-    for (const key of ['paths', 'paths-ignore']) {
+    for (const key of ['paths', 'paths-ignore', 'branches-ignore']) {
       if (trigger[key] !== undefined && trigger[key] !== null) {
         out.push(`the workflow narrows its trigger with ${key}; this check must run on every pull request`);
       }
@@ -1245,41 +1331,39 @@ function workflowStructure(document) {
   for (const [jobName, job] of Object.entries(jobs)) {
     for (const step of Array.isArray(job?.steps) ? job.steps : []) {
       const runs = typeof step?.run === 'string' ? step.run : '';
-      if (runs.includes(CHECK_PATH)) found = { jobName, job, step, runs };
+      if (runs.includes(GATE_RUNNER.runs)) found = { jobName, job, step, runs, runner: GATE_RUNNER };
     }
   }
   if (!found) {
-    out.push(`no step in this workflow runs "node ${CHECK_PATH}", so the job reports nothing`);
+    out.push(`no step in this workflow runs "node ${CHECK_PATH} --gate", so the job reports nothing`);
     return out;
   }
 
-  // The no-loss rule's own two inputs, from slice L2 stage two.
-  //
-  // Without them the check still runs, still prints a report, and still goes
-  // green — and the no-loss rule never runs at all. That is the same class of hole
-  // the batch 16 reviewer found nine ways (finding S2-1): a workflow that
-  // silences the job while the part still reads "filled". Deleting two flags
-  // is the cheapest version of it, so the scanner reads the flags, not just
-  // the path.
-  for (const flag of ['--base', '--base-sha']) {
+  // The flags. Without them the check still runs and still goes green, and the
+  // no-loss rule never runs at all, or it scores the wrong tree. Deleting a
+  // flag is the cheapest way to silence the job, so the scanner reads the flags,
+  // not just the path (finding S2-1).
+  for (const flag of found.runner.flags) {
     if (!new RegExp(`${flag}(?:[ \t=]|$)`, 'm').test(found.runs)) {
-      out.push(`the check step does not pass ${flag}, so the no-loss rule never runs and a pull request can take a part away with the job still green`);
+      out.push(`the check step does not pass ${flag}, so the no-loss rule cannot judge the pull request from the base`);
     }
   }
-  // And the tree it compares against has to be fetched by something.
-  const fetchesBase = Object.values(jobs).some((job) => (Array.isArray(job?.steps) ? job.steps : [])
-    .some((step) => typeof step?.uses === 'string' && step.uses.startsWith('actions/checkout') && step?.with?.path === BASE_DIR));
-  if (!fetchesBase) {
-    out.push(`no step checks the base commit out into ${BASE_DIR}, so the no-loss rule has no tree to compare against`);
+  // Every checkout is of the base commit and keeps no credential. A checkout
+  // of the head would run the head's copy of the check: the hole this
+  // workflow exists to close.
+  const checkouts = (Array.isArray(found.job?.steps) ? found.job.steps : [])
+    .filter((step) => typeof step?.uses === 'string' && step.uses.startsWith('actions/checkout'));
+  if (!checkouts.length) out.push('no step checks the base commit out, so there is no base copy of the check to run');
+  for (const step of checkouts) {
+    if (String(step?.with?.ref ?? '').replace(/\s+/g, '') !== '${{github.sha}}') out.push('a checkout step does not check out github.sha, the base commit; the check must run from the base');
+    if (step?.with?.['persist-credentials'] !== false) out.push('a checkout step keeps its credential; set persist-credentials: false');
   }
 
   // A condition switches the step, or its whole job, off. Same effect as a
   // narrowed trigger, by another route.
   if (found.step.if !== undefined) out.push('the workflow puts an if: on the check step; the step must always run');
   if (found.job.if !== undefined) out.push("the workflow puts an if: on the check's job; the job must always run");
-  // Two more ways to make a red check look green. Neither is in the frozen
-  // list. Both defeat the same purpose, and stage two's no-loss rule needs a red job
-  // to mean something, so the check names them (reviewer of batch 16, S2-1).
+  // Two more ways to make a red check look green (reviewer of batch 16, S2-1).
   if (found.step['continue-on-error'] === true || found.job['continue-on-error'] === true) {
     out.push('the workflow sets continue-on-error on the check; a failed check would not turn the job red');
   }
@@ -1293,8 +1377,11 @@ function checkWorkflow(context, part) {
   const text = readText(context.root, part.path);
   if (text === null || !text.trim()) return result(part, 'empty', [`${part.path} is missing or holds nothing`]);
   const findings = [];
-  if (/^\s*pull_request_target\s*:/m.test(text)) findings.push('the workflow runs on pull_request_target; it must run on pull_request');
-  if (!/^\s*pull_request\s*:/m.test(text)) findings.push('the workflow does not run on pull_request');
+  // pull_request_target takes this file from the base branch. On pull_request,
+  // GitHub runs the copy the pull request carries, and the pull request can
+  // change its own judge (roadmap R7).
+  if (!/^\s*pull_request_target\s*:/m.test(text)) findings.push('the workflow does not run on pull_request_target; it must take its file and the check from the base');
+  if (/^\s*pull_request\s*:/m.test(text)) findings.push('the workflow also runs on pull_request, which runs the head copy of this file');
   // The structure, from the parsed document. A workflow this check cannot read
   // is a finding: it can no longer say the job runs at all.
   try {
@@ -1511,7 +1598,12 @@ export function scan({ root, repoId = null, extractors = [], secretPatterns: pat
   if (spec && !spec.kinds[kind]) { errors.push(`atlas.yaml names kind "${kind}"; spec ${spec.spec} knows ${Object.keys(spec.kinds).join(', ')}`); spec = null; }
   if (!spec) return { ok: false, check_version: CHECK_VERSION, repo: repoId, kind, spec: wantedSpec ?? null, scored_as: scoreAs, product: facts?.product ?? null, files: [], by_reference: [], counts: counts([]), errors };
 
-  const context = { root, facts, factsError, repoId, extractors, secretPatterns: usable, errors };
+  // The no-loss rule can score a tree at another tree's pointers: the paths
+  // that atlas.yaml names for the procedures and the facts files. So a part
+  // that a pull request moves is also scored where the base had it (roadmap R7
+  // line 3).
+  const pointed = scoreAs?.pointers ? { ...facts, files: scoreAs.pointers.files, procedures: scoreAs.pointers.procedures } : facts;
+  const context = { root, facts: pointed, factsError, repoId, extractors, secretPatterns: usable, errors };
   // atlas.yaml's own values reach the report: the kind, the repo id, a
   // procedure's skill name, every pointer path. Scan it before any of them is
   // quoted (acceptance review of batch 16, note S3-2).
@@ -1568,21 +1660,30 @@ export function counts(files) {
 // four required parts into "not applicable" and the count falls. Scoring per
 // part, with the base tree's `kind` and `spec`, closes both (findings P2, P20).
 //
-// Which copy scores. The head's. That is this file. A pull request that
-// improves the check would otherwise turn red under the old scanners, and a
-// pull request that weakens one would turn green under them. The head's copy
-// judging its own diff would be a hole, so the two cases where the diff touches
-// the gate are the first two report-only cases below: a person merges those
-// files, and the check says plainly that it did not gate (finding P1).
+// Which copy scores. The base's, from check version 6 (roadmap R7). The gate
+// job runs on pull_request_target, so it runs this file as the base holds it,
+// over two trees written from git objects. Before that, the head's copy judged
+// its own diff, and a pull request could edit the check to print GREEN. The
+// two report-only cases for the check file and its workflow covered that hole
+// with a warning that a person merges the file. Under merge on green, no
+// person reads that warning. Now a change to either gives "owner" and the rule
+// still gates.
+//
+// A run by hand, or an old workflow, still runs the head's copy. Its answer
+// is a report. The gate's answer is the one a merge waits on.
 //
 // Where it lives. Here. The repository still carries two files and only two.
 // ---------------------------------------------------------------------------
 
-// The five cases where the no-loss rule reports and does not gate. Each is named in
-// the report, so a reader never has to guess why the job stayed green.
-export const NO_LOSS_CASES = Object.freeze(['check-file', 'workflow', 'kind', 'spec', 'base-tree']);
+// The cases that give "owner". Only the owner may approve such a change, and
+// the rule still gates: it still finds any part that went backwards. Before
+// check version 6 five cases switched the rule off and printed a warning that
+// a person merges the file. Nothing switches it off now. The base copy scores,
+// and the base kind and spec score both trees, so no case needs to.
+export const OWNER_CASES = Object.freeze(['check-file', 'workflow', 'kind', 'spec', 'moved', 'first-run']);
 
 const fileHash = (root, path) => { const text = readText(root, path); return text === null ? null : sha256(text); };
+const isEmptyDir = (root) => { try { return !readdirSync(root).length; } catch { return true; } };
 
 // The commit a checkout sits on, read from `.git/HEAD` as text. No git binary,
 // no network. `actions/checkout` leaves a detached HEAD, so the first line is
@@ -1610,45 +1711,48 @@ const partIndex = (report) => {
   return map;
 };
 
-export function noLoss({ headRoot, baseRoot, baseSha = null, repoId = null, secretPatterns: patterns = secretPatterns() }) {
+// `baseCommit` is the commit the caller wrote the base tree from, when it
+// wrote the tree itself from git objects, as the gate does. Such a tree has
+// no `.git`, and the caller is the base code, so its word is the tree's name.
+export function noLoss({ headRoot, baseRoot, baseSha = null, baseCommit = null, repoId = null, secretPatterns: patterns = secretPatterns() }) {
   const out = {
     ran: true,
-    gates: true,
     green: true,
+    broken: null,
     base_dir: baseRoot,
     base_sha: baseSha,
     base_head: null,
     base_facts: null,
     head_facts: null,
     parts_compared: 0,
-    report_only: [],
+    owner: [],
     regressions: [],
   };
-  const excuse = (name, why) => { out.gates = false; out.report_only.push({ case: name, why }); };
+  const owner = (name, why, extra = {}) => out.owner.push({ case: name, why, ...extra });
+  // A missing or wrong base tree is red, never green: there is nothing to
+  // compare, and a rule that cannot compare cannot say nothing was lost
+  // (roadmap R7 line 4).
+  const broken = (why) => { out.broken = why; out.green = false; return out; };
 
   // 1. Is there a base tree at all, and is it the pull request's base?
-  const baseRead = readFacts(baseRoot);
-  if (!existsSync(join(baseRoot, 'atlas.yaml'))) {
-    excuse('base-tree', `no base tree at ${baseRoot}: the checkout of the base commit did not land, so there is nothing to compare`);
-    return out;
-  }
-  if (baseRead.error || !baseRead.facts) {
-    excuse('base-tree', `the base tree at ${baseRoot} has no readable atlas.yaml${baseRead.error ? `: ${baseRead.error}` : ''}, so its kind and spec cannot be read`);
-    return out;
-  }
-  out.base_head = checkoutHead(baseRoot);
+  if (!existsSync(baseRoot) || isEmptyDir(baseRoot)) return broken(`no base tree at ${baseRoot}: the base commit did not land, so there is nothing to compare`);
+  out.base_head = baseCommit && PINNED.test(baseCommit) ? baseCommit : checkoutHead(baseRoot);
   // The pull request promised a base commit. If the tree cannot say which
   // commit it is, the promise is unchecked, and an unchecked promise is not a
   // base tree. Reporting a sha this check was handed but never read would be a
-  // claim it cannot support, so it takes the base-tree case instead.
-  if (baseSha && !out.base_head) {
-    excuse('base-tree', `the base tree at ${baseRoot} does not say which commit it is, so this check cannot confirm it is ${baseSha.slice(0, 12)}, the base this pull request names`);
-    return out;
-  }
-  if (baseSha && out.base_head !== baseSha) {
-    excuse('base-tree', `the base tree at ${baseRoot} is at ${out.base_head.slice(0, 12)}, and this pull request's base is ${baseSha.slice(0, 12)}; the comparison would be against the wrong commit`);
+  // claim it cannot support.
+  if (baseSha && !out.base_head) return broken(`the base tree at ${baseRoot} does not say which commit it is, so this check cannot confirm it is ${baseSha.slice(0, 12)}, the base this pull request names`);
+  if (baseSha && out.base_head !== baseSha) return broken(`the base tree at ${baseRoot} is at ${out.base_head.slice(0, 12)}, and this pull request's base is ${baseSha.slice(0, 12)}; the comparison would be against the wrong commit`);
+  // A base with no atlas.yaml is the first run in a repo: the pull request that
+  // adds Atlas. There is nothing to lose, and the owner reads the first shape.
+  const baseRead = readFacts(baseRoot);
+  if (!baseRead.facts && !baseRead.error) {
+    owner('first-run', 'the base has no atlas.yaml, so there is nothing to lose; the owner reads the first shape');
     return out;
   }
+  // A base atlas.yaml that does not read cannot name a kind or a spec, so
+  // there is no yardstick. That is red. The owner merges the fix by hand.
+  if (baseRead.error) return broken(`the base atlas.yaml does not read, so its kind and spec are unknown: ${baseRead.error}`);
 
   // 2. The base tree's kind and spec score both trees.
   const scoreAs = { kind: baseRead.facts.kind ?? null, spec: baseRead.facts.spec ?? null };
@@ -1657,28 +1761,30 @@ export function noLoss({ headRoot, baseRoot, baseSha = null, repoId = null, secr
   out.head_facts = { kind: headRead.facts?.kind ?? null, spec: headRead.facts?.spec ?? null };
 
   if (String(out.head_facts.kind) !== String(scoreAs.kind)) {
-    excuse('kind', `atlas.yaml names kind "${scoreAs.kind}" at the base and "${out.head_facts.kind}" at the head; this pull request changes which parts the repo needs`);
+    owner('kind', `atlas.yaml names kind "${scoreAs.kind}" at the base and "${out.head_facts.kind}" at the head; this pull request changes which parts the repo needs`);
   }
   if (String(out.head_facts.spec) !== String(scoreAs.spec)) {
-    excuse('spec', `atlas.yaml names spec "${scoreAs.spec}" at the base and "${out.head_facts.spec}" at the head; this pull request changes what the spec version means`);
+    owner('spec', `atlas.yaml names spec "${scoreAs.spec}" at the base and "${out.head_facts.spec}" at the head; this pull request changes what the spec version means`);
   }
 
-  // 3. Does the diff change the gate itself?
-  for (const [name, path] of [['check-file', CHECK_PATH], ['workflow', WORKFLOW_PATH]]) {
+  // 3. Does the diff change the gate itself? The base copy judges, so the
+  // change cannot score itself, but only the owner may approve it.
+  for (const [name, path] of [['check-file', CHECK_PATH], ['workflow', WORKFLOW_PATH], ['workflow', OLD_WORKFLOW_PATH]]) {
     if (fileHash(baseRoot, path) !== fileHash(headRoot, path)) {
-      excuse(name, `this pull request changes ${path}, which is the gate itself; it is instruction class, so a person merges it`);
+      owner(name, `this pull request changes ${path}, which is the gate itself; it is instruction class, so only the owner approves it`, { path });
     }
   }
 
-  // 4. Score both trees, by the same yardstick, and compare part by part.
+  // 4. Score both trees, by the same yardstick, and compare part by part. The
+  // head is scored twice: at its own pointers, and at the base's.
   const base = scan({ root: baseRoot, repoId, secretPatterns: patterns, scoreAs });
   const head = scan({ root: headRoot, repoId, secretPatterns: patterns, scoreAs });
-  if (!base.files.length) {
-    excuse('base-tree', `the base tree at ${baseRoot} could not be scored: ${base.errors.join('; ') || 'no parts came back'}`);
-    return out;
-  }
+  const pointers = { files: baseRead.facts.files, procedures: baseRead.facts.procedures };
+  const headAtBase = scan({ root: headRoot, repoId, secretPatterns: patterns, scoreAs: { ...scoreAs, pointers } });
+  if (!base.files.length) return broken(`the base tree at ${baseRoot} could not be scored: ${base.errors.join('; ') || 'no parts came back'}`);
 
   const headParts = partIndex(head);
+  const atBaseParts = partIndex(headAtBase);
   for (const [key, { file, part }] of partIndex(base)) {
     if (file.class !== 'instruction' || part.state !== 'filled') continue;
     out.parts_compared += 1;
@@ -1689,12 +1795,51 @@ export function noLoss({ headRoot, baseRoot, baseSha = null, repoId = null, secr
     }
     if (now.part.state !== 'filled') {
       out.regressions.push({ part: key, label: label(now.part), was: 'filled', now: now.part.state, findings: now.part.findings, why: `${label(now.part)} was filled at the base and is ${now.part.state} at the head` });
+      continue;
     }
+    // A moved part: the head points it somewhere else. The head is filled
+    // at its new pointer, or the part would be a regression above. The owner
+    // reads every move, and the answer says whether the base path still holds
+    // the part in the head (roadmap R7 line 3).
+    const from = part.path;
+    const to = now.part.path;
+    if (!from || !to || from === to) continue;
+    const kept = atBaseParts.get(key)?.part.state === 'filled' ? `; ${from} still holds it` : `; ${from} no longer holds it`;
+    owner('moved', `${label(part)} moved from ${from} to ${to}${kept}`, { path: to });
   }
   out.green = !out.regressions.length;
   return out;
 }
 
+// The answer of the shape rule for the gate: success, owner or red, with one
+// row for each finding. Red wins over owner. The gate job and `atlas gate
+// check` both take it from here, so the two cannot disagree.
+export const GATE_RESULTS = Object.freeze(['success', 'owner', 'red']);
+export function gateAnswer(report, state) {
+  const rows = [];
+  for (const error of report.errors) rows.push({ kind: 'red', class: 'shape', cause: `the check hit an error at the head: ${error}` });
+  if (state?.broken) rows.push({ kind: 'red', class: 'shape', cause: state.broken });
+  for (const row of state?.regressions ?? []) rows.push({ kind: 'red', class: 'shape', cause: row.why });
+  for (const row of state?.owner ?? []) rows.push({ kind: 'owner', class: 'shape', cause: `${row.case}: ${row.why}`, ...(row.path ? { path: row.path } : {}) });
+  if (!state) rows.push({ kind: 'red', class: 'shape', cause: 'the no-loss rule did not run: no base tree was named' });
+  const result = rows.some((row) => row.kind === 'red') ? 'red' : rows.some((row) => row.kind === 'owner') ? 'owner' : 'success';
+  return { result, class: result === 'success' ? null : 'shape', rows };
+}
+
+// One line for each row, with a fixed prefix, and no control character, so a
+// path cannot start a workflow command.
+const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+export function gateLines(answer, state) {
+  const base = state?.base_head ? state.base_head.slice(0, 12) : 'none';
+  const yard = state?.base_facts ? `kind ${oneLine(state.base_facts.kind)}, spec ${oneLine(state.base_facts.spec)}` : 'no yardstick';
+  const out = [`shape: base ${base}, ${yard}, ${state?.parts_compared ?? 0} instruction-class part(s) filled at the base`];
+  for (const row of answer.rows) out.push(`  ${row.kind.padEnd(6)} ${row.class.padEnd(6)} ${oneLine(row.cause)}`);
+  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: shape. Clears with the owner's signed act: atlas approve <pr> (roadmap R72).");
+  else out.push('SUCCESS: no instruction-class part went backwards.');
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // The report. Two shapes: plain text for the CI log, and GitHub markdown for
 // the job summary. Both list every part, its state and its findings.
@@ -1748,23 +1893,13 @@ export function noLossLines(state) {
   out.push(`   base ${read} in ${state.base_dir}${promised}`);
   if (state.base_facts) out.push(`   scored both trees as kind ${state.base_facts.kind}, spec ${state.base_facts.spec}, from the base tree`);
   if (state.parts_compared) out.push(`   ${state.parts_compared} instruction-class part(s) were filled at the base`);
-  for (const row of state.report_only) out.push(`   REPORT ONLY (${row.case}): ${row.why}`);
+  if (state.broken) out.push(`   NO BASE TREE: ${state.broken}`);
+  for (const row of state.owner ?? []) out.push(`   OWNER (${row.case}): ${row.why}`);
   for (const row of state.regressions) {
     out.push(`   BACKWARDS  ${row.label}: ${row.was} at the base, ${row.now} at the head`);
     for (const finding of row.findings ?? []) out.push(`       - ${finding}`);
   }
   if (!state.regressions.length && state.base_facts) out.push('   no instruction-class part went backwards');
-  if (!state.gates) {
-    out.push('   this no-loss rule reports and does not gate on this pull request');
-    // The loudest line in the report, and the one a reader must not miss. The
-    // frozen text excuses these five cases because a person merges every file
-    // that causes one. That is a compensating control, not an absence of
-    // findings, so the findings are said out loud beside the green.
-    if (state.regressions.length) {
-      out.push(`   WARNING: ${state.regressions.length} part(s) above went backwards and this job is NOT red for them.`);
-      out.push('   A person merges this pull request. Read the BACKWARDS lines before you do.');
-    }
-  }
   return out;
 }
 
@@ -1808,15 +1943,14 @@ export function toMarkdown(report) {
 export function verdict(report, failOn) {
   if (report.errors.length) return { green: false, why: `the check hit ${report.errors.length} error(s)` };
   const state = report.noLoss;
-  if (state?.gates && state.regressions.length) {
+  if (state?.broken) return { green: false, why: `the no-loss rule has no base tree to compare: ${state.broken}` };
+  if (state?.regressions.length) {
     return { green: false, why: `${state.regressions.length} instruction-class part(s) went backwards against the base: ${state.regressions.map((row) => row.label).join(', ')}` };
   }
   if (failOn === 'required' && report.counts.required_not_filled) return { green: false, why: `${report.counts.required_not_filled} required file(s) are not filled` };
   if (failOn === 'any' && report.counts.not_filled) return { green: false, why: `${report.counts.not_filled} file(s) are not filled` };
-  const excused = state && !state.gates && state.regressions.length
-    ? ` — WARNING: ${state.regressions.length} part(s) went backwards and were NOT gated; a person merges this one`
-    : '';
-  const noLossWhy = state ? (state.gates ? '; no instruction-class part went backwards' : `; the no-loss rule reported and did not gate (${state.report_only.map((row) => row.case).join(', ')})${excused}`) : '';
+  const owned = state?.owner?.length ? `; only the owner approves this change (${[...new Set(state.owner.map((row) => row.case))].join(', ')}), so the gate says "owner"` : '';
+  const noLossWhy = state ? `; no instruction-class part went backwards${owned}` : '';
   return { green: true, why: `${report.counts.required_not_filled} required file(s) are not filled; fail-on is "${failOn}"${noLossWhy}` };
 }
 
@@ -1828,7 +1962,7 @@ export const FAIL_ON = Object.freeze(['error', 'required', 'any']);
 export const EXTRACTORS = Object.freeze([]); // Slice L3 adds routes, migrations and mcp.
 
 export function parseArguments(argv) {
-  const out = { root: process.cwd(), failOn: 'error', json: null, summary: null, quiet: false, base: null, baseSha: null };
+  const out = { root: process.cwd(), failOn: 'error', json: null, summary: null, quiet: false, base: null, baseSha: null, baseCommit: null, headCommit: null, git: process.cwd(), gate: false };
   for (let index = 0; index < argv.length; index += 1) {
     const flag = argv[index];
     const next = () => { const value = argv[index + 1]; if (value === undefined) throw new Error(`${flag} needs a value`); index += 1; return value; };
@@ -1842,16 +1976,27 @@ export function parseArguments(argv) {
     // the check can say the tree it reads is the tree it was promised.
     else if (flag === '--base') out.base = resolve(next());
     else if (flag === '--base-sha') out.baseSha = next().trim() || null;
+    // Gate mode (roadmap R7). The gate job wrote the base tree from git
+    // objects, so it names the commit; the answer is success, owner or red.
+    else if (flag === '--base-commit') out.baseCommit = next().trim() || null;
+    else if (flag === '--head-commit') out.headCommit = next().trim() || null;
+    else if (flag === '--git') out.git = resolve(next());
+    else if (flag === '--gate') out.gate = true;
     else if (flag === '--repo') out.repo = next();
     else if (flag === '--version') out.version = true;
     else throw new Error(`unknown argument ${flag}`);
   }
   if (!FAIL_ON.includes(out.failOn)) throw new Error(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
+  for (const [flag, value] of [['--base-commit', out.baseCommit], ['--head-commit', out.headCommit]]) {
+    if (value && !PINNED.test(value)) throw new Error(`${flag} must be a full 40-character commit SHA`);
+  }
+  if (out.gate && (!out.baseCommit || !out.headCommit)) throw new Error('--gate needs --base-commit and --head-commit');
   return out;
 }
 
 export function run(argv, env = process.env) {
   const options = parseArguments(argv);
+  if (options.gate) return runGate({ options, env });
   const repoId = options.repo ?? env.GITHUB_REPOSITORY ?? null;
   const patterns = secretPatterns();
   const report = scan({ root: options.root, repoId, extractors: EXTRACTORS, secretPatterns: patterns });
@@ -1859,7 +2004,7 @@ export function run(argv, env = process.env) {
   // hand. The no-loss rule then does not run at all, and the report says nothing
   // about it rather than claiming a pass.
   report.noLoss = options.base
-    ? noLoss({ headRoot: options.root, baseRoot: options.base, baseSha: options.baseSha, repoId, secretPatterns: patterns })
+    ? noLoss({ headRoot: options.root, baseRoot: options.base, baseSha: options.baseSha, baseCommit: options.baseCommit, repoId, secretPatterns: patterns })
     : null;
   const decision = verdict(report, options.failOn);
   const text = toText(report);
@@ -1870,6 +2015,144 @@ export function run(argv, env = process.env) {
   return { report, decision, text, options };
 }
 
+// ---------------------------------------------------------------------------
+// The two trees of the gate (roadmap R7). Each one is written from git objects:
+// `git ls-tree` lists the entries and `git cat-file` gives each blob, so no
+// attribute of the tree applies. `git archive` would apply the head's own
+// .gitattributes (export-subst, export-ignore, a filter), and the check would
+// score bytes that do not merge (security review of R7, finding S1).
+//
+// Each blob is checked against its id. A path must be plain: no empty, "." or
+// ".." part, no ".git" part, no leading slash and no control character. A link
+// or a submodule is listed and never written, so the check never follows one.
+// ---------------------------------------------------------------------------
+
+export class TreeError extends Error {}
+
+export const TREE_LIMITS = Object.freeze({ files: 200_000, bytes: 1024 * 1024 * 1024 });
+
+function gitRun(git, args, input = null) {
+  const r = spawnSync('git', ['-C', git, ...args], { input, maxBuffer: TREE_LIMITS.bytes + 64 * 1024 * 1024 });
+  if (r.error) throw new TreeError(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) throw new TreeError(`git ${args[0]} failed: ${String(r.stderr ?? '').trim().split('\n')[0]}`);
+  return r.stdout;
+}
+
+const PLAIN_PART = /^(?!\.\.?$)(?!\.git$)[^\u0000-\u001f\u007f/\\]+$/;
+export const plainPath = (path) => typeof path === 'string' && path.length > 0 && path.split('/').every((part) => PLAIN_PART.test(part));
+
+// The entries of one commit's tree: blobs, links and submodules.
+export function treeEntries(git, commit) {
+  const out = { blobs: [], links: [], modules: [] };
+  const seen = new Set();
+  for (const row of gitRun(git, ['ls-tree', '-r', '-z', '--full-tree', commit]).toString('utf8').split('\0')) {
+    if (!row) continue;
+    const match = /^(\d{6}) (\w+) ([0-9a-f]{40,64})\t([\s\S]+)$/.exec(row);
+    if (!match) throw new TreeError('git ls-tree printed a row this check cannot read');
+    const [, mode, type, id, path] = match;
+    if (!plainPath(path)) throw new TreeError(`the tree of ${commit.slice(0, 12)} holds a path that is not plain`);
+    if (seen.has(path)) throw new TreeError(`the tree of ${commit.slice(0, 12)} holds one path twice`);
+    seen.add(path);
+    if (mode === '120000') out.links.push({ path, id });
+    else if (type === 'commit') out.modules.push({ path, id });
+    else if (type === 'blob') out.blobs.push({ path, id });
+    else throw new TreeError(`the tree of ${commit.slice(0, 12)} holds an entry of type ${type}`);
+  }
+  return out;
+}
+
+const blobId = (bytes, length) => createHash(length === 64 ? 'sha256' : 'sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+// Write the blobs of one commit under `dest`. Returns the entries.
+export function writeTree({ git, commit, dest }) {
+  const entries = treeEntries(git, commit);
+  if (entries.blobs.length > TREE_LIMITS.files) throw new TreeError(`the tree of ${commit.slice(0, 12)} holds more than ${TREE_LIMITS.files} files`);
+  const output = entries.blobs.length ? gitRun(git, ['cat-file', '--batch'], `${entries.blobs.map((blob) => blob.id).join('\n')}\n`) : Buffer.alloc(0);
+  let at = 0;
+  let total = 0;
+  for (const blob of entries.blobs) {
+    const end = output.indexOf(0x0a, at);
+    const header = output.subarray(at, end).toString('utf8');
+    const match = /^([0-9a-f]{40,64}) blob (\d+)$/.exec(header);
+    if (!match || match[1] !== blob.id) throw new TreeError(`git cat-file did not give the blob of ${blob.path}`);
+    const size = Number(match[2]);
+    total += size;
+    if (total > TREE_LIMITS.bytes) throw new TreeError(`the tree of ${commit.slice(0, 12)} is over ${TREE_LIMITS.bytes} bytes`);
+    const bytes = output.subarray(end + 1, end + 1 + size);
+    if (blobId(bytes, blob.id.length) !== blob.id) throw new TreeError(`the bytes of ${blob.path} are not its blob`);
+    const full = join(dest, ...blob.path.split('/'));
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, bytes, { flag: 'wx' });
+    at = end + 1 + size + 1;
+  }
+  return entries;
+}
+
+const commitOf = (git, ref) => {
+  const r = spawnSync('git', ['-C', git, 'rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+};
+
+// The shape rule over git data: the base commit is the tip of the base branch,
+// the head commit is the pull request's head. Both trees come from the merge
+// base and the head. Any step that fails is red.
+export function gateFromGit({ git, baseCommit, headCommit, repoId = null, trees = null, secretPatterns: patterns = secretPatterns() }) {
+  const red = (why) => ({ report: { errors: [], files: [], counts: counts([]) }, state: { broken: why, owner: [], regressions: [], parts_compared: 0, base_head: null, base_facts: null } });
+  const base = commitOf(git, baseCommit);
+  const head = commitOf(git, headCommit);
+  if (!base) return red(`the base commit ${String(baseCommit).slice(0, 12)} is not in this clone`);
+  if (!head) return red(`the head commit ${String(headCommit).slice(0, 12)} is not in this clone`);
+  let mergeBase;
+  try { mergeBase = gitRun(git, ['merge-base', '--end-of-options', base, head]).toString('utf8').trim(); } catch { return red('the base and the head share no commit in this clone'); }
+  const top = trees ?? mkdtempSync(join(tmpdir(), 'atlas-gate-'));
+  const baseRoot = join(top, GATE_TREES.base);
+  const headRoot = join(top, GATE_TREES.head);
+  try {
+    let baseEntries;
+    let headEntries;
+    try {
+      baseEntries = writeTree({ git, commit: mergeBase, dest: baseRoot });
+      headEntries = writeTree({ git, commit: head, dest: headRoot });
+    } catch (error) {
+      if (error instanceof TreeError) return red(`a tree could not be written: ${error.message}`);
+      throw error;
+    }
+    mkdirSync(baseRoot, { recursive: true });
+    mkdirSync(headRoot, { recursive: true });
+    const report = scan({ root: headRoot, repoId, secretPatterns: patterns });
+    const state = noLoss({ headRoot, baseRoot, baseCommit: mergeBase, repoId, secretPatterns: patterns });
+    // A link or a submodule that the head adds or changes is never read, so the
+    // check cannot judge it. The owner reads it.
+    const had = new Map([...baseEntries.links, ...baseEntries.modules].map((entry) => [entry.path, entry.id]));
+    for (const entry of [...headEntries.links, ...headEntries.modules]) {
+      if (had.get(entry.path) !== entry.id) state.owner.push({ case: 'link', why: `${entry.path} is a link or a submodule that this pull request adds or changes; the check never follows one`, path: entry.path });
+    }
+    return { report, state, merge_base: mergeBase, head };
+  } finally {
+    if (!trees) rmSync(top, { recursive: true, force: true });
+  }
+}
+
+// Gate mode. The job summary holds the full report and the answer. The output
+// file gets two keys only, each one word of a fixed set, so no path can add a
+// key. Exit 0 on success, 1 on owner or red.
+function runGate({ options, env }) {
+  const { report, state } = gateFromGit({ git: options.git, baseCommit: options.baseCommit, headCommit: options.headCommit, repoId: options.repo ?? env.GITHUB_REPOSITORY ?? null });
+  const answer = gateAnswer(report, state);
+  // Only the answer lines leave this process. Each one has a fixed prefix and
+  // no control character or backtick, so a head string cannot start a
+  // workflow command or close the fence of the summary (security review of
+  // R7). The full report stays in the JSON file, for a run by hand.
+  const lines = gateLines(answer, state).map((line) => line.replaceAll('`', "'"));
+  if (options.json) writeFileSync(options.json, `${JSON.stringify({ ...report, noLoss: state, gate: answer }, null, 2)}\n`);
+  const summary = `## Atlas repo shape, from the base\n\n${['```text', ...lines, '```'].join('\n')}\n`;
+  if (options.summary) writeFileSync(options.summary, summary);
+  if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, summary);
+  if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `result=${answer.result}\nclass=${answer.class ?? 'none'}\n`);
+  const decision = { green: answer.result === 'success', why: lines.at(-1) };
+  return { report, decision, text: `${lines.join('\n')}\n`, lines, options, answer, gate: true };
+}
+
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     // --version is parsed like every other flag, so an unknown flag beside it
@@ -1878,9 +2161,10 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
     if (asked.version) {
       process.stdout.write(`atlas repo-shape check, check version ${CHECK_VERSION}; it reads spec ${Object.keys(SPECS).join(', ')}\n`);
     } else {
-      const { decision, text, options } = run(process.argv.slice(2));
-      if (!options.quiet) process.stdout.write(text);
-      process.stdout.write(`${decision.green ? 'GREEN' : 'RED'}: ${decision.why}\n`);
+      const { decision, text, options, gate } = run(process.argv.slice(2));
+      if (!options.quiet || gate) process.stdout.write(text);
+      // In gate mode the last line of the text already says SUCCESS, OWNER or RED.
+      if (!gate) process.stdout.write(`${decision.green ? 'GREEN' : 'RED'}: ${decision.why}\n`);
       process.exitCode = decision.green ? 0 : 1;
     }
   } catch (error) {

package/shape/releases.json

@@ -30,6 +30,11 @@
       "sha256": "8f36633fe693ebf7a7cc0f7237d49eb4720f67d371d4758d556bab51965ec334",
       "first_package": "0.3.48",
       "workflow_sha256": "b69efaac2a3e52368ae5e7d7a33e1c88c6c7a7efa6fc1846844f79f9432ecd7d"
+    },
+    {
+      "check_version": 6,
+      "sha256": "bad1d05853e173c034971282c5762a1628dfd9f198c8276178bd17280afdf6e7",
+      "workflow_sha256": "fcddebef030e6564f97e1a5fb81c8ad1b3084ebef9622167c6565698312dcdd7"
     }
   ]
 }