@arjunkhera/atlas 0.3.46 → 0.3.49

package/door/lib/passes-after.mjs

@@ -0,0 +1,212 @@
+// `atlas tests after`: the base version of each changed, renamed or removed test case runs on the
+// head code (roadmap R73, tracker item 29e1f17d; design docs/design-docs/passes-after/).
+//
+// It reads the changed-test list (changed-tests.mjs) and takes each unit test file that the pull
+// request changes, renames or removes. It makes a tree of the head, puts in the base copy of each
+// such file and the base copy of the test helpers, runner configs and kit manifests, and runs the
+// old file there. So the old tests judge the new code.
+//
+//   the old case on the new code   the case in the PR   result
+//   pass                           changed or renamed   cleared
+//   any other                      changed or renamed   owner: changed test   (red)
+//   pass                           removed              removed, passes      (for the review job)
+//   any other                      removed              owner: removed test  (red)
+//   did not run or skipped         any                  not run              (not cleared)
+//
+// The command takes no card and no model verdict, so neither can clear a case. It runs head code
+// with the environment, the tree and the runners of fails-before, and it holds no secret.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { listChanged } from './changed-tests.mjs';
+import { casesOf, commandOf, freshTree, gitTree, readReport, runEnv, runnerOf } from './fails-before.mjs';
+
+export const VERSION = 1;
+
+const TEST_GROUPS = new Set(['unit-test', 'check-block', 'scenario-words', 'test-helper', 'runner-config', 'test-script', 'kit-manifest']);
+const SUPPORT = new Set(['test-helper', 'runner-config', 'kit-manifest']);
+const isProduct = (path) => !/^(docs|archive)\//.test(path) && !/^[^/]+\.md$/i.test(path);
+export const OWNER_RESULTS = Object.freeze(['owner: changed test', 'owner: removed test']);
+
+function git(cwd, args, { allowFail = false, buffer = false } = {}) {
+  const r = spawnSync('git', args, { cwd, encoding: buffer ? 'buffer' : 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.error) throw new Error(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) {
+    if (allowFail) return null;
+    throw new Error(`git ${args.join(' ')} failed: ${String(r.stderr || r.stdout || '').trim().split('\n')[0]}`);
+  }
+  return r.stdout;
+}
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+
+// The text of a case with its own name taken out, so a case renamed with the same body matches.
+const unnamed = (text, name) => text.split(name).join('\u0000');
+
+// The old cases of one file that the head changed, renamed or removed.
+export function oldCases(before, after) {
+  if (before === null) return { all: true, picked: [] };
+  if (after === null || before.rest !== after.rest) {
+    return { all: true, picked: [...before.cases.keys()].map((name) => ({ name, change: after?.cases.has(name) ? 'changed' : 'removed', to: null })) };
+  }
+  const picked = [];
+  const taken = new Set();
+  for (const [name, text] of before.cases) {
+    if (after.cases.has(name)) {
+      if (after.cases.get(name) !== text) picked.push({ name, change: 'changed', to: null });
+      continue;
+    }
+    const to = [...after.cases].find(([n, t]) => !before.cases.has(n) && !taken.has(n) && unnamed(t, n) === unnamed(text, name))?.[0];
+    if (to) { taken.add(to); picked.push({ name, change: 'renamed', to }); } else picked.push({ name, change: 'removed', to: null });
+  }
+  return { all: false, picked };
+}
+
+// What to run: for each changed, renamed or removed unit test file, the base path and its old cases.
+export function plan({ root, base, head = 'HEAD', list = null }) {
+  if (!base && !list) throw usage('give the base: --base <ref>');
+  const top = git(resolve(root), ['rev-parse', '--show-toplevel']).trim();
+  const changed = list ? JSON.parse(readFileSync(resolve(list), 'utf8')) : listChanged({ root: top, base, head });
+  if (changed.changed_tests !== 1) throw new Error(`the changed-test list has version ${changed.changed_tests}; this command reads version 1`);
+  const show = (sha, path) => git(top, ['show', `${sha}:${path}`], { allowFail: true });
+  const files = [];
+  const plans = [];
+  for (const r of changed.rows.filter((x) => x.group === 'check-block' && x.status !== 'added')) {
+    const path = r.from ?? r.path;
+    if (!files.some((f) => f.path === path)) files.push({ path, runner: null, result: 'not run', why: 'a scenario test needs its environment; the planted-fault procedure covers it' });
+  }
+  for (const r of changed.rows.filter((x) => x.group === 'unit-test' && x.status !== 'added')) {
+    const path = r.from ?? r.path;
+    const runner = runnerOf(path);
+    const before = casesOf(show(changed.merge_base, path), path);
+    const after = r.status === 'removed' ? { cases: new Map(), rest: before?.rest ?? '', duplicates: new Set() } : casesOf(show(changed.head, r.path), r.path);
+    const { all, picked } = oldCases(before, after);
+    if (!picked.length && !all) continue;
+    if (!runner) { files.push({ path, runner: null, result: 'not run', why: 'no runner for this file yet' }); plans.push({ path, runner: null, picked, all }); continue; }
+    files.push({ path, runner, result: 'ran', why: null });
+    plans.push({ path, runner, picked, all, head: r.status === 'removed' ? null : r.path });
+  }
+  files.sort((x, y) => (x.path < y.path ? -1 : 1));
+  return {
+    top, changed, files, plans,
+    productChanged: changed.other_paths.some(isProduct),
+    testsChanged: changed.rows.some((x) => TEST_GROUPS.has(x.group)),
+  };
+}
+
+// Puts the base copy of a path into the tree.
+function putBase(top, tree, sha, path) {
+  const bytes = git(top, ['show', `${sha}:${path}`], { allowFail: true, buffer: true });
+  if (bytes === null) return;
+  mkdirSync(dirname(join(tree, path)), { recursive: true });
+  writeFileSync(join(tree, path), bytes);
+}
+
+// Runs the old version of each planned file on a tree of the head. Returns { tree, report, env, files }.
+export function runOld({ top, changed, plans, work = join(tmpdir(), 'atlas-after') }) {
+  const tree = join(work, 'repo');
+  const report = join(work, 'report', 'report.xml');
+  const env = runEnv(work);
+  const out = { tree, report, env, files: {} };
+  try {
+    for (const p of plans.filter((x) => x.runner)) {
+      // A fresh tree, home and report folder for each file, so no file of one run reaches the next.
+      freshTree(top, tree, changed.head);
+      for (const r of changed.rows.filter((x) => SUPPORT.has(x.group) && x.status !== 'added')) putBase(top, tree, changed.merge_base, r.from ?? r.path);
+      for (const r of changed.rows.filter((x) => x.group === 'unit-test' && x.status !== 'added')) {
+        // A renamed file runs at its old path only, so no case runs twice.
+        if (r.status === 'renamed') rmSync(join(tree, r.path), { force: true });
+        putBase(top, tree, changed.merge_base, r.from ?? r.path);
+      }
+      gitTree(tree);
+      for (const dir of ['home', 'tmp', 'report']) { rmSync(join(work, dir), { recursive: true, force: true }); mkdirSync(join(work, dir), { recursive: true }); }
+      const command = commandOf(p.runner, p.path, report);
+      if (p.runner === 'pytest' && spawnSync('python3', ['-B', '-c', 'import pytest'], { cwd: tree, env }).status !== 0) {
+        out.files[p.path] = { command, cases: null, why: 'pytest is not installed', none: true };
+        continue;
+      }
+      const r = spawnSync(command[0] === 'node' ? process.execPath : command[0], command.slice(1), { cwd: tree, env, encoding: 'utf8', timeout: 10 * 60 * 1000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 * 1024 });
+      let cases = null;
+      let why = null;
+      if (r.error) why = `the runner did not finish: ${r.error.message}`;
+      else if (!existsSync(report)) why = `the runner wrote no report (exit ${r.status})`;
+      else {
+        try { cases = Object.fromEntries(readReport(readFileSync(report, 'utf8'))); } catch (error) { why = `the report does not read: ${error.message}`; }
+      }
+      out.files[p.path] = { command, cases, why };
+    }
+  } finally {
+    rmSync(tree, { recursive: true, force: true });
+  }
+  return out;
+}
+
+export function resultOf(change, after) {
+  if (after === 'skipped' || after === null) return 'not run';
+  if (change === 'removed') return after === 'pass' ? 'removed, passes' : 'owner: removed test';
+  return after === 'pass' ? 'cleared' : 'owner: changed test';
+}
+
+// The answer, from the plan and the run.
+export function answerOf(prepared, run) {
+  const { changed, files, plans, productChanged, testsChanged } = prepared;
+  const answer = { passes_after: VERSION, base: changed.base, merge_base: changed.merge_base, head: changed.head, product_changed: productChanged, tests_changed: testsChanged, red: false, owner_count: 0, files: files.map((f) => ({ ...f })), cases: [], env: run?.env ?? null };
+  for (const p of plans) {
+    const ran = run?.files[p.path];
+    const file = answer.files.find((f) => f.path === p.path);
+    if (ran?.none) Object.assign(file, { result: 'not run', why: ran.why });
+    else if (ran?.why) file.why = ran.why;
+    const results = ran && !ran.none ? (ran.cases ?? {}) : null;
+    const picked = [...p.picked];
+    // A file that cannot be read to the end: every case of its report counts as changed.
+    if (p.all && results) for (const name of Object.keys(results)) if (!picked.some((c) => c.name === name)) picked.push({ name, change: 'changed', to: null });
+    if (!picked.length) {
+      answer.cases.push({ path: p.path, name: null, change: 'changed', to: null, after: results ? 'missing' : null, result: results ? 'owner: changed test' : 'not run' });
+      continue;
+    }
+    for (const c of picked) {
+      const after = results ? (results[c.name] ?? 'missing') : null;
+      answer.cases.push({ path: p.path, name: c.name, change: c.change, to: c.to, after, result: resultOf(c.change, after) });
+    }
+  }
+  answer.cases.sort((x, y) => (x.path === y.path ? String(x.name).localeCompare(String(y.name)) : x.path < y.path ? -1 : 1));
+  answer.owner_count = answer.cases.filter((c) => OWNER_RESULTS.includes(c.result)).length;
+  answer.red = answer.owner_count > 0;
+  return answer;
+}
+
+export function passesAfter({ root, base, head = 'HEAD', list = null, work = join(tmpdir(), 'atlas-after') }) {
+  const prepared = plan({ root, base, head, list });
+  return answerOf(prepared, prepared.plans.length ? runOld({ ...prepared, work }) : null);
+}
+
+// ---------------------------------------------------------------- the command
+
+const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+
+export function renderText(a) {
+  const ran = a.files.filter((f) => f.result === 'ran').length;
+  const out = [`passes-after against ${oneLine(a.base)} (merge base ${a.merge_base.slice(0, 7)}): ${a.cases.length} old case(s) in ${ran} file(s); ${a.owner_count} for the owner; tests changed: ${a.tests_changed ? 'yes' : 'no'}`];
+  for (const c of a.cases) out.push(`  ${c.result.padEnd(20)} ${oneLine(c.path)}  ${oneLine(c.name ?? '(the whole file)')}${c.to ? `  (renamed to: ${oneLine(c.to)})` : ''}`);
+  for (const f of a.files.filter((x) => x.result === 'not run')) out.push(`  ${'not run'.padEnd(20)} ${oneLine(f.path)}  ${oneLine(f.why)}`);
+  for (const f of a.files.filter((x) => x.result === 'ran' && x.why)) out.push(`  ${'note'.padEnd(20)} ${oneLine(f.path)}  ${oneLine(f.why)}`);
+  if (a.red) out.push(`RED: ${a.owner_count} case(s) for the owner. Only the owner clears a changed test that fails on the new code.`);
+  else if (!a.tests_changed) out.push('GREEN: the pull request changes no test.');
+  else if (a.cases.some((c) => c.result === 'not run')) out.push(`GREEN with gaps: ${a.cases.filter((c) => c.result === 'not run').length} old case(s) did not run, so they are not cleared.`);
+  else out.push('GREEN: each old case that the pull request changed still passes on the new code.');
+  return out;
+}
+
+export function afterCommand({ base, head, list, out, text = false }, root, line) {
+  try {
+    const answer = passesAfter({ root, base, head: head ?? 'HEAD', list });
+    const json = `${JSON.stringify(answer, null, 2)}\n`;
+    if (out) writeFileSync(resolve(out), json);
+    else if (!text) process.stdout.write(json);
+    if (text) for (const l of renderText(answer)) line(l);
+    return answer.red ? 1 : 0;
+  } catch (error) {
+    line(`after: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/pull-request.mjs

@@ -21,8 +21,9 @@ export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'ta
 // The one label every tooling pull request carries. A person filters on it.
 export const TOOLING_LABEL = 'atlas-helper';
 
-// The only two files the tooling writer may write.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH]);
+// 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/pull_request_template.md']);
 
 export class ChangeError extends Error {}
 

package/door/lib/tooling.mjs

@@ -20,8 +20,19 @@ import { dirname, join } from 'node:path';
 import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, 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 };
+export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+
+// The pull request template (roadmap R8). The writer puts it into a repo that
+// has none, and never replaces a template the repo keeps.
+export const PACKAGE_TEMPLATE_SOURCE = 'door/templates/pull_request_template.md';
+// A package with no template file writes none.
+const packagedTemplate = (packageRoot) => {
+  const full = join(packageRoot, PACKAGE_TEMPLATE_SOURCE);
+  return existsSync(full) ? readFileSync(full, 'utf8') : null;
+};
+const templateMissing = (root, packageRoot) => packagedTemplate(packageRoot) !== null && !existsSync(join(root, PR_TEMPLATE_PATH));
 
 export class ToolingRefusal extends Error {
   constructor(message, { current = false } = {}) { super(message); this.current = current; }
@@ -64,7 +75,7 @@ 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) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(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 === 'unknown' && !replaceUnknown && !own) {
@@ -90,22 +101,33 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
-  if (!dryRun && rows.every((row) => row.state === 'unchanged')) {
-    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to write.', { current: true });
+  const template = workflowOnly ? null : packagedTemplate(packageRoot);
+  if (template !== null) {
+    const contents = template;
+    const full = join(root, PR_TEMPLATE_PATH);
+    const kept = existsSync(full);
+    if (!kept && !dryRun) {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    rows.push({ path: PR_TEMPLATE_PATH, state: kept ? 'kept' : 'written', sha256: sha256(kept ? readFileSync(full, 'utf8') : contents), was: kept ? sha256(readFileSync(full, 'utf8')) : null });
+  }
+  if (!dryRun && rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
+    throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to write.', { current: true });
   }
-  return { rows, version: packagePackageVersion(packageRoot), check_version: CHECK_VERSION, status: before?.state ?? null, changed: rows.some((row) => row.state !== 'unchanged') };
+  return { rows, version: packagePackageVersion(packageRoot), check_version: CHECK_VERSION, status: before?.state ?? null, changed: rows.some((row) => row.state !== 'unchanged' && row.state !== 'kept') };
 }
 
 // The change set the pull request machinery takes, for the two files above.
 export function changes(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
   mayWrite(root, packageRoot, { replaceUnknown, workflowOnly });
   const { rows, version } = write(root, packageRoot, { dryRun: true, workflowOnly });
-  if (rows.every((row) => row.state === 'unchanged')) {
-    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to open.', { current: true });
+  if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
+    throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = packagedFiles(packageRoot);
+  const wanted = { ...packagedFiles(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
-    .filter((row) => row.state !== 'unchanged')
+    .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => ({
       path: row.path,
       contents: wanted[row.path],
@@ -113,7 +135,9 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
         source: 'repo read',
         detail: row.path === CHECK_PATH
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
-          : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
+          : row.path === PR_TEMPLATE_PATH
+            ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
+            : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));
 }

package/door/lib/upkeep.mjs

@@ -119,21 +119,57 @@ const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i
 const SHORT = /\bitems?\b[\s:#`(_-]*(?:id[\s:#`_-]*)?([0-9a-f]{8})\b/i;
 const NO_ITEM = /\bno item:\s*(\S[^\n]*)/i;
 
+// The six headings of the pull request text (roadmap R8, design
+// docs/design-docs/pr-template/). The template in door/templates/ holds them,
+// and a test keeps the two equal. A later job reads the text under each one.
+export const PR_HEADINGS = Object.freeze(['Definition of done', 'Kind of change', 'Undo', 'Behaviour change', 'Changed tests', 'Proof']);
+export const PR_TEMPLATE_PATH = '.github/pull_request_template.md';
+
+// A pull request text without its HTML comments. The template's own comment
+// says "no item:", so the item rule and the heading rule never read a comment.
+const withoutComments = (text) => String(text ?? '').replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+
+// The sections of a pull request text: each `## ` heading and the text under it.
+export function prSections(body) {
+  const sections = new Map();
+  let current = null;
+  for (const line of withoutComments(body).split('\n')) {
+    const heading = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+    if (heading) { current = heading[1].toLowerCase(); sections.set(current, []); continue; }
+    if (current) sections.get(current).push(line);
+  }
+  return new Map([...sections].map(([name, lines]) => [name, lines.join('\n').trim()]));
+}
+
+// The findings of the text of a pull request that names an item.
+export function prTextFindings(body) {
+  const sections = prSections(body);
+  const findings = [];
+  for (const heading of PR_HEADINGS) {
+    if (!sections.has(heading.toLowerCase())) findings.push(`pr text: missing heading "${heading}"`);
+  }
+  const done = sections.get('definition of done');
+  if (done !== undefined && !/^[ \t]*\d+[.)][ \t]+\S/m.test(done)) findings.push('pr text: "Definition of done" has no numbered line');
+  const behaviour = sections.get('behaviour change');
+  if (behaviour !== undefined && !/\b(yes|no)\b/i.test(behaviour)) findings.push('pr text: "Behaviour change" says neither yes nor no');
+  return findings;
+}
+
 // Does the pull request name its tracker item? Read from a GitHub event file.
 export function itemNamed(event) {
   const pr = event?.pull_request;
   if (!pr) return { checked: false };
-  if (pr.user?.type === 'Bot') return { checked: true, ok: true, how: `opened by a bot (${pr.user.login})` };
-  const texts = [pr.title, pr.body, pr.head?.ref].map((one) => String(one ?? ''));
+  if (pr.user?.type === 'Bot') return { checked: true, ok: true, how: `opened by a bot (${pr.user.login})`, named: false };
+  const texts = [pr.title, withoutComments(pr.body), pr.head?.ref].map((one) => String(one ?? ''));
   for (const text of texts) {
     const full = text.match(UUID);
-    if (full) return { checked: true, ok: true, how: `names item ${full[0]}` };
+    if (full) return { checked: true, ok: true, how: `names item ${full[0]}`, named: true };
     const short = text.match(SHORT);
-    if (short) return { checked: true, ok: true, how: `names item ${short[1]}` };
+    if (short) return { checked: true, ok: true, how: `names item ${short[1]}`, named: true };
   }
   for (const text of texts) {
     const none = text.match(NO_ITEM);
-    if (none) return { checked: true, ok: true, how: `no item: ${none[1].trim()}` };
+    if (none) return { checked: true, ok: true, how: `no item: ${none[1].trim()}`, named: false };
   }
   return { checked: true, ok: false };
 }
@@ -149,7 +185,11 @@ export function upkeepCheck(root, { event = null } = {}) {
   for (const one of dead.slice(0, MAX_LISTED)) findings.push(`dead link: ${one.file}:${one.line} -> ${one.target}`);
   if (dead.length > MAX_LISTED) findings.push(`dead link: ${dead.length - MAX_LISTED} more`);
   if (item.checked && !item.ok) findings.push('item: the pull request names no tracker item. Put the item id in the title, the body or the branch, or write "no item:" and a reason');
-  return { green: findings.length === 0, findings, index, dead, item };
+  // The heading check holds a pull request that names an item, in a repo that
+  // keeps the Atlas template. A repo without the template is not held yet.
+  const text = { checked: Boolean(item.named) && existsSync(join(root, PR_TEMPLATE_PATH)) };
+  if (text.checked) findings.push(...prTextFindings(event.pull_request.body));
+  return { green: findings.length === 0, findings, index, dead, item, text };
 }
 
 export function upkeepCommand({ what, event: eventFile, json = false }, root, line) {
@@ -163,6 +203,7 @@ export function upkeepCommand({ what, event: eventFile, json = false }, root, li
   line(`docs index: ${result.index.checked ? `${result.index.unlisted.length} not listed, ${result.index.gone.length} gone` : 'no docs/ folder'}`);
   line(`dead links: ${result.dead.length}`);
   line(`item: ${!result.item.checked ? 'not a pull request' : result.item.ok ? result.item.how : 'none named'}`);
+  line(`pr text: ${result.text.checked ? 'the six headings were read' : 'not checked'}`);
   for (const finding of result.findings) line(`  - ${finding}`);
   line(`upkeep check: ${result.green ? 'GREEN' : 'RED'}`);
   return result.green ? 0 : 1;

package/door/templates/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- The Atlas pull request text. Name the tracker item in the title, this text or the branch, or write "no item:" and a reason. When the text names an item, `atlas upkeep check` needs each heading below. -->
+
+## Definition of done
+
+1. 
+
+## Kind of change
+
+
+
+## Undo
+
+
+
+## Behaviour change
+
+No.
+
+## Changed tests
+
+None.
+
+## Proof
+
+

package/owner-only.yaml

@@ -0,0 +1,238 @@
+# The owner-only list: the kinds of change that always come to the owner.
+#
+# The owner picked these eight classes on 24 October 2026 (decision 1c2f0d53,
+# item 94b2e2ff). Design: docs/design-docs/owner-only-list/ in the Atlas repo.
+#
+# Each class has two examples and its net. `code` means the reader in
+# door/lib/owner-only.mjs matches it on a diff. `review` means the review job
+# reads for it. A code class lists its signs: exact things that the reader
+# matches.
+#
+# The floor below holds in every repo, whatever the repo's own `owner_only:`
+# list says. The reader takes the floor from this package and the repo list
+# from the base commit, so a pull request cannot take itself off either one.
+#
+# Sign types:
+#   path          a changed path that matches one of `paths`
+#   added_line    an added line, in a file of `paths`, that matches `pattern`
+#   secret        an added line that matches a secret pattern of shape/check.mjs
+#   json_keys     a change to one of `keys` of a JSON file of `paths`
+#   surface       a line that `line` matches, keyed by its first group, is gone
+#                 at the head, or lost a part that `part` matches
+#   schema        a JSON file of `paths` lost a key, lost an enum value, or
+#                 gained a required field; versioned files compare newest to newest
+#   any_change    any change to a file of `paths`
+#
+# A code class with no signs says where its code net comes from instead:
+# `signs_from: repo` (each repo's `owner_only:` list) or `signs_from: floor`.
+#
+# Paths match on whole folder names and with no case. `**/` matches any depth.
+# A path that ends in `/` is a folder.
+
+classes:
+  - id: money
+    name: Money
+    examples:
+      - A new paid plan, or a change to a price.
+      - A cloud resource that bills by the hour.
+    net:
+      - review
+
+  - id: credentials
+    name: Credentials and keys
+    examples:
+      - A new API key, or a key written into a file.
+      - A change to the list of credentials that a repo names.
+    net:
+      - code
+      - review
+    signs:
+      - id: secret-value
+        type: secret
+      - id: credential-files
+        type: path
+        paths:
+          - "atlas/credentials.yaml"
+          - "**/.env"
+          - "**/.env.*"
+          - "**/*.pem"
+          - "**/*.key"
+
+  - id: outside-visibility
+    name: Outside visibility
+    examples:
+      - A public repo, or a public post.
+      - A release that removes a command that other people use.
+    net:
+      - code
+      - review
+    signs:
+      - id: release-surface
+        type: json_keys
+        paths:
+          - "**/package.json"
+        keys:
+          - name
+          - private
+          - publishConfig
+          - files
+          - bin
+          - main
+          - exports
+          - scripts
+      - id: removed-command-or-switch
+        type: surface
+        paths:
+          - "packages/atlas/door/cli.mjs"
+        line: "^  '?([a-z][a-z-]*)'?: \\{.*\\},?\\s*$"
+        part: "'?([a-z][a-z-]*)'?: '(?:switch|value|optional)'"
+      - id: removed-mcp-tool
+        type: surface
+        paths:
+          - "packages/atlas/work/mcp.mjs"
+        line: "^\\s*\\{ name: '([a-z_]+)'"
+      - id: kit-manifest
+        type: any_change
+        # A release moves only the "atlas" version line. That is not a sign.
+        version_key: atlas
+        paths:
+          - "**/test/atlas/manifest.json"
+          - "packages/atlas/tests/link-check.mjs"
+      - id: narrowed-schema
+        type: schema
+        paths:
+          - "packages/atlas/work/manifest-*.json"
+
+  - id: lost-data
+    name: Data that cannot be undone
+    examples:
+      - A migration that drops a table.
+      - A script that deletes rows from a live store.
+    net:
+      - code
+      - review
+    signs:
+      - id: drop-or-delete-in-migration
+        type: added_line
+        paths:
+          - "**/migrations/**"
+          - "**/migrate/**"
+          - "**/*.sql"
+        pattern: "(?i)\\b(drop|delete|truncate)\\b|\\b(drop|truncate)[A-Z_]"
+
+  - id: security
+    name: Security code
+    examples:
+      - The code that checks who may sign in.
+      - The code that keeps one tenant's rows from another.
+    net:
+      - code
+      - review
+    # No path holds sign-in code in every repo, so each repo lists its own
+    # security paths under `owner_only:` in atlas.yaml.
+    signs_from: repo
+
+  - id: new-service
+    name: A new outside service or a new repo
+    examples:
+      - A call to a new outside API.
+      - A new repo, or a new GitHub App.
+    net:
+      - review
+
+  - id: rule-book
+    name: The rule book
+    examples:
+      - An entry file, a path rule or a hook.
+      - The owner-only list itself.
+    net:
+      - code
+      - review
+    # The floor below is the code net of this class, with each repo's own list.
+    signs_from: floor
+
+  - id: direction
+    name: Direction
+    examples:
+      - What to build next.
+      - A goal of a product, or a change to a locked design.
+    net:
+      - review
+
+# The floor: rule-book paths in every repo. Each entry is class rule-book.
+# `follow` means the reader also reads the file for names: each file that it
+# names with an @ import, a Markdown link or a path in backticks joins the
+# floor, and the reader follows names out of that file in turn. A plugin
+# root's skills, agents, hooks and commands are followed the same way.
+# `version_only_exempt` lets a change to the version alone pass, because the
+# owner took Atlas's own releases off the list.
+floor:
+  - path: "**/CLAUDE.md"
+    rule: entry file
+    follow: true
+  - path: "**/CLAUDE.local.md"
+    rule: entry file
+    follow: true
+  - path: "**/AGENTS.md"
+    rule: entry file
+    follow: true
+  - path: "**/.claude/"
+    rule: .claude at any depth
+    follow: true
+  - path: "**/.claude-plugin/"
+    rule: .claude-plugin at any depth
+  - path: ".mcp.json"
+    rule: root MCP servers
+  - path: ".github/actions/"
+    rule: CI actions
+  - path: ".github/workflows/"
+    rule: CI workflows
+  - path: ".github/atlas/"
+    rule: the Atlas check copy
+  - path: "atlas.yaml"
+    rule: atlas.yaml keys
+  - path: "atlas/"
+    rule: repo facts
+  - path: "**/.gitattributes"
+    rule: git attributes
+  - path: ".gitmodules"
+    rule: submodules
+  - path: "**/.github/CODEOWNERS"
+    rule: code owners
+  - path: "docs/intake/"
+    rule: the owner's words
+  - path: "archive/"
+    rule: archive
+  - path: "packages/atlas/owner-only.yaml"
+    rule: the owner-only list
+  - path: "packages/atlas/door/lib/owner-only.mjs"
+    rule: the owner-only reader
+  - path: "packages/atlas/package.json"
+    rule: the package manifest
+    version_only_exempt: true
+  - path: "packages/atlas/.claude-plugin/plugin.json"
+    rule: the plugin manifest
+    version_only_exempt: true
+
+# The entry map. A doc that only it names is not on the floor, and the reader
+# does not follow names out of it (shape/check.mjs, the exemption).
+entry_map: docs/index.md
+
+# The keys of atlas.yaml whose change is always owner-only. A change to any
+# other key is owner-only too, until roadmap R62 lists the safe ones. The one
+# change that passes is an addition under `parts:`.
+atlas_yaml:
+  add_only:
+    - parts
+  fixed:
+    - owner_only
+    - areas
+    - required_checks
+    - product
+    - product_paths
+    - repo
+    - kind
+    - kinds
+    - up_to_date
+    - brake
+    - spec