genesis-compiler 1.10.8 → 1.10.10

package/README.md

@@ -27,7 +27,7 @@ genesis/
   collaboration.md   project-wide communication choices and authored requirements
   engineering.md     selected engineering profile and project-specific requirements
   stack.md           selected components, resources, verification, and project-owned operation contracts
-  stack/             optional per-component Description, Guidance, Adoption, Post-change, and Deslop customization
+  stack/             optional per-component Description, Guidance, Adoption, Post-change, Deslop, and UI pass customization
   subsystems.md      authored responsibilities, Program membership, and data ownership/use
   program/           concise public-operation explanations
 .agents/skills/
@@ -36,7 +36,7 @@ genesis/
 .codex/hooks.json    project-local Codex lifecycle integration
 .claude/settings.json project-local Claude Code lifecycle integration
 .opencode/plugins/   project-local OpenCode lifecycle integration
-.genesis/            local, git-ignored (`genesis init` adds the ignore lines)
+.genesis/            local, git-ignored (`genesis init` adds the ignore lines; `genesis index` reports CITY_FILES_TRACKED while Git tracks a City)
   machine-city.json  derived detailed source and function map
   program-city.json  derived simple subsystem and operation map
   call-web.json      derived function call web (`genesis index --call-web`)
@@ -187,10 +187,10 @@ type a command. It never runs adoption without approval and does nothing in an
 empty or already-adopted project.
 
 `genesis init` creates an empty Blueprint, a focused engineering approach, an
-empty optional Stack, the current `genesis/version`, three project Agent Skills,
+empty optional Stack, the current `genesis/version`, four project Agent Skills,
 and project-local guidance adapters for Codex, Claude Code and OpenCode. The skills are ordinary
 [Agent Skills](https://agentskills.io): `genesis-project`, `genesis-program`,
-and `genesis-deslop`, each with standard `SKILL.md` and `agents/openai.yaml`
+`genesis-deslop` and `genesis-ui-pass`, each with standard `SKILL.md` and `agents/openai.yaml`
 metadata. Open `/hooks` once in Codex to review and trust the guidance hook;
 Claude Code loads its project hooks and OpenCode discovers its local project plugin automatically. All three use the same
 Genesis-owned operating guide for new sessions and after compaction. When the
@@ -363,6 +363,17 @@ allowed. When a concrete requirement makes material complexity necessary, the
 agent must explain why a direct design is insufficient and ask before writing
 that complexity.
 
+The same baseline keeps what the software builds fast as it grows. A request,
+job or test costs in proportion to the rows it handles, never to stored history:
+a list reads each table once, a write decides access once, and every visibility
+check is bounded by the rows it reads. List, batch and write paths have a test
+at realistic row counts that fails above a fixed query or time budget. Test
+databases are prepared once per run from a stored schema and seed snapshot
+checked by a digest, with the full migration history replayed only by one
+separate fresh-schema check. A time limit catches a hang; a slow check is
+measured and its cause fixed, never hidden by a longer limit, retries or
+smaller data.
+
 The installed, versioned profile descriptions live in
 `profiles/engineering/*.md`. Straight Genesis users can inspect and select them
 without editing Markdown grammar:
@@ -575,6 +586,28 @@ up; it does not silently select the latest commit. Its result is a normal
 uncommitted diff for review and a later commit. It never amends selected commits,
 silently fixes newly discovered defects, or runs as an automatic completion phase.
 
+### UI pass your changes, a section, or the whole app
+
+A UI pass makes UI exact to the selected Stack's design rules without changing
+behavior. Ask directly, or generate the prompt for a host:
+
+```text
+UI pass
+UI pass the last commit
+UI pass the Suppliers section
+UI pass the whole app
+```
+
+```bash
+genesis prompt --task ui-pass "UI pass the Suppliers section"
+```
+
+The installed `genesis-ui-pass` skill resolves the scope as Deslop does, adds
+the named-section and whole-app scopes, and follows the effective `UI pass`
+prose of the selected Stack components, which names the technology's design
+rules and method. Defects become findings; screenshots at 390, 768 and 1280
+pixels in light and dark are the evidence. See [docs/ui-pass.md](docs/ui-pass.md).
+
 Projects can customize a selected technology through its matching file, such
 as `genesis/stack/jskit.md`:
 
@@ -821,6 +854,7 @@ add or replace complete project sections when its real scripts differ.
 | `Deployment` build | `npm run build` | Produce the deployable application build. | The deployment consumer. |
 | `Deployment` serve | `npm start` | Start the built production application. | The deployment consumer. |
 | `Deployment` readiness | `GET /api/health` → `200` | Prove that the deployed service is ready. | The deployment consumer. |
+| `Deployment` generated secrets | `AUTH_LOCAL_SESSION_SECRET` | Let the deployment create the local-authentication session secret instead of committing or inventing it. | The deployment consumer. |
 
 The JSKIT proposal also declares `.env` as its environment projection and says
 that inactive deployment workspaces may recreate `node_modules`; it deliberately
@@ -834,7 +868,8 @@ database-preparation command. If the application implements a real migration or
 seed script, the agent records that exact command in the complete project
 sections whose consumers need it. Local authentication similarly requires the
 application to declare `AUTH_LOCAL_SESSION_SECRET` without committing its
-value.
+value; the JSKIT Deployment proposal lists it as a generated secret for the
+deployment consumer to create.
 
 ### How the Stack contract is enforced
 

package/docs/prompt-integration.md

@@ -290,6 +290,13 @@ once in the same turn so those effective Stack instructions are present. A
 prompt whose Genesis context already identifies the Deslop task is followed
 directly and never generated recursively.
 
+A UI pass is an explicit prompt task with the same scope rules, plus a named
+section or the whole app. Selected Stack `UI pass` prose supplies the design
+rules and the method for each scope; the installed `genesis-ui-pass` skill
+generates the canonical `ui-pass` prompt once, like Deslop's. A host offers it
+only when `inspectPromptTasks()` reports Stack guidance for `ui-pass`; see
+[UI pass](ui-pass.md).
+
 Once Codex identifies relevant source, `genesis context <path...>` returns only
 Program modules citing those paths plus the effective engineering approach,
 concise selected Stack guidance, exact project-owned Stack contracts, the

package/docs/stack-components.md

@@ -95,6 +95,11 @@ Concise technology context.
 
 - Technology-specific cleanup guidance.
 
+## UI pass
+
+- The design rules and per-scope method for a UI pass, usually a pointer to
+  the technology's own guidance.
+
 ## Consumer operation
 
 ```json example.consumer-operation.v1
@@ -105,7 +110,8 @@ Concise technology context.
 ```
 ````
 
-`Description`, `Guidance`, `Adoption`, `Post-change`, and `Deslop` are prose.
+`Description`, `Guidance`, `Adoption`, `Post-change`, `Deslop`, and `UI pass`
+are prose.
 `Requires` and `Conflicts` define component selection. `Skill` names one
 complete authoritative Agent Skill directory. `Indexers` selects installed
 structural adapters.
@@ -223,8 +229,11 @@ the installed Skill do not rewrite what an already-run command proved.
 
 `City regions` and `Indexers` control only the derived structural maps. Indexers
 identify language adapters. City regions can exclude test/spec paths and group
-indexed files into deterministic regions and campuses. Both projections are
-navigation data, not proof of complete runtime behavior.
+indexed files into deterministic regions and campuses. A project adds its own
+exclusions, such as example fixtures, in a `## City exclusions` section of
+`genesis/stack.md` with the same ``- Ignore `glob` `` lines (or `- Nothing.`);
+they add to the component exclusions. Both projections are navigation data, not
+proof of complete runtime behavior.
 
 ## Project customization
 
@@ -252,7 +261,7 @@ A selected component may have one prose-only customization at
 ```
 
 Customizations may add or override only Description, Guidance, Adoption,
-Post-change, and Deslop. They cannot mutate selection, resources, environment
+Post-change, Deslop, and UI pass. They cannot mutate selection, resources, environment
 declarations, Verification, Agent Skill ownership, indexers, or opaque consumer
 sections.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.10.8",
+  "version": "1.10.10",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -32,6 +32,7 @@
     "prompts/adopt.txt",
     "prompts/describe.txt",
     "prompts/deslop.txt",
+    "prompts/ui-pass.txt",
     "prompts/program.txt",
     "prompts/review.txt",
     "prompts/start.txt",

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.10.8",
+  "version": "1.10.10",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/profiles/engineering/baseline.md

@@ -4,6 +4,9 @@
 - Prefer direct control flow, existing ownership boundaries, and established project or technology seams.
 - Do not overengineer or overcomplicate the solution. Do not add speculative abstractions, layers, dependencies, infrastructure, compatibility paths, distributed patterns, cryptography, enterprise patterns, or other advanced machinery unless an explicit requirement or a concrete constraint makes it necessary.
 - If good software requires material complexity beyond these rules, stop before writing it. Explain the requirement, why the direct design is insufficient, and the smallest added complexity proposed, then ask the user to approve or clarify the tradeoff.
+- Keep the cost of each request, job and test proportional to the rows it handles, never to stored history or the whole dataset; this is the direct design, not speculative scale work. A list reads each table once for the whole list (one query with an id-list filter, grouped in memory), never one row or lookup per item. A write decides access once and never pays a read-side visibility check whose cost grows with stored history; every visibility check is bounded by the rows being read.
+- Give each list, batch and write path a test at realistic row counts and history that fails above a fixed query or time budget; a handful of rows hides per-row reads. Tests take the time their work needs, no more: prepare databases and other shared fixtures once per run from a stored schema and seed snapshot checked by a digest of their sources, never by replaying the full migration history inside the run, and keep the full-history migration proof as one separate check. Report preparation and suite timings.
 - During implementation, run the relevant checks and batch related cases when they share setup. Follow the project's verification policy for broad or final checks; do not repeat them merely because an item finishes or a session resumes. Preserve required coverage and isolation.
 - Bound each long check by a time limit so it ends even when it hangs; write its complete output to a local file and preserve its exit status. Afterwards read concise counts, timings and actionable failure excerpts first, expanding evidence only when needed; never load full passing reports into agent context. Retain startup and cleanup failures; retry only after a change or new evidence justifies it.
+- A time limit catches a hang; it does not fix slowness. When a check, test or request is slower than its work needs, measure where the time goes and fix the cause; never raise a time limit, add retries, repeat a call or shrink realistic data or coverage to make it pass.
 - For browser verification, batch related actions and return only the relevant values or page region. Capture screenshots at meaningful visual checkpoints or failures, not after every action. Preserve required viewport, identity and security coverage; prefer existing automated cases for repeated checks.

package/prompts/review.txt

@@ -8,6 +8,12 @@ directions. Identify missing or contradictory behavior, misleading explanation,
 unnecessarily difficult public shape, and verification gaps. Distinguish direct
 evidence from inference and state questions that require human intent.
 
+Report what makes requests or tests slower than their work: a list that reads
+one row or lookup per item, an access check whose cost grows with stored
+history, a list, batch or write path without a realistic-count query or time
+budget, test preparation that replays the migration history, and a time limit
+raised to absorb slowness.
+
 Do not edit any file. Return a concise report ordered by impact with exact file
 references, the evidence inspected, and the smallest sensible correction.
 

package/prompts/ui-pass.txt

@@ -0,0 +1,23 @@
+This UI pass task has already been rendered by Genesis. Do not generate another
+UI pass prompt. Read and follow `.agents/skills/genesis-ui-pass/SKILL.md`
+completely.
+
+This is an explicitly requested behavior-preserving UI pass. With no stated
+scope, select your own changes for the current task across preceding turns,
+committed or uncommitted. An explicit commit, first-parent count, or range in
+USER REQUEST takes precedence regardless of who authored those changes. A named
+section or "the whole app" in USER REQUEST selects that scope instead.
+Establish ownership from task and edit history; the entire dirty diff is not
+automatically yours. If ownership is unclear, ask for scope. A dirty worktree
+is allowed: preserve unrelated edits and existing staging, and leave the pass
+as ordinary uncommitted work for review.
+
+Apply the selected Stack UI pass guidance and applicable technology skills in
+addition to the Genesis UI pass contract. Stack guidance owns the design rules
+and the method for each scope; it cannot broaden the resolved scope or turn
+this into another implementation pass. Navigation rules that the Stack
+guidance marks as must-fix are fixed at every scope.
+
+Report the resolved scope, what changed, files changed, the checks and
+screenshots actually taken, and any defect or gap deliberately left for
+follow-up.

package/skills/genesis-project/SKILL.md

@@ -151,13 +151,35 @@ technology's workspace substrate exists. Finishing an item or resuming a
 session does not itself require a broad verification run. Keep full output in
 local artifacts, preserve exit status, and read summaries and relevant failure
 excerpts before expanding logs. Do not weaken assertions or omit required
-coverage to save time or tokens. An unconfigured result
-means the declared workspace or checks do not exist yet; it is not a failing
-check. Before reporting completion, compare the requested observable behavior,
-required inputs and resources, declared project operations, and focused evidence
-with what actually exists. Report files changed, checks actually run,
-anything not proven, and anything still requiring attention. Never claim that
-an unrun check passed or that passing checks prove the whole product.
+coverage to save time or tokens.
+
+A change to user-visible behavior ships with the browser specs that cover it
+updated and run in the same change, before pushing. When an existing spec
+fails, first classify it as outdated (the behavior changed on purpose) or as a
+regression. Fix regressions in the product, and change a spec only for an
+intended change, naming the change that made it outdated. Test resources a
+managed host supplies, such as a login state, base URL, browser, or ports, are
+the host's contract. If they do not work (for example, tests run signed out
+despite a supplied login), report the host defect with evidence and stop; never
+compensate in the project by rewriting cookies or adding its own login or
+browser.
+
+Speed is verified like behavior, so tests stay fast as the project grows. A
+change to a list, batch or write path ships with a test at realistic row counts
+and history that fails above a fixed query or time budget. Read the run's
+preparation, suite and slowest-case timings with its counts; when one grows,
+find the cause (a read per row, an access check sized by stored history, test
+preparation that replays migrations) before reporting completion. Never raise a
+time limit, add retries, or shrink fixtures or coverage to make a slow check
+pass.
+
+An unconfigured result means the declared workspace or checks do not exist
+yet; it is not a failing check. Before reporting completion, compare the
+requested observable behavior, required inputs and resources, declared project
+operations, and focused evidence with what actually exists. Report files
+changed, checks actually run, anything not proven, and anything still requiring
+attention. Never claim that an unrun check passed or that passing checks prove
+the whole product.
 
 ## Subsystem maintenance
 

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

@@ -0,0 +1,111 @@
+---
+name: genesis-ui-pass
+description: Make a project's UI exact to its selected Stack's UI guidance (for example Material 3) through a behavior-preserving UI pass over the agent's own task changes, explicitly selected commits, a named section, or the whole app. Use when asked for a UI pass, to make screens follow the design system exactly, or when a host runs its automatic UI pass after a plan.
+---
+
+# Genesis UI pass
+
+Make the selected UI exact to the project's design rules without changing what
+the product does. A UI pass is explicit: never run it merely because
+implementation finished, unless the host's automatic UI pass asked for it.
+
+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 UI pass request may arrive as a complete Genesis-generated prompt or as a
+direct request such as `UI pass` or `UI pass the Suppliers section`.
+
+If the current task already contains `GENESIS CONTEXT` whose task is
+`ui-pass`, continue with it directly. Do not generate another prompt.
+
+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
+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.
+
+## 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.
+
+- **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
+  confirmed against the current source. Neither the dirty diff, the latest
+  commit, nor a Git author proves ownership. An explicit commit, first-parent
+  count, or range takes precedence, with the same meaning as for Deslop ("the
+  last commit" is `HEAD` against its first parent; "the last N commits" is the
+  net change across them). In scope: every screen, component and style those
+  changes created or edited, and the screens that render them. If you made no
+  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.
+
+If the scope is ambiguous, ask which changes or which section.
+
+## Apply the UI pass contract
+
+The SELECTED STACK UI PASS GUIDANCE is the design authority: read every
+document it names completely before editing, and follow its method for the
+resolved scope. Without Stack UI pass guidance, follow the project's own
+established design system and the official documentation of its UI framework;
+do not invent a new one.
+
+- **Behavior stays as it is.** Change how the UI looks and is laid out, never
+  what it does: no feature, field, action, permission, validation, data or
+  copy change beyond what the design rules require. A defect, missing behavior,
+  contract mismatch or test gap you notice is a follow-up finding, left
+  unchanged. Rules the Stack guidance marks as must-fix (such as navigation
+  rules) are fixed at every scope, never only reported.
+- **Fix at the owner.** When the framework itself blocks an exact result,
+  report the exact framework change instead of compensating with app CSS,
+  `!important`, or a copied framework file.
+- **Prove it.** Run the conformance checks the Stack guidance names on the
+  scope until they pass. Take screenshots of every affected screen at 390, 768
+  and 1280 pixels wide, in light and dark, through the host's managed browser
+  or a temporary browser test: after the pass for the changes, and before and
+  after for a section or the whole app. Look at every screenshot. Keep them out
+  of the repository's tracked files and delete temporary test files. Close
+  every browser you start. Run the focused tests of the affected screens.
+- **Edits.** You may edit UI source, styles and tests whose markup changed;
+  every behavior assertion stays. Do not edit `.genesis/`, Git metadata,
+  dependency directories, generated build output, retained migration history,
+  or external resources. Update an affected Program citation only when a move
+  makes it stale.
+
+Leave the pass as ordinary uncommitted work for review and a later normal
+commit. Never amend or rewrite the selected commits. Summarize the resolved
+scope and any commit identities, what changed, files changed, the checks and
+screenshots actually taken (with their paths), and follow-up findings left
+unchanged.

package/skills/genesis-ui-pass/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis UI pass"
+  short_description: "Make your task's UI, a section or the whole app exact"
+  default_prompt: "Use $genesis-ui-pass to UI pass your own changes for the current task."

package/src/cli.js

@@ -76,7 +76,7 @@ const USAGE = `Usage:
   genesis inspect skills
   genesis inspect section <name>
   genesis prompt [request...]
-  genesis prompt --task <start|adopt|work|deslop|program|blueprint|describe|review> [request...]
+  genesis prompt --task <start|adopt|work|deslop|ui-pass|program|blueprint|describe|review> [request...]
   genesis verify
   genesis check
 

package/src/index/agent-skills.js

@@ -38,6 +38,7 @@ const CORE_SKILLS = [
   'genesis-project',
   'genesis-program',
   'genesis-deslop',
+  'genesis-ui-pass',
 ].map((name) => ({
   component: null,
   package: null,

package/src/index/assets.js

@@ -10,6 +10,7 @@ const assets = {
   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),
   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

@@ -308,6 +308,31 @@ async function callWebIgnored(root) {
   }
 }
 
+// The Cities are rebuilt from the working tree, so a copy Git tracks is stale
+// after every commit. Reports the exact fix: ignore lines for any City the
+// patterns miss (matched without the index, which never ignores tracked
+// files), then untracking the tracked copies.
+async function trackedCityDiagnostics(root) {
+  const cities = [MACHINE_CITY_PATH, PROGRAM_CITY_PATH];
+  const { stdout } = await runGit(root, ['ls-files', '-z', '--cached', '--', ...cities]);
+  const tracked = stdout.toString('utf8').split('\0').filter(Boolean);
+  if (tracked.length === 0) return [];
+  const unignored = [];
+  for (const city of cities) {
+    try {
+      await runGit(root, ['check-ignore', '--quiet', '--no-index', city]);
+    } catch (error) {
+      if (error.details?.status !== 1) throw error;
+      unignored.push(`\`/${city}\``);
+    }
+  }
+  const untrack = `\`git rm --cached -- ${tracked.join(' ')}\` and commit`;
+  const message = unignored.length
+    ? `Add ${unignored.join(' and ')} to .gitignore, then run ${untrack}`
+    : `Run ${untrack}`;
+  return [{ code: 'CITY_FILES_TRACKED', path: tracked[0], message }];
+}
+
 // Call sites are only checked for presence up front. Their values are read
 // when the call web is built, after the observation reader, so a host's
 // inspector never runs beside them.
@@ -382,6 +407,7 @@ export async function buildProjectIndex({
     if (await callWebIgnored(root)) callSites = await prepareCallSites(root, indexers, files);
     else callWebDiagnostics.push({ code: 'CALL_WEB_NOT_IGNORED', path: CALL_WEB_PATH, message: 'Add `/.genesis/call-web.json` to .gitignore' });
   }
+  const cityDiagnostics = await trackedCityDiagnostics(root);
   const extractionRoot = await extractionCacheRoot(root, 'extractions');
   const { contributions, diagnostics, cacheLocations } = await extractCodeIndexes({ indexers, files, projectRoot: root, signal, callSites: callSites?.misses.map(entry => entry.path) || [], cacheRoot: extractionRoot });
   if (callSites) {
@@ -430,7 +456,7 @@ export async function buildProjectIndex({
   }
   const architecture = machine.architecture;
   const discovered = await discoverEntryPoints({ projectRoot: root, architecture, functions: machine.functions, program });
-  architecture.diagnostics.push(...discovered.diagnostics, ...callWebDiagnostics);
+  architecture.diagnostics.push(...discovered.diagnostics, ...callWebDiagnostics, ...cityDiagnostics);
   architecture.capabilities.entryPoints = discovered.capability;
   let callWebDocument = null;
   let callWebSource = null;
@@ -478,7 +504,7 @@ export async function buildProjectIndex({
     if (callSites) await pruneExtractions(callSites.cacheRoot, callSites.candidates.map(entry => entry.location));
   }
   const allMatches = machine.functions.filter((entry) => functionMatches(entry, queries));
-  // Entry-point and call-web diagnostics are already part of the architecture's.
+  // Entry-point, call-web and tracked-City diagnostics are already part of the architecture's.
   const allDiagnostics = [...diagnostics, ...program.diagnostics, ...architectureDiagnostics];
   return {
     status: allDiagnostics.length > 0 ? 'completed-with-warning' : 'ready',

package/src/index/contracts.js

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

package/src/index/project-inspection.js

@@ -29,7 +29,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'].flatMap((name) => [
+  ...['genesis-project', 'genesis-program', 'genesis-deslop', 'genesis-ui-pass'].flatMap((name) => [
     `.claude/skills/${name}`,
     `.agents/skills/${name}/SKILL.md`,
     `.agents/skills/${name}/agents/openai.yaml`,

package/src/index/prompt.js

@@ -11,6 +11,7 @@ import {
 import { readStack, stackPromptContext } from './stack.js';
 import { listStackCatalogPieces } from './stack-catalog.js';
 import { normalizeStackPieceId } from './stack-piece.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
@@ -22,12 +23,13 @@ import { classifyProjectKind } from './project-files.js';
 import { inspectProjectFormatAtRoot } from './project-format.js';
 import { inspectProject } from './project-inspection.js';
 
-const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
+const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'ui-pass', '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.',
   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.',
@@ -131,6 +133,7 @@ function renderPrompt({
   skills = '',
   guidance = '',
   cleanup = '',
+  uiPass = '',
   postChange = '',
   adoption = '',
   collaborationGuidance = '',
@@ -155,6 +158,7 @@ function renderPrompt({
     ...(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] : []),
     '',
   ].join('\n');
 }
@@ -404,6 +408,21 @@ 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,
+ * 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 };
+  return {
+    contract: GENESIS_CONTRACTS.promptTasks,
+    tasks: [...TASKS].map((task) => ({ task, stackGuidance: Boolean(lanes[task]) })),
+  };
+}
+
 export async function generateProjectPrompt({
   environment = process.env,
   hiddenStackPieces = [],
@@ -574,6 +593,7 @@ export async function generateProjectPrompt({
     skills: renderAgentSkillCatalog(projectSkills.skills),
     postChange: task === 'work' ? stack.postChange : '',
     cleanup: task === 'deslop' ? stack.deslop : '',
+    uiPass: task === 'ui-pass' ? stack.uiPass : '',
   });
   return {
     status: 'ready',

package/src/index/stack-city-presentation.js

@@ -7,8 +7,8 @@ const FALLBACK_LINE = /^- Fallback `([^`]+)` as `([^`]+)`[ \t]*$/u;
 const REGEXP_SPECIAL = /[.+^${}()|[\]\\]/u;
 const compiledGlobPatterns = new Map();
 
-function invalid(piecePath, message) {
-  throw new GenesisError('STACK_PIECE_INVALID', message, { path: piecePath });
+function invalid(piecePath, message, code = 'STACK_PIECE_INVALID') {
+  throw new GenesisError(code, message, { path: piecePath });
 }
 
 function normalizedPrefix(value, piecePath) {
@@ -25,7 +25,7 @@ function normalizedPrefix(value, piecePath) {
   return prefix;
 }
 
-function normalizedGlob(value, piecePath) {
+function normalizedGlob(value, piecePath, { code, section = 'City regions' } = {}) {
   const pattern = String(value || '').trim();
   if (
     !pattern
@@ -37,7 +37,8 @@ function normalizedGlob(value, piecePath) {
   ) {
     invalid(
       piecePath,
-      '## City regions ignore patterns must be canonical project-relative globs using only * and ** wildcards.',
+      `## ${section} ignore patterns must be canonical project-relative globs using only * and ** wildcards.`,
+      code,
     );
   }
   return pattern;
@@ -156,6 +157,27 @@ export function parseStackCityPresentationLines(lines, { path = 'stack piece' }
   return { exclusions, regions };
 }
 
+/**
+ * A project's own `## City exclusions` section removes paths no selected
+ * component can know about, such as example fixtures. It uses the City regions
+ * Ignore grammar and adds to the component exclusions.
+ */
+export function parseProjectCityExclusionLines(lines, { path }) {
+  if (lines === undefined) return [];
+  const content = lines.filter((line) => line.trim());
+  if (content.length === 1 && content[0].trim() === '- Nothing.') return [];
+  const options = { code: 'STACK_INVALID', section: 'City exclusions' };
+  const exclusions = content.map((line) => {
+    const ignore = line.match(IGNORE_LINE);
+    if (!ignore) invalid(path, '## City exclusions entries must each be one Ignore with a glob.', options.code);
+    return normalizedGlob(ignore[1], path, options);
+  });
+  if (exclusions.length === 0 || new Set(exclusions).size !== exclusions.length) {
+    invalid(path, '## City exclusions needs distinct Ignore entries or `- Nothing.`.', options.code);
+  }
+  return exclusions;
+}
+
 export function composeStackCityPresentation(components = []) {
   const owners = components.filter((component) => (
     component.cityRegions.length > 0 || component.cityExclusions.length > 0

package/src/index/stack-piece.js

@@ -16,6 +16,7 @@ const STACK_CUSTOMIZATION_FIELDS = new Map([
   ['Adoption', 'adoption'],
   ['Post-change', 'postChange'],
   ['Deslop', 'deslop'],
+  ['UI pass', 'uiPass'],
 ]);
 const STACK_PIECE_SECTIONS = new Set([
   'Adoption',
@@ -31,6 +32,7 @@ const STACK_PIECE_SECTIONS = new Set([
   'Requires',
   'Resources',
   'Skill',
+  'UI pass',
   'Verification',
 ]);
 
@@ -115,12 +117,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, or Deslop.');
+      invalid(piecePath, 'Customization content must be below Description, Guidance, Adoption, Post-change, Deslop, or UI pass.');
     }
   }
   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, or Deslop.');
+    invalid(piecePath, 'Stack customization must add or override Description, Guidance, Adoption, Post-change, Deslop, or UI pass.');
   }
   return result;
 }
@@ -329,6 +331,7 @@ export function parseStackPieceSource(value, {
   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') || [],
@@ -364,6 +367,7 @@ export function parseStackPieceSource(value, {
     environmentFiles: environmentFiles || [],
     extensions: opaqueStackSections(all, STACK_PIECE_SECTIONS),
     deslop,
+    uiPass,
   };
 }
 
@@ -412,5 +416,6 @@ export function applyStackPieceCustomization(piece, customization) {
       customization.add.postChange,
     ),
     deslop: customizedText(piece.deslop, customization.override.deslop, customization.add.deslop),
+    uiPass: customizedText(piece.uiPass, customization.override.uiPass, customization.add.uiPass),
   };
 }

package/src/index/stack.js

@@ -7,7 +7,10 @@ import {
   normalizeStackPackageName,
   readStackCatalog,
 } from './stack-catalog.js';
-import { composeStackCityPresentation } from './stack-city-presentation.js';
+import {
+  composeStackCityPresentation,
+  parseProjectCityExclusionLines,
+} from './stack-city-presentation.js';
 import { parseUiDiscovery } from './stack-ui-discovery.js';
 import { parsePackageDiscovery } from './stack-package-discovery.js';
 import { resolveStackPieces } from './stack-composition.js';
@@ -371,6 +374,13 @@ async function readStackWithContractMode(projectRoot, {
     source: 'project',
     diagnostics: [],
   }));
+  const cityExclusions = [...new Set([
+    ...cityPresentation.exclusions,
+    ...parseProjectCityExclusionLines(
+      extensions.find(entry => entry.name === 'City exclusions')?.lines,
+      { path: STACK_PATH },
+    ),
+  ])];
   const uiDiscovery = parseUiDiscovery(extensions.find(entry => entry.name === 'UI discovery')?.lines);
   const packageDiscovery = parsePackageDiscovery(extensions.find(entry => entry.name === 'Package discovery')?.lines);
   return {
@@ -378,7 +388,7 @@ async function readStackWithContractMode(projectRoot, {
     identityHash: sha256(stableJson({
       stackPackages: declaredPackages,
       components: components.map(({ id }) => id),
-      cityExclusions: cityPresentation.exclusions,
+      cityExclusions,
       cityRegions: cityPresentation.regions,
       verificationCommands: verificationCommands.map(({ label, argv }) => ({ label, argv })),
       environmentDefaults,
@@ -388,7 +398,7 @@ async function readStackWithContractMode(projectRoot, {
     })),
     components,
     stackPackages: declaredPackages,
-    cityExclusions: cityPresentation.exclusions,
+    cityExclusions,
     cityRegions: cityPresentation.regions,
     uiDiscovery,
     packageDiscovery,
@@ -404,6 +414,7 @@ async function readStackWithContractMode(projectRoot, {
     adoption: composedProse(components, 'adoption'),
     postChange: composedProse(components, 'postChange'),
     deslop: composedProse(components, 'deslop'),
+    uiPass: composedProse(components, 'uiPass'),
   };
 }
 

package/src/index.js

@@ -12,7 +12,7 @@ import {
 } from './index/collaboration.js';
 import { GENESIS_CONTRACTS } from './index/contracts.js';
 import { contextForProjectPaths } from './index/context.js';
-import { generateProjectPrompt } from './index/prompt.js';
+import { generateProjectPrompt, inspectProjectPromptTasks } from './index/prompt.js';
 import {
   inspectProjectEngineering,
   listEngineeringProfileCatalog,
@@ -192,6 +192,10 @@ export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }
 
+export function inspectPromptTasks(options) {
+  return inspectProjectPromptTasks(options);
+}
+
 export function getContext({ paths, projectRoot = process.cwd(), stackPackages = [] } = {}) {
   return contextForProjectPaths({ paths, projectRoot, stackPackages });
 }