genesis-compiler 1.10.21 → 1.10.23

package/src/index/prompt.js

@@ -1,3 +1,5 @@
+import path from 'node:path';
+
 import { readInstalledAsset } from './assets.js';
 import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
 import { buildProjectIndex, MACHINE_CITY_PATH, PROGRAM_CITY_PATH } from './code-index.js';
@@ -22,11 +24,16 @@ import { stableJson } from './utils.js';
 import { classifyProjectKind } from './project-files.js';
 import { inspectProjectFormatAtRoot } from './project-format.js';
 import { inspectProject } from './project-inspection.js';
-import { PASSES } from './passes.js';
-import { PASS_RECORD_PATH, passRecordCommit, readPassRecord } from './pass-record.js';
+import { masterPassSection, masterRecordStep, masterSelection } from './master-pass.js';
+import { baseRequest, deepRequest, MASTER_PASS, PASSES } from './passes.js';
+import { inspectPassRecord, passRecordCommit, passRecordPath, readPassRecord, unknownRecordMessage } from './pass-record.js';
 import { projectPassSupport } from './pass-support.js';
+import { changedSince, projectSourceLines, sourceSize } from './source-size.js';
+import { runGitText } from './process.js';
 
-const TASKS = new Set(['start', 'adopt', 'work', ...PASSES.map(({ task }) => task), 'program', 'blueprint', 'describe', 'review']);
+const TASKS = new Set([
+  'start', 'adopt', 'work', ...PASSES.map(({ task }) => task), MASTER_PASS.task, 'program', 'blueprint', 'describe',
+]);
 /** Every prompt task Genesis renders, the passes' tasks among them. */
 export const PROMPT_TASKS = Object.freeze([...TASKS]);
 // Each task's request when none is given. A pass task asked for bare runs as its pass, except Deslop and the UI pass,
@@ -38,6 +45,7 @@ const DEFAULT_REQUEST = {
   ...Object.fromEntries(PASSES.map(({ task, request }) => [task, request])),
   deslop: 'Deslop your own changes for the current task.',
   'ui-pass': 'UI pass your own changes for the current task.',
+  [MASTER_PASS.task]: MASTER_PASS.request,
   program: 'Refresh the complete useful Program for the code that exists now.',
   describe: 'Create or refresh the complete Blueprint and useful Program for the codebase that exists now.',
   review: 'Review the complete useful relationship between Blueprint, code, Program, and tests.',
@@ -166,15 +174,26 @@ function renderPrompt({
     ...(postChange ? ['', 'SELECTED STACK POST-CHANGE GUIDANCE', '', postChange] : []),
     ...(passGuidance?.text ? ['', passGuidance.heading, '', passGuidance.text] : []),
     ...(passGuidance?.run ? ['', 'PASS RUN', '', passRunScope(passGuidance.title, passGuidance.run)] : []),
-    ...(passGuidance?.record ? ['', 'PASS RECORD', '', passRecordStep(passGuidance.task)] : []),
+    ...(passGuidance?.deep ? ['', 'DEEP RUN', '', passGuidance.deep] : []),
+    ...(passGuidance?.master ? ['', 'MASTER PASS', '', passGuidance.master] : []),
+    ...(passGuidance?.report ? ['', 'PASS REPORT', '', passGuidance.report.trim()] : []),
+    ...(passGuidance?.record ? ['', 'PASS RECORD', '', passGuidance.record] : []),
     '',
   ].join('\n');
 }
 
-// The runs a pass offers, each with the request Genesis writes for it: the whole app, always, and, while the commit of
-// the pass's last completed run is in HEAD's history, the changes since that commit judged against the whole app.
-// Either run records the pass, so a whole run followed by runs since the last one covers every change.
-function passRuns(pass, since) {
+// A run's label with its size, in the files and lines its checklist starts from, for a person to see what it takes.
+function sized(label, size) {
+  if (!size) return label;
+  const text = `${size.files.toLocaleString('en-US')} files, ${size.lines.toLocaleString('en-US')} lines`;
+  return label.endsWith(')') ? `${label.slice(0, -1)}; ${text})` : `${label} (${text})`;
+}
+
+// The runs a pass offers, each with the request Genesis writes for it: the whole app, always; while the commit of the
+// pass's last completed run is in HEAD's history, the changes since that commit judged against the whole app; and,
+// when the project's own Genesis runs it, the whole app deeply, item by item, sized in a listing by `size`. Every run
+// records the pass, so a whole or deep run followed by runs since the last one covers every change.
+function passRuns(pass, since, deep, size = null) {
   return [
     { id: 'whole', label: 'Whole app', request: pass.request },
     ...(since ? [{
@@ -184,21 +203,72 @@ function passRuns(pass, since) {
       commit: since.commit,
       commitsSince: since.commitsSince,
     }] : []),
+    ...(deep ? [{ id: 'deep', label: sized('Deep', size), request: deepRequest(pass), ...size }] : []),
   ];
 }
 
-async function projectPassRuns(root, pass, lastRun) {
-  return passRuns(pass, await passRecordCommit(root, pass.task, lastRun));
+async function projectPassRuns(root, pass, lastRun, deep, size = null) {
+  return passRuns(pass, await passRecordCommit(root, pass.task, lastRun), deep, size);
+}
+
+// The Master pass's runs: the whole app, and the changes since its last completed run, each with the request for every
+// pass it offers and, as `selectedRequest`, the request for the passes a person chooses, `{passes}` standing for their
+// names separated by commas. In a listing each is sized: the whole app's own source, or the files the changes touch.
+function masterRuns(since, whole = null, changed = null) {
+  return passRuns(MASTER_PASS, since, false).map((run) => {
+    const size = run.id === 'whole' ? whole : changed;
+    return {
+      ...run,
+      label: sized(run.label, size),
+      selectedRequest: run.request.replace(MASTER_PASS.title, `${MASTER_PASS.title} ({passes})`),
+      ...size,
+    };
+  });
+}
+
+// The commit of the Master pass's last completed run, and the commits since it, or null.
+function masterSince(root, record) {
+  return passRecordCommit(root, MASTER_PASS.task, record[MASTER_PASS.task]?.lastRun ?? null);
+}
+
+// A request's last paragraph: a host may frame Genesis's request with its own paragraphs before it.
+function lastParagraph(request) {
+  return request.trim().split(/\n[ \t]*\n/u).at(-1).trim();
 }
 
 // The run a request asks for: one of the pass's runs whose request it is, alone or as the last paragraph after a host's
 // own framing. Genesis wrote those requests, so nothing is read into other wording: any other request, such as one
 // commit or the agent's own changes, runs the task and is never the pass.
 function requestedRun(runs, request) {
-  const last = request.trim().split(/\n[ \t]*\n/u).at(-1).trim();
+  const last = lastParagraph(request);
   return runs.find((run) => run.request === last) ?? null;
 }
 
+// A run over the changes since a base commit a host chooses: the request is the pass's base request, or its deep form
+// when `deep`, with a commit hash in place of `{base}`, alone or as the last paragraph after a host's own framing. A
+// base that is not a commit of this repository is refused, so the run never starts from nothing.
+async function baseRun(root, pass, request, deep) {
+  const last = lastParagraph(request);
+  const templates = [['base', baseRequest(pass)], ...(deep ? [['deep-base', baseRequest(pass, true)]] : [])];
+  for (const [id, template] of templates) {
+    const [before, after] = template.split('{base}');
+    if (!last.startsWith(before) || !last.endsWith(after) || last.length < before.length + after.length) continue;
+    const commit = last.slice(before.length, last.length - after.length);
+    const found = /^[0-9a-f]{7,64}$/u.test(commit) && await runGitText(root, [
+      'rev-parse', '--verify', '--quiet', `${commit}^{commit}`,
+    ]).catch((error) => {
+      if (error?.code === 'GIT_EXEC_FAILED') return '';
+      throw error;
+    });
+    if (!found) {
+      throw new GenesisError('PASS_REQUEST_INVALID', `The ${pass.title} cannot start from "${commit}": `
+        + 'name a commit of this repository by its hash.', { pass: pass.task });
+    }
+    return { id, request: last, commit };
+  }
+  return null;
+}
+
 const OWN_SOURCE = 'Generated output, build artifacts, vendored or copied third-party code, dependency directories and '
   + 'lockfiles are never part of it. This scope replaces the task\'s default scope.';
 
@@ -208,42 +278,97 @@ function passRunScope(title, run) {
     return `This request is a ${title} run over the whole app: the project's own source in every subsystem, whoever `
       + `changed it and whenever. ${OWN_SOURCE}`;
   }
-  return `This request is a ${title} run over the changes since commit ${run.commit}, the commit of its last completed `
-    + `run, judged against the whole app. Start from those changes: \`git diff ${run.commit}\` and the files it touches. `
+  if (run.id === 'deep') {
+    return `This request is a deep ${title} run over the whole app: the project's own source in every subsystem, `
+      + `whoever changed it and whenever, worked through item by item as DEEP RUN says. ${OWN_SOURCE}`;
+  }
+  const from = {
+    'since-last': 'the commit of its last completed run',
+    'deep-since': `the commit of the last completed ${MASTER_PASS.title}`,
+    base: 'the base its request names',
+    'deep-base': 'the base its request names',
+  }[run.id];
+  if (run.id === 'deep-since' || run.id === 'deep-base') {
+    return `This request is a deep ${title} run over the changes since commit ${run.commit}, ${from}, judged against `
+      + 'the whole app and worked through item by item as DEEP RUN says. Start from those changes: '
+      + `\`git diff ${run.commit}\` and the files it touches. ${OWN_SOURCE}`;
+  }
+  return `This request is a ${title} run over the changes since commit ${run.commit}, ${from}, judged against the `
+    + `whole app. Start from those changes: \`git diff ${run.commit}\` and the files it touches. `
     + 'Then judge them against the rest of the project\'s own source, because what they duplicate, what they should '
     + 'reuse and the checks they lack show only there, and make the pass\'s changes wherever that leads: the diff is '
     + `where the run starts, not its limit. ${OWN_SOURCE}`;
 }
 
-// A pass task's selected Stack prose under its own heading, the pass run its request asks for, and whether its prompt
-// records the pass: only for one of the pass's own runs, and only when the project's own Genesis runs and records it.
-// Null for other tasks.
-function passPromptGuidance(task, stack, request, support, runs) {
-  const pass = PASSES.find((entry) => entry.task === task);
+// Where a deep run keeps its checklist, and a Master pass its ledger: in Git's own directory for this worktree, which is
+// never committed or pushed, so they survive an interrupted run and are found again when it continues.
+async function ledgerPath(root, name) {
+  return path.resolve(root, await runGitText(root, ['rev-parse', '--git-path', `genesis/passes/${name}.md`]));
+}
+
+// How a deep run works, for every pass alike, written once in prompts/pass-deep.txt; each pass's skill adds only its
+// lens's checklist items.
+async function deepRunGuidance(root, task) {
+  const [checklist, guidance] = await Promise.all([ledgerPath(root, task), readInstalledAsset('pass-deep')]);
+  return `Keep this run's checklist at \`${checklist}\`.\n\n${guidance.trim()}`;
+}
+
+// A pass task's selected Stack prose under its own heading, the pass run its request asks for with a deep run's
+// guidance, what every report of the pass states (whatever its scope, so no report overstates its coverage), and its
+// record step: only for one of the pass's own runs, never a run over a base a host chose, and only when the project's
+// own Genesis runs and records it. Null for other tasks.
+function passPromptGuidance({ pass, stack, run, support, report, deep }) {
   if (!pass) return null;
-  const run = requestedRun(runs, request);
+  const recorded = run && !['base', 'deep-base'].includes(run.id) && support.unavailableFor(pass) === null;
   return {
-    task,
     title: pass.title,
     heading: pass.heading,
     text: stack[pass.field],
     run,
-    record: Boolean(run) && support.unavailableFor(pass) === null,
+    deep,
+    report,
+    record: recorded ? passRecordStep(pass.task, Boolean(deep)) : '',
   };
 }
 
-// A pass's prompt ends with recording the pass, so the record lands in the pass's own commit.
-function passRecordStep(task) {
+// A pass's prompt ends with recording the pass, so the record lands in the pass's own commit: with its other changes,
+// left uncommitted, or, for a deep run, which commits its work as it goes, as the run's last commit.
+function passRecordStep(task, committed) {
   return [
     'Only once this pass has finished, make your last step the Genesis',
     `\`passes done ${task}\` operation, invoked as`,
     `\`.agents/skills/genesis-${task}/SKILL.md\` says. It records the time in`,
-    `\`${PASS_RECORD_PATH}\`; leave that change uncommitted with the pass's other`,
-    'changes, so the record lands in the same commit. Do not run it for a pass that',
+    ...(committed ? [
+      `\`${passRecordPath(task)}\`; commit that change as the run's last commit, so the`,
+      'record lands in the run\'s own history. Do not run it for a pass that',
+    ] : [
+      `\`${passRecordPath(task)}\`; leave that change uncommitted with the pass's other`,
+      'changes, so the record lands in the same commit. Do not run it for a pass that',
+    ]),
     'stopped early, was abandoned, or still has failing checks.',
   ].join('\n');
 }
 
+// The passes a Master pass runs: every pass the project's own Genesis runs, in the Master order.
+function masterOffered(support) {
+  return MASTER_PASS.order
+    .map((task) => PASSES.find((pass) => pass.task === task))
+    .filter((pass) => support.unavailableFor(pass) === null);
+}
+
+// A Master pass's prompt: the passes its request selects, in order, each with its own Deep run's request, the ledger
+// that lets an interrupted Master pass continue, and its record step. A request that is not one of its runs, or names
+// a pass the project does not offer, is refused here, before anything else is read.
+async function masterPromptGuidance({ root, request, support }) {
+  const record = await readPassRecord(root);
+  const offered = masterOffered(support);
+  const { run, passes } = masterSelection(lastParagraph(request), masterRuns(await masterSince(root, record)), offered);
+  return {
+    master: masterPassSection({ run, passes, ledger: await ledgerPath(root, MASTER_PASS.task) }),
+    record: masterRecordStep(),
+  };
+}
+
 function collaborationPromptContext(collaboration) {
   return {
     path: collaboration.path,
@@ -512,9 +637,15 @@ export async function inspectProjectPromptTasks({ projectRoot, stackPackages = [
  * The passes a person can run, so a host lists them without naming any: each with its prompt task as `id`, a title,
  * a one-line description, a recommendation hint the host interprets itself, the pass's own request (the whole app),
  * its workflow skill, whether the selected Stack adds its own guidance to it, when it last finished (`lastRun`, a UTC
- * time from genesis/passes.json, or null), why the project's own Genesis cannot run it (`unavailable`, naming the
+ * time from the pass record, or null), why the project's own Genesis cannot run it (`unavailable`, naming the
  * update, or null) and the runs it offers (`runs`, none when unavailable), each with a label and the request a host
- * sends for it as written. The top-level `unavailable` says why that Genesis runs no pass at all, or is null.
+ * sends for it as written. `sinceBase` holds the requests of a run over the changes since a base commit the host
+ * chooses, `{base}` standing for the commit: `request`, and `deep` when the project's own Genesis runs Deep runs (or
+ * null); Genesis never records those runs. It is null when the pass cannot run there, except for a self-contained pass,
+ * whose prompt needs nothing from that Genesis. The top-level `unavailable` says why that Genesis runs no pass at all,
+ * or is null.
+ * `master` is the Master pass: the passes it runs, in its order, when it last finished and with which passes, why it
+ * cannot run, and its runs, each with the request for every pass and `selectedRequest` for the passes a person chooses.
  */
 export async function inspectProjectPasses({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
@@ -523,6 +654,13 @@ export async function inspectProjectPasses({ projectRoot, stackPackages = [] } =
     readPassRecord(root),
     projectPassSupport(root),
   ]);
+  const masterUnavailable = support.unavailableFor(MASTER_PASS);
+  const masterRecord = record[MASTER_PASS.task] ?? null;
+  // One walk of the project's own source sizes every deep run and the Master pass.
+  const sources = support.deep ? await projectSourceLines(root, stack) : null;
+  const whole = sources && sourceSize(sources);
+  const since = masterUnavailable ? null : await masterSince(root, record);
+  const changed = since && sources && sourceSize(sources, await changedSince(root, since.commit));
   return {
     contract: GENESIS_CONTRACTS.passes,
     unavailable: support.unavailable,
@@ -539,9 +677,25 @@ export async function inspectProjectPasses({ projectRoot, stackPackages = [] } =
         stackGuidance: Boolean(stack[pass.field]),
         lastRun,
         unavailable,
-        runs: unavailable ? [] : await projectPassRuns(root, pass, lastRun),
+        runs: unavailable ? [] : await projectPassRuns(root, pass, lastRun, support.deep, whole),
+        sinceBase: unavailable && !pass.selfContained ? null : {
+          request: baseRequest(pass),
+          deep: !unavailable && support.deep ? baseRequest(pass, true) : null,
+        },
       };
     })),
+    master: {
+      id: MASTER_PASS.task,
+      title: MASTER_PASS.title,
+      description: MASTER_PASS.description,
+      request: MASTER_PASS.request,
+      skill: `genesis-${MASTER_PASS.task}`,
+      lastRun: masterRecord?.lastRun ?? null,
+      lastPasses: masterRecord?.passes ?? null,
+      unavailable: masterUnavailable,
+      passes: masterUnavailable ? [] : masterOffered(support).map(({ task }) => task),
+      runs: masterUnavailable ? [] : masterRuns(since, whole, changed),
+    },
   };
 }
 
@@ -559,23 +713,44 @@ export async function generateProjectPrompt({
   }
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const userRequest = requestText(request, task);
-  // A pass task's prompt sends the agent to the project's own Genesis skill for it, so that Genesis must have it.
+  // A pass task's prompt sends the agent to the project's own Genesis skill for it, so that Genesis must have it; a
+  // Master pass runs other passes deeply through that Genesis, so it must run them too. A self-contained pass's prompt
+  // needs no skill, so without it the task still runs, with no run of its own but one over a base.
   const pass = PASSES.find((entry) => entry.task === task);
-  const passSupport = pass ? await projectPassSupport(root) : null;
-  if (pass && !passSupport.has(pass)) {
+  const master = task === MASTER_PASS.task;
+  const passSupport = pass || master ? await projectPassSupport(root) : null;
+  const ownRuns = Boolean(pass) && passSupport.has(pass);
+  if (pass && !ownRuns && !pass.selfContained) {
     throw new GenesisError('PASS_UNAVAILABLE', passSupport.unavailableFor(pass), { pass: task });
   }
-  // The pass's runs, to recognise one of their requests; a malformed record leaves only the whole run, with a warning.
+  if (master && passSupport.unavailableFor(MASTER_PASS)) {
+    throw new GenesisError('PASS_UNAVAILABLE', passSupport.unavailableFor(MASTER_PASS), { pass: task });
+  }
+  // The pass's runs, to recognise one of their requests; a malformed record leaves only the whole and deep runs, with a
+  // warning. A Master pass since its last completed run runs each pass deeply over the same changes, so that request is
+  // the pass's too. Any other request may be a run over a base the host chose.
   const passWarnings = [];
-  let runs = pass ? passRuns(pass, null) : [];
-  if (pass) {
+  let runs = ownRuns ? passRuns(pass, null, passSupport.deep) : [];
+  if (ownRuns) {
     try {
-      runs = await projectPassRuns(root, pass, (await readPassRecord(root))[task] ?? null);
+      const { record, unknown } = await inspectPassRecord(root);
+      if (unknown.length) {
+        passWarnings.push(asDiagnostic(new GenesisError('PASS_RECORD_UNKNOWN', unknownRecordMessage(unknown))));
+      }
+      runs = await projectPassRuns(root, pass, record[task] ?? null, passSupport.deep);
+      const since = passSupport.deep ? await masterSince(root, record) : null;
+      if (since) runs.push({ id: 'deep-since', request: deepRequest(pass, since.commit), commit: since.commit });
     } catch (error) {
       if (error?.code !== 'PASS_RECORD_INVALID') throw error;
       passWarnings.push(asDiagnostic(error));
     }
   }
+  const run = pass
+    ? requestedRun(runs, userRequest) ?? await baseRun(root, pass, userRequest, ownRuns && passSupport.deep)
+    : null;
+  const masterGuidance = master
+    ? await masterPromptGuidance({ root, request: userRequest, support: passSupport })
+    : null;
   const openingInspection = task === 'start' ? await inspectProject({ projectRoot: root, stackPackages }) : null;
   if (openingInspection) {
     const inspection = openingInspection;
@@ -585,10 +760,12 @@ export async function generateProjectPrompt({
         warnings: inspection.diagnostics, verificationCommands: [] };
     }
   }
-  const [instructions, collaboration, engineering] = await Promise.all([
+  const [instructions, collaboration, engineering, passReport, deepGuidance] = await Promise.all([
     readInstalledAsset(task),
     collaborationForPrompt(root),
     readEngineering(root),
+    pass || master ? readInstalledAsset('pass-report') : '',
+    ['deep', 'deep-since', 'deep-base'].includes(run?.id) ? deepRunGuidance(root, task) : '',
   ]);
   const sessionPrompt = stableSessionPromptParts({
     collaboration,
@@ -732,7 +909,14 @@ export async function generateProjectPrompt({
     guidance: stack.guidance,
     skills: renderAgentSkillCatalog(projectSkills.skills),
     postChange: task === 'work' ? stack.postChange : '',
-    passGuidance: passPromptGuidance(task, stack, userRequest, passSupport, runs),
+    passGuidance: masterGuidance ? { ...masterGuidance, report: passReport } : passPromptGuidance({
+      pass,
+      stack,
+      run,
+      support: passSupport,
+      report: passReport,
+      deep: deepGuidance,
+    }),
   });
   return {
     status: 'ready',

package/src/index/source-size.js

@@ -0,0 +1,62 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { isProjectContentPath } from './paths.js';
+import { runGit } from './process.js';
+import { visiblePaths } from './project-files.js';
+
+// Written by package managers, never the project's own source.
+const LOCKFILES = new Set([
+  'Cargo.lock', 'Gemfile.lock', 'Package.resolved', 'Pipfile.lock', 'Podfile.lock', 'bun.lock', 'bun.lockb',
+  'composer.lock', 'go.sum', 'gradle.lockfile', 'mix.lock', 'npm-shrinkwrap.json', 'package-lock.json',
+  'packages.lock.json', 'pnpm-lock.yaml', 'poetry.lock', 'pubspec.lock', 'uv.lock', 'yarn.lock',
+]);
+const BATCH = 32;
+
+/** The folders the selected Stack discovers packages in, such as dependency folders it declares. */
+export function stackPackageRoots(stack) {
+  return stack.packageDiscovery.discoveries.flatMap((discovery) => discovery.manifests
+    .map((manifest) => path.posix.join(path.posix.dirname(manifest), discovery.packageRoot)));
+}
+
+function lineCount(content) {
+  let lines = 0;
+  for (let index = content.indexOf(10); index !== -1; index = content.indexOf(10, index + 1)) lines += 1;
+  return content.length > 0 && content.at(-1) !== 10 ? lines + 1 : lines;
+}
+
+/**
+ * The project's own source a pass covers, each file with its line count: Git-visible text files outside Genesis's
+ * own files, the Stack's package folders and lockfiles. One walk, one Git listing and one read per file, whatever is
+ * sized from it, so a listing costs what the project's files cost, never that times its passes.
+ * @returns {Promise<Map<string, number>>}
+ */
+export async function projectSourceLines(root, stack) {
+  const packageRoots = stackPackageRoots(stack);
+  const files = (await visiblePaths(root)).filter((file) => isProjectContentPath(file)
+    && !LOCKFILES.has(path.posix.basename(file))
+    && !packageRoots.some((directory) => file === directory || file.startsWith(`${directory}/`)));
+  const lines = new Map();
+  for (let index = 0; index < files.length; index += BATCH) {
+    await Promise.all(files.slice(index, index + BATCH).map(async (file) => {
+      const full = path.join(root, file);
+      // A link, folder or binary file is not source an agent reads line by line.
+      if (!(await lstat(full)).isFile()) return;
+      const content = await readFile(full);
+      if (!content.includes(0)) lines.set(file, lineCount(content));
+    }));
+  }
+  return new Map([...lines].sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
+/** The number of files and lines among `sources`, of all of them or of only `files`. */
+export function sourceSize(sources, files = [...sources.keys()]) {
+  const sized = files.filter((file) => sources.has(file));
+  return { files: sized.length, lines: sized.reduce((total, file) => total + sources.get(file), 0) };
+}
+
+/** The files the changes since `commit` touch, as `git diff <commit>` shows them. */
+export async function changedSince(root, commit) {
+  const { stdout } = await runGit(root, ['diff', '--name-only', '-z', commit, '--']);
+  return stdout.toString('utf8').split('\0').filter(Boolean);
+}

package/src/index.js

@@ -202,7 +202,11 @@ export function inspectPasses(options) {
   return inspectProjectPasses(options);
 }
 
-/** Records in genesis/passes.json that the pass `pass` finished now; a pass's own last step. */
+/**
+ * Records that the pass `pass` finished now, in genesis/passes.json for the passes Genesis 1.10.21 knew and in
+ * genesis/passes-added.json for every pass added since; a pass's own last step. The Master pass also names the passes
+ * it ran (`passes`), which it records with it.
+ */
 export function recordPassDone(options) {
   return recordProjectPassDone(options);
 }