@nurix/etna 0.19.41 → 0.19.43

package/data/harnesses/apollo/skills/documentation/templates/migration-runbook.md

@@ -0,0 +1,34 @@
+# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
+
+Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
+
+Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.
+
+```
+# Migration: {Title}
+
+**Goal:** What this migration accomplishes and why it runs now, one or two lines.
+**Executes against:** {environment / database / system}
+
+## Preconditions
+
+- Backups taken, feature flags set, access confirmed — exact checks
+
+## Steps
+
+1. One action per step, exact command in a code block
+2. Note expected output where it disambiguates success from failure
+
+## Verification
+
+- The observable end state that confirms success — exact check commands
+
+## Rollback
+
+- How to undo, and the point of no return
+
+## Outcome
+
+<!-- Stamped once, immediately after execution; the file freezes with it. -->
+**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
+```

package/data/harnesses/apollo/skills/documentation/templates/non-goals.md

@@ -0,0 +1,11 @@
+# Non-Goals (docs/architecture/non-goals.md)
+
+Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
+
+```
+# Non-Goals
+
+Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
+
+- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+```

package/data/harnesses/apollo/skills/documentation/templates/operations-procedure.md

@@ -0,0 +1,36 @@
+# Operations Procedure (docs/operations/{procedure}.md)
+
+Truth document. Use for: any **recurring** procedure — setup, development, deployment, maintenance. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
+
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
+
+Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
+
+If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
+
+```
+# {Procedure Name}
+
+**Goal:** What this procedure accomplishes, one line.
+
+## Preconditions
+
+- Access, tools, or state required before starting — exact versions, env vars, credentials location
+
+## Steps
+
+1. One action per step, exact command in a code block
+2. Note expected output where it disambiguates success from failure
+
+## Verification
+
+- The observable end state that confirms it worked — exact check commands, not "it should work now"
+
+## Troubleshooting
+
+- Symptom → cause → fix (append entries as failures are root-caused)
+
+## Rollback
+
+- How to undo, and when undo stops being possible
+```

package/data/harnesses/apollo/skills/documentation/templates/plan.md

@@ -0,0 +1,71 @@
+# Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
+
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `test-plan`) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
+
+```
+# {Feature Name}
+
+**Status:** Draft | In Progress | Complete | Abandoned
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Started:** YYYY-MM-DD
+**Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
+
+## Background
+
+Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.
+
+## Proposed Changes
+
+### New Files
+
+- `src/path/new-file.js` — purpose
+
+### Modified Files
+
+- `src/path/existing.js` — what changes and why
+
+### New Entities / State
+
+- `entities.foo` — new Redux slice / DB table / persisted shape
+- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)
+
+### API Changes
+
+- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
+- `PUT /api/bar` — request shape changes; see Migration
+
+### Cross-Module Contracts Affected
+
+- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
+- "None" is a valid answer and means the `boundary` check will pass cleanly
+
+## Implementation Steps
+
+1. Concrete, ordered, testable
+2. Each step ends with something verifiable
+3. ...
+
+## Test Obligations
+
+<!-- Written by the `test-plan` skill at the plan gate (after `boundary`). One row per
+     promised behavior: layer · target file · oracle · fixtures. Amendable while the
+     plan is open; discharged at the verification gate. Do not hand-author. -->
+
+## Done Criteria
+
+- [ ] Implementation complete
+- [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
+- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
+- [ ] Plan marked `Status: Complete`, **Completed:** date filled
+
+## Open Questions
+
+- Question — who decides, by when
+
+## Risks
+
+- Risk — likelihood / impact / mitigation
+```

package/data/harnesses/apollo/skills/documentation/templates/protected-files.md

@@ -0,0 +1,37 @@
+# Protected Files
+
+Truth document. Use for: documenting critical files that need approval before modification.
+
+This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
+
+```
+# Protected Files
+
+Critical files requiring approval before modification.
+
+## File List
+
+# Category 1 - Description
+path/to/critical/file1.js
+path/to/critical/file2.js
+
+# Category 2 - Description
+path/to/another/file.js
+
+## Risk Summary
+
+| Category   | Risk if Broken  |
+|------------|-----------------|
+| Category 1 | Specific impact |
+| Category 2 | Specific impact |
+
+## Why Protected
+
+### Category 1: [Name]
+
+**Purpose:** What these files do, one or two lines
+**Owning doc:** [docs/features/{feature}.md] — canonical reference for how this code works
+**Invariants:**
+- The behavior that must not break, stated as a constraint (not a function tour)
+- Important point 2
+```

package/data/harnesses/apollo/skills/documentation/templates/root-readme.md

@@ -0,0 +1,104 @@
+# Project Root README
+
+Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
+
+### Strategy
+
+The root README answers, in order:
+
+1. **What is this?** — one to two sentences, no marketing claims
+2. **What do I get if I install it?** — capability families
+3. **What's it built on?** — terse stack list with versions
+4. **How do I run it?** — the three or four scripts that matter
+5. **How is it laid out?** — directory tree, one-liner per significant folder
+6. **How do I extend it?** — numbered contribution checklist
+7. **What state is it in?** — pre-publish, beta, stable, internal
+
+Skip any section that doesn't apply. Don't pad to fill the template.
+
+### Writing rules
+
+- **Sentence-case headings.** "Getting started", not "Getting Started".
+- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
+- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
+- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
+- **Directory tree as a code block**, not a nested markdown list.
+- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
+- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
+- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
+
+### Template
+
+```markdown
+# {package-name}
+
+{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
+
+## What's in the box
+
+- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
+- **{Family 2}** — {what's in it.}
+- **{Family 3}** — {what's in it.}
+
+The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
+
+## Stack
+
+- {Framework} {version} · {Language} {version}
+- {Build tool} {version}
+- {Other load-bearing deps}
+
+## Getting started
+
+\`\`\`bash
+{pm} install
+{pm} run dev        # what it does (port, URL)
+{pm} run build      # what it does
+{pm} run preview    # what it does (omit if not applicable)
+\`\`\`
+
+{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
+
+## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
+
+{Brief description of the dev/runtime surface.}
+
+| {Thing}              | {What it shows / does} |
+| -------------------- | ---------------------- |
+| `{route or command}` | {description}          |
+
+## Layout
+
+\`\`\`
+src/
+├── {entry-file}        # {purpose}
+├── {folder}/           # {purpose}
+│   └── ...
+└── {folder}/           # {purpose}
+\`\`\`
+
+## Adding a {primary unit}
+
+1. {Drop the source under the right family/folder.}
+2. {Re-export from the public surface.}
+3. {Wire into the playground / example app / test harness so reviewers can see it render.}
+4. {Document any divergence from upstream in `docs/{...}`.}
+
+## Styling ← optional; replace with whichever cross-cutting concern matters most
+
+{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
+
+## Status
+
+{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}
+
+## License
+
+{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
+```
+
+### Baseline scaffolding behavior
+
+The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
+
+**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.

package/data/harnesses/apollo/skills/documentation/templates/security-overview.md

@@ -0,0 +1,27 @@
+# Security Overview (docs/architecture/security.md)
+
+Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
+
+Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
+
+```
+# Security Overview
+
+## Assets
+
+- {What's worth protecting — data classes, credentials, tenant isolation}
+
+## Trust boundaries
+
+- {Boundary} — {what crosses it, and what checks the crossing} 
+
+## Controls
+
+| Control | Protects against | Implemented in |
+| ------- | ---------------- | -------------- |
+| {control} | {threat} | `{file/module}` |
+
+## Accepted risks
+
+- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+```

package/data/harnesses/apollo/skills/documentation/templates/structure.md

@@ -0,0 +1,65 @@
+# docs/structure.md (Authority Map)
+
+Truth document. Use for: defining which folder owns which topic and how docs are maintained.
+
+```
+---
+harness-version: 1.0.0
+---
+
+# Documentation Structure
+
+> This file is the entry point for understanding the docs folder.
+> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
+
+## Authority Map
+
+Each topic has one canonical location. Read from here, not from plans or changelogs.
+
+| Topic | Authority | Key Files |
+| ----- | --------- | --------- |
+| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
+| System overview | `docs/architecture/` | system-design.md |
+| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
+| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
+| API surface | `docs/architecture/` | api.md |
+| Security | `docs/architecture/` | security.md |
+| Feature behavior | `docs/features/` | {key files} |
+| Setup & development | `docs/operations/` | {key files} |
+| Environment / config surface | `docs/operations/` | environment.md |
+| Testing strategy | `docs/tests/` | strategy.md |
+| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
+| Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
+| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
+| Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
+| Backlog | `docs/history/` | backlog.md |
+
+## The Two Natures
+
+Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
+
+- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
+- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
+- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
+
+## Folder Rules
+
+- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
+- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
+- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
+- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
+- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
+- `docs/history/changelog/`: Records. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
+- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
+- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
+- `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
+- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
+
+## Health Log
+
+<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
+| Date | Review Summary |
+| ---- | -------------- |
+| {today} | Initial baseline — v{harness-version} structure established |
+```

package/data/harnesses/apollo/skills/documentation/templates/system-overview.md

@@ -0,0 +1,32 @@
+# System Overview (docs/architecture/system-design.md)
+
+Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
+
+Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+
+```
+# System Overview
+
+## What this is
+
+{Two or three sentences: what the system does, for whom, in what environment it runs.}
+
+## Subsystem map
+
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Frontend │────▶│   API    │────▶│    DB    │
+└──────────┘     └──────────┘     └──────────┘
+{One box per subsystem; label the arrows with the contract that crosses them.}
+
+- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+
+## Key flows
+
+{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+
+## Where the truth lives
+
+| Area | Canonical doc |
+| ---- | ------------- |
+| {area} | [{doc}](path) |
+```

package/data/harnesses/apollo/skills/documentation/templates/testing-strategy.md

@@ -0,0 +1,29 @@
+# Testing Strategy (docs/tests/strategy.md)
+
+Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
+
+Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+
+```
+# Testing Strategy
+
+## Levels
+
+| Layer | Runner | Lives in | Covers |
+| ----- | ------ | -------- | ------ |
+| Unit / integration | {runner} | `tests/` | {what} |
+| E2E | {runner} | `e2e/` | {what} |
+
+## Running
+
+- `{pm} test` — the whole unit suite (CI gate)
+- `{pm} run test:e2e` — {when to run}
+
+## Deliberately untested
+
+- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
+
+## Adding a test
+
+1. {Where the file goes, what it's named, where fixtures live}
+```

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

@@ -0,0 +1,83 @@
+---
+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."
+
+## 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.