genesis-compiler 1.10.21 → 1.10.23

package/skills/genesis-project/references/sanity-checks.md

@@ -173,35 +173,75 @@ one matching, and see it found.
 
 **Outer limit:** a capped read narrowed in code is broken at any size.
 
-## Data: saves, batches and background work
+## Data: batches and background work
 
 **Good:** a batch writes each table in a few statements inside the owner's
 transaction, not one full create per row. Work nobody waits for runs as a
 scheduled or queued job in bounded chunks: it loops over units of work (a
 tenant, a user), one transaction each, never one around the whole run and
-never one per row. A read request takes no lock and writes nothing. Every path
-takes its locks in one order, parents before children, so two transactions
-never wait on each other. Two writers on the same records never produce a
-server error.
+never one per row. A read request takes no lock and writes nothing.
 
 **Check:** count a batch's statements at 10 items and at 500. Look for due work
 run inside whichever request comes first, and one long transaction around it.
 Find any lock or write a read path takes for one-time setup: read first, lock
-only on the rare unset path. Compare the order in which each path locks rows.
-Run two writers on the same records; a retried transaction must be safe to
-repeat, so HTTP calls, email and uploads go before or after it, or into an
-outbox row written inside it.
+only on the rare unset path.
 
 **Examples:**
 - An import created each row through the full single-record create path, with
   its lookups and read-back, one row at a time.
 - Overdue work ran inside the first user request after a quiet period, so that
   request's time depended on how long nobody had used the app.
-- Concurrent saves surfaced database deadlocks as 500s.
 
 **Outer limit:** thousands of queries or tens of seconds for one action, or a
 request whose time depends on how long since anyone used the app.
 
+## Data: two changes at once
+
+**Good:** each write uses the lightest tool that keeps the stored data right.
+Most need nothing beyond the transaction they already run in:
+- An ordinary edit (a form saving a record, a name or a description, settings,
+  a saved game) is a plain write, and the last save wins: when two people edit
+  the same thing at the same moment, one change replaces the other. That is
+  usually acceptable, and it needs no lock and no concurrency test. Where
+  people would care, the save can carry the version it read and refuse when
+  the record has moved on, saying that someone else changed it and to reload.
+- A change allowed only while a value still holds (open to booked, a reward
+  claimed once) is a conditional update, a compare-and-set: of two writers one
+  wins and the other gets a clear refusal, with no lock.
+- A value that must be unique gets a unique index or constraint, and an
+  insert that loses that race is retried where the tools offer it, or refused
+  clearly.
+- An explicit lock is for a race that would silently leave wrong data that
+  matters: stock or quantities, money or balances, sequential document
+  numbers, a capacity limit (two bookings of the last place), or a
+  check-then-act on a shared resource (is the drier empty? then load it).
+
+A lock makes other writers wait, can deadlock and needs a test with two
+writers, so it usually pays only where you can name the wrong data a race
+would leave. Whatever the tool, a lost race never becomes a server error: the
+loser gets a refusal it can act on, or its work runs again. Take locks in one
+order on every path, parents before children, so two transactions never wait
+on each other. Work that may run again must be safe to repeat, so HTTP calls,
+email and uploads go before or after the transaction, or into an outbox row
+written inside it.
+
+**Check:** for each write path, name its tool and why: for a lock, the wrong
+data a race would leave; for a plain write, why the last save winning is
+acceptable. Run two writers at once on each path that locks, writes
+conditionally or relies on a unique key, and see one win and the other refused
+or run again, never a server error and never both applied. Compare the order in
+which each path locks rows. An ordinary edit needs neither a lock nor a
+two-writer test.
+
+**Examples:**
+- Concurrent saves surfaced database deadlocks as 500s.
+- A business app locked the rows of every save, names and settings included,
+  and spent hours on lock order, deadlocks and two-writer tests for edits
+  where the last save winning was fine.
+
+**Outer limit:** a lost race that ends in a server error, or that leaves stock,
+money, numbering or a capacity limit silently wrong.
+
 ## Work that repeats or lingers
 
 **Good:** work whose answer does not change between calls runs once and is
@@ -440,8 +480,9 @@ hundreds of requests on a first screen.
 
 **Good:** the same state twice gives the same result. Each fact has one
 resolver. Each status names what clears it, and each gate has a case that must
-fail it. Writes are conditional on the version read. A delete removes what it
-created elsewhere. Readiness is checked directly.
+fail it. A step that moves a status writes only while the status it read
+still holds, so of two at once one wins and the other is refused. A delete
+removes what it created elsewhere. Readiness is checked directly.
 
 **Check:** find every place that resolves the same fact. Check that what a
 delete created outside its table is gone. When a rule's result breaks another

package/skills/genesis-quality-pass/SKILL.md

@@ -53,6 +53,10 @@ to another agent and do not generate it again. This step composes the selected
 Stack's quality pass guidance and any project customization with the portable
 contract below.
 
+When the user asks for a deep run of this pass, pass its Deep request,
+`Quality pass the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
 ## Resolve the scope
 
 Inspect `git status --short` and the staged and unstaged diffs before editing.
@@ -60,9 +64,11 @@ A dirty worktree is allowed. Preserve the existing index and unrelated work; do
 not stage, stash, commit, or discard changes as a prerequisite.
 
 When the prompt has a `PASS RUN` section, the request is one of the pass's own
-runs, the whole app or the changes since its last completed run judged against
-the whole app, and its scope is the one that section states, whatever the
-defaults below say.
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
 
 - **The whole app (default).** Every screen, command and flow a person uses.
 - **A section.** A named area (a module, a route subtree, a set of screens or
@@ -172,3 +178,15 @@ step only to the pass's own runs, whose requests it writes itself, so a quality
 pass of a section, commits or your own changes is never recorded as the pass;
 neither is a pass that stopped early, was abandoned or still has failing
 checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every screen and flow, with each of its states (loading, empty, partial,
+  failed, refused, offline, first use) as an item of its own, and every
+  refusal message;
+- the cross-subsystem item: the same state or refusal handled or worded
+  differently in different places.

package/skills/genesis-review/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: genesis-review
+description: Review the work against what the software should do through an explicitly requested review over the whole app, the changes since its last completed run, a named section or the current work, judging the tests (each changed behavior has one that would fail without it; none weakened or skipped), the gaps between intent, code and explanation, and costs that grow with the data, writing only tests and reporting everything else. Use when asked for a review, a review pass, or to check the tests and the work against the Blueprint.
+---
+
+# Genesis review
+
+Judge the work against what the software should do, and the tests against the
+work, and say plainly what was and was not verified. A review is explicit:
+never run it merely because implementation finished.
+
+Resolve the invocation before running the first Genesis operation. Do not use a
+Genesis operation or `genesis --version` as an availability probe.
+
+1. Read the repository-root `package.json`. Treat Genesis as project-pinned only
+   when that manifest's `name` is `genesis-compiler`, or its `dependencies`,
+   `devDependencies`, or `optionalDependencies` contain the exact
+   `genesis-compiler` key.
+2. For a project-pinned repository, invoke every Genesis CLI operation with
+   `npm exec --no -- genesis <arguments>`. This runs without fetching another
+   package. If the declared package is not installed, report that the project's
+   dependencies are not prepared; do not fall back to another Genesis version.
+3. Otherwise, do not try `npm exec`. Run `command -v genesis` (or the current
+   shell's equivalent `PATH` lookup). When it resolves an executable, invoke
+   `genesis <arguments>` directly.
+4. When neither source is available, stop and report that Genesis is
+   unavailable. Never install or update Genesis merely to satisfy a workflow
+   instruction.
+
+Successful invocation resolution is routine. Do not narrate whether Genesis is
+project-pinned or on `PATH`, and never describe direct `PATH` use as a fallback.
+Mention how the invocation was selected only when resolution fails or the user
+explicitly asks.
+
+Follow the configured Collaboration approach for user-facing updates, including
+its technical depth and response length. Report concrete progress,
+findings, or blockers; do not announce that you are following guidance.
+
+
+## Load the effective project instructions once
+
+A review request may arrive as a complete Genesis-generated prompt or as a
+direct request such as `Review` or `Review the Orders section`.
+
+If the current task already contains `GENESIS CONTEXT` whose task is `review`,
+continue with it directly. Do not generate another prompt.
+
+Otherwise, before resolving scope, run the Genesis `prompt --task review`
+operation once using the invocation rule above. For a bare `Review` request,
+pass no request argument. When the user names a section, commits or the
+current work, pass that exact request as one safely quoted argument. Treat the
+printed prompt as the instructions for this same turn; do not dispatch it to
+another agent and do not generate it again.
+
+When the user asks for a deep run of this pass, pass its Deep request,
+`Review the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
+## Resolve the scope
+
+Inspect `git status --short` and the staged and unstaged diffs before editing.
+A dirty worktree is allowed. Preserve the existing index and unrelated work; do
+not stage, stash, commit, or discard changes as a prerequisite.
+
+When the prompt has a `PASS RUN` section, the request is one of the pass's own
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
+
+- **The work (default).** The relationship between the Blueprint, the code, the
+  Program and the tests as they stand now.
+- **The whole app.** Every behavior the project's own source exposes and the
+  tests that prove it.
+- **A section or the changes.** A named area, explicit commits, or the current
+  task's changes: the behavior they create or change and its tests.
+
+If the scope is ambiguous, ask which section or changes.
+
+## Boundaries
+
+- The prompt says what a review judges. It edits only tests: it adds or updates
+  the tests changed behavior lacks and changes no product code, Blueprint,
+  Program, Stack or other file. Every other finding is reported with the
+  smallest sensible correction, left unchanged.
+- Run the tests relevant to the scope; report what actually ran and what was not
+  verified, and never report an unrun check as passing.
+
+Leave the review as ordinary uncommitted work for a later normal commit. Never
+amend or rewrite selected commits.
+
+When the prompt ends with a `PASS RECORD` step, take it once the review has
+finished: the Genesis `passes done review` operation records it in `genesis/passes-added.json`,
+an uncommitted change that lands in the review's own commit. Genesis adds that
+step only to the pass's own runs, whose requests it writes itself, so a review
+of a section, commits, a base or the current work is never recorded as the
+pass; neither is a review that stopped early, was abandoned or still has
+failing checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every behavior the source exposes (operation, screen, command or job), each
+  with the test that would fail without it, or the missing test written or
+  reported;
+- every test file: whether it runs in the whole suite, what it proves, what it
+  costs, and any test weakened, skipped or loosened;
+- every list, batch and write path, with its query or call counts at a few rows
+  and at a realistic number;
+- the Blueprint, Program and `genesis/subsystems.md` entries against the code;
+- the cross-subsystem item: the same behavior tested in different ways or not
+  at all, a table with more than one owner, and work over a whole population
+  done inside a request.
+
+Review's limits hold in a deep run: it writes only tests, and every other
+finding is reported and left unchanged.

package/skills/genesis-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis review"
+  short_description: "Review the work and its tests against what the app should do"
+  default_prompt: "Use $genesis-review to Review the whole app."

package/skills/genesis-security-pass/SKILL.md

@@ -54,6 +54,10 @@ to another agent and do not generate it again. This step composes the selected
 Stack's security pass guidance and any project customization with the portable
 contract below.
 
+When the user asks for a deep run of this pass, pass its Deep request,
+`Security pass the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
 ## Resolve the scope
 
 Inspect `git status --short` and the staged and unstaged diffs before editing.
@@ -61,9 +65,11 @@ A dirty worktree is allowed. Preserve the existing index and unrelated work; do
 not stage, stash, commit, or discard changes as a prerequisite.
 
 When the prompt has a `PASS RUN` section, the request is one of the pass's own
-runs, the whole app or the changes since its last completed run judged against
-the whole app, and its scope is the one that section states, whatever the
-defaults below say.
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
 
 - **The whole app (default).** Every way in: each route, page, command,
   action, message or socket handler, webhook, scheduled or background job,
@@ -277,3 +283,15 @@ step only to the pass's own runs, whose requests it writes itself, so a security
 of a section, commits or your own changes is never recorded as the pass;
 neither is a pass that stopped early, was abandoned or still has failing
 checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every way in from the map (each route, page, command, action, handler,
+  webhook, job, file read from outside and outbound call), every sign-in,
+  session and token flow, and every secret;
+- the cross-subsystem item: one resource guarded differently on different
+  ways in, and a protection applied on some ways in but not on others.

package/skills/genesis-speed-pass/SKILL.md

@@ -53,6 +53,10 @@ to another agent and do not generate it again. This step composes the selected
 Stack's speed pass guidance and any project customization with the portable
 contract below.
 
+When the user asks for a deep run of this pass, pass its Deep request,
+`Speed pass the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
 ## Resolve the scope
 
 Inspect `git status --short` and the staged and unstaged diffs before editing.
@@ -60,9 +64,11 @@ A dirty worktree is allowed. Preserve the existing index and unrelated work; do
 not stage, stash, commit, or discard changes as a prerequisite.
 
 When the prompt has a `PASS RUN` section, the request is one of the pass's own
-runs, the whole app or the changes since its last completed run judged against
-the whole app, and its scope is the one that section states, whatever the
-defaults below say.
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
 
 - **The whole app (default).** The test suite and its preparation, every
   screen, view or command a person opens and the main actions in it, and
@@ -331,3 +337,15 @@ step only to the pass's own runs, whose requests it writes itself, so a speed
 pass of a section, commits or your own changes is never recorded as the pass;
 neither is a pass that stopped early, was abandoned or still has failing
 checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every slow test file and phase of the suite, every screen's first load and
+  each navigation, every main request, command and job, startup, and work that
+  runs while nobody asks for anything, each measured before and after;
+- the cross-subsystem item: the same work done in several places (repeated
+  setup, duplicate fetches, the same computation on several paths).

package/skills/genesis-ui-pass/SKILL.md

@@ -54,6 +54,10 @@ prompt as the instructions for this same turn; do not dispatch it to another
 agent and do not generate it again. This step composes the selected Stack's UI
 pass guidance and any project customization with the portable contract below.
 
+When the user asks for a deep run of this pass, pass its Deep request,
+`UI pass the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
 ## Resolve the scope
 
 Inspect `git status --short` and the staged and unstaged diffs before editing.
@@ -61,9 +65,11 @@ A dirty worktree is allowed. Preserve the existing index and unrelated work; do
 not stage, stash, commit, or discard changes as a prerequisite.
 
 When the prompt has a `PASS RUN` section, the request is one of the pass's own
-runs, the whole app or the changes since its last completed run judged against
-the whole app, and its scope is the one that section states, whatever the
-defaults below say.
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
 
 - **The changes (default).** With no stated scope, select only your own changes
   for the current task, including preceding turns: staged, unstaged, untracked
@@ -127,3 +133,15 @@ step only to the pass's own runs, whose requests it writes itself, so a UI pass
 of your own changes, a section or commits is never recorded as the pass;
 neither is a pass that stopped early, was abandoned or still has failing
 checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every screen (page, view, dialog or panel) and every shared interface
+  component, each checked against the Stack's design rules, with a screenshot
+  after any change;
+- the cross-subsystem item: the same control, layout or pattern built or
+  styled differently on different screens.

package/skills/genesis-ux-pass/SKILL.md

@@ -54,6 +54,10 @@ turn; do not dispatch it to another agent and do not generate it again. This
 step composes the selected Stack's user experience pass guidance and any
 project customization with the portable contract below.
 
+When the user asks for a deep run of this pass, pass its Deep request,
+`User experience pass the whole app deeply.`, exactly;
+Genesis then adds the run's `DEEP RUN` section.
+
 ## Resolve the scope
 
 Inspect `git status --short` and the staged and unstaged diffs before editing.
@@ -61,9 +65,11 @@ A dirty worktree is allowed. Preserve the existing index and unrelated work; do
 not stage, stash, commit, or discard changes as a prerequisite.
 
 When the prompt has a `PASS RUN` section, the request is one of the pass's own
-runs, the whole app or the changes since its last completed run judged against
-the whole app, and its scope is the one that section states, whatever the
-defaults below say.
+runs (the whole app, the changes since its last completed run judged against
+the whole app, or a deep run) or a run over the changes since a base commit the
+request names, and its scope is the one that section states, whatever the
+defaults below say. A deep run's prompt also has a `DEEP RUN`
+section; follow it with "Deep run" below.
 
 - **The whole app (default).** Every main task a person comes to do, from
   where they start to where it is done.
@@ -257,3 +263,14 @@ step only to the pass's own runs, whose requests it writes itself, so a user exp
 of a section, commits or your own changes is never recorded as the pass;
 neither is a pass that stopped early, was abandoned or still has failing
 checks.
+
+## Deep run
+
+When the prompt has a `DEEP RUN` section, follow it: it says how the checklist,
+evidence, chunks, commits and report work for every pass. This pass adds to the
+checklist:
+
+- every main task, walked as a new and as a returning person, with its steps
+  and decisions counted before and after;
+- the cross-subsystem item: similar tasks or screens that work differently,
+  and one thing called by different names.

package/src/cli-commands.js

@@ -72,7 +72,9 @@ async function execute({ command, operands, options }, { signal, hostContext = n
   }
   if (command === 'migrate') return migrate({ projectRoot, stackPackages });
   if (command === 'skills') return syncSkills({ projectRoot, stackPackages });
-  if (command === 'passes') return { action: 'done', ...await recordPassDone({ projectRoot, pass: operands[1] }) };
+  if (command === 'passes') {
+    return { action: 'done', ...await recordPassDone({ projectRoot, pass: operands[1], passes: operands.slice(2) }) };
+  }
   if (command === 'adopt') {
     return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
   }

package/src/cli.js

@@ -27,6 +27,7 @@ const USAGE = `Usage:
   genesis stack add <piece...>
   genesis skills sync
   genesis passes done <pass>
+  genesis passes done master-pass <pass...>
   genesis templates list
   genesis templates apply <catalogue:technology/variant>
   genesis context <path...>
@@ -42,7 +43,7 @@ const USAGE = `Usage:
   genesis inspect passes
   genesis inspect section <name>
   genesis prompt [request...]
-  genesis prompt --task <start|adopt|work|deslop|ui-pass|identity-pass|quality-pass|data-pass|security-pass|ux-pass|speed-pass|program|blueprint|describe|review> [request...]
+  genesis prompt --task <start|adopt|work|deslop|ui-pass|identity-pass|quality-pass|data-pass|security-pass|ux-pass|speed-pass|master-pass|program|blueprint|describe|review> [request...]
   genesis verify
   genesis check
 
@@ -179,8 +180,10 @@ function parseCommand(argv) {
       fail('CLI_SKILLS_ACTION_REQUIRED', 'Command skills requires exactly: sync.');
     }
   } else if (command === 'passes') {
-    if (operands.length !== 2 || operands[0] !== 'done') {
-      fail('CLI_PASSES_ACTION_REQUIRED', 'Command passes requires exactly: done <pass>.');
+    // Only the Master pass records the passes it ran with it.
+    const master = operands[1] === 'master-pass';
+    if (operands[0] !== 'done' || (master ? operands.length < 3 : operands.length !== 2)) {
+      fail('CLI_PASSES_ACTION_REQUIRED', 'Command passes requires exactly: done <pass>, or done master-pass <pass...>.');
     }
   } else if (command === 'codex') {
     if (operands.length !== 1 || operands[0] !== 'install') {
@@ -317,10 +320,15 @@ function writeResult(command, result) {
       line(process.stdout, `  recommended ${pass.recommend.hint}; Stack guidance: ${pass.stackGuidance ? 'yes' : 'no'}; last run: ${pass.lastRun ?? 'never'}`);
       if (pass.unavailable && !result.unavailable) line(process.stdout, `  unavailable: ${pass.unavailable}`);
     }
+    const { master } = result;
+    line(process.stdout, `${master.id}: ${master.title} — ${master.description}`);
+    if (master.unavailable) line(process.stdout, `  unavailable: ${master.unavailable}`);
+    else line(process.stdout, `  runs, in order: ${master.passes.join(', ')}; last run: ${master.lastRun ?? 'never'}`);
     return;
   }
   if (command === 'passes') {
-    line(process.stdout, `${result.pass}: recorded ${result.lastRun} in ${result.path}`);
+    const ran = result.passes ? ` with ${result.passes.join(', ')}` : '';
+    line(process.stdout, `${result.pass}: recorded ${result.lastRun}${ran} in ${result.path}`);
     return;
   }
   if (command === 'inspect' && result.inspection === 'skills') {

package/src/index/agent-skills.js

@@ -17,7 +17,7 @@ import { parse as parseYaml } from 'yaml';
 
 import { asDiagnostic, GenesisError } from './errors.js';
 import { claudeSkillLinks } from './claude-hooks.js';
-import { PASSES } from './passes.js';
+import { MASTER_PASS, PASSES } from './passes.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
 const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
@@ -35,12 +35,13 @@ const SKILL_FIELDS = new Set([
   'allowed-tools',
 ]);
 
-// This release's Genesis workflow skills: the project and Program skills, and one for each pass. Its skills
-// directory holds exactly these, as every release's does (see projectGenesis).
+// This release's Genesis workflow skills: the project and Program skills, one for each pass and one for the Master
+// pass. Its skills directory holds exactly these, as every release's does (see projectGenesis).
 export const CORE_SKILL_NAMES = Object.freeze([
   'genesis-project',
   'genesis-program',
   ...PASSES.map(({ task }) => `genesis-${task}`),
+  `genesis-${MASTER_PASS.task}`,
 ]);
 
 function invalidSkill(message, details = {}) {

package/src/index/assets.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 
-import { PASSES } from './passes.js';
+import { MASTER_PASS, PASSES } from './passes.js';
 
 const root = new URL('../../', import.meta.url);
 const assets = {
@@ -12,6 +12,9 @@ const assets = {
   work: new URL('prompts/work.txt', root),
   describe: new URL('prompts/describe.txt', root),
   ...Object.fromEntries(PASSES.map(({ task }) => [task, new URL(`prompts/${task}.txt`, root)])),
+  [MASTER_PASS.task]: new URL('prompts/master-pass.txt', root),
+  'pass-report': new URL('prompts/pass-report.txt', root),
+  'pass-deep': new URL('prompts/pass-deep.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/code-index.js

@@ -19,6 +19,7 @@ import { attachEntryFunctions, discoverEntryPoints } from './entry-points.js';
 import { runGit } from './process.js';
 import { CITY_SCHEMA_VERSION, MACHINE_CITY_SCHEMA, PROGRAM_CITY_SCHEMA } from './city-documents.js';
 import { gitVisibleFileStates } from './project-files.js';
+import { stackPackageRoots } from './source-size.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, stableJsonParts } from './utils.js';
 
@@ -388,7 +389,7 @@ export async function buildProjectIndex({
   if (observationReader) observations = null;
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root, { allowUnresolvedSections, stackPackages });
-  const packageRoots = stack.packageDiscovery.discoveries.flatMap(discovery => discovery.manifests.map(manifest => path.posix.join(path.posix.dirname(manifest), discovery.packageRoot)));
+  const packageRoots = stackPackageRoots(stack);
   const includePath = filePath => isProjectContentPath(filePath) && !packageRoots.some(directory => filePath === directory || filePath.startsWith(`${directory}/`));
   const states = await gitVisibleFileStates(root, { includePath });
   const files = [...states]

package/src/index/contracts.js

@@ -4,6 +4,7 @@ export const GENESIS_CONTRACTS = Object.freeze({
   promptTasks: 'genesis.prompt-tasks.v1',
   passes: 'genesis.passes.v1',
   passRuns: 'genesis.pass-runs.v1',
+  deepRuns: 'genesis.deep-runs.v1',
   templates: 'genesis.templates.v1',
   templateApplication: 'genesis.template-application.v1',
   collaboration: 'genesis.collaboration.v1',

package/src/index/master-pass.js

@@ -0,0 +1,76 @@
+import { GenesisError } from './errors.js';
+import { ADDED_PASS_RECORD_PATH } from './pass-record.js';
+import { deepRequest, MASTER_PASS } from './passes.js';
+
+// The names a request may give a pass: its id or its title, either without "pass", in any case.
+function passNames(pass) {
+  return [pass.task, pass.title, pass.task.replace(/-pass$/u, ''), pass.title.replace(/ pass$/iu, '')]
+    .map((name) => name.toLowerCase());
+}
+
+const NAMED = new RegExp(`^${MASTER_PASS.title} \\(([^()]*)\\)(.*)$`, 'su');
+
+/**
+ * The run and the passes a Master pass request asks for. The request is one of the runs Genesis writes (`runs`),
+ * optionally naming the passes in brackets after "Master pass", such as `Master pass (security, data, deslop) the whole
+ * app.`; without names it runs every pass the project offers. The passes run in the Master order, whatever order they
+ * were named in. Any other request, or a name the project offers no pass for, is refused, naming what it accepts.
+ * @param {string} request the request's last paragraph, after any framing a host put before it
+ * @param {{ request: string }[]} runs the Master pass's runs
+ * @param {{ task: string, title: string }[]} offered the passes the project offers, in the Master order
+ */
+export function masterSelection(request, runs, offered) {
+  const named = NAMED.exec(request);
+  const run = runs.find((entry) => entry.request === (named ? `${MASTER_PASS.title}${named[2]}` : request));
+  if (!run) {
+    throw new GenesisError('PASS_REQUEST_INVALID', `A ${MASTER_PASS.title} request is ${runs.map(({ request: text }) => `"${text}"`).join(' or ')}, `
+      + `naming the passes to run, if not all, in brackets after "${MASTER_PASS.title}", such as "${MASTER_PASS.title} (security, data, deslop) the whole app."`);
+  }
+  if (!named) return { run, passes: offered };
+  const chosen = new Set();
+  for (const name of named[1].split(/,|\s+and\s+/u).map((part) => part.trim()).filter(Boolean)) {
+    const pass = offered.find((entry) => passNames(entry).includes(name.toLowerCase()));
+    if (!pass) {
+      throw new GenesisError('PASS_UNKNOWN', `The ${MASTER_PASS.title} cannot run "${name}". Name any of: `
+        + `${offered.map(({ task, title }) => `${title} (${task})`).join(', ')}.`, { pass: name });
+    }
+    chosen.add(pass);
+  }
+  if (chosen.size === 0) {
+    throw new GenesisError('PASS_REQUEST_INVALID', `The ${MASTER_PASS.title} request names no pass in its brackets; leave them out to run every pass.`);
+  }
+  return { run, passes: offered.filter((pass) => chosen.has(pass)) };
+}
+
+/**
+ * The prompt's MASTER PASS section: the run's scope, the passes to run in order, each with the request of its own
+ * Deep run, and where the Master ledger lives. The Master pass adds only this sequence: each pass's Deep run says how
+ * that pass works, from that pass's own prompt, and is never copied here.
+ */
+export function masterPassSection({ run, passes, ledger }) {
+  const scope = run.commit
+    ? `over the changes since commit ${run.commit}, the commit of its last completed run, judged against the whole app`
+    : 'over the whole app';
+  return [
+    `This request is a ${MASTER_PASS.title} ${scope}. It runs these passes deeply, one after another, in this`,
+    'order, each as that pass\'s own Deep run: generate its prompt with the Genesis `prompt` operation and the exact',
+    `request below, as \`.agents/skills/genesis-${MASTER_PASS.task}/SKILL.md\` says, and follow it in full before the`,
+    'next pass starts.',
+    '',
+    ...passes.map((pass, index) => `${index + 1}. ${pass.title}: \`prompt --task ${pass.task} "${deepRequest(pass, run.commit)}"\``),
+    '',
+    `Keep the Master ledger at \`${ledger}\`.`,
+  ].join('\n');
+}
+
+// A Master pass's prompt ends with recording it, with the passes it ran, as its last commit.
+export function masterRecordStep() {
+  return [
+    'Only once every listed pass has finished or been skipped, make your last step the',
+    `Genesis \`passes done ${MASTER_PASS.task} <pass id...>\` operation, naming the passes it ran`,
+    `and leaving out those it skipped, invoked as \`.agents/skills/genesis-${MASTER_PASS.task}/SKILL.md\``,
+    `says. It records the time and those passes in \`${ADDED_PASS_RECORD_PATH}\`; commit that change`,
+    `as the ${MASTER_PASS.title}'s last commit. Do not run it for a ${MASTER_PASS.title} that stopped`,
+    'early, was abandoned, or still has failing checks.',
+  ].join('\n');
+}