genesis-compiler 1.10.10 → 1.10.12

package/README.md

@@ -363,16 +363,34 @@ 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 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
@@ -973,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
 
@@ -1028,10 +1052,12 @@ The CLI can also prepare and verify parsers for an offline host; see
 [language parser management](docs/parsers.md).
 `migrate()` updates recognized older Genesis project-file formats and returns
 the resulting structural check for hosts.
-`inspectProjectFormat({ projectRoot })` returns only the format marker's `path`,
+`inspectProjectFormat({ projectRoot, rootMode })` returns only the format marker's `path`,
 `status`, `projectVersion`, `supportedVersion`, `action`, and diagnostic when
-invalid. It retains Git repository discovery and trust checks, but does not
+invalid. By default it retains Git repository discovery and trust checks, but does not
 enumerate application files, load Stack catalogs, or inspect project guidance.
+`rootMode: "directory"` reads an explicit absolute directory without Git, as for
+Stack sections below.
 Missing markers distinguish uninitialized projects from unversioned Genesis
 material. Each call reads current state; it neither migrates nor writes files.
 `adoptProject()` also returns the initial `adopt` prompt for an existing
@@ -1092,7 +1118,11 @@ hosts may pass `rootMode: "directory"` and an explicit absolute `projectRoot`.
 This reads that exact directory, including when it sits inside another Git
 repository. It retains the same Stack validation and performs no writes or
 commands. Missing/invalid roots fail; this is never an automatic fallback from
-Git ownership or discovery errors.
+Git ownership or discovery errors. `inspectEnvironment()` and
+`inspectProjectFormat()` accept the same `rootMode` with the same rules. A host
+that already knows the project root and inspects it on every request, such as a
+preview status poll, can pass `rootMode: "directory"` to all three and start no
+Git process.
 
 `inspectStackSections({ names, projectRoot, rootMode, stackPackages })` returns
 an array of those same section results in the requested order. Names must be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.10.10",
+  "version": "1.10.12",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -48,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.10",
+  "version": "1.10.12",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/plugins/opencode/project-guidance.js

@@ -6,11 +6,11 @@ import { promisify } from "node:util";
 const execute = promisify(execFile);
 
 const HOST_CONTEXT_INPUT_ENV = "GENESIS_HOST_CONTEXT_INPUT";
+const HOOK_TIMEOUT_MS = 5_000;
 
-async function renderContext(projectRoot, sessionId, scope, parentSessionIds = []) {
+async function renderContext(projectRoot, sessionId, scope, parentSessionIds = [], timeoutMs = HOOK_TIMEOUT_MS) {
   if (scope === "turn" && process.env.GENESIS_TURN_CONTEXT_ENABLED === "0") return "";
   const started = Date.now();
-  const timeoutMs = 5_000;
   try {
     const { stdout } = await execute(
       "genesis",
@@ -54,7 +54,8 @@ function eventSessionId(event = {}) {
   ).trim();
 }
 
-export const GenesisProjectGuidance = async ({ client, directory, worktree } = {}) => {
+// OpenCode passes no hookTimeoutMs, so its hooks get five seconds; a test passes a shorter deadline to prove it.
+export const GenesisProjectGuidance = async ({ client, directory, worktree, hookTimeoutMs = HOOK_TIMEOUT_MS } = {}) => {
   const projectRoot = path.resolve(directory || worktree || process.cwd());
   const contexts = new Map();
   const turnContexts = new Map();
@@ -72,7 +73,7 @@ export const GenesisProjectGuidance = async ({ client, directory, worktree } = {
           if (!id || id === sessionId || parents.includes(id)) break;
           parents.push(id);
         }
-        return renderContext(projectRoot, sessionId, "session", parents);
+        return renderContext(projectRoot, sessionId, "session", parents, hookTimeoutMs);
       });
       contexts.set(sessionId, context);
       context.catch(() => {
@@ -108,7 +109,7 @@ export const GenesisProjectGuidance = async ({ client, directory, worktree } = {
       if (!sessionId || !messageId || !Array.isArray(message.parts)) return;
       let current = turnContexts.get(sessionId);
       if (current?.messageId !== messageId) {
-        current = { messageId, context: renderContext(projectRoot, sessionId, "turn") };
+        current = { messageId, context: renderContext(projectRoot, sessionId, "turn", [], hookTimeoutMs) };
         turnContexts.set(sessionId, current);
         current.context.catch(() => {
           if (turnContexts.get(sessionId) === current) turnContexts.delete(sessionId);

package/profiles/engineering/baseline.md

@@ -4,9 +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.
-- 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.
+- 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,11 +8,18 @@ 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.
+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/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,14 +164,17 @@ 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.
+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

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.