@nurix/etna 0.19.55 → 0.19.57

package/data/harnesses/apollo/rules/express.md

@@ -1,33 +0,0 @@
-# Express & API Format
-
-Express 5.x server setup and the JSON response envelope every Nurix HTTP service returns — backend only. Package versions live in [`general.md`](general.md); web-frontend conventions in [`frontend.md`](frontend.md).
-
-## Express 5.x
-
-Canonical middleware stack:
-
-```javascript
-app.use(cors({ origin: process.env.FRONTEND_URL }));
-app.use(compression());
-app.use(express.json({ limit: '10mb' }));
-app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-```
-
-- **Middleware order is fixed**: body parsers → custom middleware → routes → error handlers (centralized, **always** last) — no ad-hoc per-route error responses.
-- Auth is middleware, not inline route checks. Routes are modular via Express Router.
-
-## API Response Format
-
-Success and error share **one** envelope — a cross-service contract clients branch on, so a per-service "improvement" (`success: true`, a boolean `status`, a bare payload) breaks every consumer:
-
-```json
-{
-  "status": 1,
-  "message": "Message sent successfully",
-  "data": { "delivered": [{ "user@example.com": 2 }] }
-}
-```
-
-Error: `{ "status": 0, "message": "Error description", "data": null }`
-
-HTTP codes, **closed list**: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`.

package/data/harnesses/apollo/rules/verification.md

@@ -1,67 +0,0 @@
-# Verification
-
-**When** work is proven and **by what mechanism** — the gate, the two regimes, and the ladder of ways to drive a change. Framework choice, suite layout, and mocking policy are [`testing.md`](testing.md); the plan-gate obligation manifest is the `test-plan` skill. This rule owns the moment, not the technology.
-
-## Two regimes
-
-**Deferral is a property of plans, not of code.** A plan carries a Test Obligations ledger and a gate that discharges it; nothing else does, so nothing else may defer.
-
-| Regime | During the work | Proven |
-| --- | --- | --- |
-| **Plan-driven build** | No new test files. Code only — the loop stays fast | At the verification gate, before `Status: Complete` |
-| **Bug fix** — a defect in shipped behavior | The regression test ships with the fix | Immediately — it fails before the change, passes after |
-| **Ad-hoc / non-plan change** | The test ships with the change | Immediately, same discipline as a bug fix |
-
-- **A bug fix cannot defer, because "fails before, passes after" is provable afterward only by reverting to the pre-fix ref** — a cost nobody pays, so the property is captured at fix time or lost.
-- **Ad-hoc work cannot defer, because there is no ledger to defer into.** An obligation recorded nowhere is an obligation forgotten. A non-plan change that alters no promised behavior — a pure refactor, a rename — owes no test: the implementer applies § What earns a durable test directly.
-
-## During the loop
-
-Rules for the plan regime between the plan gate and the verification gate:
-
-- **No new test files** — obligations wait in the ledger.
-- **Existing tests broken by the plan's intended behavior change are updated to the new contract before any mid-plan commit** — the shared branch never carries a red suite, and an update is never a weakening (§ What earns a durable test).
-- **A defect in the plan's own in-flux code is the loop iterating** — no test, no ledger row; the behavior it belongs to is already in the ledger. **A pre-existing bug in shipped behavior is the bug-fix regime even mid-plan**: fix it with its regression test now — deferring it to the gate loses "fails before", the property the regime exists to capture — or, when not fixing it now, send it to the backlog via Out-of-Scope Discovery. Never fix silently.
-- **The ledger is amendable while the plan is open** — a boundary finding or a newly promised behavior appends a row; the gate discharges whatever the ledger holds at gate time.
-- **A mid-plan commit is a checkpoint, not a verification claim.** It may ship deliberately unverified code; the gate, not the commit, is the verification event for plan work.
-
-## The gate
-
-**The gate is a discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. A plan with outstanding obligations stays open, whatever the code does.
-
-- **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `test-plan` skill on it first. Without this check an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
-- **Every row is discharged into exactly one outcome**: **satisfied** (the test exists and is green, or the driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (the missing infrastructure named, the row converted to a backlog item so the debt outlives the frozen plan). A row left unexamined blocks the gate.
-- **The gate's verdict is never delegated.** A sub-agent's summary is not verifiable ground truth, and where browser work is main-session-only (the root `CLAUDE.md` § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
-- **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
-- **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
-
-## The mechanism ladder
-
-**Drive the real thing first, then pin what must not regress.** Ordering matters: driving finds the defects that matter to a user, and shows which behaviors are worth the permanent cost of a test.
-
-| Rung | Mechanism | Proves |
-| --- | --- | --- |
-| 0 | **Write the checklist** — `docs/tests/{feature}.md`, from the ledger and the LLD's promises | There is a stated behavior to drive against, and to trace a test back to |
-| 1 | **Drive the real surface** — browser automation for web UI, the actual CLI binary, HTTP against the running worker | The change works in the product, against real wiring |
-| 2 | **Pin the durable behaviors** as suite tests per [`testing.md`](testing.md) | The behavior survives the next change |
-| 3 | **Run the affected suite**, plus the project's e2e smoke gate where one is wired | Nothing else broke |
-
-- **Rung 0 is what makes 1 and 2 repeatable.** The checklist is the script rung 1 executes and the menu rung 2 selects from — one `**Assert**` per observable, and the section records which test now guards it (or that none does, and why). Derived after the driving it is a report; derived before, it is the only artifact that survives the session and still says what the feature promises. Its shape is the `documentation` skill's `templates/behavioral-checklist.md`.
-- **A failing checklist assertion is never softened to make a run green.** The checklist states the contract; a run that fails records the defect and sends it to the backlog.
-- **Browser automation is the default for a web surface, and needs no permission to use** — a rendered page driven through real interaction is the only oracle that catches wiring, styling, and state defects together.
-- **Where the runtime offers no browser automation**, rung 1's verdict belongs to the user: emit a browser-verification checklist (URLs, actions, expected outcomes), the user runs it and reports, the result lands in the changelog entry — and `Status: Complete` waits for it.
-- **A driven check is evidence, not an artifact.** It proves the change works today; it leaves nothing behind. That is why rung 2 exists.
-
-## What earns a durable test
-
-**A test is a permanent maintenance cost, so it is bought deliberately** — the ledger names behaviors, and the gate decides which of them are worth pinning.
-
-| 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 behavior that is compiler-guarded owes no test** — if it cannot ship green-but-broken, a test adds cost and no safety.
-- **Never weaken, skip, or delete a test to mask an unexplained failure.** When a plan or LLD intentionally changes behavior, updating the affected tests to the new contract is part of that change.
-- **Throwaway checks are not tests.** Temporary scripts written to drive a change live in scratch space and are deleted — never committed into the test tree.

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

@@ -1,85 +0,0 @@
----
-name: test-plan
-description: "Use when deriving the tests a plan owes. Test-obligation diagnostic: runs at the plan gate after boundary, reads the plan's Proposed Changes + owning LLD, and writes a Test Obligations section (a row per behavior: layer, target file, oracle, fixtures). Writes no test files. Triggers on 'test plan'."
----
-
-# Test-Obligation Diagnostic
-
-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 the verification gate discharges** (`.claude/rules/verification.md`), so the gate proves a checklist instead of a vibe, and so a later doc-health pass can prove the tests match the promises.
-
-**The litmus is "which promise, at which altitude, proven by what?"** A plan promises behavior (an LLD's `owns:` surface does X); 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.
-
-## The three-moment split
-
-Testing spans three moments in the plan lifecycle. This skill owns **only the first** — it is why "write the tests at plan time" is wrong: at the gate the code does not exist yet, so the only coherent artifact is the manifest.
-
-| Moment | Artifact | Owner |
-| --- | --- | --- |
-| **Plan gate** (here, after boundary) | Test Obligations section written into the plan | this skill |
-| **Verification gate** (before `Status: Complete`) | the obligated tests written and green, plus the driven checks against the real surface | the implementer at the gate (`.claude/rules/verification.md`) |
-| **Verification gate** | behavioral checklist at `docs/tests/{feature}.md`, derived from this ledger **before** the driving, then the tests it seeds | the gate + the `documentation` skill |
-| **Completion** | the gate's results recorded in the changelog; each checklist section carrying its `Pinned:` trace | Completion steps |
-
-Writing tests *before* the code they cover either fabricates implementation coupling (labels/routes/copy the plan hasn't fixed) or leaves the suite red on the shared branch for the plan's whole duration. Writing them *during* the build loop taxes every iteration for behavior still in flux. So the plan gate emits obligations, the build loop stays free of test files, and the manifest is discharged in one pass at the verification gate.
-
-## Contract sources
-
-- **The plan's Proposed Changes** — files created/modified, entities/state, API changes, cross-module contracts. Each is a behavior that may owe a test.
-- **The owning LLD** (`docs/features/{feature}.md`, matched via the ownership index) — the canonical statement of *what the feature does*. Every obligation names the LLD promise it proves; the LLD is never restated, only referenced. This one-directional chain (LLD → manifest → tests + Completion checklist) is what stops the three artifacts drifting into three contradictory truths.
-- **`.claude/rules/testing.md`** — the frameworks and canonical placement per stack. The manifest's target paths and runners come from here, never invented. The repo's existing runner always wins.
-- **`boundary`'s output** — a HIGH/CRITICAL finding it surfaced is itself a behavior owed a regression test (the failure mode, asserted). 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 concrete thing that shows pass/fail):
-
-- **unit** — a pure function / reducer / validator. Oracle: return value, thrown error.
-- **component** — a UI unit's behavior in isolation (a widget, form, panel). Oracle: rendered role/text, emitted event. Runner: the stack's component runner per `testing.md`.
-- **integration** — a route/handler against a real in-memory datastore via the app instance (not a mock of what you own). Oracle: response envelope shape, status code, the row actually written. **This is the default for server behavior** — most obligations land here, and this layer is the one the `test` script / CI runs.
-- **e2e** — see the altitude gate below.
-
-Error paths, races, and idempotency are obligations too, and they belong at **integration** with injected faults (network mock, the runner's fake timers, a forced constraint) — a process driving a live product cannot reliably *produce* them, so they are never an e2e obligation.
-
-### The e2e altitude gate
-
-An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is earned **only** when the behavior genuinely spans processes/services that no single-process test can exercise together. A single-process behavior, however important, is an integration obligation, never e2e.
-
-- Density is **one scenario per cross-process journey, not one per feature** — the project's existing scenarios are the reference density. Mark each e2e obligation **"extend scenario `<name>`"** in preference to **"new scenario"**; a new scenario needs a genuinely new journey.
-- **Refuse to emit any e2e obligation while the project's e2e smoke gate is not wired.** A generated spec fed to a suite nothing runs is a rot accelerator. The gate is a capped, tagged smoke subset run in CI (not the full e2e suite — an oversized always-on e2e suite is what gets evicted from CI, taking all enforcement with it). If no such CI gate exists, emit the e2e obligation as a **blocked** row naming the missing gate, not as work to do.
-
-## Run
-
-**Input:** a plan path (given, or the newest in `docs/history/plans/`), already boundary-checked with amendments folded. For a non-plan diff in test-worthy code, the hunks stand in for Proposed Changes — but the derived obligations are paid **immediately**, not deferred: only a plan has a ledger and a gate, so for a diff your output is the checklist the implementer satisfies now.
-
-1. **Build the behavior list.** From the plan's Proposed Changes + the owning LLD's promised behavior, list the behaviors this plan introduces or changes. Fold in each HIGH/CRITICAL boundary finding as a regression obligation. Note behaviors a type or the compiler already guards — those owe **no** test (the boundary litmus, inverted: if it can't ship green-but-broken, it needs no test).
-
-2. **Assign a layer + oracle** to each behavior (rules above). Prefer the cheapest layer that can actually prove the promise.
-
-3. **Map to a target file** per `testing.md` — the stack's unit/integration path for most, the e2e scenario tree for a program scenario. Name fixtures/factories (existing helper, or new) and the fault-injection needed (network mock, fake timers, forced constraint). Use the repo-standard fake-data source.
-
-4. **Apply the e2e altitude gate** to any cross-process obligation; downgrade everything else to integration.
-
-5. **Emit the Test Obligations section into the plan**, plus a one-line chat summary. Write it as a subsection of the plan (an executor dispatched with only the plan file sees nothing else — an obligation that lives only in chat is lost at dispatch):
-
-   ```
-   ## Test Obligations
-
-   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults |
-   | - | ---------------------- | ----- | ----------- | ------ | ----------------- |
-
-   Coverage: {N} behaviors · {N} integration · {N} component · {N} unit · {N} e2e ({N} extend, {N} new)
-   Completion checklist: docs/tests/{feature}.md  (derived at Completion, not now)
-   ```
-
-   A behavior with no obligation is stated too, with the reason (compiler-guarded, covered by an existing test) — an empty cell reads as "not yet analyzed"; an explicit "none — compiler-guarded" reads as "checked."
-
-6. **Record the write in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Test-plan: written YYYY-MM-DD (N rows)` where N is the ledger's row count. The compliance hook greps this exact form. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
-
-## Rules
-
-- **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are verification-gate-time and Completion-time, owned by others.
-- **Every obligation names its LLD promise.** No promise, no obligation source — trace it or drop it. This is the anti-drift pin.
-- **Cheapest proving layer wins.** Do not obligate an e2e scenario for what an integration test proves, or an integration test for what a unit test proves.
-- **e2e only above the cross-process bar, and only while the smoke gate runs.** Otherwise the obligation is a blocked row naming the missing gate.
-- **Runs after boundary; skipped on BLOCK.** A blocked plan is re-planned first; there is nothing stable to obligate tests against.
-- **A short manifest is valid.** A plan that owes three integration tests owes three rows — do not pad. The coverage line is the evidence it was analyzed, not skipped.

package/data/harnesses/code/rules/express.md

@@ -1,33 +0,0 @@
-# Express & API Format
-
-Express 5.x server setup and the JSON response envelope every Nurix HTTP service returns — backend only. Package versions live in [`general.md`](general.md); web-frontend conventions in [`frontend.md`](frontend.md).
-
-## Express 5.x
-
-Canonical middleware stack:
-
-```javascript
-app.use(cors({ origin: process.env.FRONTEND_URL }));
-app.use(compression());
-app.use(express.json({ limit: '10mb' }));
-app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-```
-
-- **Middleware order is fixed**: body parsers → custom middleware → routes → error handlers (centralized, **always** last) — no ad-hoc per-route error responses.
-- Auth is middleware, not inline route checks. Routes are modular via Express Router.
-
-## API Response Format
-
-Success and error share **one** envelope — a cross-service contract clients branch on, so a per-service "improvement" (`success: true`, a boolean `status`, a bare payload) breaks every consumer:
-
-```json
-{
-  "status": 1,
-  "message": "Message sent successfully",
-  "data": { "delivered": [{ "user@example.com": 2 }] }
-}
-```
-
-Error: `{ "status": 0, "message": "Error description", "data": null }`
-
-HTTP codes, **closed list**: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`.

package/data/harnesses/code/rules/verification.md

@@ -1,67 +0,0 @@
-# Verification
-
-**When** work is proven and **by what mechanism** — the gate, the two regimes, and the ladder of ways to drive a change. Framework choice, suite layout, and mocking policy are [`testing.md`](testing.md); the plan-gate obligation manifest is the `test-plan` skill. This rule owns the moment, not the technology.
-
-## Two regimes
-
-**Deferral is a property of plans, not of code.** A plan carries a Test Obligations ledger and a gate that discharges it; nothing else does, so nothing else may defer.
-
-| Regime | During the work | Proven |
-| --- | --- | --- |
-| **Plan-driven build** | No new test files. Code only — the loop stays fast | At the verification gate, before `Status: Complete` |
-| **Bug fix** — a defect in shipped behavior | The regression test ships with the fix | Immediately — it fails before the change, passes after |
-| **Ad-hoc / non-plan change** | The test ships with the change | Immediately, same discipline as a bug fix |
-
-- **A bug fix cannot defer, because "fails before, passes after" is provable afterward only by reverting to the pre-fix ref** — a cost nobody pays, so the property is captured at fix time or lost.
-- **Ad-hoc work cannot defer, because there is no ledger to defer into.** An obligation recorded nowhere is an obligation forgotten. A non-plan change that alters no promised behavior — a pure refactor, a rename — owes no test: the implementer applies § What earns a durable test directly.
-
-## During the loop
-
-Rules for the plan regime between the plan gate and the verification gate:
-
-- **No new test files** — obligations wait in the ledger.
-- **Existing tests broken by the plan's intended behavior change are updated to the new contract before any mid-plan commit** — the shared branch never carries a red suite, and an update is never a weakening (§ What earns a durable test).
-- **A defect in the plan's own in-flux code is the loop iterating** — no test, no ledger row; the behavior it belongs to is already in the ledger. **A pre-existing bug in shipped behavior is the bug-fix regime even mid-plan**: fix it with its regression test now — deferring it to the gate loses "fails before", the property the regime exists to capture — or, when not fixing it now, send it to the backlog via Out-of-Scope Discovery. Never fix silently.
-- **The ledger is amendable while the plan is open** — a boundary finding or a newly promised behavior appends a row; the gate discharges whatever the ledger holds at gate time.
-- **A mid-plan commit is a checkpoint, not a verification claim.** It may ship deliberately unverified code; the gate, not the commit, is the verification event for plan work.
-
-## The gate
-
-**The gate is a discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. A plan with outstanding obligations stays open, whatever the code does.
-
-- **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `test-plan` skill on it first. Without this check an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
-- **Every row is discharged into exactly one outcome**: **satisfied** (the test exists and is green, or the driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (the missing infrastructure named, the row converted to a backlog item so the debt outlives the frozen plan). A row left unexamined blocks the gate.
-- **The gate's verdict is never delegated.** A sub-agent's summary is not verifiable ground truth, and where browser work is main-session-only (the root `CLAUDE.md` § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
-- **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
-- **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
-
-## The mechanism ladder
-
-**Drive the real thing first, then pin what must not regress.** Ordering matters: driving finds the defects that matter to a user, and shows which behaviors are worth the permanent cost of a test.
-
-| Rung | Mechanism | Proves |
-| --- | --- | --- |
-| 0 | **Write the checklist** — `docs/tests/{feature}.md`, from the ledger and the LLD's promises | There is a stated behavior to drive against, and to trace a test back to |
-| 1 | **Drive the real surface** — browser automation for web UI, the actual CLI binary, HTTP against the running worker | The change works in the product, against real wiring |
-| 2 | **Pin the durable behaviors** as suite tests per [`testing.md`](testing.md) | The behavior survives the next change |
-| 3 | **Run the affected suite**, plus the project's e2e smoke gate where one is wired | Nothing else broke |
-
-- **Rung 0 is what makes 1 and 2 repeatable.** The checklist is the script rung 1 executes and the menu rung 2 selects from — one `**Assert**` per observable, and the section records which test now guards it (or that none does, and why). Derived after the driving it is a report; derived before, it is the only artifact that survives the session and still says what the feature promises. Its shape is the `documentation` skill's `templates/behavioral-checklist.md`.
-- **A failing checklist assertion is never softened to make a run green.** The checklist states the contract; a run that fails records the defect and sends it to the backlog.
-- **Browser automation is the default for a web surface, and needs no permission to use** — a rendered page driven through real interaction is the only oracle that catches wiring, styling, and state defects together.
-- **Where the runtime offers no browser automation**, rung 1's verdict belongs to the user: emit a browser-verification checklist (URLs, actions, expected outcomes), the user runs it and reports, the result lands in the changelog entry — and `Status: Complete` waits for it.
-- **A driven check is evidence, not an artifact.** It proves the change works today; it leaves nothing behind. That is why rung 2 exists.
-
-## What earns a durable test
-
-**A test is a permanent maintenance cost, so it is bought deliberately** — the ledger names behaviors, and the gate decides which of them are worth pinning.
-
-| 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 behavior that is compiler-guarded owes no test** — if it cannot ship green-but-broken, a test adds cost and no safety.
-- **Never weaken, skip, or delete a test to mask an unexplained failure.** When a plan or LLD intentionally changes behavior, updating the affected tests to the new contract is part of that change.
-- **Throwaway checks are not tests.** Temporary scripts written to drive a change live in scratch space and are deleted — never committed into the test tree.

package/data/harnesses/code/skills/test-plan/SKILL.md

@@ -1,85 +0,0 @@
----
-name: test-plan
-description: "Use when deriving the tests a plan owes. Test-obligation diagnostic: runs at the plan gate after boundary, reads the plan's Proposed Changes + owning LLD, and writes a Test Obligations section (a row per behavior: layer, target file, oracle, fixtures). Writes no test files. Triggers on 'test plan'."
----
-
-# Test-Obligation Diagnostic
-
-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 the verification gate discharges** (`.claude/rules/verification.md`), so the gate proves a checklist instead of a vibe, and so a later doc-health pass can prove the tests match the promises.
-
-**The litmus is "which promise, at which altitude, proven by what?"** A plan promises behavior (an LLD's `owns:` surface does X); 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.
-
-## The three-moment split
-
-Testing spans three moments in the plan lifecycle. This skill owns **only the first** — it is why "write the tests at plan time" is wrong: at the gate the code does not exist yet, so the only coherent artifact is the manifest.
-
-| Moment | Artifact | Owner |
-| --- | --- | --- |
-| **Plan gate** (here, after boundary) | Test Obligations section written into the plan | this skill |
-| **Verification gate** (before `Status: Complete`) | the obligated tests written and green, plus the driven checks against the real surface | the implementer at the gate (`.claude/rules/verification.md`) |
-| **Verification gate** | behavioral checklist at `docs/tests/{feature}.md`, derived from this ledger **before** the driving, then the tests it seeds | the gate + the `documentation` skill |
-| **Completion** | the gate's results recorded in the changelog; each checklist section carrying its `Pinned:` trace | Completion steps |
-
-Writing tests *before* the code they cover either fabricates implementation coupling (labels/routes/copy the plan hasn't fixed) or leaves the suite red on the shared branch for the plan's whole duration. Writing them *during* the build loop taxes every iteration for behavior still in flux. So the plan gate emits obligations, the build loop stays free of test files, and the manifest is discharged in one pass at the verification gate.
-
-## Contract sources
-
-- **The plan's Proposed Changes** — files created/modified, entities/state, API changes, cross-module contracts. Each is a behavior that may owe a test.
-- **The owning LLD** (`docs/features/{feature}.md`, matched via the ownership index) — the canonical statement of *what the feature does*. Every obligation names the LLD promise it proves; the LLD is never restated, only referenced. This one-directional chain (LLD → manifest → tests + Completion checklist) is what stops the three artifacts drifting into three contradictory truths.
-- **`.claude/rules/testing.md`** — the frameworks and canonical placement per stack. The manifest's target paths and runners come from here, never invented. The repo's existing runner always wins.
-- **`boundary`'s output** — a HIGH/CRITICAL finding it surfaced is itself a behavior owed a regression test (the failure mode, asserted). 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 concrete thing that shows pass/fail):
-
-- **unit** — a pure function / reducer / validator. Oracle: return value, thrown error.
-- **component** — a UI unit's behavior in isolation (a widget, form, panel). Oracle: rendered role/text, emitted event. Runner: the stack's component runner per `testing.md`.
-- **integration** — a route/handler against a real in-memory datastore via the app instance (not a mock of what you own). Oracle: response envelope shape, status code, the row actually written. **This is the default for server behavior** — most obligations land here, and this layer is the one the `test` script / CI runs.
-- **e2e** — see the altitude gate below.
-
-Error paths, races, and idempotency are obligations too, and they belong at **integration** with injected faults (network mock, the runner's fake timers, a forced constraint) — a process driving a live product cannot reliably *produce* them, so they are never an e2e obligation.
-
-### The e2e altitude gate
-
-An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is earned **only** when the behavior genuinely spans processes/services that no single-process test can exercise together. A single-process behavior, however important, is an integration obligation, never e2e.
-
-- Density is **one scenario per cross-process journey, not one per feature** — the project's existing scenarios are the reference density. Mark each e2e obligation **"extend scenario `<name>`"** in preference to **"new scenario"**; a new scenario needs a genuinely new journey.
-- **Refuse to emit any e2e obligation while the project's e2e smoke gate is not wired.** A generated spec fed to a suite nothing runs is a rot accelerator. The gate is a capped, tagged smoke subset run in CI (not the full e2e suite — an oversized always-on e2e suite is what gets evicted from CI, taking all enforcement with it). If no such CI gate exists, emit the e2e obligation as a **blocked** row naming the missing gate, not as work to do.
-
-## Run
-
-**Input:** a plan path (given, or the newest in `docs/history/plans/`), already boundary-checked with amendments folded. For a non-plan diff in test-worthy code, the hunks stand in for Proposed Changes — but the derived obligations are paid **immediately**, not deferred: only a plan has a ledger and a gate, so for a diff your output is the checklist the implementer satisfies now.
-
-1. **Build the behavior list.** From the plan's Proposed Changes + the owning LLD's promised behavior, list the behaviors this plan introduces or changes. Fold in each HIGH/CRITICAL boundary finding as a regression obligation. Note behaviors a type or the compiler already guards — those owe **no** test (the boundary litmus, inverted: if it can't ship green-but-broken, it needs no test).
-
-2. **Assign a layer + oracle** to each behavior (rules above). Prefer the cheapest layer that can actually prove the promise.
-
-3. **Map to a target file** per `testing.md` — the stack's unit/integration path for most, the e2e scenario tree for a program scenario. Name fixtures/factories (existing helper, or new) and the fault-injection needed (network mock, fake timers, forced constraint). Use the repo-standard fake-data source.
-
-4. **Apply the e2e altitude gate** to any cross-process obligation; downgrade everything else to integration.
-
-5. **Emit the Test Obligations section into the plan**, plus a one-line chat summary. Write it as a subsection of the plan (an executor dispatched with only the plan file sees nothing else — an obligation that lives only in chat is lost at dispatch):
-
-   ```
-   ## Test Obligations
-
-   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults |
-   | - | ---------------------- | ----- | ----------- | ------ | ----------------- |
-
-   Coverage: {N} behaviors · {N} integration · {N} component · {N} unit · {N} e2e ({N} extend, {N} new)
-   Completion checklist: docs/tests/{feature}.md  (derived at Completion, not now)
-   ```
-
-   A behavior with no obligation is stated too, with the reason (compiler-guarded, covered by an existing test) — an empty cell reads as "not yet analyzed"; an explicit "none — compiler-guarded" reads as "checked."
-
-6. **Record the write in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Test-plan: written YYYY-MM-DD (N rows)` where N is the ledger's row count. The compliance hook greps this exact form. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
-
-## Rules
-
-- **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are verification-gate-time and Completion-time, owned by others.
-- **Every obligation names its LLD promise.** No promise, no obligation source — trace it or drop it. This is the anti-drift pin.
-- **Cheapest proving layer wins.** Do not obligate an e2e scenario for what an integration test proves, or an integration test for what a unit test proves.
-- **e2e only above the cross-process bar, and only while the smoke gate runs.** Otherwise the obligation is a blocked row naming the missing gate.
-- **Runs after boundary; skipped on BLOCK.** A blocked plan is re-planned first; there is nothing stable to obligate tests against.
-- **A short manifest is valid.** A plan that owes three integration tests owes three rows — do not pad. The coverage line is the evidence it was analyzed, not skipped.