genesis-compiler 1.10.20 → 1.10.22

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

@@ -46,18 +46,31 @@ If the current task already contains `GENESIS CONTEXT` whose task is
 
 Otherwise, before resolving scope, run the Genesis `prompt --task ui-pass`
 operation once using the invocation rule above. For a bare `UI pass` request,
-pass no request argument. When the user names commits, a section, or the whole
-app, pass that exact request as one safely quoted argument. Treat the printed
+pass no request argument. When the user names commits or a section, pass that
+exact request as one safely quoted argument. When the user asks for the UI pass
+of the whole app, pass its own pass request, `UI pass the whole app.`, exactly;
+Genesis then adds the pass's `PASS RUN` and `PASS RECORD` steps. Treat the printed
 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.
 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 changes (default).** With no stated scope, select only your own changes
   for the current task, including preceding turns: staged, unstaged, untracked
   and already-committed task changes, identified from task and edit history and
@@ -70,7 +83,10 @@ not stage, stash, commit, or discard changes as a prerequisite.
   UI changes, report that there is nothing to pass.
 - **A section.** A named area (a module, a route subtree, a set of screens, or
   a shared component family): every screen in it, touched or not.
-- **The whole app.** Every screen, the shell and navigation included.
+- **The whole app.** The UI pass's own pass request, `UI pass the whole app.`:
+  every screen of the project's own source, the shell and navigation included,
+  whoever changed it and whenever. It never includes generated output, vendored
+  or copied third-party UI, or dependency directories.
 
 If the scope is ambiguous, ask which changes or which section.
 
@@ -110,7 +126,22 @@ scope and any commit identities, what changed, files changed, the checks and
 screenshots actually taken (with their paths), and follow-up findings left
 unchanged.
 
-Once the pass has finished, end with the prompt's `PASS RECORD` step: the
-Genesis `passes done ui-pass` operation records it in `genesis/passes.json`, an
-uncommitted change that lands in the pass's own commit. A pass that stopped
-early, was abandoned or still has failing checks is not recorded.
+When the prompt ends with a `PASS RECORD` step, take it once the pass has
+finished: the Genesis `passes done ui-pass` operation records it in `genesis/passes.json`,
+an uncommitted change that lands in the pass's own commit. Genesis adds that
+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

@@ -0,0 +1,276 @@
+---
+name: genesis-ux-pass
+description: Make software easy to use for what people come to do through an explicitly requested user experience pass over the whole app, a named section, or the agent's own changes, covering each main task's steps, navigation and findability, the words people read, defaults, first use, feedback and forgiving actions, verified by walking each task before and after. Use when asked for a UX pass, a user experience review that fixes what it finds, or to make the app simpler or clearer to use.
+---
+
+# Genesis user experience pass
+
+Make the main things people do with the software short, clear and hard to get
+wrong, and prove it by walking each one. A user experience pass 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 user experience pass request may arrive as a complete Genesis-generated
+prompt or as a direct request such as `User experience pass`, `UX pass` or
+`UX pass the checkout`.
+
+If the current task already contains `GENESIS CONTEXT` whose task is
+`ux-pass`, continue with it directly. Do not generate another prompt.
+
+Otherwise, before resolving scope, run the Genesis `prompt --task ux-pass`
+operation once using the invocation rule above. For a bare `User experience
+pass` or `UX pass` request, pass no request argument. When the user names a
+section, commits or your own changes, 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. 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.
+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 whole app (default).** Every main task a person comes to do, from
+  where they start to where it is done.
+- **A section.** A named area (a module, a set of screens or commands, a game
+  mode): every task that runs through it, touched or not.
+- **The changes.** Your own changes for the current task, or explicit commits,
+  established and resolved as for Deslop: the tasks they create or change,
+  each walked from its start.
+
+If the scope is ambiguous, ask which section or changes.
+
+## Know who it is for and what they come to do
+
+Read the Blueprint first: who uses the software, what they come to do, and the
+first useful outcome it promises. From it and from the software itself, list
+the main tasks in scope: the few things people do most often or care about
+most, such as placing an order, answering a message, running a build from the
+command line or starting a match. For each, note who does it (a first-time
+visitor, a regular, an occasional administrator), how often, and what done
+looks like to them. A pass that polishes screens nobody reaches while the main
+task stays long has missed its point.
+
+The sanity checks guide
+(`.agents/skills/genesis-project/references/sanity-checks.md`) sections
+"Screens in use", "The wait a person sees" and "State and workflow" describe
+what good looks like; read them before walking.
+
+## Walk each task before changing anything
+
+Walk each main task through the real interface (a browser, a terminal, a
+device, the game itself), twice when possible: once as a new person with no
+data and no knowledge of the code, once as a returning person with realistic
+data. Start where that person starts: the address they were given, a link in an
+email, the installed command, the title screen. For each walk, write down:
+
+- each step (a screen, a field, a click, a command, a menu) and each decision
+  the person must make to reach done;
+- each place where they must know something the software doesn't tell them:
+  an internal name, an id, where a feature hides, what to type;
+- each wait and each moment where nothing says what happened;
+- each dead end, each detour back to the start, and each place where a mistake
+  costs work.
+
+These notes are what the pass is measured against; keep them for the report.
+Reading code shows what the software can do; only walking it shows what a
+person has to do.
+
+## Fewer steps and decisions
+
+- **Ask only what is needed now.** A field, question or setting the task can
+  do without moves later or out of the way, with a default when possible.
+  Every extra field is a chance to stop, so each one earns its place.
+- **Good defaults.** Pre-fill what the software knows or can reasonably guess:
+  today's date, the person's own details, the last choice they made, the only
+  option there is. When one choice is clearly sensible, take it and let the
+  person change it, rather than asking.
+- **Remember where they were.** Return a person to the place, filters and
+  choices they left when possible, so coming back doesn't start over.
+- **The next step is obvious.** After each step, the most likely next action is
+  the most visible one, near where the person's attention already is. A
+  finished task leads somewhere useful, not to a blank page.
+- **Do the work for them.** When the software can compute, look up or fill in
+  something (a total, an address from a postcode, a name from an id), it does,
+  and the person confirms instead of typing.
+- **Keep related steps together.** What belongs together happens in one place,
+  instead of a trip across several screens or commands.
+
+## Easy to find
+
+- **Where people look.** Each main task is reachable from where its people
+  start, in one or two steps when possible, and named in the main navigation,
+  the command's help or the game's main menu. A frequent task is never buried
+  in settings or an overflow menu.
+- **Names people use.** Navigation, labels and commands use the words people
+  use for things, the ones the Blueprint uses, not the code's internal names.
+- **Search where lists grow.** A list that can grow past a screenful can be
+  searched or filtered by what people remember about an item.
+- **Every place has an address.** A page or record people share or come back
+  to opens directly from its link, and going back returns them where they came
+  from.
+- **Beyond screens.** A command-line program lists its commands and options
+  with examples in `--help`, suggests the closest command for a typo and keeps
+  the common case short; a game shows its controls when they are needed and
+  lets the player reach each mode from the main menu.
+
+## Words
+
+- **Say what happens.** A button or command says what it does to what: "Send
+  invoice", not "Submit" or "OK". People decide from the label, so it carries
+  the consequence.
+- **One name for each thing.** The same thing has the same name everywhere:
+  navigation, titles, buttons, messages, help and emails. Two names make people
+  wonder whether they are two things.
+- **Plain and short.** Everyday words and the person's own terms, never
+  jargon, internal codes or ids; the important word comes first.
+- **Say what happened and what's next.** After an action, the software says
+  what changed and, when there is one, what the person can do next.
+- **Translated text stays translatable.** In translated software, changed
+  words go through its translation keys, not stored or hard-coded text.
+
+## First use
+
+- **To the first useful outcome.** A new person reaches the first outcome the
+  Blueprint promises in as few steps and with as little setup as possible,
+  without reading instructions when possible. Setup that can wait, waits.
+- **Show by example.** Where a blank start would leave people guessing, offer
+  an example, a template or sample content they can try and remove.
+- **One way to learn.** What a new person learns works the same way for a
+  returning one, and first-use help gets out of the way once it has done its
+  job.
+
+## Forgiving
+
+- **Undo over confirm.** When an action can be undone (archive, move, remove
+  from a list), do it at once and offer Undo, rather than asking first; people
+  click through confirmations they see too often. Confirmation stays for what
+  cannot be undone, and names the thing and what will be lost: "Delete the
+  project Spring launch and its 40 tasks?".
+- **Keep the person's work.** Typed input survives a refused save, going back
+  or an expired session when possible, and leaving unsaved work asks first or
+  keeps a draft.
+- **A way out of every step.** Each step can be cancelled, and leaving a flow
+  returns to where it began. A long task can be paused and resumed.
+- **Hard to get wrong.** Offer choices instead of free text where the set is
+  known, show the expected format before the person types, and accept the
+  common ways of writing a value (spaces in a phone number, a date written
+  several ways) when possible.
+
+## Consistent
+
+- **Same thing, same place.** Similar screens put their main action, their
+  search and their way out in the same place, so learning one teaches the
+  rest.
+- **The platform's conventions.** Follow what people already know from their
+  platform: links, Back and new tabs on the web; exit codes, standard input
+  and `--yes` or `--dry-run` on a command line; a pause menu and a way back to
+  the title screen in a game. Where the selected Stack's design guidance
+  decides, it comes first.
+
+## Walk again and prove it
+
+- Walk each main task again exactly as before, as the new and the returning
+  person, and compare: steps, decisions, things they had to know unprompted,
+  waits without feedback, dead ends. The report gives each task's counts
+  before and after.
+- Where the project's tests can drive a flow (a browser test, a command-line
+  test, a scripted playthrough), lock the changed path in at the cheapest level
+  that proves it, and watch the test fail once against the old path. Run the
+  focused tests of the affected areas and the checks the Stack guidance names.
+- Take screenshots, terminal transcripts or recordings of each changed step,
+  at phone and desktop widths on the web, and look at every one. Keep them out
+  of the repository's tracked files, delete temporary test files, and close
+  every browser and process you start.
+
+## Boundaries
+
+- **The path changes, the product doesn't.** The pass changes the steps,
+  words, defaults, order and placement a task takes. It adds no feature and
+  changes no permission, product rule, price, limit or stored data. A missing
+  feature, a rule that makes a task long, or a choice only the person can make
+  is a finding with a recommendation, left unchanged.
+- **Never trade safety for a step.** Never remove a permission check, a
+  validation, the confirmation of an irreversible action, or a security step
+  such as a second factor to make a task shorter.
+- **Other passes own their parts.** How screens look belongs to the UI pass
+  and the visual identity pass; loading, empty and error states, edge cases
+  and accessibility belong to the quality pass. Record what you notice there
+  as findings for those passes, unless it blocks a main task.
+- The selected Stack's user experience pass guidance names where navigation,
+  actions, defaults and words live in its technology; follow it.
+- **Fix at the owner.** When the framework itself makes a task long, report the
+  exact framework change instead of working around it in the app.
+- You may edit source, styles, messages and tests in scope; every existing
+  behavior assertion stays, and an assertion of old wording or an old step
+  changes with it. Do not edit `.genesis/`, Git metadata, dependency
+  directories, generated build output, retained migration history, or external
+  resources. When a task's observable steps change, keep the Blueprint, the
+  Program and the project's usage documentation in step.
+
+Leave the pass as ordinary uncommitted work for review and a later normal
+commit. Never amend or rewrite selected commits. Summarize the resolved scope,
+the main tasks with who does them, each task's steps and decisions before and
+after, what changed and why, the tests, screenshots and transcripts actually
+taken and run (with their paths), files changed, and findings left unchanged
+with what they need and who must decide.
+
+When the prompt ends with a `PASS RECORD` step, take it once the pass has
+finished: the Genesis `passes done ux-pass` operation records it in `genesis/passes.json`,
+an uncommitted change that lands in the pass's own commit. Genesis adds that
+step only to the pass's own runs, whose requests it writes itself, so a user experience 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 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/skills/genesis-ux-pass/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis user experience pass"
+  short_description: "Make the main tasks short and clear, each walked before and after"
+  default_prompt: "Use $genesis-ux-pass to user experience pass the whole app."

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|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') {
@@ -311,14 +314,21 @@ function writeResult(command, result) {
     return;
   }
   if (command === 'inspect' && result.inspection === 'passes') {
+    if (result.unavailable) line(process.stdout, result.unavailable);
     for (const pass of result.passes) {
       line(process.stdout, `${pass.id}: ${pass.title} — ${pass.description}`);
       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,18 +35,14 @@ const SKILL_FIELDS = new Set([
   'allowed-tools',
 ]);
 
-// Every project's Genesis workflow skills: the project and Program skills, and one for each pass.
+// 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}`,
 ]);
-const CORE_SKILLS = CORE_SKILL_NAMES.map((name) => ({
-  component: null,
-  package: null,
-  path: `skills/${name}`,
-  source: `genesis:skills/${name}`,
-}));
 
 function invalidSkill(message, details = {}) {
   throw new GenesisError('AGENT_SKILL_INVALID', message, details);
@@ -314,30 +310,58 @@ async function resolveLocator(locator) {
   return { ...skill, component: locator.component };
 }
 
-/** Resolves the three Genesis workflow skills plus authoritative selected Stack skills. */
-export async function projectSkillPlan(stack, { projectRoot } = {}) {
-  let coreRoot = packageRoot;
-  if (projectRoot) {
-    let manifest;
-    try { manifest = JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')); } catch (error) {
-      // The manifest says whether the project declares its own genesis-compiler skills.
-      if (error instanceof SyntaxError) {
-        throw new GenesisError('AGENT_SKILL_SOURCE_INVALID',
-          `package.json is not valid JSON, so the project's genesis-compiler skills cannot be located: ${error.message}.`,
-          { path: 'package.json' });
-      }
-      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
-    }
-    if (manifest?.name === 'genesis-compiler') {
-      coreRoot = projectRoot;
-    } else if (['dependencies', 'devDependencies', 'optionalDependencies'].some((field) => (
-      Object.hasOwn(manifest?.[field] || {}, 'genesis-compiler')
-    ))) {
-      coreRoot = await packageDirectory('genesis-compiler', projectRoot, { projectOnly: true });
+// The Genesis a project's core skills come from: Genesis's own source repository, the installed genesis-compiler the
+// project declares (even when a different compiler embeds this API), or else this compiler.
+async function projectGenesisRoot(projectRoot) {
+  if (!projectRoot) return packageRoot;
+  let manifest;
+  try { manifest = JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')); } catch (error) {
+    // The manifest says whether the project declares its own genesis-compiler skills.
+    if (error instanceof SyntaxError) {
+      throw new GenesisError('AGENT_SKILL_SOURCE_INVALID',
+        `package.json is not valid JSON, so the project's genesis-compiler skills cannot be located: ${error.message}.`,
+        { path: 'package.json' });
     }
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+  }
+  if (manifest?.name === 'genesis-compiler') return projectRoot;
+  const declared = ['dependencies', 'devDependencies', 'optionalDependencies'].some((field) => (
+    Object.hasOwn(manifest?.[field] || {}, 'genesis-compiler')
+  ));
+  return declared ? packageDirectory('genesis-compiler', projectRoot, { projectOnly: true }) : packageRoot;
+}
+
+/**
+ * The project's own Genesis: its root and the names of its core skills, which are the directories of its skills
+ * folder. That Genesis is the one authority for what the project has, so a project pinned to an older
+ * genesis-compiler is planned the skills its release has: a skill this compiler added since is not selected for it,
+ * and none is taken from this compiler. Without projectRoot, this compiler's own.
+ */
+export async function projectGenesis({ projectRoot } = {}) {
+  const root = await projectGenesisRoot(projectRoot);
+  const skills = path.join(root, 'skills');
+  let entries;
+  try { entries = await readdir(skills, { withFileTypes: true }); } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    throw new GenesisError('AGENT_SKILL_UNAVAILABLE', `Genesis Agent Skills are unavailable: ${skills}.`, { path: skills });
   }
+  return {
+    root,
+    coreSkills: entries.filter((entry) => entry.isDirectory()).map(({ name }) => name).sort(),
+  };
+}
+
+/** Resolves the project's own Genesis workflow skills plus authoritative selected Stack skills. */
+export async function projectSkillPlan(stack, { projectRoot } = {}) {
+  const genesis = await projectGenesis({ projectRoot });
   const locators = [
-    ...CORE_SKILLS.map((skill) => ({ ...skill, root: coreRoot })),
+    ...genesis.coreSkills.map((name) => ({
+      component: null,
+      package: null,
+      path: `skills/${name}`,
+      root: genesis.root,
+      source: `genesis:skills/${name}`,
+    })),
     ...(stack?.components || []).flatMap((component) => (
       component.skill ? [{ ...component.skill, component: component.id }] : []
     )),

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

@@ -3,6 +3,8 @@ export const GENESIS_CONTRACTS = Object.freeze({
   projectInspection: 'genesis.project-inspection.v1',
   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');
+}