genesis-compiler 1.10.9 → 1.10.11

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,35 @@ 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 and correct as it
+grows, through checks the agent makes and judges rather than numbers it must
+hit. A request, job or test costs in proportion to the rows it handles, never
+to stored history: the agent counts a list's, batch's or write's queries at a
+few rows and at a realistic number and finds what grows with the rows. Tests
+take the time their work needs: the agent reads the suite's time and its
+slowest files and fixes where the time goes, prepares test databases once per
+run (usually from a stored snapshot checked by a digest, with the full
+migration history replayed only by one separate fresh-schema check), and keeps
+each test file independent so files run in parallel and two identical runs
+agree. A refactor lists the behaviors and tests before changing code and walks
+the list again afterwards.
+A failing test is a defect to explain, never noise to rerun, skip or call
+pre-existing, and a final run is one whole run of the pushed tree. Each declared
+constraint and protection is tried with one input that breaks it, access comes
+from the trusted context, and a change others depend on fails loudly where the
+old shape is still used. A short list names what is wrong in any context, such
+as a silently capped read, an edited migration that has run, an edited
+generated file, or tests against a real database. 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. Coarse outer limits, such as a list making hundreds of
+queries or a suite running for hours, mark what is clearly broken; they are not
+targets. The baseline is the short form: the genesis-project skill's sanity
+checks guide (`references/sanity-checks.md`) gives each check's examples and
+outer limits and is read before the agent reports such work done, and each
+Stack piece's "Sanity checks with <stack>" guidance names the stack's own tools
+for them, such as its query counter, parallel test runner and strict loading
+mode.
+
 The installed, versioned profile descriptions live in
 `profiles/engineering/*.md`. Straight Genesis users can inspect and select them
 without editing Markdown grammar:
@@ -575,6 +604,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 +872,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 +886,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
 
@@ -938,9 +991,15 @@ ordinary project operations stop until the migration is resolved.
 ## Development
 
 Run `npm ci` in this source checkout, then `npm test`. The test command runs the
-original test files with file concurrency fixed at one. The local first-party
-catalogue is a development-only dependency so catalogue and starter tests work
-after a clean install; it is not required by the published compiler runtime.
+test files in parallel at Node's default file concurrency; each file creates its
+own temporary projects and directories, so it can run beside any other. The
+suite is kept cheap by what it runs rather than by how many cores share it: a
+test about command logic calls the CLI's own `runCli` in its process, each
+command keeps one real `genesis` run, test projects copy one prepared empty Git
+repository, and the template tests copy one prepared starter instead of
+rebuilding it. The local first-party catalogue is a development-only dependency
+so catalogue and starter tests work after a clean install; it is not required by
+the published compiler runtime.
 
 ## Public API
 

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.
@@ -255,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.9",
+  "version": "1.10.11",
   "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",
@@ -47,7 +48,7 @@
     "docs/parsers.md"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/*.test.js"
+    "test": "node --test test/*.test.js"
   },
   "jskitRelease": {
     "versionFiles": [

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

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

package/profiles/engineering/baseline.md

@@ -4,6 +4,15 @@
 - 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.
+- A request, job or test costs what the rows it handles cost, never what stored history or the whole dataset costs; this is the direct design, not speculative scale work. Check it instead of assuming it: count a list's, batch's or write's queries or storage calls at a few rows and at a realistic number, and judge whether the count follows the pages read or grows with the rows. A count that grows usually means a read, lookup or access check runs per row, or an access check is sized by stored history; related rows come in batches, one query per related table, and every visibility check is bounded by the rows being read. A list that makes hundreds of queries, or a save that takes tens of seconds, is broken: find the cause first. Such limits mark what is clearly broken; they are not targets, and code is never bent to reach a number.
+- Give list, batch and write paths a test at realistic row counts and history, since a handful of rows hides per-row work; it compares counts at two sizes rather than holding a fixed ceiling tuned until it passes. Tests take the time their work needs, no more: read the suite's total time and its slowest files, and find where a slow file's time goes (database preparation, replayed migrations, fixed sleeps, polling, server or build starts). Prepare databases and shared fixtures once per run and reuse them, usually from a stored schema and seed snapshot checked by a digest of their sources rather than by replaying migrations, and keep the full-history migration proof as one separate check. Each test file owns its data, ports and files, never touches a development or production database, and can run beside any other, so two identical runs give the same result; files run in parallel within the machine's test budget, and a suite whose wall time is close to the sum of its files' times ran them one at a time, so find why. A suite that runs for hours, or test preparation measured in minutes, is broken.
+- A refactor, consolidation or move keeps every behavior, or drops one only with the person's agreement. Before changing code, list what it does (its operations, inputs and their validation, permissions, states and edge cases) with the test covering each, adding one where none does; afterwards walk the list again, with the original tests passing and their assertions unchanged. A change that deletes tests or weakens their assertions is not a refactor.
+- A failing test is a defect to explain, in the product or in the test, never noise or a "pre-existing" baseline: do not rerun it until it passes, skip it or loosen it to finish. A final run is one run of the whole suite on the tree that is pushed; reruns, chunks and partial runs are reported as partial. A skipped test records its reason and the run that does cover it. A new test is seen to fail once, by breaking the behavior or reverting the fix.
+- Every constraint and protection the code declares is enforced: send one input that breaks each (a missing required field, a call past a rate limit, a caller without permission, another tenant's id) and see it refused. Authorization is decided before validation answers, from the trusted context rather than ids the client sends, and a missing value, scope or collaborator refuses instead of allowing.
+- A change that other code depends on (a name, a default, a contract) fails loudly, naming its fix, wherever the old shape is still used, and every dependent project is booted and checked with it.
+- Never, whatever the context: cap a read its callers treat as complete; drop a behavior, rule or access decision silently; declare a constraint or protection that nothing enforces; let a client's ids or a missing value decide access; store a missing value as a real one; run tests against a developer's or production database or configuration; edit a migration that has run anywhere; edit a generated file instead of its source; let the first visitor to a new deployment own it; run production with development settings; release a test's servers, processes or timers only where a timeout skips it. Each one silently loses data, protection or a whole run.
 - 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.
+- These are the short form. Genesis's sanity checks guide (`.agents/skills/genesis-project/references/sanity-checks.md`) gives each check's examples and outer limits: read the section that applies before reporting data access, tests, a refactor, a screen or a release done, and apply it with the tools your Stack pieces name.

package/prompts/deslop.txt

@@ -16,5 +16,6 @@ addition to the Genesis Deslop contract. Stack guidance may improve
 technology-specific cleanup, but it cannot broaden the resolved scope,
 weaken behavior preservation, or turn this into another implementation pass.
 
-Report the resolved scope, what became simpler, files changed, checks actually
-run, and any defect or gap deliberately left for follow-up.
+Report the resolved scope, what became simpler, the behaviors checked before
+and after, files changed, checks actually run, and any defect or gap
+deliberately left for follow-up.

package/prompts/review.txt

@@ -8,6 +8,19 @@ 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, citing a count or
+timing where one exists and the code path otherwise: a list or batch whose
+query count grows with its rows, an access check whose cost grows with stored
+history, a list, batch or write path never tested at realistic counts, test
+preparation that replays the migration history, tests that share drifting data
+or cannot run in parallel, and a time limit raised to absorb slowness. Report
+behavior a refactor dropped: operations, validation, permissions or edge cases
+the earlier code had and the current code lacks, and tests deleted or weakened
+with it. Report declared constraints and protections that nothing enforces, and
+access decided from ids the client sends rather than the trusted context.
+Judge each against the matching section and outer limit of
+`.agents/skills/genesis-project/references/sanity-checks.md`.
+
 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-deslop/SKILL.md

@@ -108,6 +108,14 @@ abstractions. Consolidate ownership where one clear module is enough. Do not
 optimize for tiny files or indirection; optimize for a small, obvious design
 that a junior programmer can follow.
 
+Before editing, list the behaviors of the code in scope with the test that
+covers each, as the engineering approach's refactor rule and the "Refactors
+keep behavior" section of
+`.agents/skills/genesis-project/references/sanity-checks.md` describe. After
+cleanup, walk the list again: every item must still hold and still have a test,
+and a test the cleanup changed must assert no less than before. A behavior no
+test covers is a follow-up finding, never permission to drop it.
+
 Cleanup is not a second implementation pass. The selected changes limit where
 cleanup may occur; sharing a file does not bring unrelated edits into scope or
 authorize different behavior in that file. Deslop may reorganize behavior
@@ -136,5 +144,5 @@ Leave the cleanup as ordinary uncommitted work for review and a later normal
 commit. Never amend or rewrite the selected commits. Run focused checks when
 useful. Final declared checks remain available through the Genesis `verify`
 operation. Summarize the resolved scope and any selected commit identities,
-what became simpler, files changed, checks actually run, and follow-up findings
-left unchanged.
+what became simpler, the behaviors checked before and after, files changed,
+checks actually run, and follow-up findings left unchanged.

package/skills/genesis-project/SKILL.md

@@ -164,6 +164,18 @@ 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, with the engineering approach's sanity
+checks. A change to a list, batch or write path ships with a test at realistic
+row counts and history that compares its query count at a few rows and at a
+realistic number. Read the run's preparation, suite and slowest-file timings
+with its counts; when one grows with the data, find the cause (a read per row,
+an access check sized by stored history, test preparation that replays
+migrations) before reporting completion. After a refactor, walk the behavior
+list made before it and report any item that no longer holds. Before reporting
+data access, tests, a refactor, a screen or a release done, read the matching
+section of [the sanity checks guide](references/sanity-checks.md) and apply its
+checks with the tools your Stack pieces name.
+
 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

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

@@ -0,0 +1,352 @@
+# Sanity checks
+
+The Engineering baseline states these checks in short form. This guide gives
+each one's examples and outer limits. Read the section that applies before
+reporting data access, tests, a refactor, a screen or a release done.
+
+## How to use this guide
+
+- Each section gives what good looks like, the check you make and judge, real
+  failures it catches, and an outer limit.
+- Measure, then judge. Prefer counts (queries, requests, processes, DOM nodes)
+  to clock times, which change with the machine.
+- An outer limit marks what is clearly broken, never a target: code just under
+  one is not thereby fine, and code is never bent to reach a number.
+- Apply each check with the tools your Stack pieces name under "Sanity checks
+  with <stack>": the query counter, the parallel runner, the strict mode.
+- Examples come from real projects; one that depends on a stack names it.
+
+## Never do these
+
+Each one silently loses data, protection or a whole run.
+
+- Cap a read its callers treat as complete: they act on a silent first page.
+- Drop a behavior, rule or access decision silently in a restructure.
+- Declare a constraint or protection that nothing enforces.
+- Let a client's ids or a missing value decide access.
+- Store a missing value as a real one: a blank later reads as fact.
+- Run tests against a development or production database or configuration.
+- Edit a migration that has run anywhere: databases diverge.
+- Let the first visitor to a new deployment own it.
+- Run production with development settings, fallbacks, hosts or secrets.
+- Release a test's servers, processes or timers only where a timeout skips it.
+- Edit a generated file instead of its source: the next generation erases it.
+
+## Data: loading a dataset
+
+**Good:** a list, page or report takes about as many queries for 10 rows as
+for 200. Related rows come in one batch per related table, and each visibility
+check is part of the query, bounded by the rows read.
+
+**Check:** seed hundreds of rows and long per-person histories. Count the
+queries at a small and a realistic size and look at what grows. A count that
+grows with the rows means something runs per row: a single-record read, lookup
+or access check inside a loop. A count that grows with a person's history means
+an access check sized by history. Read the captured SQL for:
+- a schema-metadata read on a request path;
+- a row read back just after it was written;
+- the same table and id read twice in one request;
+- one statement repeated with one id at a time;
+- access-policy SQL that runs to kilobytes (print it per role and read its
+  plan).
+
+Compare a response's size with what the screen shows of it.
+
+**Examples:**
+- A page of 100 incidents read each incident's revision, pinned module and
+  readers one at a time: 1,801 queries and 5–7 s. Batched per table it took
+  181, still about one a row.
+- A notice policy checked every source a reader had ever been notified about:
+  26–33 s and 13,176 queries per 100 notices.
+- Schema metadata joined across a database server holding hundreds of
+  databases cost 25–63 s per call (MySQL `information_schema`).
+
+**Outer limit:** a list that makes hundreds of queries, takes over a second on
+a quiet database, runs the same access check more than a few times per
+request, or returns megabytes for one screen is broken. Find the loop first.
+
+## Data: saves, 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. A read request takes no lock and
+writes nothing. Two writers on the same records never produce a server error.
+
+**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. Run two writers on the same records; a retried
+transaction must be safe to repeat.
+
+**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.
+
+## Work that repeats or lingers
+
+**Good:** work whose answer does not change between calls runs once and is
+reused. Everything a feature starts has a named owner that stops it. Each poll
+stands in for a named event, and retries cover network errors, 5xx and 429
+only. Logs say each thing once.
+
+**Check:** time a call that should do nothing. List the processes alive after
+the app has been idle. After a run, read the log's size and most repeated line.
+
+**Example:** an idempotent "ensure" step rediscovered its whole configuration on
+every call.
+
+**Outer limit:** a no-op check over a second, an idle page requesting every
+second, or a log growing by hundreds of MB per run.
+
+## The wait a person sees
+
+**Good:** the time from click to result is known, cold and warm, and each part
+of it has a name.
+
+**Check:** read the server's own request times while the tests run. Time the
+main actions from click to result, and split the time into its parts.
+
+**Outer limit:** an ordinary page taking seconds on a test database, or tens of
+seconds with no feedback.
+
+## Refactors keep behavior
+
+**Good:** a refactor, consolidation or move keeps every behavior and access
+decision, or drops one only with the person's agreement.
+
+**Check:** before changing code, list its operations, inputs and their
+validation, permissions per role, states and edge cases, with the test covering
+each. Afterwards walk the list again with the original tests passing and their
+assertions unchanged. Compare per-file test counts before and after, and name
+each removal. Search for what a removed caller was the only caller of. After a
+mechanical sweep, compare files changed with files expected and search for the
+old form. A new mechanism replaces the one already doing the job.
+
+**Examples:**
+- Restructures dropped validation and access rules along with the tests that
+  covered them, so the suite stayed green.
+
+**Outer limit:** dozens of dropped items found at review.
+
+## Failing tests are bugs
+
+**Good:** a failing test is a defect with an owner, in the product or in the
+test. Red CI on the main branch stops the line. A final run is one whole run on
+the tree that is pushed.
+
+**Check:** name each failure's cause; never rerun until green, skip or loosen
+to finish. Compare the tested commit with the pushed one. List every skip with
+its reason and the run that covers it, against the last run's count. See each
+new test fail once. Diagnosis runs may stop early; a final run runs everything
+and reports what did not run. Report a speed win with its absolute number.
+
+**Examples:**
+- A preparation script ended with `exit $status` instead of
+  `test $status -eq 0`, so it ended the caller and the tests never ran while
+  the run reported success (shell).
+- A suite kept a set of "known" failures as a baseline until they hid a new
+  regression.
+
+**Outer limit:** a red test on main nobody owns, a suite that needs reruns to
+look green, or dozens of skips nobody can place.
+
+## Tests: time
+
+**Good:** tests take the time their work needs. Files run in parallel within
+the machine's test budget. Databases and fixtures are prepared once per run
+from a stored schema and seed, checked by a digest of their sources, and the
+full migration history is replayed once, as its own check. Builds and server starts happen once per run.
+
+**Check:** after every run, read the suite time, each phase's time
+(preparation, import, sign-in, tests) and the slowest files. A wall time close
+to the sum of the files' times means they ran one at a time: find why. In a
+slow file, find where the time goes: repeated preparation, replayed
+migrations, fixed sleeps, polling, a process per test, repeated builds or
+sign-ins. Split test time into the app's request time and the harness's before
+choosing a fix. Remove exact repeats across CI jobs. Each sleep names the
+condition it waits for; wait for that. Compare each raised time limit with the
+measured need, and check a limit exists. Assert counts, not tight times.
+
+**Examples:**
+- 359 tests ran one file at a time, 163 s in all, because the test command
+  forced a concurrency of one.
+- Test databases were rebuilt by replaying every migration for each file.
+- Time limits were raised until slow tests passed, and the slowness stayed.
+
+**Outer limit:** a suite running for hours (a small app's for an hour),
+preparation in minutes, or a limit ten times the measured need.
+
+## Tests: each owns what it uses
+
+**Good:** each test creates and signs in as what it asserts, and each file owns
+its data, system-picked ports, directories and caches. A skip caused by the
+environment is a failure.
+
+**Check:** run a file twice, beside another, reversed and shuffled, and two
+suites at once; the result does not change. Run at a fake time near midnight,
+in another time zone and in a clean environment. Each seed names what needs it;
+volume fixtures belong to the volume tests. A disposable test database server
+may relax durability; each run drops what it made.
+
+**Examples:**
+- Specs passed only after an earlier spec left a signed-in user behind.
+- Two parallel runs collided on one fixed port and one shared cache directory.
+
+**Outer limit:** a test that passes only in one order, or two identical runs
+that differ.
+
+## Tests: nothing hangs or lingers
+
+**Good:** everything a test starts is released by teardown that also runs
+after a timeout, and the process exits when its tests end. Waits wait for the
+thing that matters.
+
+**Check:** list what keeps a finished file alive. A wait that often ends at its
+cap waits for the wrong thing: an idle network on a page with live connections,
+or an animation that never ends.
+
+**Outer limit:** a file that ends only when its limit kills it.
+
+## Tests that prove behavior
+
+**Good:** a test drives the real path, passes after a behavior-preserving
+refactor and fails when the behavior breaks. Doubles answer like the real
+collaborator, refusals included. Every spec is linted and listed by the quick
+check.
+
+**Check:** ask whether each test you touch pins source text or internals. An
+export, option or branch only tests use goes. Name the committed test for each
+user-visible feature you changed.
+
+**Outer limit:** a feature shipped with no test that would fail without it.
+
+## Inputs and access
+
+**Good:** every declared constraint and protection is enforced and has one
+test that trips it. Access comes from the authenticated context, is decided
+before validation answers, and refuses when a scope, role or collaborator is
+missing. Refusals keep their status, code and message to the client. Writes go
+through the layer that applies policy, validation and audit.
+
+**Check:** send one input that breaks each constraint (a missing required
+field, a call past a rate limit, a caller without permission, another tenant's
+id) and see it refused. A malformed request from someone without permission
+gets a 403 and no field errors. Trace inputs that reach file paths. Ask what
+production does when each optional collaborator is missing: "nothing,
+silently" means it is required. Each write that bypasses the policy layer, and
+each "anyway" override, names its reason. Before removing a guard, prove the
+layer below enforces it.
+
+**Examples:**
+- A partial-update mode accepted an empty body and saved nothing, while the
+  schema declared the fields required.
+- A framework silently discarded fields the model did not allow, and the save
+  reported success (Laravel without strict mode).
+
+**Outer limit:** a request missing a required field succeeds, or a user acts in
+another tenant.
+
+## Changes others depend on
+
+**Good:** a change to a name, default or contract fails loudly, naming its
+fix, wherever the old shape remains. A fix reaches every copy of the code it
+fixes. A new setup step runs in every deploy path.
+
+**Check:** boot and check every dependent with the change. Search every copy
+of fixed code, scaffold copies included. Prove a new setup step runs in the
+deploy path. Search the docs for removed or renamed names. A local workaround
+for a dependency's gap names the owner's fix and is marked for removal.
+
+**Outer limit:** a project that runs differently after an update without
+saying so.
+
+## Screens in use
+
+**Good:** a screen renders what is visible, loads what its first view needs,
+and feedback never covers the next action. Each inner page opens directly and
+by link, and Up and Back stay inside the app. Screens use the design system's
+tokens and components and show names, not ids.
+
+**Check:**
+- Count DOM nodes with realistic data, and the requests one action causes
+  across open screens. Follow a big first-screen chunk to its import.
+- After each action, look at what its feedback covers, use the next action and
+  press Escape. At phone width, tap each control after the previous field
+  blurs.
+- Scroll every screen to its end at about 390 px, 1,000 px and desktop width,
+  in light and dark. With a cold cache, look for numbers where names belong.
+- Make each endpoint the first request after a restart; go offline and back;
+  sign out in another tab and return; close the tab during a long action.
+- In a production build, change a screen's inputs and see what it shows change,
+  with no render loops.
+
+**Examples:**
+- A success message appeared over the Save button and took the next tap.
+- A list rendered every row of a large data set into the page.
+
+**Outer limit:** tens of thousands of DOM nodes, typing lag, or megabytes or
+hundreds of requests on a first screen.
+
+## State and workflow
+
+**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.
+
+**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
+stated rule, stop and ask, and keep the failing case.
+
+**Outer limit:** a step that fails because the one before said ready.
+
+## Production settings
+
+**Good:** production fails closed. Development modes, `localhost`, fixed ports
+and fixed secrets exist only in tests. Security headers are sent, email
+ownership is confirmed where sign-up needs it, and tokens and CI jobs have the
+least permission they need.
+
+**Check:** read the running production server's mode and flags and a
+production build's response headers. Sign up without confirming email and try
+to sign in. Run the ecosystem's dependency audit; fix it at the dependency
+ranges. Search fixtures for real names, hosts and emails. Name what ends each
+token.
+
+**Outer limit:** the first visitor can own the deployment, or it runs as
+development.
+
+## AI features
+
+**Good:** the assistant can see and do no more than its user. Volatile state
+sits after the stable prompt prefix, so the model's prompt cache holds.
+
+**Check:** sign in as the least-privileged user and list what the assistant can
+read and change. Read cached and uncached input tokens on two turns of one
+conversation.
+
+**Outer limit:** most input tokens uncached on a long conversation.
+
+## How you work
+
+- Reproduce and measure before changing anything; verify a reviewer's premise.
+- Lint the touched files and confirm the lint reads them. After the gates pass,
+  read the code against this guidance and check each suppression's reason.
+- A reviewer can read each changed function, and the commit, in one sitting.
+- Raise an instruction that slows the work or hides failures; do not follow it
+  silently.
+- Run the smallest check that answers the question, and do not fill a shared
+  machine with full runs. Wait without polling, and read counts and failures,
+  not whole logs.
+- Before acting on a shared machine or tree, name the approval that allows it,
+  and stay inside the approved scope.
+- At the end of a task, list what is uncommitted, and save or revert it.
+
+**Outer limit:** gates green while review finds hundreds of defects, or
+functions thousands of lines long.

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/process.js

@@ -216,6 +216,7 @@ export async function runGit(cwd, args, options = {}) {
       ...options.env,
     }),
     maxBytes: options.maxBytes,
+    input: options.input,
     timeoutMs: options.timeoutMs,
     signal: options.signal,
     code: options.code || 'GIT_EXEC_FAILED',

package/src/index/project-inspection.js

@@ -29,11 +29,12 @@ 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`,
   ]),
+  '.agents/skills/genesis-project/references/sanity-checks.md',
 ]);
 const bootstrapPaths = new Set(GENESIS_BOOTSTRAP_PATHS);
 // Genesis creates .gitignore only to ignore its Cities; any other content is the project's.

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-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

@@ -414,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/template-source.js

@@ -17,6 +17,29 @@ function validateRepository(repository) {
   }
 }
 
+/** Read every listed blob through one `git cat-file --batch` process, in listing order. */
+async function readBlobs(root, entries) {
+  if (entries.length === 0) return [];
+  const { stdout } = await runGit(root, ['cat-file', '--batch'], {
+    input: `${entries.map(({ object }) => object).join('\n')}\n`,
+    // Each blob is preceded by "<object> blob <size>\n" and followed by "\n".
+    maxBytes: entries.reduce((total, { size }) => total + size + 128, 0),
+  });
+  const blobs = [];
+  let offset = 0;
+  for (const { object, size } of entries) {
+    const headerEnd = stdout.indexOf(0x0a, offset);
+    const header = headerEnd === -1 ? '' : stdout.subarray(offset, headerEnd).toString('utf8');
+    const start = headerEnd + 1;
+    if (header !== `${object} blob ${size}` || stdout.length < start + size + 1) {
+      throw new GenesisError('TEMPLATE_SOURCE_INVALID', `Git did not return template blob ${object}.`);
+    }
+    blobs.push(stdout.subarray(start, start + size));
+    offset = start + size + 1;
+  }
+  return blobs;
+}
+
 /**
  * Fetch a branch once and read ordinary blobs; never execute or check out remote hooks/filters.
  * The scratch repository is created below scratchRoot (the system temporary directory by default).
@@ -32,31 +55,43 @@ export async function readGitSnapshot({ repository, branch, scratchRoot = os.tmp
     await runGit(temporaryRoot, ['check-ref-format', `refs/heads/${branch}`]);
     await runGit(temporaryRoot, ['fetch', '--quiet', '--depth=1', '--no-tags', '--', repository, `refs/heads/${branch}`], { timeoutMs: 120_000 });
     const revision = await runGitText(temporaryRoot, ['rev-parse', 'FETCH_HEAD^{commit}']);
-    const tree = await runGit(temporaryRoot, ['ls-tree', '-rz', '--full-tree', revision]);
-    const files = [];
+    // The long listing carries each blob's size, so the limits hold before any content is read.
+    const tree = await runGit(temporaryRoot, ['ls-tree', '-rlz', '--full-tree', revision]);
+    const entries = [];
     let bytes = 0;
+    let fileCount = 0;
     for (const item of tree.stdout.toString('utf8').split('\0').filter(Boolean)) {
       const separator = item.indexOf('\t');
-      const [mode, type, object] = item.slice(0, separator).split(' ');
+      const [mode, type, object, size] = item.slice(0, separator).split(/ +/u);
       const name = item.slice(separator + 1);
       if (!['100644', '100755', '120000'].includes(mode) || type !== 'blob' || path.isAbsolute(name)
         || name.includes('\\') || name.split('/').some((part) => !part || ['.', '..', '.git'].includes(part.toLowerCase()))) {
         throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported path or file: ${name}.`);
       }
-      const blob = await runGit(temporaryRoot, ['cat-file', 'blob', object]);
+      if (mode === '120000') {
+        // Only short Claude skill links are accepted; never read a large one.
+        if (Number(size) > 1024) throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported link: ${name}.`);
+      } else {
+        bytes += Number(size);
+        fileCount += 1;
+        if (bytes > 64 * 1024 * 1024 || fileCount > 10_000) {
+          throw new GenesisError('TEMPLATE_TREE_TOO_LARGE', 'Template exceeds the source size limit.');
+        }
+      }
+      entries.push({ mode, object, name, size: Number(size) });
+    }
+    const blobs = await readBlobs(temporaryRoot, entries);
+    const files = [];
+    for (const [index, { mode, name }] of entries.entries()) {
       if (mode === '120000') {
         const target = claudeSkillLinkTarget(name);
-        if (!target || !blob.stdout.equals(Buffer.from(target))) {
+        if (!target || !blobs[index].equals(Buffer.from(target))) {
           throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported link: ${name}.`);
         }
         // Regenerate these through initialization from the canonical skill files.
         continue;
       }
-      bytes += blob.stdout.length;
-      if (bytes > 64 * 1024 * 1024 || files.length >= 10_000) {
-        throw new GenesisError('TEMPLATE_TREE_TOO_LARGE', 'Template exceeds the source size limit.');
-      }
-      files.push({ path: name, contents: blob.stdout, mode: mode === '100755' ? 0o777 : 0o666 });
+      files.push({ path: name, contents: blobs[index], mode: mode === '100755' ? 0o777 : 0o666 });
     }
     return { repository, branch, revision, files };
   } finally { await rm(temporaryRoot, { recursive: true, force: true }); }

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 });
 }