@arjunkhera/atlas 0.4.15 → 0.4.17

package/shape/check.mjs

@@ -7,21 +7,25 @@
 // 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
-// required parts that are not filled.
+// What it reports: one state per part of the six files. Four states: filled,
+// empty, stale, not applicable. It leads with the count of required parts
+// that are not filled.
 //
 // It carries the version of the Atlas package it came from, so a copy in a
 // repo says where it came from. It refuses a spec version it cannot read.
 //
 // 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 = 7;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -49,8 +53,7 @@ export const SPEC_1 = {
     "filled": "The part exists and matches the repo.",
     "empty": "The part is missing, or it holds nothing.",
     "stale": "The part exists but disagrees with the repo.",
-    "not applicable": "This repo kind does not need the part.",
-    "no extractor": "The part is generated, and no extractor exists for it yet."
+    "not applicable": "This repo kind does not need the part."
   },
   "kinds": {
     "service": "A running product with a deploy target, logs and metrics.",
@@ -316,109 +319,17 @@ export const SPEC_1 = {
         }
       ]
     },
-    {
-      "id": "docs-content",
-      "number": 6,
-      "title": "Docs content",
-      "class": "docs",
-      "written_by": "the upkeep task and the talk-through; merges on its own",
-      "parts": [
-        {
-          "id": "pages",
-          "path": "docs/site",
-          "glob": "*.md",
-          "holds": "The pages: home, features, flows with their step lists, concepts. Each page carries the commit it was built from.",
-          "kind": {
-            "service": "required",
-            "library": "optional",
-            "schema": "optional",
-            "plugin": "optional",
-            "cli": "optional"
-          },
-          "check": "docs-pages"
-        },
-        {
-          "id": "features",
-          "path": "docs/site/features.yaml",
-          "holds": "The feature list the renderer reads.",
-          "kind": {
-            "service": "required",
-            "library": "optional",
-            "schema": "optional",
-            "plugin": "optional",
-            "cli": "optional"
-          },
-          "check": "features"
-        },
-        {
-          "id": "notes",
-          "path": "docs/site/notes.md",
-          "class": "instruction",
-          "holds": "The standing corrections. Each note names who said it and the session. A person merges it.",
-          "kind": {
-            "service": "optional",
-            "library": "optional",
-            "schema": "optional",
-            "plugin": "optional",
-            "cli": "optional"
-          },
-          "check": "notes"
-        },
-        {
-          "id": "api",
-          "path": "docs/site/reference/api.md",
-          "holds": "Every route with its method, path, principal, handler file and line.",
-          "kind": {
-            "service": "required",
-            "library": "not applicable",
-            "schema": "not applicable",
-            "plugin": "not applicable",
-            "cli": "not applicable"
-          },
-          "check": "generated",
-          "extractor": "routes"
-        },
-        {
-          "id": "database",
-          "path": "docs/site/reference/database.md",
-          "holds": "The tables, their fields, their types and the purpose of each field.",
-          "kind": {
-            "service": "required",
-            "library": "not applicable",
-            "schema": "required",
-            "plugin": "not applicable",
-            "cli": "not applicable"
-          },
-          "check": "generated",
-          "extractor": "migrations"
-        },
-        {
-          "id": "mcp-tools",
-          "path": "docs/site/reference/mcp-tools.md",
-          "holds": "Every MCP tool, its inputs, and when to use it.",
-          "kind": {
-            "service": "optional",
-            "library": "optional",
-            "schema": "optional",
-            "plugin": "optional",
-            "cli": "optional"
-          },
-          "check": "generated",
-          "extractor": "mcp"
-        }
-      ]
-    },
     {
       "id": "tooling",
-      "number": 7,
+      "number": 6,
       "title": "Tooling",
       "class": "instruction",
       "written_by": "the helper; a person merges",
       "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",
@@ -463,11 +374,6 @@ export const SPEC_1 = {
       ]
     }
   ],
-  "extractors": {
-    "routes": "Slice L3 builds it.",
-    "migrations": "Slice L3 builds it.",
-    "mcp": "Slice L3 builds it."
-  },
   "by_reference": {
     "rule": "A file under docs/ that an instruction file points at is instruction class by reference (D7 finding R1). The check computes that set and reports each member.",
     "scanned": [
@@ -476,8 +382,7 @@ export const SPEC_1 = {
       ".claude/rules/*.md",
       ".claude/skills/*/SKILL.md",
       "atlas.yaml",
-      "atlas/*.yaml",
-      "docs/site/notes.md"
+      "atlas/*.yaml"
     ]
   }
 };
@@ -494,7 +399,7 @@ function deepFreeze(value) {
 }
 deepFreeze(SPEC_1);
 
-// Spec 2 adds one part: the check file itself, scored inside file 7.
+// Spec 2 adds one part: the check file itself, scored inside file 6.
 //
 // Why a new version and not a line in spec 1. Adding a scored part changes what
 // `spec: 1` means, and the spec version is the whole coupling between a
@@ -502,8 +407,9 @@ deepFreeze(SPEC_1);
 // P11). The check reads both versions, so a repository stays green while it is
 // still on spec 1, and it opts in by moving `atlas.yaml` to `spec: 2`.
 //
-// Nothing else moves. Spec 1 keeps its twenty-two parts, and spec 2 has
-// twenty-three.
+// Nothing else moves. Spec 1 keeps its sixteen parts, and spec 2 has
+// seventeen. Check version 7 took the six parts of the retired docs site out
+// of both (roadmap R37).
 //
 // Check version 4 adds two kinds, plugin and cli, to both specs (issue #141).
 // No cell of an older kind moves, so a repo that names service, library or
@@ -640,64 +546,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
@@ -890,8 +867,8 @@ export function frontMatter(source) {
 // The scanners. One per part of the spec.
 // ---------------------------------------------------------------------------
 
-export const STATES = Object.freeze(['filled', 'empty', 'stale', 'not applicable', 'no extractor']);
-export const NOT_FILLED = Object.freeze(['empty', 'stale', 'no extractor']);
+export const STATES = Object.freeze(['filled', 'empty', 'stale', 'not applicable']);
+export const NOT_FILLED = Object.freeze(['empty', 'stale']);
 export const CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]*$/;
 const PINNED = /^[0-9a-f]{40}$/;
 const MAX_LISTED = 12;
@@ -932,10 +909,10 @@ function symlinks(root, path, out = []) {
 
 // A symbolic link is a finding, never a state on its own: the part it sits
 // under says what state it makes.
-function symlinkFindings(root, path, keep = () => true) {
-  const found = symlinks(root, path).filter(keep);
+function symlinkFindings(root, path) {
+  const found = symlinks(root, path);
   return found.length
-    ? [`${found.length} symbolic link(s) under ${path}/: ${found.slice(0, MAX_LISTED).join(', ')}; the check does not follow one, and a renderer that does would publish what it points at`]
+    ? [`${found.length} symbolic link(s) under ${path}/: ${found.slice(0, MAX_LISTED).join(', ')}; the check does not follow one`]
     : [];
 }
 
@@ -1013,21 +990,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
@@ -1130,59 +1115,16 @@ function checkDocsIndex(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 listed = new Set(pointers(text).map((path) => (path.startsWith('docs/') ? path : posix.join('docs', path))));
-  const onDisk = walk(context.root, 'docs').filter((path) => path.endsWith('.md') && path !== part.path && !path.startsWith('docs/site/'));
+  const onDisk = walk(context.root, 'docs').filter((path) => path.endsWith('.md') && path !== part.path);
   const unlisted = onDisk.filter((path) => !listed.has(path));
   const gone = [...listed].filter((path) => !existsSync(join(context.root, path)));
   const findings = [];
   if (unlisted.length) findings.push(`${unlisted.length} file(s) under docs/ are not listed: ${unlisted.slice(0, MAX_LISTED).join(', ')}`);
   if (gone.length) findings.push(`${gone.length} listed file(s) are gone: ${gone.slice(0, MAX_LISTED).join(', ')}`);
-  // The docs tree outside docs/site/. The pages part below owns docs/site/.
-  findings.push(...symlinkFindings(context.root, 'docs', (path) => !path.startsWith('docs/site/')));
+  findings.push(...symlinkFindings(context.root, 'docs'));
   return findings.length ? result(part, 'stale', findings) : result(part, 'filled', [`${onDisk.length} file(s) listed`]);
 }
 
-function checkDocsPages(context, part) {
-  const links = symlinkFindings(context.root, part.path);
-  if (!isDirectory(context.root, part.path)) return result(part, 'empty', [`${part.path}/ does not exist`]);
-  const pages = walk(context.root, part.path).filter((path) => path.endsWith('.md') && !path.endsWith('/notes.md'));
-  if (!pages.length) return result(part, links.length ? 'stale' : 'empty', [`${part.path}/ holds no page`, ...links]);
-  const without = pages.filter((path) => !frontMatter(readText(context.root, path) ?? '')?.built_from);
-  const findings = [...(without.length ? [`${without.length} page(s) do not name the commit they were built from: ${without.slice(0, MAX_LISTED).join(', ')}`] : []), ...links];
-  return findings.length ? result(part, 'stale', findings) : result(part, 'filled', [`${pages.length} page(s)`]);
-}
-
-function checkFeatures(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`]);
-  let data;
-  try { data = parseYaml(text); } catch (error) { return result(part, 'stale', [`${part.path} cannot be read: ${error.message}`]); }
-  const rows = data?.features;
-  if (emptyValue(rows)) return result(part, 'stale', [`${part.path} lists no feature`]);
-  const list = Array.isArray(rows) ? rows : Object.values(rows);
-  const dead = list.filter((row) => row?.page && !existsSync(join(context.root, String(row.page)))).map((row) => row.page);
-  return dead.length ? result(part, 'stale', [`${dead.length} feature page(s) are gone: ${dead.slice(0, MAX_LISTED).join(', ')}`]) : result(part, 'filled', [`${list.length} feature(s)`]);
-}
-
-function checkNotes(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`]);
-  // Finding R12 and the spec: each note names who said it and the session.
-  // A note that does not is a stale note, not a remark on a filled file.
-  const entries = text.split('\n').filter((line) => /^\s*[-*]\s+/.test(line));
-  if (!entries.length) return result(part, 'empty', [`${part.path} holds no note`]);
-  const without = entries.filter((line) => !/session/i.test(line));
-  if (without.length) return result(part, 'stale', [`${without.length} of ${entries.length} note(s) do not name the session they came from`]);
-  return result(part, 'filled', [`${entries.length} note(s)`]);
-}
-
-function checkGenerated(context, part) {
-  const available = context.extractors.includes(part.extractor);
-  if (!available) return result(part, 'no extractor', [`no ${part.extractor} extractor exists yet; slice L3 builds it`]);
-  const text = readText(context.root, part.path);
-  if (text === null || !text.trim()) return result(part, 'empty', [`${part.path} is missing or holds nothing`]);
-  return result(part, 'filled');
-}
-
 // Every permission the workflow grants at anything other than read. It reads a
 // block map under `permissions:` and a flow map on the same line.
 function writeGrants(text) {
@@ -1221,6 +1163,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 +1175,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 +1190,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 +1236,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 {
@@ -1372,10 +1318,6 @@ const CHECKS = {
   'facts-section': checkFactsSection,
   'facts-credentials': checkCredentials,
   'docs-index': checkDocsIndex,
-  'docs-pages': checkDocsPages,
-  features: checkFeatures,
-  notes: checkNotes,
-  generated: checkGenerated,
   workflow: checkWorkflow,
   'check-file': checkCheckFile,
   linters: checkLinters,
@@ -1383,7 +1325,7 @@ const CHECKS = {
 
 // The one exemption in the by-reference set, and it is exactly one.
 //
-// File 1, the entry map, must hold a pointer to each of the seven files, and
+// File 1, the entry map, must hold a pointer to each of the six files, and
 // `docs/index.md` is one of them. Rule R1 makes any `docs/` file an instruction
 // file points at instruction class by reference. Those two together make the
 // index instruction class, and the frozen L4 path limit lets the upkeep routine
@@ -1397,8 +1339,7 @@ const CHECKS = {
 // only this one path, only these two pointing files, and the row stays in the
 // report with `exempt: true` so nothing is hidden. Any other instruction file
 // that names the index still makes it instruction class, and the index's own
-// row then carries that file. The docs lint of slice L3 bounds the rest, by
-// treating the index as an agent-facing surface.
+// row then carries that file.
 export const EXEMPT_PATH = 'docs/index.md';
 export const EXEMPT_FROM = Object.freeze(['CLAUDE.md', 'AGENTS.md']);
 
@@ -1484,7 +1425,7 @@ export function readFacts(root) {
 // `kind: library` would be two different spec tables, and the comparison would
 // mean nothing (architect finding P2). Nothing else about the scan changes: the
 // tree still speaks for itself about every part.
-export function scan({ root, repoId = null, extractors = [], secretPatterns: patterns = secretPatterns(), scoreAs = null }) {
+export function scan({ root, repoId = null, secretPatterns: patterns = secretPatterns(), scoreAs = null }) {
   const { facts, error: factsError } = readFacts(root);
   const errors = [];
   // The credential-value check is the only thing that turns the job red at the
@@ -1511,7 +1452,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, 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).
@@ -1534,7 +1480,7 @@ export function scan({ root, repoId = null, extractors = [], secretPatterns: pat
 }
 
 export function counts(files) {
-  const out = { filled: 0, empty: 0, stale: 0, 'not applicable': 0, 'no extractor': 0, required: 0, optional: 0, not_filled: 0, required_not_filled: 0, optional_not_filled: 0 };
+  const out = { filled: 0, empty: 0, stale: 0, 'not applicable': 0, required: 0, optional: 0, not_filled: 0, required_not_filled: 0, optional_not_filled: 0 };
   for (const file of files) for (const part of file.parts) {
     out[part.state] += 1;
     if (part.required === 'required') out.required += 1;
@@ -1568,21 +1514,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 +1565,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 +1615,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,18 +1649,57 @@ 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.
 // ---------------------------------------------------------------------------
 
-const MARK = { filled: '+', empty: '-', stale: '~', 'not applicable': '.', 'no extractor': '?' };
+const MARK = { filled: '+', empty: '-', stale: '~', 'not applicable': '.' };
 const label = (part) => part.procedure ? `procedure ${part.procedure}` : part.path ?? part.id;
 
 // The one number the owner sees is the count of REQUIRED files not filled.
@@ -1748,23 +1747,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 +1797,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}` };
 }
 
@@ -1825,10 +1813,9 @@ export function verdict(report, failOn) {
 // ---------------------------------------------------------------------------
 
 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,24 +1829,35 @@ 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 });
+  const report = scan({ root: options.root, repoId, secretPatterns: patterns });
   // No `--base` means no pull request to measure: a push build, or a run by
   // 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 +1868,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 +2014,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) {