genesis-compiler 1.10.21 → 1.10.23

package/src/index/pass-record.js

@@ -3,28 +3,50 @@ import path from 'node:path';
 
 import { fail } from './errors.js';
 import { gitContext } from './git.js';
-import { PASSES } from './passes.js';
+import { MASTER_PASS, PASSES } from './passes.js';
 import { runGitText } from './process.js';
 import { inspectProjectFormatAtRoot } from './project-format.js';
 import { stableJson, writeFileAtomic } from './utils.js';
 
 // When each pass last finished, committed with the project so every clone and host sees the same record:
-// `{ "<pass id>": "<UTC time>" }`. The pass's own last step writes it, so it lands in the pass's commit and a pass
-// that never finished is never recorded.
+// `{ "<pass id>": "<UTC time>" }`, and the Master pass's time with the passes it ran,
+// `"master-pass": { "lastRun": "<UTC time>", "passes": ["<pass id>", ...] }`. The pass's own last step writes it, so
+// it lands in the pass's commit and a pass that never finished is never recorded.
+// Two files, so that a Genesis older than a pass never meets its record: genesis-compiler 1.10.21 and earlier read only
+// `genesis/passes.json` and refuse an id they do not know, so that file keeps the passes they know, and every pass
+// added since, the Master pass among them, is recorded in `genesis/passes-added.json`. This Genesis keeps an entry it
+// does not know, which a newer Genesis wrote, and leaves it unused, so a pass added later never strands it.
 export const PASS_RECORD_PATH = 'genesis/passes.json';
+export const ADDED_PASS_RECORD_PATH = 'genesis/passes-added.json';
 
+const FIRST_PASS_IDS = Object.freeze([
+  'deslop', 'ui-pass', 'identity-pass', 'quality-pass', 'data-pass', 'security-pass', 'ux-pass', 'speed-pass',
+]);
 const PASS_IDS = PASSES.map(({ task }) => task);
+const RECORDED_IDS = [...PASS_IDS, MASTER_PASS.task];
 const UTC_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
 
-function invalidRecord(problem) {
-  fail('PASS_RECORD_INVALID', `${PASS_RECORD_PATH} ${problem}. It maps pass ids (${PASS_IDS.join(', ')}) to UTC times such as 2026-01-31T09:30:00Z; fix or remove the entry.`, { path: PASS_RECORD_PATH });
+/** The file that records `pass`. */
+export function passRecordPath(pass) {
+  return FIRST_PASS_IDS.includes(pass) ? PASS_RECORD_PATH : ADDED_PASS_RECORD_PATH;
 }
 
-/** The project's pass record: each recorded pass id with the UTC time it last finished. A missing file records none. */
-export async function readPassRecord(root) {
+function invalidRecord(file, problem) {
+  fail('PASS_RECORD_INVALID', `${file} ${problem}. It maps pass ids to UTC times such as 2026-01-31T09:30:00Z, and ${MASTER_PASS.task} to { "lastRun": <UTC time>, "passes": [<pass id>, ...] }; fix or remove the entry.`, { path: file });
+}
+
+const utcTime = (value) => typeof value === 'string' && UTC_TIME.test(value) && !Number.isNaN(Date.parse(value));
+
+// The passes a Master pass ran: pass ids, each once, at least one. A record may name a pass a newer Genesis added; a
+// Master pass recorded here names only passes this Genesis has.
+const passList = (value, known = null) => Array.isArray(value) && value.length > 0
+  && new Set(value).size === value.length
+  && value.every((id) => typeof id === 'string' && (!known || known.includes(id)));
+
+async function readRecordFile(root, file) {
   let source;
   try {
-    source = await readFile(path.join(root, PASS_RECORD_PATH), 'utf8');
+    source = await readFile(path.join(root, file), 'utf8');
   } catch (error) {
     if (error?.code === 'ENOENT') return {};
     throw error;
@@ -33,38 +55,92 @@ export async function readPassRecord(root) {
   try {
     record = JSON.parse(source);
   } catch (error) {
-    invalidRecord(`is not JSON (${error.message})`);
+    invalidRecord(file, `is not JSON (${error.message})`);
   }
-  if (record === null || typeof record !== 'object' || Array.isArray(record)) invalidRecord('is not a JSON object');
-  for (const [id, time] of Object.entries(record)) {
-    if (!PASS_IDS.includes(id)) invalidRecord(`names ${JSON.stringify(id)}, which is not a pass`);
-    if (typeof time !== 'string' || !UTC_TIME.test(time) || Number.isNaN(Date.parse(time))) {
-      invalidRecord(`records ${JSON.stringify(time)} for ${id}, which is not a UTC time`);
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) invalidRecord(file, 'is not a JSON object');
+  return record;
+}
+
+/**
+ * The project's pass record, from both files: each recorded pass id with the UTC time it last finished, and the Master
+ * pass's time with the passes it ran; and, as `unknown`, the entries this Genesis does not know, which it keeps and
+ * does not use. Missing files record none.
+ * @returns {Promise<{ record: object, unknown: { id: string, path: string }[] }>}
+ */
+export async function inspectPassRecord(root) {
+  const record = {};
+  const unknown = [];
+  for (const file of [PASS_RECORD_PATH, ADDED_PASS_RECORD_PATH]) {
+    for (const [id, value] of Object.entries(await readRecordFile(root, file))) {
+      if (!RECORDED_IDS.includes(id)) {
+        unknown.push({ id, path: file });
+        continue;
+      }
+      if (passRecordPath(id) !== file) invalidRecord(file, `records ${id}, which belongs in ${passRecordPath(id)}; move the entry there`);
+      if (id === MASTER_PASS.task) {
+        if (!utcTime(value?.lastRun) || !passList(value?.passes) || Object.keys(value).length !== 2) {
+          invalidRecord(file, `records ${JSON.stringify(value)} for ${id}, which is not a UTC time with the passes it ran`);
+        }
+      } else if (!utcTime(value)) {
+        invalidRecord(file, `records ${JSON.stringify(value)} for ${id}, which is not a UTC time`);
+      }
+      record[id] = value;
     }
   }
-  return record;
+  return { record, unknown };
 }
 
-/** Records that `pass` finished now, as its last step. */
-export async function recordProjectPassDone({ projectRoot, pass, now = new Date() } = {}) {
-  if (!PASS_IDS.includes(pass)) {
-    fail('PASS_UNKNOWN', `${JSON.stringify(pass)} is not a pass; use one of ${PASS_IDS.join(', ')}.`);
+/** The project's pass record: each pass id this Genesis knows with its last finished run. */
+export async function readPassRecord(root) {
+  return (await inspectPassRecord(root)).record;
+}
+
+/** What a reader says about entries it does not know: a newer Genesis wrote them, and updating Genesis uses them. */
+export function unknownRecordMessage(unknown) {
+  const names = unknown.map(({ id, path: file }) => `${id} (${file})`).join(', ');
+  return `The pass record names passes this Genesis does not know: ${names}. A newer Genesis recorded them; they are `
+    + 'kept as they are. Update genesis-compiler to the release that has them to use those records.';
+}
+
+/**
+ * Records that `pass` finished now, as its last step; the Master pass records the passes it ran with it, in the order
+ * it runs them. Entries this Genesis does not know stay as they are.
+ */
+export async function recordProjectPassDone({ projectRoot, pass, passes = [], now = new Date() } = {}) {
+  if (!RECORDED_IDS.includes(pass)) {
+    fail('PASS_UNKNOWN', `${JSON.stringify(pass)} is not a pass this Genesis knows; use one of ${RECORDED_IDS.join(', ')}, or update genesis-compiler to the release that added it.`);
+  }
+  const master = pass === MASTER_PASS.task;
+  if (master ? !passList(passes, PASS_IDS) : passes.length > 0) {
+    fail('PASS_RECORD_PASSES_INVALID', master
+      ? `The ${MASTER_PASS.title} records the passes it ran, each once: name at least one of ${PASS_IDS.join(', ')}.`
+      : `Only the ${MASTER_PASS.title} records the passes it ran; record ${pass} on its own.`);
   }
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const format = await inspectProjectFormatAtRoot(root);
   if (format.status !== 'current') {
     fail('PASS_RECORD_PROJECT_REQUIRED', `Passes are recorded in a current Genesis project; this one is ${format.status} (next action: ${format.action}).`);
   }
+  await inspectPassRecord(root);
+  const file = passRecordPath(pass);
   const lastRun = now.toISOString().replace(/\.\d{3}Z$/u, 'Z');
-  const record = { ...await readPassRecord(root), [pass]: lastRun };
-  await writeFileAtomic(path.join(root, PASS_RECORD_PATH), stableJson(record));
-  return { status: 'recorded', pass, lastRun, path: PASS_RECORD_PATH, changedFiles: [PASS_RECORD_PATH] };
+  const ran = MASTER_PASS.order.filter((id) => passes.includes(id));
+  const entries = { ...await readRecordFile(root, file), [pass]: master ? { lastRun, passes: ran } : lastRun };
+  await writeFileAtomic(path.join(root, file), stableJson(entries));
+  return {
+    status: 'recorded',
+    pass,
+    lastRun,
+    ...(master ? { passes: ran } : {}),
+    path: file,
+    changedFiles: [file],
+  };
 }
 
 /**
  * The commit that recorded a pass's last completed run, which is the pass's own commit, and the commits since it on
  * HEAD; null when the run is not committed or that commit is no longer in HEAD's history. Git keeps it: the commit
- * that added this exact entry to the record file, so nothing else is stored.
+ * that added this exact entry to the pass's record file (for the Master pass, its time), so nothing else is stored.
  * @param {string} root the project's repository root
  * @param {string} pass the pass id
  * @param {string | null} lastRun the run's UTC time, from readPassRecord
@@ -79,7 +155,8 @@ export async function passRecordCommit(root, pass, lastRun) {
     if (error?.code === 'GIT_EXEC_FAILED') return null;
     throw error;
   }
-  const commit = await runGitText(root, ['log', '-1', '--format=%h', `-S"${pass}": "${lastRun}"`, 'HEAD', '--', PASS_RECORD_PATH]);
+  const entry = pass === MASTER_PASS.task ? `"lastRun": "${lastRun}"` : `"${pass}": "${lastRun}"`;
+  const commit = await runGitText(root, ['log', '-1', '--format=%h', `-S${entry}`, 'HEAD', '--', passRecordPath(pass)]);
   if (!commit) return null;
   const commitsSince = Number(await runGitText(root, ['rev-list', '--count', `${commit}..HEAD`]));
   return { commit, commitsSince };

package/src/index/pass-support.js

@@ -25,7 +25,8 @@ async function readManifest(directory) {
  * Which of this Genesis's passes the project's own Genesis runs. A pass's prompt sends the agent to that Genesis's
  * workflow skill, and its PASS RECORD step to that Genesis's `passes done`, so that Genesis alone decides, from what
  * it ships: it runs passes when its package declares this pass-run contract (`genesisContracts.passRuns`), and it has
- * a pass when its skills folder holds the pass's workflow skill. A project pinned to a release without either, or
+ * a pass when its skills folder holds the pass's workflow skill, and it runs each pass's Deep run when its package also
+ * declares the deep-run contract (`genesisContracts.deepRuns`). A project pinned to a release without either, or
  * whose pinned release is not installed, is told plainly, with the step that fixes it; nothing else stands in for
  * that release.
  * @param {string} projectRoot the project's repository root
@@ -62,6 +63,8 @@ export async function projectPassSupport(projectRoot) {
     unavailable,
     /** Whether the project's Genesis has the pass's task, which its prompt needs even when no pass is recorded. */
     has,
+    /** Whether the project's Genesis runs each pass's Deep run: its package declares this deep-run contract. */
+    deep: unavailable === null && own.genesisContracts.deepRuns === GENESIS_CONTRACTS.deepRuns,
     /** Why the project's Genesis cannot run this pass, naming the update; null when it can. */
     unavailableFor: (pass) => unavailable ?? (has(pass) ? null : `${named} has no ${pass.title}. ${update}`),
   };

package/src/index/passes.js

@@ -6,7 +6,11 @@
  * The task's request when none is given is the task's own (prompt.js), which for Deslop and the UI pass stays the
  * agent's own changes.
  * A host lists the passes with inspectPasses() and decides itself when to offer one: `recommend` is a hint
- * (`when`: `after-change`, `first-version` or `periodic`), never a schedule.
+ * (`when`: `after-change`, `first-version` or `periodic`), never a schedule. A host may also run a pass over the
+ * changes since a base commit it chooses, such as where a piece of work started (baseRequest); Genesis never records
+ * those runs, so they never move the pass's last completed run.
+ * `selfContained` marks a pass whose prompt carries all its instructions, without its skill: it was a task before it
+ * was a pass, so it still runs as that task, and over a base, where the project's own Genesis lacks the pass.
  */
 export const PASSES = Object.freeze([
   {
@@ -89,4 +93,54 @@ export const PASSES = Object.freeze([
     field: 'speedPass',
     heading: 'SELECTED STACK SPEED PASS GUIDANCE',
   },
+  {
+    task: 'review',
+    title: 'Review',
+    description: 'Checks the work against what the app should do: a test that would fail without each behavior, nothing weakened or skipped, and gaps between intent, code and explanation, changing only tests.',
+    recommend: { when: 'after-change', hint: 'after each saved change' },
+    request: 'Review the whole app.',
+    section: 'Review',
+    field: 'review',
+    heading: 'SELECTED STACK REVIEW GUIDANCE',
+    selfContained: true,
+  },
 ].map((pass) => Object.freeze({ ...pass, recommend: Object.freeze(pass.recommend) })));
+
+/**
+ * The Master pass: the passes run deeply, one after another, each as its own Deep run, committed and tested before the
+ * next starts. It runs every pass the project offers, or the ones a request names, always in `order`, whatever order
+ * they were named in: the review first, so every later pass starts from tested work, then security, so later passes
+ * build on the access it fixes, and Deslop last, so it cleans up after what the others changed. Every pass has a place
+ * in `order`; a pass added later takes one there.
+ */
+export const MASTER_PASS = Object.freeze({
+  task: 'master-pass',
+  title: 'Master pass',
+  description: 'Runs every pass deeply, one after another, or the passes you choose, committing and running the whole test suite after each.',
+  request: 'Master pass the whole app.',
+  order: Object.freeze([
+    'review', 'security-pass', 'data-pass', 'quality-pass', 'speed-pass', 'ux-pass', 'identity-pass', 'ui-pass', 'deslop',
+  ]),
+});
+
+/**
+ * The request of a pass's Deep run: its pass request deeply, or, for a Master pass since its last completed run, the
+ * changes since that commit deeply, judged against the whole app.
+ * @param {{ title: string, request: string }} pass
+ * @param {string | null} [commit] the commit of the Master pass's last completed run, for a run since it
+ */
+export function deepRequest(pass, commit = null) {
+  return commit
+    ? `${pass.title} deeply: the changes since commit ${commit}, judged against the whole app.`
+    : pass.request.replace(/\.$/u, ' deeply.');
+}
+
+/**
+ * The request of a run over the changes since a base commit a host chooses, judged against the whole app, or of its
+ * deep form; `{base}` stands for the commit. Genesis never records these runs.
+ * @param {{ title: string }} pass
+ * @param {boolean} [deep]
+ */
+export function baseRequest(pass, deep = false) {
+  return `${pass.title}${deep ? ' deeply' : ''}: the changes since base commit {base}, judged against the whole app.`;
+}

package/src/index/project-files.js

@@ -4,7 +4,8 @@ import { runGit } from './process.js';
 import { pathState } from './utils.js';
 import { inspectProjectContent } from './project-inspection.js';
 
-async function visiblePaths(projectRoot) {
+/** Git-visible paths: tracked and untracked files that are not ignored or deleted, sorted. */
+export async function visiblePaths(projectRoot) {
   const [visible, deleted] = await Promise.all([
     runGit(projectRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.']),
     runGit(projectRoot, ['ls-files', '-z', '--deleted', '--', '.']),