genesis-compiler 1.10.18 → 1.10.20

package/src/index/assets.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 
+import { PASSES } from './passes.js';
+
 const root = new URL('../../', import.meta.url);
 const assets = {
   start: new URL('prompts/start.txt', root),
@@ -9,8 +11,7 @@ const assets = {
   adopt: new URL('prompts/adopt.txt', root),
   work: new URL('prompts/work.txt', root),
   describe: new URL('prompts/describe.txt', root),
-  deslop: new URL('prompts/deslop.txt', root),
-  'ui-pass': new URL('prompts/ui-pass.txt', root),
+  ...Object.fromEntries(PASSES.map(({ task }) => [task, new URL(`prompts/${task}.txt`, root)])),
   program: new URL('prompts/program.txt', root),
   blueprint: new URL('prompts/blueprint.txt', root),
   review: new URL('prompts/review.txt', root),

package/src/index/contracts.js

@@ -2,6 +2,7 @@ export const GENESIS_CONTRACTS = Object.freeze({
   subsystems: 'genesis.subsystems.v0',
   projectInspection: 'genesis.project-inspection.v1',
   promptTasks: 'genesis.prompt-tasks.v1',
+  passes: 'genesis.passes.v1',
   templates: 'genesis.templates.v1',
   templateApplication: 'genesis.template-application.v1',
   collaboration: 'genesis.collaboration.v1',

package/src/index/pass-record.js

@@ -0,0 +1,61 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { fail } from './errors.js';
+import { gitContext } from './git.js';
+import { PASSES } from './passes.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.
+export const PASS_RECORD_PATH = 'genesis/passes.json';
+
+const PASS_IDS = PASSES.map(({ task }) => 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 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) {
+  let source;
+  try {
+    source = await readFile(path.join(root, PASS_RECORD_PATH), 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+  let record;
+  try {
+    record = JSON.parse(source);
+  } catch (error) {
+    invalidRecord(`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`);
+    }
+  }
+  return record;
+}
+
+/** 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(', ')}.`);
+  }
+  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}).`);
+  }
+  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] };
+}

package/src/index/passes.js

@@ -0,0 +1,59 @@
+/**
+ * The passes: operations a person asks for by name over a scope of the project, never run because a turn finished.
+ * Each is a prompt task (`task`) with a workflow skill (`genesis-<task>`) and a Stack section (`section`), whose prose
+ * the selected components add to the task's prompt under `heading`. `request` is the request when none is given.
+ * 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.
+ */
+export const PASSES = Object.freeze([
+  {
+    task: 'deslop',
+    title: 'Deslop',
+    description: 'Simplifies changes without changing what they do: no repeated helpers, unclear code or code that ignores the project\'s patterns.',
+    recommend: { when: 'after-change', hint: 'after each saved change' },
+    request: 'Deslop your own changes for the current task.',
+    section: 'Deslop',
+    field: 'deslop',
+    heading: 'SELECTED STACK CLEANUP GUIDANCE',
+  },
+  {
+    task: 'ui-pass',
+    title: 'UI pass',
+    description: 'Makes screens follow the design rules of the project\'s technology exactly, without changing what they do.',
+    recommend: { when: 'after-change', hint: 'after a change to the screens' },
+    request: 'UI pass your own changes for the current task.',
+    section: 'UI pass',
+    field: 'uiPass',
+    heading: 'SELECTED STACK UI PASS GUIDANCE',
+  },
+  {
+    task: 'identity-pass',
+    title: 'Visual identity',
+    description: 'Gives the app a look of its own: one seed colour, artwork drawn for its content, a logo, empty states, a loading screen and a sign-in page.',
+    recommend: { when: 'first-version', hint: 'once a first working version exists' },
+    request: 'Give the whole app its visual identity.',
+    section: 'Identity pass',
+    field: 'identityPass',
+    heading: 'SELECTED STACK IDENTITY PASS GUIDANCE',
+  },
+  {
+    task: 'quality-pass',
+    title: 'Quality pass',
+    description: 'Makes the app hold up in use: loading, empty and error states, edge cases, refusals the person understands and accessibility, checked by using it.',
+    recommend: { when: 'periodic', hint: 'after a stretch of changes, about every few weeks of active work' },
+    request: 'Quality pass the whole app.',
+    section: 'Quality pass',
+    field: 'qualityPass',
+    heading: 'SELECTED STACK QUALITY PASS GUIDANCE',
+  },
+  {
+    task: 'data-pass',
+    title: 'Data pass',
+    description: 'Makes data hold up at real sizes: queries that grow with the rows read, enforced constraints, safe migrations and indexes for real filters, tested at realistic sizes.',
+    recommend: { when: 'periodic', hint: 'after a stretch of changes, about every few weeks of active work' },
+    request: 'Data pass the whole app.',
+    section: 'Data pass',
+    field: 'dataPass',
+    heading: 'SELECTED STACK DATA PASS GUIDANCE',
+  },
+].map((pass) => Object.freeze({ ...pass, recommend: Object.freeze(pass.recommend) })));

package/src/index/project-inspection.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
+import { CORE_SKILL_NAMES } from './agent-skills.js';
 import { readBlueprint } from './blueprint.js';
 import { readCollaboration } from './collaboration.js';
 import { GENESIS_DERIVED_ARTIFACTS_GITIGNORE_LINES } from './code-index.js';
@@ -29,7 +30,7 @@ export const GENESIS_BOOTSTRAP_PATHS = Object.freeze([
   '.claude/settings.json',
   '.opencode/plugins/genesis-project-guidance.js',
   '.agents/skills/.genesis-managed.json',
-  ...['genesis-project', 'genesis-program', 'genesis-deslop', 'genesis-ui-pass'].flatMap((name) => [
+  ...CORE_SKILL_NAMES.flatMap((name) => [
     `.claude/skills/${name}`,
     `.agents/skills/${name}/SKILL.md`,
     `.agents/skills/${name}/agents/openai.yaml`,

package/src/index/prompt.js

@@ -22,14 +22,15 @@ 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, readPassRecord } from './pass-record.js';
 
-const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'ui-pass', 'program', 'blueprint', 'describe', 'review']);
+const TASKS = new Set(['start', 'adopt', 'work', ...PASSES.map(({ task }) => task), 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
   start: 'Start a conversation about this project.',
   adopt: 'Import the existing project into a truthful Genesis project contract.',
   work: 'Implement the product intent expressed by the current Blueprint.',
-  deslop: 'Deslop your own changes for the current task.',
-  'ui-pass': 'UI pass your own changes for the current task.',
+  ...Object.fromEntries(PASSES.map(({ task, request }) => [task, 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.',
@@ -132,8 +133,7 @@ function renderPrompt({
   context,
   skills = '',
   guidance = '',
-  cleanup = '',
-  uiPass = '',
+  passGuidance = null,
   postChange = '',
   adoption = '',
   collaborationGuidance = '',
@@ -157,12 +157,30 @@ function renderPrompt({
     ...(adoption ? ['', 'SELECTED STACK ADOPTION GUIDANCE', '', adoption] : []),
     ...(skills ? ['', 'AVAILABLE AGENT SKILLS', '', skills] : []),
     ...(postChange ? ['', 'SELECTED STACK POST-CHANGE GUIDANCE', '', postChange] : []),
-    ...(cleanup ? ['', 'SELECTED STACK CLEANUP GUIDANCE', '', cleanup] : []),
-    ...(uiPass ? ['', 'SELECTED STACK UI PASS GUIDANCE', '', uiPass] : []),
+    ...(passGuidance?.text ? ['', passGuidance.heading, '', passGuidance.text] : []),
+    ...(passGuidance ? ['', 'PASS RECORD', '', passRecordStep(passGuidance.task)] : []),
     '',
   ].join('\n');
 }
 
+// A pass task's selected Stack prose under its own heading; null for every other task.
+function passPromptGuidance(task, stack) {
+  const pass = PASSES.find((entry) => entry.task === task);
+  return pass ? { task, heading: pass.heading, text: stack[pass.field] } : null;
+}
+
+// Every pass prompt ends with recording the pass, so the record lands in the pass's own commit.
+function passRecordStep(task) {
+  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',
+    'stopped early, was abandoned, or still has failing checks.',
+  ].join('\n');
+}
+
 function collaborationPromptContext(collaboration) {
   return {
     path: collaboration.path,
@@ -410,19 +428,47 @@ async function generateStartPrompt({
 
 /**
  * The prompt tasks Genesis renders, each with whether the selected Stack adds its own guidance to that task (Adoption,
- * Post-change, Deslop or UI pass prose). A host offers a Stack-dependent operation, such as an automatic UI pass,
+ * Post-change or a pass's prose). A host offers a Stack-dependent operation, such as an automatic UI pass,
  * from this answer instead of inferring it from component ids.
  */
 export async function inspectProjectPromptTasks({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root, { stackPackages });
-  const lanes = { adopt: stack.adoption, work: stack.postChange, deslop: stack.deslop, 'ui-pass': stack.uiPass };
+  const lanes = {
+    adopt: stack.adoption,
+    work: stack.postChange,
+    ...Object.fromEntries(PASSES.map(({ task, field }) => [task, stack[field]])),
+  };
   return {
     contract: GENESIS_CONTRACTS.promptTasks,
     tasks: [...TASKS].map((task) => ({ task, stackGuidance: Boolean(lanes[task]) })),
   };
 }
 
+/**
+ * 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 request used when none is given, its
+ * workflow skill, whether the selected Stack adds its own guidance to it, and when it last finished (`lastRun`, a UTC
+ * time from genesis/passes.json, or null).
+ */
+export async function inspectProjectPasses({ projectRoot, stackPackages = [] } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const [stack, record] = await Promise.all([readStack(root, { stackPackages }), readPassRecord(root)]);
+  return {
+    contract: GENESIS_CONTRACTS.passes,
+    passes: PASSES.map(({ task, title, description, recommend, request, field }) => ({
+      id: task,
+      title,
+      description,
+      recommend: { ...recommend },
+      request,
+      skill: `genesis-${task}`,
+      stackGuidance: Boolean(stack[field]),
+      lastRun: record[task] ?? null,
+    })),
+  };
+}
+
 export async function generateProjectPrompt({
   environment = process.env,
   hiddenStackPieces = [],
@@ -592,8 +638,7 @@ export async function generateProjectPrompt({
     guidance: stack.guidance,
     skills: renderAgentSkillCatalog(projectSkills.skills),
     postChange: task === 'work' ? stack.postChange : '',
-    cleanup: task === 'deslop' ? stack.deslop : '',
-    uiPass: task === 'ui-pass' ? stack.uiPass : '',
+    passGuidance: passPromptGuidance(task, stack),
   });
   return {
     status: 'ready',

package/src/index/stack-piece.js

@@ -2,6 +2,7 @@ import { GenesisError } from './errors.js';
 import { parseStackCityPresentationLines } from './stack-city-presentation.js';
 import { parseStackEnvironmentDefaultLines } from './stack-environment-defaults.js';
 import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
+import { PASSES } from './passes.js';
 import { opaqueStackSections } from './stack-section.js';
 import { parseStackVerificationLines } from './stack-verification.js';
 import { normalizeSource } from './utils.js';
@@ -15,15 +16,16 @@ const STACK_CUSTOMIZATION_FIELDS = new Map([
   ['Guidance', 'guidance'],
   ['Adoption', 'adoption'],
   ['Post-change', 'postChange'],
-  ['Deslop', 'deslop'],
-  ['UI pass', 'uiPass'],
+  ...PASSES.map(({ section, field }) => [section, field]),
 ]);
+const CUSTOMIZATION_FIELD_LIST = [...STACK_CUSTOMIZATION_FIELDS.keys()]
+  .map((name, index, names) => (index === names.length - 1 ? `or ${name}` : name))
+  .join(', ');
 const STACK_PIECE_SECTIONS = new Set([
   'Adoption',
   'City regions',
   'Conflicts',
   'Description',
-  'Deslop',
   'Environment defaults',
   'Environment files',
   'Guidance',
@@ -32,8 +34,8 @@ const STACK_PIECE_SECTIONS = new Set([
   'Requires',
   'Resources',
   'Skill',
-  'UI pass',
   'Verification',
+  ...PASSES.map(({ section }) => section),
 ]);
 
 export function normalizeStackPieceId(value, {
@@ -117,12 +119,12 @@ function customizationSections(source, piecePath) {
     if (/^#{1,3}\s+/u.test(line)) invalid(piecePath, `Unknown customization heading: ${line.trim()}.`);
     if (field) content.push(line);
     else if (line.trim()) {
-      invalid(piecePath, 'Customization content must be below Description, Guidance, Adoption, Post-change, Deslop, or UI pass.');
+      invalid(piecePath, `Customization content must be below ${CUSTOMIZATION_FIELD_LIST}.`);
     }
   }
   finishField();
   if (Object.values(result).every((values) => Object.keys(values).length === 0)) {
-    invalid(piecePath, 'Stack customization must add or override Description, Guidance, Adoption, Post-change, Deslop, or UI pass.');
+    invalid(piecePath, `Stack customization must add or override ${CUSTOMIZATION_FIELD_LIST}.`);
   }
   return result;
 }
@@ -330,8 +332,6 @@ export function parseStackPieceSource(value, {
   const guidance = textSection(all, 'Guidance');
   const adoption = textSection(all, 'Adoption');
   const postChange = textSection(all, 'Post-change');
-  const deslop = textSection(all, 'Deslop');
-  const uiPass = textSection(all, 'UI pass');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const verificationCommands = parseStackVerificationLines(
     all.get('Verification') || [],
@@ -366,8 +366,7 @@ export function parseStackPieceSource(value, {
     environmentDefaults,
     environmentFiles: environmentFiles || [],
     extensions: opaqueStackSections(all, STACK_PIECE_SECTIONS),
-    deslop,
-    uiPass,
+    ...Object.fromEntries(PASSES.map(({ section, field }) => [field, textSection(all, section)])),
   };
 }
 
@@ -415,7 +414,9 @@ export function applyStackPieceCustomization(piece, customization) {
       customization.override.postChange,
       customization.add.postChange,
     ),
-    deslop: customizedText(piece.deslop, customization.override.deslop, customization.add.deslop),
-    uiPass: customizedText(piece.uiPass, customization.override.uiPass, customization.add.uiPass),
+    ...Object.fromEntries(PASSES.map(({ field }) => [
+      field,
+      customizedText(piece[field], customization.override[field], customization.add[field]),
+    ])),
   };
 }

package/src/index/stack.js

@@ -38,6 +38,7 @@ import {
   parseStackPieceCustomizationSource,
   parseStackResourceLines,
 } from './stack-piece.js';
+import { PASSES } from './passes.js';
 import { STACK_PATH } from './paths.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
@@ -413,8 +414,7 @@ async function readStackWithContractMode(projectRoot, {
     guidance: composedProse(components, 'guidance'),
     adoption: composedProse(components, 'adoption'),
     postChange: composedProse(components, 'postChange'),
-    deslop: composedProse(components, 'deslop'),
-    uiPass: composedProse(components, 'uiPass'),
+    ...Object.fromEntries(PASSES.map(({ field }) => [field, composedProse(components, field)])),
   };
 }
 

package/src/index.js

@@ -12,7 +12,8 @@ import {
 } from './index/collaboration.js';
 import { GENESIS_CONTRACTS } from './index/contracts.js';
 import { contextForProjectPaths } from './index/context.js';
-import { generateProjectPrompt, inspectProjectPromptTasks } from './index/prompt.js';
+import { generateProjectPrompt, inspectProjectPasses, inspectProjectPromptTasks } from './index/prompt.js';
+import { recordProjectPassDone } from './index/pass-record.js';
 import {
   inspectProjectEngineering,
   listEngineeringProfileCatalog,
@@ -196,6 +197,15 @@ export function inspectPromptTasks(options) {
   return inspectProjectPromptTasks(options);
 }
 
+export function inspectPasses(options) {
+  return inspectProjectPasses(options);
+}
+
+/** Records in genesis/passes.json that the pass `pass` finished now; a pass's own last step. */
+export function recordPassDone(options) {
+  return recordProjectPassDone(options);
+}
+
 export function getContext({ paths, projectRoot = process.cwd(), stackPackages = [] } = {}) {
   return contextForProjectPaths({ paths, projectRoot, stackPackages });
 }