genesis-compiler 1.10.19 → 1.10.20

package/README.md

@@ -27,8 +27,9 @@ 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, Deslop, and UI pass customization
+  stack/             optional per-component Description, Guidance, Adoption, Post-change, and pass customization
   subsystems.md      authored responsibilities, Program membership, and data ownership/use
+  passes.json        when each pass last finished, written by its last step (absent until one does)
   program/           concise public-operation explanations
 .agents/skills/
   genesis-*          Genesis workflow skills
@@ -187,11 +188,12 @@ 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`, four project Agent Skills,
+empty optional Stack, the current `genesis/version`, seven 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`,
-`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;
+and one for each pass (`genesis-deslop`, `genesis-ui-pass`, `genesis-identity-pass`,
+`genesis-quality-pass` and `genesis-data-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
 optional first-party catalog is installed beside Genesis, that guide includes
@@ -253,10 +255,12 @@ files alone does not refresh its existing context.
 | `genesis stack list` | Lists technology components from the installed Stack catalog. |
 | `genesis stack add <piece...>` | Resolves component dependencies/conflicts, records the selection, materializes missing project contracts, synchronizes declared skills, and prints the one-time preparation prompt. It does not install application packages or run an agent. |
 | `genesis skills sync` | Refreshes selected, unmodified managed skills while preserving customized and unmanaged copies. |
+| `genesis passes done <pass>` | Records in `genesis/passes.json` that a pass finished now; every pass prompt ends with it. |
 | `genesis context <path...>` | Returns path-focused Program explanations, indexed functions, selected technology guidance, exact project contracts, and relevant skills. |
 | `genesis index [--call-web] [function-or-path...]` | Regenerates the derived code indexes and optionally searches the existing function/method inventory. `--call-web` also writes the derived function call web. |
 | `genesis inspect environment` | Reports declared resources, public defaults, missing input names, and environment-file paths without returning secret values. |
 | `genesis inspect skills` | Reports selected skill freshness and ownership without changing files. |
+| `genesis inspect passes` | Lists every pass with its title, description, recommendation hint, Stack guidance and last run. |
 | `genesis inspect section <name>` | Returns one exact consumer-owned Stack section without interpreting or executing it. |
 | `genesis prompt [request...]` | Generates the ordinary implementation prompt. Use `--task` for opening, adoption, Deslop, explanation, review, and other explicit prompt tasks. |
 | `genesis verify` | Executes only the ordered finite commands in `## Verification` and records exact evidence. |
@@ -628,6 +632,36 @@ 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).
 
+### Identity, quality and data passes
+
+Three more passes run only when asked, over the whole app unless the request
+names a section or your changes:
+
+```text
+Give the app its visual identity
+Quality pass
+Data pass the Orders section
+```
+
+```bash
+genesis prompt --task identity-pass
+genesis prompt --task quality-pass
+genesis prompt --task data-pass "Data pass the Orders section"
+genesis inspect passes --json
+```
+
+The identity pass gives the software a look of its own: one seed colour, art
+drawn in code for each kind of content, a logo, empty states, a loading screen
+and sign-in. The quality pass makes loading, empty, error and refused states,
+edge cases and accessibility hold up, proved by using the software. The data
+pass makes queries, constraints, migrations and indexes hold up at real sizes,
+proved by counts. Each skill holds the portable method and points at the
+sanity checks guide; selected Stack components add where each piece lives in
+their technology. `genesis inspect passes` lists every pass, Deslop and the UI
+pass included, for a host to offer, with when each last finished: a pass's last
+step, `genesis passes done <pass>`, records that in the committed
+`genesis/passes.json`. See [docs/passes.md](docs/passes.md).
+
 Projects can customize a selected technology through its matching file, such
 as `genesis/stack/jskit.md`:
 

package/docs/prompt-integration.md

@@ -307,6 +307,12 @@ 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).
 
+The identity, quality and data passes are explicit prompt tasks of the same
+family, whose default scope is the whole app. A host lists every pass, with its
+title, description, recommendation hint and last run, through `inspectPasses()`
+or `genesis inspect passes --json`, instead of naming them itself; see
+[Passes](passes.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

@@ -100,6 +100,21 @@ Concise technology context.
 - The design rules and per-scope method for a UI pass, usually a pointer to
   the technology's own guidance.
 
+## Identity pass
+
+- Where the theme, content colours, artwork, logo, loading screen and sign-in
+  live in this technology, usually a pointer to its own guidance.
+
+## Quality pass
+
+- How this technology shows loading, empty, error and refused states and how
+  to drive the software to see them.
+
+## Data pass
+
+- The data owner layer, query counter, migration mechanics and database
+  differences of this technology.
+
 ## Consumer operation
 
 ```json example.consumer-operation.v1
@@ -110,8 +125,8 @@ Concise technology context.
 ```
 ````
 
-`Description`, `Guidance`, `Adoption`, `Post-change`, `Deslop`, and `UI pass`
-are prose.
+`Description`, `Guidance`, `Adoption`, `Post-change`, and each pass's section
+(`Deslop`, `UI pass`, `Identity pass`, `Quality pass`, `Data pass`) are prose.
 `Requires` and `Conflicts` define component selection. `Skill` names one
 complete authoritative Agent Skill directory. `Indexers` selects installed
 structural adapters.
@@ -261,7 +276,8 @@ A selected component may have one prose-only customization at
 ```
 
 Customizations may add or override only Description, Guidance, Adoption,
-Post-change, Deslop, and UI pass. They cannot mutate selection, resources, environment
+Post-change, and the pass sections (Deslop, UI pass, Identity pass, Quality pass
+and Data 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.19",
+  "version": "1.10.20",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -33,6 +33,9 @@
     "prompts/describe.txt",
     "prompts/deslop.txt",
     "prompts/ui-pass.txt",
+    "prompts/identity-pass.txt",
+    "prompts/quality-pass.txt",
+    "prompts/data-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.19",
+  "version": "1.10.20",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/prompts/data-pass.txt

@@ -0,0 +1,21 @@
+This data pass task has already been rendered by Genesis. Do not generate
+another data pass prompt. Read and follow
+`.agents/skills/genesis-data-pass/SKILL.md` completely.
+
+This is an explicitly requested data pass. With no stated scope it covers the
+whole app. A named section, your own changes, or an explicit commit,
+first-parent count, or range in USER REQUEST narrows it. Establish ownership of
+your own changes from task and edit history; the entire dirty diff is not
+automatically yours. 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 data pass guidance and applicable technology skills in
+addition to the Genesis data pass contract. Stack guidance names its data owner
+layer, query counter, migration mechanics and what differs between databases;
+it cannot broaden the resolved scope or change what the data means. Measure on
+test databases only, never on a development or production database.
+
+Report the resolved scope, the data map, each path's counts before and after at
+a few rows and at a realistic size, the constraints, migrations and indexes
+added with their evidence, files changed, checks actually run, and any defect
+or gap deliberately left for follow-up.

package/prompts/identity-pass.txt

@@ -0,0 +1,23 @@
+This identity pass task has already been rendered by Genesis. Do not generate
+another identity pass prompt. Read and follow
+`.agents/skills/genesis-identity-pass/SKILL.md` completely.
+
+This is an explicitly requested visual identity pass. With no stated scope it
+covers the whole app. A named section, your own changes, or an explicit commit,
+first-parent count, or range in USER REQUEST narrows it; a narrower scope
+extends the app's existing identity rather than inventing another. Establish
+ownership of your own changes from task and edit history; the entire dirty diff
+is not automatically yours. 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 identity pass guidance and applicable technology
+skills in addition to the Genesis identity pass contract. Stack guidance names
+where the theme, the colour module, the artwork, the logo, the loading screen
+and sign-in live in its technology; it cannot broaden the resolved scope or
+turn this into a feature change.
+
+Report the resolved scope, the look spec (style option, seed, content kinds
+and their motifs), what changed, files changed, the checks, contrast figures
+and screenshots actually taken, and any defect or gap deliberately left for
+follow-up.

package/prompts/quality-pass.txt

@@ -0,0 +1,21 @@
+This quality pass task has already been rendered by Genesis. Do not generate
+another quality pass prompt. Read and follow
+`.agents/skills/genesis-quality-pass/SKILL.md` completely.
+
+This is an explicitly requested quality pass. With no stated scope it covers
+the whole app. A named section, your own changes, or an explicit commit,
+first-parent count, or range in USER REQUEST narrows it. Establish ownership of
+your own changes from task and edit history; the entire dirty diff is not
+automatically yours. 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 quality pass guidance and applicable technology skills
+in addition to the Genesis quality pass contract. Stack guidance names how its
+technology shows loading, empty, error and refused states and how to drive the
+software; it cannot broaden the resolved scope or turn this into a feature
+change. Prove the result by using the software through its real interface.
+
+Report the resolved scope, the states listed for each screen or flow with what
+was missing and what changed, the edge cases tried, the refusals reworded, the
+accessibility checks, files changed, the screenshots and tests actually taken
+and run, and any defect or gap deliberately left for follow-up.

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

@@ -0,0 +1,163 @@
+---
+name: genesis-data-pass
+description: Make a project's data hold up at real sizes through an explicitly requested data pass over the whole app, a named section, or the agent's own changes, covering queries that grow with the rows read, no per-row lookups, filters and limits in the query, every constraint enforced and tried, safe migrations, indexes for the filters the app really runs, and tests at realistic sizes. Use when asked for a data pass, or to check data access, scale, constraints, migrations or indexes.
+---
+
+# Genesis data pass
+
+Make the software's data access correct and affordable at the sizes it will
+really hold, and prove it with counts. A data pass is explicit: never run it
+merely because implementation finished.
+
+Resolve the invocation before running the first Genesis operation. Do not use a
+Genesis operation or `genesis --version` as an availability probe.
+
+1. Read the repository-root `package.json`. Treat Genesis as project-pinned only
+   when that manifest's `name` is `genesis-compiler`, or its `dependencies`,
+   `devDependencies`, or `optionalDependencies` contain the exact
+   `genesis-compiler` key.
+2. For a project-pinned repository, invoke every Genesis CLI operation with
+   `npm exec --no -- genesis <arguments>`. This runs without fetching another
+   package. If the declared package is not installed, report that the project's
+   dependencies are not prepared; do not fall back to another Genesis version.
+3. Otherwise, do not try `npm exec`. Run `command -v genesis` (or the current
+   shell's equivalent `PATH` lookup). When it resolves an executable, invoke
+   `genesis <arguments>` directly.
+4. When neither source is available, stop and report that Genesis is
+   unavailable. Never install or update Genesis merely to satisfy a workflow
+   instruction.
+
+Successful invocation resolution is routine. Do not narrate whether Genesis is
+project-pinned or on `PATH`, and never describe direct `PATH` use as a fallback.
+Mention how the invocation was selected only when resolution fails or the user
+explicitly asks.
+
+Follow the configured Collaboration approach for user-facing updates, including
+its technical depth and response length. Report concrete progress,
+findings, or blockers; do not announce that you are following guidance.
+
+## Load the effective project instructions once
+
+A data pass request may arrive as a complete Genesis-generated prompt or as a
+direct request such as `Data pass` or `Data pass the Orders section`.
+
+If the current task already contains `GENESIS CONTEXT` whose task is
+`data-pass`, continue with it directly. Do not generate another prompt.
+
+Otherwise, before resolving scope, run the Genesis `prompt --task data-pass`
+operation once using the invocation rule above. For a bare `Data pass` request,
+pass no request argument. When the user names a section, commits or your own
+changes, pass that exact request as one safely quoted argument. Treat the
+printed prompt as the instructions for this same turn; do not dispatch it to
+another agent and do not generate it again. This step composes the selected
+Stack's data 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 whole app (default).** Every table, collection or store, and every
+  path that reads or writes them.
+- **A section.** A named area (a module, a subsystem, a set of tables): its
+  stores and every path through them, touched or not.
+- **The changes.** Your own changes for the current task, or explicit commits,
+  established and resolved as for Deslop: the stores and paths they create or
+  change.
+
+If the scope is ambiguous, ask which section or changes.
+
+## Map the data first
+
+Read the engineering approach's rules on query counts and realistic tests, and
+these sections of the sanity checks guide
+(`.agents/skills/genesis-project/references/sanity-checks.md`): "Never do
+these", "Data: one owner per table", "Data: one source for each fact", "Data:
+loading a dataset", "Data: each read asks for the rows it uses", "Data: saves,
+batches and background work" and "Inputs and access". They describe what good
+looks like; this pass applies them across the whole scope and fixes what they
+find.
+
+Then list, for the scope: each table, collection or store with its one owner
+(`genesis/subsystems.md` records data ownership), who reads and writes it, its
+constraints and its indexes; and each list, batch, write and background path
+with the filters, sorts and joins it runs. A query, a constraint or an index
+can only be judged against the data it serves.
+
+## Measure before changing
+
+Seed realistic sizes in a test database: hundreds of rows in each list, long
+histories per person, and more rows than any cap. Never use a development or
+production database. Count each path's queries or storage calls at a few rows
+and at the realistic size, and keep the statements captured. A handful of rows
+hides per-row work, and these counts are the figures the report compares.
+
+## Apply the data contract
+
+1. **Counts follow the rows read.** Fix each path whose count grows with the
+   rows or with a person's history, as "Data: loading a dataset" describes:
+   related rows in one batch per related table, and no lookup, single-record
+   read or access check inside a loop.
+2. **The query narrows.** Move each filter, sort, limit, existence check and
+   count that code applies to returned rows into the query, as "Data: each read
+   asks for the rows it uses" describes; a list that can grow is paged, and a
+   capped read is never used as if complete.
+3. **Every constraint enforced, and each one tried.** Every rule the data must
+   keep (required, unique, unique within an owner, a reference to another row,
+   an allowed range or set) is enforced by the store where it can express it,
+   and by the data's owner otherwise. A test sends one value that breaks each
+   and sees it refused, with a message the person can act on. Before adding a
+   constraint, count the existing rows that break it; never delete or rewrite
+   them to make it fit: ask the person what the data should say.
+4. **Safe migrations.** Each change is a new migration; one that has run
+   anywhere is never edited. Prefer additive steps: add, backfill in bounded
+   chunks, then constrain or switch over, and remove the old shape in a later
+   change. Know how long each step holds its locks at the real size, and use
+   the database's online forms for large tables. A step that cannot be undone,
+   or that may lose data, needs the person's agreement first. Run the migration
+   on a copy at realistic size, and keep replaying the full history from empty
+   as its own check.
+5. **Indexes for the filters the app really runs.** From the captured
+   statements, list each filter, sort and join, and give each one an index that
+   serves it, its columns in the order the query uses them; index the columns
+   that reference other rows when the app filters or joins by them. Read the
+   query plan to see each index used. Add no speculative index: each one slows
+   every write and takes space. Remove an index only when you can show nothing
+   uses it.
+6. **Tests at realistic sizes.** Each list, batch and write path keeps a test
+   comparing its count at a few rows and at a realistic number, never a fixed
+   ceiling tuned until it passes; each constraint keeps the test that trips it;
+   each owner keeps a test that another owner's rows stay unseen and unchanged.
+
+## Boundaries
+
+- The pass changes how data is read, written, constrained and indexed, never
+  what it means: no product rule change, no dropped column or row, and no data
+  rewritten without the person's agreement. A missing feature is a follow-up
+  finding, left unchanged.
+- Tests and measurements use test databases the run creates and drops; never a
+  development or production database or its configuration.
+- The selected Stack's data pass guidance names its owner layer, its query
+  counter, its migration mechanics and what differs between databases; follow
+  it.
+- **Fix at the owner.** When the framework or a library blocks a correct
+  query, report the exact change it needs instead of working around it in the
+  app.
+- Do not edit `.genesis/`, Git metadata, dependency directories, generated
+  build output, retained migration history (add new migrations instead), or
+  external resources.
+
+Leave the pass as ordinary uncommitted work for review and a later normal
+commit. Never amend or rewrite selected commits. Summarize the resolved scope,
+the data map, each path's counts before and after at both sizes, the
+constraints added with the test that trips each, the migrations with their
+lock and time notes, the indexes with the query each serves and the plan that
+uses it, the tests added, files changed, checks actually run, and follow-up
+findings left unchanged.
+
+Once the pass has finished, end with the prompt's `PASS RECORD` step: the
+Genesis `passes done data-pass` operation records it in `genesis/passes.json`, an
+uncommitted change that lands in the pass's own commit. A pass that stopped
+early, was abandoned or still has failing checks is not recorded.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis data pass"
+  short_description: "Make queries, constraints, migrations and indexes hold up at real sizes"
+  default_prompt: "Use $genesis-data-pass to data pass the whole app."

package/skills/genesis-deslop/SKILL.md

@@ -146,3 +146,8 @@ useful. Final declared checks remain available through the Genesis `verify`
 operation. Summarize the resolved scope and any selected commit identities,
 what became simpler, the behaviors checked before and after, files changed,
 checks actually run, and follow-up findings left unchanged.
+
+Once the pass has finished, end with the prompt's `PASS RECORD` step: the
+Genesis `passes done deslop` operation records it in `genesis/passes.json`, an
+uncommitted change that lands in the pass's own commit. A pass that stopped
+early, was abandoned or still has failing checks is not recorded.