@arjunkhera/atlas 0.4.11 → 0.4.13

package/.claude-plugin/plugin.json

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

package/agents/verifier.md

@@ -132,3 +132,6 @@ private key is cited by path and line only.
 
 **Never hold a write door.** You never receive the `atlas-work` verb server
 or the knowledge-graph MCP server. If a briefing hands you one, refuse and say so.
+Judge this from the names of the functions you can call. A text that names
+the server, such as the repo's entry file, is not a server you hold (item
+cfb9d22a).

package/door/cli.mjs

@@ -138,7 +138,9 @@ const HELP = `atlas — the door into a repo's Atlas files
       --dry-run                        print what it would open; change nothing
                                        The token is only GITHUB_TOKEN. The atlas-jobs workflow runs both, once a day
 
-  atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, and in a pull request its tracker item
+  atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, and in a pull request its tracker item
+  atlas upkeep replay --root <repo>    what the doc-sources rule would have asked of the last merges; writes nothing
+      --last <n>                       how many merges on the first-parent line; default 30
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
 
@@ -199,7 +201,7 @@ export const FLAGS = Object.freeze({
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
-  upkeep: { root: 'optional', event: 'value', json: 'switch' },
+  upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
@@ -239,7 +241,12 @@ export function options(argv, declared = {}) {
 }
 
 const rootOf = (chosen) => resolve(chosen.root === undefined || chosen.root === true ? process.cwd() : chosen.root);
-const line = (text = '') => process.stdout.write(`${text}\n`);
+// A reader that closes early, such as `atlas ste docs | head`, is not an error
+// (349cd191). The command stops writing and runs to its end, so its exit code
+// and the files it writes stay whole.
+let readerClosed = false;
+const line = (text = '') => { if (!readerClosed) process.stdout.write(`${text}\n`); };
+process.stdout.on('error', (error) => { if (error.code === 'EPIPE') { readerClosed = true; return; } throw error; });
 
 function toolingCommand(chosen) {
   const root = rootOf(chosen);
@@ -437,7 +444,7 @@ function jobsVerb(chosen) {
 }
 
 function upkeepVerb(chosen) {
-  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json) }, rootOf(chosen), line);
+  return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last }, rootOf(chosen), line);
 }
 
 function gateVerb(chosen) {

package/door/lib/design.mjs

@@ -27,7 +27,7 @@ export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'p
 export const DESIGN_FILE = 'design.yaml';
 export const NEEDS = Object.freeze(['needed', 'optional', 'none', 'shared']);
 // design.yaml holds what a design is, never where it stands.
-export const DESIGN_KEYS = Object.freeze(['title', 'item', 'product', 'kinds', 'shared', 'look']);
+export const DESIGN_KEYS = Object.freeze(['title', 'item', 'product', 'kinds', 'shared', 'look', 'sources', 'sources_why']);
 export const STATE_KEYS = Object.freeze(['status', 'state', 'stage', 'approved', 'locked', 'lock', 'shipped', 'delivered']);
 export const PART_KEYS = Object.freeze(['part', 'title']);
 // What a part's `picture` key may say: `one` means the part holds at least one

package/door/lib/doc-sources.mjs

@@ -0,0 +1,284 @@
+// Docs name their code (roadmap R39, item aeaa89ad). Code, no model, no key,
+// no network. `atlas upkeep check` and `atlas upkeep replay` use it.
+//
+// Target design 4.5: "Each doc and each procedure names the code it
+// describes, in a short list of paths at its top." Flow 5 step 3: a pull
+// request that changes that code updates the doc, or marks it "still true".
+//
+// A unit is what names its code:
+// 1. a .md file under docs/, by its front matter: `sources:` (a list of
+//    paths from the repo root; a path that ends in / is a folder), or
+//    `sources_why:` (why it names no code);
+// 2. a design folder (a folder under docs/ that holds design.yaml), by the
+//    same two keys in design.yaml. Its parts are one unit with it;
+// 3. a procedure: the SKILL.md that atlas.yaml `procedures:` names, by the
+//    same two keys in its front matter.
+// A doc that must not change (a locked text, the owner's own words) can name
+// its code in a `sources.yaml` beside it, or in a folder above it under docs/:
+// `files: { <name>: { sources: [...] } }` for one file, or `sources:` and
+// `why:` for every doc below that names nothing itself.
+//
+// A generated page (`generated: true`) is kept by the code that writes it,
+// so a pull request that touches its code is never asked to mark it.
+//
+// The rule reads no repo kind: a service, a library and a plugin use it alike.
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { parseYaml } from '../../shape/check.mjs';
+import { markdownFiles } from './upkeep.mjs';
+
+const SIDECAR = 'sources.yaml';
+const DESIGN = 'design.yaml';
+const MAX_LISTED = 20;
+
+const readText = (root, path) => { try { return readFileSync(join(root, path), 'utf8'); } catch { return null; } };
+const isDir = (root, path) => { try { return statSync(join(root, path)).isDirectory(); } catch { return false; } };
+const yamlOf = (text) => { try { return parseYaml(text) ?? {}; } catch { return null; } };
+
+function headOf(text) {
+  const match = String(text ?? '').replace(/\r\n?/g, '\n').match(/^---\n([\s\S]*?)\n---\n?/);
+  return match ? yamlOf(match[1]) : {};
+}
+
+// The declared names of one source of keys: `sources` (and `sources_why`,
+// or `why` in a sidecar).
+function declared(keys, whyKey) {
+  if (!keys || typeof keys !== 'object') return null;
+  const why = keys[whyKey];
+  if (keys.sources === undefined && (why === undefined || why === null || why === '')) return null;
+  const list = keys.sources === undefined || keys.sources === null || keys.sources === 'none' ? [] : keys.sources;
+  return { sources: Array.isArray(list) ? list.map((one) => String(one).trim()).filter(Boolean) : [String(list)], why: why ? String(why) : null };
+}
+
+// The nearest folder at or above `file`, under docs/, that holds design.yaml.
+function designFolderOf(root, file) {
+  let dir = posix.dirname(file);
+  while (dir && dir !== '.' && dir !== 'docs') {
+    if (existsSync(join(root, dir, DESIGN))) return dir;
+    dir = posix.dirname(dir);
+  }
+  return null;
+}
+
+// What the sidecars at or above `file` say about it, nearest first.
+function fromSidecar(root, file) {
+  const name = posix.basename(file);
+  let dir = posix.dirname(file);
+  let rel = name;
+  while (dir && dir !== '.') {
+    const text = readText(root, posix.join(dir, SIDECAR));
+    if (text !== null) {
+      const data = yamlOf(text);
+      if (data === null) return { error: `${posix.join(dir, SIDECAR)} cannot be read` };
+      const own = declared(data.files?.[rel], 'why');
+      if (own) return { ...own, where: posix.join(dir, SIDECAR) };
+      const all = declared(data, 'why');
+      if (all) return { ...all, where: posix.join(dir, SIDECAR) };
+    }
+    if (dir === 'docs') break;
+    rel = `${posix.basename(dir)}/${rel}`;
+    dir = posix.dirname(dir);
+  }
+  return null;
+}
+
+// The procedures of atlas.yaml, as SKILL.md paths that exist.
+function procedureFiles(root) {
+  const facts = yamlOf(readText(root, 'atlas.yaml') ?? '') ?? {};
+  const named = Object.values(facts.procedures ?? {}).filter((one) => typeof one === 'string' && one.trim());
+  return [...new Set(named)].map((name) => posix.join('.claude/skills', name, 'SKILL.md')).filter((path) => existsSync(join(root, path))).sort();
+}
+
+// Every unit of the repo, with what it names. `named` is null when the unit
+// names neither its code nor a reason.
+export function docUnits(root) {
+  const units = [];
+  const folders = new Set();
+  for (const file of markdownFiles(root, 'docs')) {
+    if (file.startsWith('docs/site/')) continue;
+    const folder = designFolderOf(root, file);
+    if (folder) {
+      if (folders.has(folder)) continue;
+      folders.add(folder);
+      const where = posix.join(folder, DESIGN);
+      units.push({ unit: folder, kind: 'design', where, named: declared(yamlOf(readText(root, where) ?? ''), 'sources_why') ?? fromSidecar(root, where), generated: false });
+      continue;
+    }
+    const head = headOf(readText(root, file));
+    units.push({ unit: file, kind: 'doc', where: file, named: declared(head, 'sources_why') ?? fromSidecar(root, file), generated: head?.generated === true });
+  }
+  for (const file of procedureFiles(root)) {
+    units.push({ unit: posix.dirname(file), kind: 'procedure', where: file, named: declared(headOf(readText(root, file)), 'sources_why'), generated: false });
+  }
+  return units;
+}
+
+// Line 1: each unit names its code, or why it names none.
+export const unnamed = (units) => units.filter((one) => !one.named || one.named.error);
+
+// Line 2: each named path resolves. A path that does not makes its doc stale.
+export function unresolved(root, units) {
+  const out = [];
+  for (const one of units) {
+    for (const source of one.named?.sources ?? []) {
+      const path = source.replace(/\/+$/, '');
+      if (!path || path.startsWith('/') || path.split('/').includes('..') || !existsSync(join(root, path))) out.push({ unit: one.unit, where: one.where, source });
+    }
+  }
+  return out;
+}
+
+// Does a changed path fall under one named source? A folder source covers
+// each path below it.
+export function covers(root, source, path) {
+  const clean = source.replace(/\/+$/, '');
+  if (path === clean) return true;
+  const folder = source.endsWith('/') || isDir(root, clean);
+  return folder && path.startsWith(`${clean}/`);
+}
+
+// Is a unit itself changed by the pull request?
+const touchedItself = (unit, changed) => changed.some((path) => path === unit.unit || path === unit.where || path.startsWith(`${unit.unit}/`));
+
+// The pull request text that marks a doc "still true": one line that names the
+// unit (its path, or for a design folder its folder) and says "still true".
+export function stillTrue(body, unit) {
+  const text = String(body ?? '').replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+  return text.split('\n').some((line) => /still true/i.test(line) && (line.includes(unit.unit) || line.includes(unit.where)));
+}
+
+// Line 4: the units whose named code a pull request changes. Each one needs an
+// update in the same pull request, or a "still true" mark in its text.
+export function touchedUnits(root, units, changed, body = '') {
+  const out = [];
+  for (const one of units) {
+    if (one.generated || !one.named?.sources?.length) continue;
+    const hits = changed.filter((path) => one.named.sources.some((source) => covers(root, source, path)));
+    if (!hits.length) continue;
+    const updated = touchedItself(one, changed);
+    const marked = !updated && stillTrue(body, one);
+    out.push({ unit: one.unit, where: one.where, hits, updated, marked, ok: updated || marked });
+  }
+  return out;
+}
+
+const git = (root, args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+
+// The paths a range changes, old and new names both. A range of the form
+// `base...head` starts from the commit the two share.
+export function changedPaths(root, range) {
+  const out = git(root, ['diff', '--name-status', '-M', '--no-color', range]);
+  const paths = new Set();
+  for (const row of out.split('\n').filter(Boolean)) for (const path of row.split('\t').slice(1)) paths.add(path);
+  return [...paths].sort();
+}
+
+// The findings for `atlas upkeep check`. `pr` is the event's pull request, or
+// null on the main branch. `gate` says whether a touched doc with no update
+// and no mark is a finding (true) or a note (false).
+export function docSourceFindings(root, { pr = null, gate = false } = {}) {
+  const units = docUnits(root);
+  const findings = [];
+  const notes = [];
+  // A repo where no doc names its code yet has not taken up the rule: one
+  // note, not a finding for each doc.
+  const adopted = units.some((one) => one.named && !one.named.error && !one.generated);
+  if (!adopted && units.length) notes.push(`doc sources: no doc names its code yet (${units.length} doc(s) and procedure(s)). Add sources: or sources_why: to each`);
+  for (const one of adopted ? unnamed(units) : []) findings.push(`doc sources: ${one.where} names no code. Add sources: (paths) or sources_why: (why none)${one.named?.error ? `; ${one.named.error}` : ''}`);
+  for (const one of unresolved(root, units).slice(0, MAX_LISTED)) findings.push(`doc sources: ${one.where} is stale: it names ${one.source}, which does not exist`);
+  let touched = null;
+  const base = pr?.base?.sha;
+  const head = pr?.head?.sha;
+  if (base && head && existsSync(join(root, '.git'))) {
+    let range = null;
+    try {
+      range = changedPaths(root, `${base}...${head}`);
+    } catch (error) {
+      findings.push(`doc sources: the changed paths could not be read: ${String(error.message).split('\n')[0]}`);
+    }
+    if (range) {
+      touched = touchedUnits(root, units, range, pr.body);
+      for (const one of touched.filter((t) => !t.ok)) {
+        const text = `doc sources: ${one.unit} names ${one.hits.slice(0, 3).join(', ')}${one.hits.length > 3 ? ` and ${one.hits.length - 3} more` : ''}. Update it in this pull request, or write "${one.unit}: still true" in its text`;
+        (gate ? findings : notes).push(text);
+      }
+    }
+  }
+  return { units: units.length, findings, notes, touched };
+}
+
+// ---------- the replay (R39 line 3) ----------
+
+// The lines of the old side that a commit changes, per old path.
+function changedLines(root, parent, commit) {
+  const out = git(root, ['diff', '-U0', '-M', '--no-color', parent, commit]);
+  const lines = new Map();
+  let file = null;
+  for (const row of out.split('\n')) {
+    if (row.startsWith('--- ')) { file = row === '--- /dev/null' ? null : row.slice(6); continue; }
+    const hunk = row.match(/^@@ -(\d+)(?:,(\d+))? /);
+    if (hunk && file) {
+      const start = Number(hunk[1]);
+      const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+      if (!lines.has(file)) lines.set(file, []);
+      // A pure insert (count 0) lands between start and start + 1.
+      lines.get(file).push([start, count ? start + count - 1 : start + 1]);
+    }
+  }
+  return lines;
+}
+
+// The `path:line` citations in a unit's text, resolved against the repo root,
+// then against each folder it names, then against packages/<name>/.
+const CITE = /`?([\w.@-]+(?:\/[\w.@-]+)*\.[A-Za-z]{1,5}):(\d+)(?:-(\d+))?/g;
+function citedLines(root, unit) {
+  const files = unit.kind === 'design'
+    ? markdownFiles(root, unit.unit).concat([unit.where])
+    : [unit.where];
+  const out = [];
+  for (const file of files) {
+    const text = readText(root, file) ?? '';
+    for (const m of text.matchAll(CITE)) {
+      const tries = [m[1], ...(unit.named?.sources ?? []).filter((s) => s.endsWith('/')).map((s) => posix.join(s, m[1])), posix.join('packages/atlas', m[1])];
+      const path = tries.find((one) => existsSync(join(root, one)));
+      if (path) out.push({ path, from: Number(m[2]), to: Number(m[3] ?? m[2]) });
+    }
+  }
+  return out;
+}
+
+// For the last `last` merges on the first-parent line of `ref`, count the
+// units that each rule pulls in: rule "file" (a changed path falls under a
+// named source) and rule "line" (a changed line is a line the unit cites).
+// It reads the units of the current tree, and writes nothing.
+export function replay(root, { last = 30, ref = 'HEAD' } = {}) {
+  const units = docUnits(root).filter((one) => !one.generated && one.named?.sources?.length);
+  const cites = new Map(units.map((one) => [one.unit, citedLines(root, one)]));
+  const merges = git(root, ['log', '--first-parent', '--merges', `-n${Number(last)}`, '--format=%H %s', ref]).split('\n').filter(Boolean);
+  const rows = [];
+  const byUnit = new Map(units.map((one) => [one.unit, { file: 0, line: 0 }]));
+  for (const row of merges) {
+    const [sha, ...words] = row.split(' ');
+    const changed = changedPaths(root, `${sha}^1..${sha}`);
+    const lines = changedLines(root, `${sha}^1`, sha);
+    const file = touchedUnits(root, units, changed);
+    const line = units.filter((one) => cites.get(one.unit).some((c) => (lines.get(c.path) ?? []).some(([a, b]) => a <= c.to && c.from <= b)));
+    for (const one of file) byUnit.get(one.unit).file += 1;
+    for (const one of line) byUnit.get(one.unit).line += 1;
+    rows.push({ sha: sha.slice(0, 7), title: words.join(' '), changed: changed.length, file: file.map((one) => ({ unit: one.unit, updated: one.updated })), line: line.map((one) => one.unit) });
+  }
+  return {
+    merges: rows.length,
+    units: units.length,
+    rows,
+    totals: {
+      file: rows.reduce((n, r) => n + r.file.length, 0),
+      fileNotUpdated: rows.reduce((n, r) => n + r.file.filter((one) => !one.updated).length, 0),
+      line: rows.reduce((n, r) => n + r.line.length, 0),
+      mergesWithFile: rows.filter((r) => r.file.length).length,
+      mergesWithLine: rows.filter((r) => r.line.length).length,
+    },
+    byUnit: [...byUnit].filter(([, n]) => n.file || n.line).map(([unit, n]) => ({ unit, ...n })).sort((a, b) => b.file - a.file || b.line - a.line || a.unit.localeCompare(b.unit)),
+  };
+}

package/door/lib/fails-before.mjs

@@ -180,7 +180,8 @@ export function casesOf(text, path) {
 
 // The text of each <testcase> element, in order, so a failure can be sorted.
 function caseTexts(xml) {
-  return [...String(xml).matchAll(/<testcase\b[^>]*?(?:\/>|>([\s\S]*?)<\/testcase>)/g)].map((m) => m[1] ?? '');
+  // Node writes a ">" in a name as it is, so a quoted value may hold one.
+  return [...String(xml).matchAll(/<testcase\b(?:[^>"']|"[^"]*"|'[^']*')*?(?:\/>|>([\s\S]*?)<\/testcase>)/g)].map((m) => m[1] ?? '');
 }
 
 // The results of one report: Map of case name to pass, assertion, error or skipped.
@@ -193,7 +194,9 @@ export function readReport(xml) {
   cases.forEach((c, i) => {
     let result = c.result;
     if (result === 'fail') result = /AssertionError|ERR_ASSERTION/.test(`${c.message ?? ''}\n${texts[i] ?? ''}`) ? 'assertion' : 'error';
-    const name = c.name.replace(/\[.*\]$/, '');
+    // The junit reporter of node writes a double quote as "&amp;quot;", so one
+    // unescape leaves "&quot;" (f2d07e35). Undo the second escape here.
+    const name = c.name.replaceAll('&quot;', '"').replace(/\[.*\]$/, '');
     // When one name holds several results, the worst one counts: a fail beats a pass.
     if (!out.has(name) || rank[result] > rank[out.get(name)]) out.set(name, result);
   });
@@ -209,6 +212,11 @@ export function resultOf(before, after) {
   return 'error before';
 }
 
+// A case with only a changed helper makes no new claim, so passing on the
+// old code is no fault: it reads "helper only". It proves nothing either, and
+// passes-after checks that its old text still passes on the new code.
+const helperResult = (change, result) => (change === 'helper' && result === 'passes before' ? 'helper only' : result);
+
 export const RED_RESULTS = Object.freeze(['passes before', 'fails after', 'skipped', 'duplicate']);
 
 // ---------------------------------------------------------------- the plan
@@ -243,7 +251,10 @@ export function plan({ root, base, head = 'HEAD', list = null }) {
     else {
       if (r.status !== 'added' && before.rest !== after.rest) all = true;
       for (const [name, text] of after.cases) {
-        if (all || !before.cases.has(name) || squash(before.cases.get(name), r.path) !== squash(text, r.path)) picked.push({ name, change: before.cases.has(name) ? 'changed' : 'added', duplicate: after.duplicates.has(name) });
+        // A case whose own text is the same, in a file whose text outside the
+        // cases changed, has only a changed helper (item 46498d2e).
+        const same = before.cases.has(name) && squash(before.cases.get(name), r.path) === squash(text, r.path);
+        if (all || !same) picked.push({ name, change: !before.cases.has(name) ? 'added' : same ? 'helper' : 'changed', duplicate: after.duplicates.has(name) });
       }
     }
     if (!picked.length && !all && r.status !== 'added') continue;
@@ -372,7 +383,7 @@ export function combine(prepared, oldRun, newRun) {
     for (const c of picked) {
       const before = b.cases?.[c.name] ?? 'missing';
       const after = headCases[c.name] ?? 'missing';
-      answer.cases.push({ path: p.path, name: c.name, change: c.change, before, after, result: c.duplicate ? 'duplicate' : resultOf(before, after) });
+      answer.cases.push({ path: p.path, name: c.name, change: c.change, before, after, result: c.duplicate ? 'duplicate' : helperResult(c.change, resultOf(before, after)) });
     }
   }
   return finish(answer, nothingProven(prepared, answer));
@@ -385,7 +396,7 @@ export function combine(prepared, oldRun, newRun) {
 // file with no runner here, gets its proof elsewhere: the planted-fault
 // procedure.
 function nothingProven({ changed, productChanged }, answer) {
-  if (!productChanged || answer.cases.length) return false;
+  if (!productChanged || answer.cases.some((c) => c.result !== 'helper only')) return false;
   return changed.rows.some((r) => r.group === 'unit-test' && r.status !== 'removed' && runnerOf(r.path));
 }
 

package/door/lib/gate.mjs

@@ -218,36 +218,64 @@ export const gateRunTitle = (pr, sha) => `gate #${pr} at ${sha}`;
 // Why one workflow run cannot carry a required check of this pull request,
 // or null when it can. The run must come from a base file that defines the
 // check, from a pull request event, on this head, for this pull request into
-// its base branch.
-export function refusal(run, { name, pr, sha, baseRef, homes }) {
+// its base branch. The gate runs on pull_request_target, and its title must
+// name this pull request and this head. The probe of 26 October (done line
+// 15, atlas#211) showed that its run and its check run sit on the head commit,
+// like the others.
+export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [] }) {
   if (!run) return 'no workflow run';
   if (!homes.get(name)?.has(run.path)) return `from ${run.path ?? 'no file'}, not a base file that defines the check`;
-  if (run.event !== 'pull_request') return `from the event ${run.event}`;
+  const event = name === GATE_CHECK ? 'pull_request_target' : 'pull_request';
+  if (run.event !== event) return `from the event ${run.event}`;
   if (run.head_sha !== sha) return 'of another head commit';
+  if (name === GATE_CHECK && run.display_title !== gateRunTitle(pr, sha)) return 'of another pull request or head';
   const pulls = run.pull_requests ?? [];
   if (!pulls.some((each) => Number(each.number) === Number(pr) && each.base?.ref === baseRef)) return `not of #${pr} into ${baseRef}`;
   // GitHub lists every open pull request with this head, so a run made for a
   // pull request into a side branch can also name this one. Such a run used
   // the side branch's file, so it does not count.
   if (pulls.some((each) => each.base?.ref !== baseRef)) return `also of a pull request into ${pulls.find((each) => each.base?.ref !== baseRef).base?.ref ?? 'another branch'}`;
+  // GitHub builds that list when it is read, from the open pull requests of
+  // the head branch. Once a side pull request closes, its gate run names only
+  // this one, and its title can be set to match. So the gate also refuses a
+  // head branch that ever had a pull request into another branch.
+  if (name === GATE_CHECK) {
+    const side = sides();
+    if (side === null) return 'no head branch to check for side pull requests';
+    if (side.length) return `the head branch also had #${side[0].number} into ${side[0].base?.ref ?? 'another branch'}`;
+  }
   return null;
 }
 
-// The same for a run of the gate. It runs on pull_request_target, so it sits
-// on a commit of the base branch, not on the head. Its title names the pull
-// request and the head; the run must come from the base branch and its file.
-export function gateRefusal(run, { pr, sha, baseRef, onBase }) {
-  if (run.path !== GATE_WORKFLOW) return `from ${run.path ?? 'no file'}, not ${GATE_WORKFLOW}`;
-  if (run.event !== 'pull_request_target') return `from the event ${run.event}`;
-  if (run.display_title !== gateRunTitle(pr, sha)) return 'of another pull request or head';
-  if (run.head_branch !== baseRef) return `from the branch ${run.head_branch}, not ${baseRef}`;
-  if (!onBase(run.head_sha)) return `from a commit that is not on ${baseRef}`;
+// Why one check run is not a job that ran in its workflow run, or null when
+// it is. A job token with `checks: write` can post a check run under any name.
+// GitHub files it under the GitHub Actions app, in the check suite of a run
+// of the base file, and lists it as a job of that run. The probe of 26
+// October (R10 P10, atlas-scratch#7) showed it: such a run had no runner, no
+// labels and no steps. GitHub refuses to change a check run that a job made
+// (atlas-scratch#8), so only a new one can lie, and it never had a runner.
+export function jobRefusal(job, check, run) {
+  if (!job) return 'no job of the workflow run has this check run';
+  if (run?.id === undefined || Number(job.run_id) !== Number(run.id)) return 'a job of another workflow run';
+  // Only a green run can lie in the merge's favour. A red or cancelled job
+  // that never got a runner still counts, so an older green try cannot win.
+  if (check?.conclusion === 'success' && (job.runner_id === null || job.runner_id === undefined)) return 'a check run that no runner ran (posted through the API)';
   return null;
 }
 
 // The check runs that may count for this pull request, and the ones refused.
-function pinnedRuns(gh, repo, { pr, sha, baseRef, checks }) {
+function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks }) {
   const homes = homesAt(gh, repo, baseRef, checks);
+  // Every pull request, open or closed, from the head branch into another
+  // branch. Read once, and only when a gate run needs it.
+  let sideList;
+  const sides = () => {
+    if (sideList !== undefined) return sideList;
+    const owner = head?.repo?.owner?.login ?? head?.user?.login;
+    if (!head?.ref || !owner) return (sideList = null);
+    const all = gh('GET', `repos/${repo}/pulls?head=${encodeURIComponent(`${owner}:${head.ref}`)}&state=all&per_page=100`) ?? [];
+    return (sideList = all.filter((each) => each.base?.ref !== baseRef));
+  };
   const suites = new Map();
   const runOf = (id) => {
     if (!suites.has(id)) suites.set(id, id ? (gh('GET', `repos/${repo}/actions/runs?check_suite_id=${id}`)?.workflow_runs ?? [])[0] ?? null : null);
@@ -256,21 +284,12 @@ function pinnedRuns(gh, repo, { pr, sha, baseRef, checks }) {
   const kept = [];
   const refused = [];
   for (const check of checkRuns(gh, repo, sha)) {
-    if (!checks.includes(check.name) || check.name === GATE_CHECK || check.app?.id !== ACTIONS_APP_ID) continue;
-    const why = refusal(runOf(check.check_suite?.id), { name: check.name, pr, sha, baseRef, homes });
+    if (!checks.includes(check.name) || check.app?.id !== ACTIONS_APP_ID) continue;
+    const run = runOf(check.check_suite?.id);
+    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides })
+      ?? jobRefusal(check.id === undefined ? null : gh('GET', `repos/${repo}/actions/jobs/${check.id}`), check, run);
     if (why) refused.push({ name: check.name, why }); else kept.push(check);
   }
-  if (checks.includes(GATE_CHECK)) {
-    const onBase = (commit) => ['ahead', 'identical'].includes(gh('GET', `repos/${repo}/compare/${commit}...${encodeURIComponent(baseRef)}`)?.status);
-    const runs = gh('GET', `repos/${repo}/actions/workflows/${GATE_WORKFLOW.split('/').pop()}/runs?event=pull_request_target&per_page=100`)?.workflow_runs ?? [];
-    for (const run of runs.filter((each) => each.display_title === gateRunTitle(pr, sha))) {
-      const why = gateRefusal(run, { pr, sha, baseRef, onBase });
-      if (why) { refused.push({ name: GATE_CHECK, why }); continue; }
-      for (const job of gh('GET', `repos/${repo}/actions/runs/${run.id}/jobs`)?.jobs ?? []) {
-        if (job.name === GATE_CHECK) kept.push({ ...job, app: { id: ACTIONS_APP_ID } });
-      }
-    }
-  }
   return { kept, refused };
 }
 
@@ -283,7 +302,7 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
   const sha = pull.head.sha;
   const checks = checksAt(gh, repo, pull.base.ref);
-  const { kept, refused } = pinnedRuns(gh, repo, { pr, sha, baseRef: pull.base.ref, checks });
+  const { kept, refused } = pinnedRuns(gh, repo, { pr, sha, baseRef: pull.base.ref, head: pull.head, checks });
   const rows = checkStates(checks, kept);
   line(`atlas gate ready: #${pr} at ${sha.slice(0, 7)}, ${checks.length} required check(s) from atlas.yaml on ${pull.base.ref}.`);
   for (const row of rows) line(checkLine(row));

package/door/lib/install.mjs

@@ -299,6 +299,38 @@ export function proveCopy({ packageRoot, exec = defaultExec }) {
   }
 }
 
+// The release notes of each version after `from`, up to `to` (roadmap R52,
+// item c271b9dd). The release job writes them into the body of each GitHub
+// release. They explain a release and prove nothing: the checks above prove
+// it. Anyone who can push can edit a body, so the upgrade prints it as text
+// from GitHub, with a cap on its length.
+const NOTE_VERSION = /^v(\d+\.\d+\.\d+)$/;
+const versionParts = (version) => version.split('.').map(Number);
+export const newer = (a, b) => { const [x, y] = [versionParts(a), versionParts(b)]; for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] > y[i]; return false; };
+export function releaseNotes({ gh, repo, from, to }) {
+  const rows = gh(['api', '--method', 'GET', `repos/${repo}/releases?per_page=100`]);
+  return (Array.isArray(rows) ? rows : [])
+    .map((row) => ({ version: NOTE_VERSION.exec(row.tag_name ?? '')?.[1], body: String(row.body ?? '') }))
+    .filter((row) => row.version && newer(row.version, from) && !newer(row.version, to))
+    .sort((a, b) => (newer(a.version, b.version) ? 1 : -1));
+}
+const MAX_NOTE_LINES = 60;
+export function notesLines({ gh, repo, from, to }) {
+  let notes;
+  try { notes = releaseNotes({ gh, repo, from, to }); } catch (error) {
+    return [`The release notes could not be read: ${firstLines(error, 1)}. The checks above still hold.`];
+  }
+  if (!notes.length) return [`No release notes for the versions after ${from}.`];
+  const out = [`What changed, from the release notes on GitHub (${notes.length} version${notes.length === 1 ? '' : 's'} after ${from}). The notes explain; the checks above prove:`];
+  for (const { version, body } of notes) {
+    const text = body.replace(/\r/g, '').replace(/\n+$/, '').split('\n');
+    out.push('', `Atlas ${version}:`);
+    for (const one of text.slice(0, MAX_NOTE_LINES)) out.push(`  | ${one}`);
+    if (text.length > MAX_NOTE_LINES) out.push(`  | … ${text.length - MAX_NOTE_LINES} more lines on GitHub`);
+  }
+  return out;
+}
+
 export async function upgrade({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec, ask = defaultAsk }) {
   const { name, version: installed } = packageJson(packageRoot);
   const repo = repoOf(packageRoot);
@@ -334,6 +366,8 @@ export async function upgrade({ packageRoot, options = {}, line = console.log, e
       return 1;
     }
     line(`  every one of ${files.size} files matches that commit`);
+    line('');
+    for (const text of notesLines({ gh, repo, from: installed, to: target })) line(text);
 
     const current = existsSync(packageRoot) ? filesUnder(packageRoot) : new Map();
     line('');

package/door/lib/upkeep.mjs

@@ -13,11 +13,21 @@
 //    purpose, so both are skipped; so is text inside code.
 // 3. Item named. With --event only: the pull request title, body or branch
 //    names a tracker item, or says "no item:" and a reason.
+// 4. Doc sources (roadmap R39, lib/doc-sources.mjs). Each doc and each
+//    procedure names its code, or why it names none, and each named path
+//    exists. With --event, each doc whose code the pull request changes is
+//    updated in it, or marked "still true" in its text. Until the replay of
+//    R39 line 3 is read, that last rule only reports (TOUCHED_DOCS_GATE).
 //
 // It reads the tree and the event file, and writes nothing.
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
+import { docSourceFindings, replay } from './doc-sources.mjs';
+
+// R39 line 4 gates only after the replay of line 3. False: a touched doc with
+// no update and no mark is a note, not a finding.
+export const TOUCHED_DOCS_GATE = false;
 
 const INDEX = 'docs/index.md';
 const SKIP_DIRS = new Set(['node_modules', 'archive', 'fixtures']);
@@ -220,6 +230,8 @@ export function upkeepCheck(root, { event = null } = {}) {
   if (index.gone.length) findings.push(`docs index: ${index.gone.length} listed path(s) are gone: ${index.gone.slice(0, MAX_LISTED).join(', ')}`);
   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`);
+  const sources = docSourceFindings(root, { pr: event?.pull_request ?? null, gate: TOUCHED_DOCS_GATE });
+  findings.push(...sources.findings);
   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');
   // 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.
@@ -230,11 +242,12 @@ export function upkeepCheck(root, { event = null } = {}) {
     if (text.tests.error) findings.push(`pr text: the changed-test list could not be made: ${text.tests.error}`);
     else if (text.tests.checked) findings.push(...changedTestsFindings(event.pull_request.body, text.tests.rows));
   }
-  return { green: findings.length === 0, findings, index, dead, item, text };
+  return { green: findings.length === 0, findings, notes: sources.notes, index, dead, item, text, sources };
 }
 
-export function upkeepCommand({ what, event: eventFile, json = false }, root, line) {
-  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check.`);
+export function upkeepCommand({ what, event: eventFile, json = false, last }, root, line) {
+  if (what === 'replay') return replayCommand({ last, json }, root, line);
+  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, or atlas upkeep replay.`);
   let event = null;
   if (eventFile !== undefined) {
     try { event = JSON.parse(readFileSync(resolve(eventFile), 'utf8')); } catch (error) { throw new Error(`cannot read the event file ${eventFile}: ${error.message}`); }
@@ -246,7 +259,29 @@ export function upkeepCommand({ what, event: eventFile, json = false }, root, li
   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'}`);
   if (result.text.checked) line(`changed tests: ${result.text.tests?.checked ? (result.text.tests.error ? 'no list' : `${result.text.tests.rows.filter((row) => NAMED_GROUPS.has(row.group)).length} row(s) to name`) : `not checked (${result.text.tests?.why})`}`);
+  line(`doc sources: ${result.sources.units} doc(s) and procedure(s)${result.sources.touched ? `; this pull request touches the code of ${result.sources.touched.length}` : ''}`);
   for (const finding of result.findings) line(`  - ${finding}`);
+  for (const note of result.notes) line(`  note: ${note}`);
   line(`upkeep check: ${result.green ? 'GREEN' : 'RED'}`);
   return result.green ? 0 : 1;
 }
+
+// `atlas upkeep replay`: what the doc-sources rule (R39 line 4) would have
+// asked of the last merges. It writes nothing.
+function replayCommand({ last = '30', json = false }, root, line) {
+  const n = Number(last);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`--last takes a whole number, not "${last}"`);
+  const out = replay(root, { last: n });
+  if (json) { process.stdout.write(`${JSON.stringify(out, null, 2)}\n`); return 0; }
+  line(`replay of the last ${out.merges} merge(s), with the sources of ${out.units} doc(s) and procedure(s) in this tree`);
+  line('rule "file": a changed path falls under a path the doc names. Rule "line": a changed line is a line the doc cites as path:line.');
+  for (const row of out.rows) {
+    const file = row.file.map((one) => `${one.unit}${one.updated ? ' (updated)' : ''}`);
+    line(`  ${row.sha} ${row.title.slice(0, 60)} · ${row.changed} path(s) · file ${row.file.length}${file.length ? `: ${file.join(', ')}` : ''} · line ${row.line.length}${row.line.length ? `: ${row.line.join(', ')}` : ''}`);
+  }
+  const t = out.totals;
+  line(`totals: rule "file" pulls in ${t.file} doc(s) over ${t.mergesWithFile} merge(s), ${t.fileNotUpdated} not updated in the merge; rule "line" pulls in ${t.line} doc(s) over ${t.mergesWithLine} merge(s)`);
+  line('by doc (file, line):');
+  for (const one of out.byUnit) line(`  ${one.unit}: ${one.file}, ${one.line}`);
+  return 0;
+}

package/package.json

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

package/skills/lead/SKILL.md

@@ -110,7 +110,7 @@ set. A test keeps the two lists equal.
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
-| `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
+| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 

package/skills/sdlc-task/SKILL.md

@@ -135,10 +135,13 @@ A lock is the owner's approval of a short design.
    `tripwires`): a discovery that touches the definition of done, security, a
    schema or cost stops the build and goes back to the owner, as a change after
    approval (above).
-6. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
-   pull request. Its text holds the definition of done, the kind of change, the
-   undo, and the list of existing tests it changes or removes, and it links the
-   tracker item.
+6. Test with the repo's own `test` procedure, which `atlas.yaml` names.
+   Update what the change touches, and run each generator.
+   `atlas upkeep check` lists each doc or procedure whose `sources:` names a
+   changed path. Update each one, or write "<doc path>: still true" and why
+   in the pull request text. Open a pull request. Its text holds the
+   definition of done, the kind of change, the undo, and the list of existing
+   tests it changes or removes, and it links the tracker item.
 7. **Proof before the merge.** Run the `atlas:verifier` agent on the pull
    request. It proves each line of the definition of done from a fresh run and
    posts its own proof comment. When it returns a comment file instead,

package/skills/sdlc-task/design/README.md

@@ -27,6 +27,12 @@ Set `shared: true` when many repos use the design, such as Atlas itself.
 Then "Each kind of repo" is needed. For a design in one product it is
 optional.
 
+Name the code the design describes under `sources:` in `design.yaml`.
+It is a list of paths from the repo root. A path that ends in `/` is a
+folder. A design with no code yet says why under `sources_why:`. A pull
+request that changes a named path updates the design, or marks it "still
+true" (roadmap R39). `atlas upkeep check` reads both keys.
+
 ## All parts by kind
 
 `needed` means the check fails when the part is missing or empty.