@nurix/etna 0.19.66 → 0.19.67

package/data/harnesses/apollo/skills/schema-design/SKILL.md

@@ -1,141 +0,0 @@
----
-name: schema-design
-description: "Use when designing or altering a relational schema — a new table, column, index, junction, migration, or seed — or reviewing one. Owns the design doctrine: what earns a table, where a fact lives (state column vs. sequence log vs. audit log), scope columns over parallel tables, junction = M:N only, FK policy including append-only tables, uniqueness with nullable columns, vocabulary tables, copying rows between scopes. Naming and column types stay in the `database.md` rule. Triggers on 'new table', 'schema', 'migration', 'add a column', 'junction table', 'foreign key', 'audit log', 'versioning'."
----
-
-# Schema Design — the doctrine
-
-You decide **what earns a table and where a fact lives** — for every Nurix relational schema, engine-agnostic (written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same names and semantics with native types). Naming, the `id`/`slug`/`label` vocabulary, and column types are the `database.md` rule and are never restated here — this skill owns the design arguments consulted at schema-change time.
-
-Apply the sections below to the change in hand; when reviewing, report violations with the section that names them.
-
-## What earns a table
-
-A table is the most expensive home for data — a migration to change its shape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one only with at least one property in the left column.
-
-| A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
-| -------------------------------------------------------------------------- | ------------------------------------------------------- |
-| identity minted at **runtime** — a session, an upload                      | —                                                       |
-| variation **per tenant / user** — a workspace's theme                      | —                                                       |
-| **independent addressing** — queried, indexed, or FK'd in isolation        | a **JSON column** on its parent row                     |
-| **concurrency-safe** writes — racing writers must not clobber a shared blob | —                                                       |
-| a **DB-enforced invariant** — immutability trigger, unique, atomic boundary | —                                                       |
-| dev-authored, published on deploy, identical for every tenant — plan tiers | **config / a constants file**, validated at build       |
-| exactly recomputable from other rows — a tenant's usage total              | a **cache** (KV / edge), recomputed on demand           |
-| process state dead once the request completes — a retry count             | a **log or workflow engine**, never the domain DB       |
-| owned by another system-of-record — the payment processor's invoice        | a **reference column** — store the id, not the data     |
-
-Each right-column route is one test: process state — would a product feature break if this vanished the instant the request finished?; derived output — exactly recomputable from other rows + code?; un-addressed detail — is the row ever `SELECT`ed / `JOIN`ed / FK'd alone?; another system's record — does a specialized service (chat, telemetry, object store) already own it?
-
-- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant/type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
-- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
-- **A surviving table names the invariant it buys** — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it.
-
-Table count tracks **requirements, not domain richness** — a rich domain is not entitled to a table per noun.
-
-## State, rules, and history
-
-**One fact has one home, chosen by what kind of fact it is.** Confusing these produces the most common redundant table in a schema — a queue whose rows restate state the entity already carries.
-
-| The fact | Home | Example |
-| --- | --- | --- |
-| What the entity **is now** | a **column on the entity's own row** | `documents.state = 'blocked'` |
-| What may be **done** about that state | **code** — the transition map, the UI's affordances | which inputs unblock a document |
-| What **was done**, and by whom | the **append-only audit log** | an `audit_log` row: `document.override_applied` |
-| What a consumer must **replay in order** | the **sequence log** | an `app_events` row keyed `(app_id, sequence)` |
-
-- **State becomes a column the moment anything selects on it.** `WHERE state = 'blocked'` takes an index; `WHERE json_extract(metadata, '$.state') = 'blocked'` scans the table and is invisible to every schema check. JSON keeps only what § What earns a table leaves it — detail nothing addresses alone.
-- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
-- **Legal transitions live in code, never as rows** — a `status_transitions` table is a state machine the database cannot enforce and the code must re-implement anyway to use.
-
-**The two logs are not substitutes**, and no one table serves both:
-
-| | Sequence log | Audit log |
-| --- | --- | --- |
-| Answers | what happened here, **in order** | who did what, **and whether it succeeded** |
-| Ordinal | a **gapless per-entity `sequence`**, allocated from a counter | none — nothing replays it |
-| Scope | one entity, always | any — **including none**: a sign-up predates every tenant |
-| Records | only what **happened** | **attempts too** — `denied`, `failure` |
-| Read by | cursors replaying forward | investigations, at any age |
-
-The bottom two rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
-
-### The audit log's own shape
-
-**An audit log outlives every row it names, so it stores what it needs to stay readable without them.** Both consequences are missing from most first drafts:
-
-- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted, which is the one thing it exists to survive.
-- **Record the attempt, not the success** — `outcome` (`success | failure | denied`) plus a `reason`. Refused sign-ins and permission denials are most of what anyone opens an audit log for; without the column they cannot be written at all.
-- **Keep the columns product-neutral** — `actor_*` · `action` · `outcome` · `target_*` · `scope_path` · `channel` · `source_ip` · `correlation_id` · `changes_json` serve any domain. Per-level tenancy columns tie the log to today's model; a materialized `scope_path` (`workspace:abc/app:def`) makes "everything under this tenant" one prefix scan and survives a new level appearing — at the price of enforcing the hierarchy in code rather than a `CHECK`.
-
-## Scope, not parallel tables
-
-One entity that exists at several scopes is **one table with a nullable scope column** — never one table per scope, and never one table shared across entity families.
-
-- **A table shared by several families carries the union of their columns** — one `settings` table for users, apps, and workspaces. Almost nothing can be `NOT NULL`, the payload lands in JSON beyond every constraint, index, and FK, and a new family widens a table other features already depend on. One table per family.
-- **Two tables declared to have "the same columns" are two schemas maintained by hand** — the drift is silent, surfacing as an incomplete copy, never as an error. Collapse them and discriminate by column.
-- **The scope column is the discriminator** (`app_id IS NULL` = parent scope, set = child scope). Copying a scope is then `INSERT … SELECT` over one table with one column rewritten, so source and target cannot disagree about shape.
-- **A nullable owner column is how a row exists before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which is what lets a `pending_*` / `*_requests` table collapse into the real one.
-- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It must then be excluded from every tenant-scoped query — state that invariant where the id is defined.
-
-## Copying rows between scopes
-
-- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (§ Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
-- **Provenance is a soft reference — no FK.** `source_id` must outlive its referent; an FK would either block the source's deletion or erase the lineage.
-- **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
-- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
-
-## A junction spells many-to-many — nothing else
-
-**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
-
-| Relationship | Shape |
-| --- | --- |
-| **1:M** — the child has exactly one parent | a **reference column on the child** (`agents.routing_slug`), plus an index |
-| **M:N** — both sides have many | a **`<a>_<b>_map` junction** with a composite unique |
-
-- **The test is one question about the child**: can this row ever belong to two parents at once? No ⇒ column. A junction "in case it becomes M:N later" ships the unenforced model today to buy a migration you may never run.
-- **A junction for a 1:M also** makes the association a row that can go missing independently of the child — a child can exist correctly while its wiring does not — and forces a join onto the most common read in the system.
-- **A junction carrying only its two endpoints and timestamps is the tell** — a real M:N junction usually earns its own columns (a role, an order, a status); one that never does is a 1:M waiting to be collapsed into a column.
-- **Collapsing deletes a copy step** — the association travels inside the row it belongs to: no second pass to remap, no copy landing with its wiring half-applied.
-- **A pair already recorded elsewhere needs no table at all.** If an append-only log stores `(parent, child)` on every write, the association table is `SELECT DISTINCT` over that log — a cache free to disagree with the log it derives from (§ What earns a table).
-
-## Foreign keys into and out of append-only tables
-
-**An append-only table can afford no `ON DELETE` action at all, so its references to mutable tables are soft — no FK.** Every option is closed to it:
-
-| Action | Why it fails on an append-only table |
-| --- | --- |
-| `SET NULL` | It is an **UPDATE**. An append-only trigger aborts it, so the parent's deletion fails — with an error naming the trigger, not the constraint. |
-| `CASCADE` | Deletes history to delete a person. The log exists precisely to outlive its subjects. |
-| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub defect above. |
-
-- **`SET NULL` is the trap** — it reads like a safe relaxation of `NO ACTION` and passes review as one.
-- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`). The log keeps naming who acted after the account is gone, which is what an audit trail is for.
-- **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
-- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
-
-## Uniqueness with a nullable column
-
-**`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
-
-```sql
-CREATE UNIQUE INDEX <t>_parent_slug_unique ON <t> (parent_id, slug) WHERE child_id IS NULL;
-CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_id IS NOT NULL;
-```
-
-**Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
-
-## Vocabulary / lookup tables
-
-A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
-
-- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
-
-## Run
-
-1. **Route every new fact through § What earns a table** — default to *not* a table; name the left-column property that earns one, or the right-column home it takes instead.
-2. **Classify every fact by § State, rules, and history** — now-state → entity column; rules → code; what-was-done → audit log; replayable → sequence log.
-3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` (§ Keys, § Append-only).
-4. **Prove uniqueness claims by inserting the forbidden duplicate** — a schema review cannot tell a firing index from a silent one by reading.
-5. **Report as a findings list** — one line per violation: the section, the table/column, the fix.

package/data/harnesses/apollo/skills/test/SKILL.md

@@ -1,104 +0,0 @@
----
-name: test
-description: Test Runner using Chrome DevTools Protocol (CDP). Run UI tests with Claude-in-Chrome browser automation. Triggers include: "run my tests", "run the test suite", "execute tests", "test this code", "check if tests pass".
-argument-hint: [test-name]
----
-
-# Test Runner (CDP)
-
-Run UI tests using Claude-in-Chrome browser automation.
-
-## Prerequisites
-
-Complete these steps before executing test assertions:
-
-### 1. Load Credentials
-
-Read `tests/.env` for: `TEST_USER_EMAIL`, `TEST_USER_PASSWORD`, `TEST_BASE_URL`, `TEST_APP_ID`
-
-- `TEST_USER_EMAIL` / `TEST_USER_PASSWORD`: credentials used to log in during browser setup.
-- `TEST_BASE_URL`: the root URL the browser will navigate to (e.g. `http://localhost:3000`).
-- `TEST_APP_ID` _(optional)_: an application or workspace identifier passed to tests that need to target a specific app instance. When unset, tests run against the default app/workspace returned by the base URL.
-
-If the file is missing, instruct user to copy `tests/.env.example` to `tests/.env`.
-
-### 2. Connect to Chrome
-
-```
-mcp__claude-in-chrome__tabs_context_mcp with createIfEmpty: true
-```
-
-If connection fails: Install Claude-in-Chrome extension, ensure Chrome is running.
-
-### 3. Setup Browser
-
-```
-mcp__claude-in-chrome__tabs_create_mcp
-```
-
-Navigate to `${TEST_BASE_URL}`. Login if required using credentials from step 1.
-
-### 4. Verify Ready State
-
-Confirm main dashboard is visible before proceeding.
-
-## Execution
-
-1. **Locate test file**: `.github/docs/tests/<test-name>.md`
-2. **Validate exists**: If not found, list available tests in `.github/docs/tests/`. If that directory does not exist, search for common test patterns: `*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/` directories, or check `package.json` for a `test` script to determine how tests should be run.
-3. **Create results file**: `tests/claude-runs/<test-name>-<YYYY-MM-DD-HHmmss>.md`
-4. **Execute sequentially**: Update checkboxes as you go
-5. **Save results**: Write completed file with summary header
-
-## Checkbox Markers
-
-| Marker | Meaning                             |
-| ------ | ----------------------------------- |
-| `[x]`  | Passed                              |
-| `[!]`  | Failed - add `**FAILED**: <reason>` |
-| `[-]`  | Skipped                             |
-| `[ ]`  | Not run                             |
-
-## Results Template
-
-```markdown
-# Test Results: <Test Name>
-
-## Execution Summary
-
-| Property    | Value                           |
-| ----------- | ------------------------------- |
-| Test File   | `<path>`                        |
-| Executed At | `<YYYY-MM-DD HH:mm:ss>`         |
-| Status      | `PASSED` / `FAILED` / `PARTIAL` |
-
-## Results Overview
-
-| Metric           | Count |
-| ---------------- | ----- |
-| Total Assertions | X     |
-| Passed           | X     |
-| Failed           | X     |
-| Skipped          | X     |
-
-## Failed Assertions Summary
-
-- Section X.X: <failure description>
-
----
-
-## Test: <Original Title>
-
-... (test content with updated checkboxes)
-```
-
-## Error Handling
-
-- **Network errors**: Retry once, then mark failed
-- **Timeout**: Mark failed with timeout note
-- **Element not found**: Screenshot, mark failed, continue
-- **Browser disconnect**: Stop, save partial results, inform user
-
-## Screenshots
-
-Take screenshots: before each major section, on failures, after completion.

package/data/harnesses/apollo/skills/testing/SKILL.md

@@ -1,166 +0,0 @@
----
-name: testing
-description: "The test-lifecycle skill — three modes. Plan-gate mode: after `boundary` passes, derives the tests a plan owes and writes the Test Obligations ledger into the plan (a row per behavior: layer, target file, oracle, fixtures); writes no test files. Placement mode: layered test strategy — which ownership strata the application has, where a test lives and what it may assert; use for any testing-strategy, test-architecture, test-pyramid, or 'unit/integration/e2e?' question, even if 'layer' is never said. Gate mode: executes the verification gate — derives the behavioral checklist, drives the real surface (browser automation, the real CLI, HTTP; the `/test` runner where wired), pins durable behaviors, discharges every ledger row. Triggers on 'test plan', 'testing strategy', 'test architecture', 'test layers', 'where should this test live', 'run the verification gate'."
----
-
-# Testing — Ledger, Layers, Gate
-
-One skill owns the test lifecycle's three procedural moments; the standing constraints (regimes, deferral, gate preconditions) are `.claude/rules/testing.md` and are never restated here. Pick the mode from the moment:
-
-| Moment | Mode |
-| --- | --- |
-| Plan gate, after `boundary` passes | **Plan-gate** — derive what the plan owes |
-| A strategy / placement / altitude question, or laying out a suite | **Placement** — derive the strata, place the tests |
-| The user triggers the verification gate | **Gate** — drive, pin, discharge |
-
----
-
-## Plan-gate mode — the Test Obligations ledger
-
-You derive the tests an implementation plan owes and pin them into the plan as an explicit, reviewable manifest — at the same gate `boundary` runs, ordered second. You never write a test file; you write the **ledger gate mode discharges**, so the gate proves a checklist instead of a vibe.
-
-**The litmus is "which promise, at which altitude, proven by what?"** A plan promises behavior; each promise earns exactly one test at the cheapest layer that can actually prove it. Spend your reading deciding the *layer* and the *oracle*, not on prose. Writing tests *before* the code exists fabricates implementation coupling or leaves the suite red for the plan's duration; writing them *during* the build loop taxes every iteration — so the plan gate emits obligations, the loop stays free of test files, and gate mode discharges the manifest in one pass.
-
-### Contract sources
-
-- **The plan's Proposed Changes** — each file/entity/API change is a behavior that may owe a test.
-- **The owning LLD** (`docs/features/{feature}.md`, via the ownership index) — every obligation names the LLD promise it proves; the LLD is referenced, never restated. This one-directional chain (LLD → manifest → tests + Completion checklist) is what stops the artifacts drifting.
-- **`.claude/rules/testing.md`** — frameworks and canonical placement per stack; target paths come from there, never invented. The repo's existing runner always wins.
-- **`boundary`'s output** — a HIGH/CRITICAL finding is itself a behavior owed a regression test. Fold boundary's amendments first, then read the amended plan.
-
-### Layer assignment
-
-Assign each behavior the **cheapest layer that can prove it**, then name the oracle. The ledger altitudes are `unit` / `component` / `integration` / `e2e` (strata mapping: § Bridge below); **integration is the default for server behavior** — a route/handler against a real in-memory datastore via the app instance. Error paths, races, and idempotency are obligations too, and belong at **integration** with injected faults (network mock, fake timers, forced constraint) — never e2e.
-
-**The e2e altitude gate:** an e2e obligation is earned **only** when the behavior genuinely spans processes no single-process test can exercise together. Density is one scenario per cross-process journey, not per feature — prefer **"extend scenario `<name>`"** over **"new scenario"**. **Refuse to emit any e2e obligation while the project's e2e smoke gate is not wired in CI** — emit a **blocked** row naming the missing gate instead.
-
-### Run (plan-gate)
-
-**Input:** a plan path (given, or the newest in `docs/history/plans/`), boundary-checked with amendments folded; skipped on a boundary BLOCK. For a non-plan diff, the hunks stand in for Proposed Changes but the obligations are paid **immediately** — only a plan has a ledger to defer into.
-
-1. **Build the behavior list** from Proposed Changes + the LLD's promises + HIGH/CRITICAL boundary findings. Note compiler-guarded behaviors — they owe **no** test.
-2. **Assign layer + oracle** per behavior; cheapest proving layer wins.
-3. **Map to a target file** per `testing.md`; name fixtures/factories and fault injection; use the repo-standard fake-data source.
-4. **Apply the e2e altitude gate**; downgrade everything else to integration.
-5. **Emit the Test Obligations section into the plan** (an executor dispatched with only the plan sees nothing else), plus a one-line chat summary:
-
-   ```
-   ## Test Obligations
-
-   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults | Outcome |
-   | - | ---------------------- | ----- | ----------- | ------ | ----------------- | ------- |
-
-   Coverage: {N} behaviors · {N} integration · {N} component · {N} unit · {N} e2e ({N} extend, {N} new)
-   Completion checklist: docs/tests/{feature}.md  (derived at the gate, not now)
-   ```
-
-   A behavior with no obligation is stated too, with the reason — "none — compiler-guarded" reads as *checked*; an empty cell reads as *not analyzed*. A short manifest is valid — do not pad. **`Outcome` is written empty here — it is gate mode's cell**, and the completion walls read it: a plan cannot reach `Status: Complete` while any row's Outcome is empty.
-6. **Record the write in the plan's `Gates:` line**, rewriting only your segment to exactly `Test-plan: written YYYY-MM-DD (N rows)` — the compliance hook greps this exact form. Add the line if the plan predates the format.
-
----
-
-## Placement mode — layered test strategy
-
-You decide **where a test lives and what it may assert**. **The litmus is "where can this defect originate?"** A test lives with the only layer that can produce the defect it catches. "The 409 response carries the current body" can only break in a route handler — service-contract layer. "The buffer the user typed survives the 409" can only break in component state — component layer. Same feature, two owners, two tests, zero overlap. Placement is decided by this question alone — testing a feature wherever you first *see* it is what makes suites flat, duplicative, and multiplicative in cost.
-
-### The stack
-
-The maximum form, for a full-stack application. Each layer names what only it can break, the oracle that proves it, and the technology **class** — the concrete framework comes from `testing.md`'s stack table, never from here.
-
-| # | Layer | Owns (defects only it can originate) | Oracle | Technology class |
-| --- | --- | --- | --- | --- |
-| 1 | **Persistence schema** | Invariants the storage engine enforces against any code: uniqueness, checks, cascades, append-only triggers | The engine's refusal of a forbidden write | The real engine, in-memory — never a mock of storage you own |
-| 2 | **Domain** | Business rules and state transitions, via direct calls | Resulting state in real storage | Real datastore + modeled fakes for external ports |
-| 3 | **Service contract** | The published wire: authn/authz at the door, envelope shape, status mapping, field projection, stream/event grammar. For a CLI this is argv/stdout/exit codes; for a library, its exported API | Requests against the real app instance, in-process | `supertest` / `SELF.fetch` class — never a spawned server, never naked handler functions |
-| 4 | **Contract artifact** | Nothing behavioral. Typed fixtures / interception handlers **compiled from the provider's own types**, exported for every consumer-side test | The typechecker — drift from the provider is a compile error | No runner; a module the provider owns |
-| 5 | **Client data** | The consumer's half of the wire: error taxonomy, parsing, byte fidelity, stream reassembly, retry/abort | Intercepted network serving layer-4 artifacts; no DOM | `msw`-class interception |
-| 6 | **View logic** | Pure presentation derivations: grouping, ordering, status vocabularies, formatting | Table-driven equality | Plain runner |
-| 7 | **Component / surface** | Interaction orchestration — what a user action changes on screen: buffer lifecycle, optimistic states, error surfaces | Rendered output a user can observe; network answered by layer 4 | DOM testing-library class + interception |
-| 8 | **System smoke** | Composition only — the layers are actually stacked: the build serves, auth flows end to end, one write round-trips | A real browser or real binary against the really-running app | Browser/process driver class; 3–5 journeys, zero variants |
-
-Layer 4 is the hinge. Every layer ≥5 runs on the assumption that layers 1–3 are green — and the artifact makes that assumption *enforceable*: when the provider's response type changes, the fixture stops compiling, and every consumer test fails at typecheck before it runs. A consumer-side test that hand-writes a wire response has smuggled unverified layer-3 knowledge upward; route it through the artifact.
-
-### How many layers — derived, never chosen
-
-**A layer exists iff the application has the boundary that can originate that layer's defects; an absent boundary makes the layer vanish** — it never merges into a neighbor. Merging is the failure mode: "simplifying" layers 3 and 7 together reinvents the flat feature test, where every UI assertion silently re-verifies the API beneath it and cost goes multiplicative again.
-
-| Application shape | Strata present |
-| --- | --- |
-| Full-stack web app | all eight |
-| Backend-only service | 1, 2, 3, 8 |
-| CLI | 2, 3 (the CLI's argv/stdout contract), 8 |
-| Frontend on a third-party API | 4 (derived from the API's published spec), 5, 6, 7, 8 |
-| Library | 2 only — its exported API is the contract, its tests are its consumers |
-
-Derive the stack first, then place tests: a placement argument that starts "this feels like an integration test" has skipped the derivation.
-
-### Placement discipline
-
-- **An assertion provable at two layers is misplaced — it belongs at the lower one.** The duplication check is mechanical, not judgment.
-- **Behavior variants sink to the cheapest layer that owns them** — almost always 2 or 6. A variant at layer 3 pays wire tax on a domain test; a variant at layer 8 is a placement failure below, by definition.
-- **One representative path upward.** Layer 3 keeps one happy path per route plus exhaustive coverage of *contract edges only*; layer 8 keeps 3–5 journeys total.
-- **External systems enter as modeled fakes, not spies.** A fake implements the port's semantics so tests assert resulting state; a spy only proves methods were called, which passes just as happily with the bytes swapped.
-- **Failure localization is the payoff to protect.** One defect turns exactly one layer red, at its owner. When a single change reddens several layers, at most one of those tests was correctly placed — treat the rest as findings.
-
-Layering makes cost **additive** — a new API behavior costs one layer-2 test and maybe a layer-3 edge, zero frontend tests; a new UI state costs one layer-7 test, zero backend tests. A flat suite pays N×M, because every top-layer path implicitly re-verifies every behavior beneath it.
-
-### The tree
-
-```
-tests/
-  schema/      L1 — infrastructure-bound runner (real engine)
-  domain/      L2 — infrastructure-bound runner (real storage, modeled ports)
-  routes/      L3 — infrastructure-bound runner (in-process app)
-  contract/    L4 — no runner; typed fixtures + interception handlers
-  client/      L5 — plain unit runner
-  view/        L6 — plain unit runner
-  component/   L7 — unit runner + DOM environment (per-file opt-in)
-  helpers/     shared seeds, fakes, and builders — owned by no stratum
-e2e/           L8 — its own config, never mixed into the unit runner's glob
-```
-
-- **A stratum the app lacks gets no directory** — an empty `component/` in a backend service is a lie about the app's shape.
-- **One shared glob list, imported by both runner configs** — two hand-maintained lists drift; one imported constant cannot.
-- **Concrete runner, framework, and DOM environment come from `testing.md`'s per-stack table** — this skill names the slot, never the brand.
-- **Contract modules the provider binds** (the layer-4 source types) live in the app's shared source zone — importable by both sides; `tests/contract/` holds only the compiled fixtures and fakes.
-
-### Bridge to the obligation ledger
-
-The ledger's altitudes are coarse names for where a test *runs*; the strata say what it may *assert*:
-
-| Ledger altitude | Strata it covers |
-| --- | --- |
-| unit | 2 (pure domain), 5, 6 |
-| integration | 1, 2 (stateful), 3 |
-| component | 7 |
-| e2e | 8 |
-
-When writing or discharging a ledger row, name the stratum, not just the altitude — "integration" alone leaves open whether the row asserts a schema invariant, a business rule, or an envelope: three owners, three oracles.
-
-### Run (placement)
-
-1. **Derive the stack** from the application's real boundaries (storage? published wire? separate client? DOM?).
-2. **Place each behavior** by the litmus; name stratum, oracle, technology class; take the concrete framework and file placement from `testing.md`.
-3. **Flag violations, don't just place** — assertions provable lower, variants above 2/6, hand-written wire fixtures above layer 4, spies where fakes should model state, layer-8 variants.
-4. **Report as a stratum map** — one line per stratum: exists/absent (why), what lives there, what is misplaced and where it moves. For a plan, feed the strata into the ledger's rows.
-
----
-
-## Gate mode — discharge the ledger
-
-Runs only when the user triggers the verification gate (constraints — preconditions, verdict-inline, tier, honesty — are `.claude/rules/testing.md` § The gate). **Drive the real thing first, then pin what must not regress**: driving finds the defects that matter to a user, and shows which behaviors are worth the permanent cost of a test.
-
-1. **Write the checklist** — derive or update `docs/tests/{feature}.md` from the ledger and the LLD's promises (the `documentation` skill's `templates/behavioral-checklist.md`; one `**Assert**` per observable). Derived before the driving it is the script; derived after, it is merely a report with nothing to trace tests back to.
-2. **Drive the real surface** — browser automation for web UI (the `/test` runner skill where the repo wires it), the actual CLI binary, HTTP against the running worker. **A failing checklist assertion is never softened to make a run green** — record the defect, send it to the backlog. Where the runtime offers no browser automation, emit the browser-verification checklist for the user to run; their report is the rung's verdict and `Status: Complete` waits for it.
-3. **Pin the durable behaviors** as suite tests per `testing.md`, naming each test's stratum (§ Bridge). A test is a permanent maintenance cost, bought deliberately:
-
-   | Earns a suite test | Verified by driving alone |
-   | --- | --- |
-   | A promise an LLD makes about the feature's contract | Layout, spacing, copy — restated by a test, not protected by one |
-   | A bug that occurred once — its regression test | A one-off migration or backfill's output |
-   | An error path, race, or idempotency guarantee | Behavior a type or the compiler already makes unshippable |
-
-   A driven check is evidence, not an artifact — it proves the change works today and leaves nothing behind; that is why this rung exists.
-4. **Run the affected suite**, plus the project's e2e smoke gate where one is wired.
-5. **Discharge every ledger row into exactly one outcome**: **satisfied** (test green, or driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (missing infrastructure named, row converted to a backlog item). **Open by re-reading the ledger from the plan file on disk, never from conversation memory** — a context-held copy is how rows get missed. **Write each row's outcome into its `Outcome` cell in the plan file** — exactly `satisfied`, `owes nothing — {reason}`, or `blocked → backlog` — because the Stop wall and CI read that cell, and a row left unexamined blocks completion.
-6. **Report results honestly, including failures**; record which test now guards each checklist section (`Pinned:` traces) and each section's `AC:` line where the repo carries a keyed acceptance-criteria source, closing with the coverage count — `AC coverage: {n}/{m}; uncovered: {keys} → backlog`. Completion steps — freezing the plan, the changelog entry — are the root policy file's, not yours.