@xhulz/nina 0.28.16

package/releases/0.8.0/core/tree/.claude/pipeline.md

@@ -0,0 +1,103 @@
+# Pipeline
+
+<!-- nina:slot project.1 track-summary -->
+
+<!-- nina:slot project.2 pipeline-diagram -->
+
+`dba`, `integration-tester` and `reviewer` are all read-only, so **dispatch them together in one
+message** after the implementer rather than in sequence. The reviewer remains the gate — it does not
+approve until the applicable guardrails have signed off. After approval, `qa` runs vitest once, on
+its own. On a diff over ~200 lines, fan the reviewer out by dimension. Full rules:
+`.claude/router.md` § *Parallelization*.
+
+---
+
+## Stage contracts
+
+Each stage has: **Input** → what arrives, **Output** → the artifact handed on, **Tools** → what it may use, **Exit criteria** → what must be true before handing off.
+
+---
+
+### 1. Planner
+
+- **Input:** user request, often ambiguous or multi-step.
+- **Output:** ordered list of subtasks, each tagged with a 1-line goal + scope (S/M/L) + retrieval list + parallelization tag (`SEQUENTIAL` / `PARALLEL-SAFE`).
+- **Tools:** Read, Grep, Glob, WebSearch, WebFetch. **No edits except planning artifacts.**
+- **Exit criteria:** each subtask is small enough for an architect to design in a single pass.
+- **Skip if:** task is already small, single-concern, and concrete.
+
+### 2. Architect
+
+- **Input:** one subtask from planner, or a well-scoped direct request.
+- **Output:** technical spec — files to touch, function signatures, data flow, edge cases, tests to add, patterns to follow. Marks **"DBA REQUIRED"** if the database will be touched. Marks **"INTEGRATION-TESTER REQUIRED"** if an integration boundary will be touched, AND includes an **Integration premises** section: every behavior the implementation depends on, each carrying the evidence its kind requires — a `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>` citation, a contract-test case, an observed response, or a `P<n>` reference into `.claude/integrations/<slug>.md`. No premise without a citation.
+- **Tools:** Read, Write, Edit, Grep, Glob, WebSearch, WebFetch. **No edits except spec files + `.claude/integrations/**`.**
+- **Exit criteria:** implementer can code without re-planning AND integration-tester can verify each premise / contract case without re-deriving it.
+
+### 3. Implementer
+
+- **Input:** architect's spec.
+- **Output:** working TS code + tests. `pnpm typecheck`, `pnpm lint`, and (when frontend) `pnpm build` clean for the affected packages. Diff scoped to the spec. **Does NOT run vitest.**
+- **Tools:** Read, Write, Edit, Glob, Grep, Bash.
+- **Exit criteria:** typecheck/lint/build pass; no scope creep; if the database was touched, says so on first line; if an external service surface touched, says so.
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+
+### 5. Reviewer (gate before qa)
+
+- **Input:** implementer's diff + all upstream artifacts.
+- **Output:** approve, or request changes with `path:line` references.
+- **Tools:** Read, Grep, Glob, Bash, WebFetch. **No edits. No vitest.**
+- **Exit criteria:**
+  - `pnpm typecheck`, `pnpm lint` pass; `pnpm build` when frontend touched.
+  - Diff matches spec (reject scope creep).
+  - `.claude/patterns.md` conventions followed (TSDoc, layering, naming, `userId` scoping, `BigInt` money, state-machine + idempotency invariants).
+<!-- nina:slot db.2 -->
+<!-- nina:slot integrations.2 -->
+  - No security / privacy regression (no PII in logs, no leaked secret, no missing `userId` scope).
+<!-- nina:slot money.1 -->
+  - **Preview-first deploy invariant:** a spec that culminates in prod deploy names a preview URL where smoke runs FIRST.
+
+### 6. QA (test execution)
+
+- **Input:** reviewer's APPROVED verdict + the implementer's touched-package list.
+- **Output:** PASS (ready for deploy) or FAIL (loops back to implementer/architect).
+- **Tools:** Read, Grep, Glob, Bash.
+- Runs vitest **once**, per affected package, **sequentially** (configs enforce single-fork). Kills stray test processes at start and end. See `.claude/agents/qa.md`.
+
+### 7. Devops (deploy)
+
+- **Trigger:** qa PASS on a step that changes a deployed surface. Not for test-only, docs-only or harness-only steps.
+- **Input:** qa PASS + the touched-package list + the architect spec's preview-deploy plan.
+- **Output:** `DEPLOYED` (targets, migrations, the smoke it actually ran, the rollback) or `BLOCKED` (what stopped it, which stage owns the fix).
+- **Tools:** Read, Grep, Glob, Bash, WebFetch. **No edits to code, tests or config.**
+- **Checks:** clean rebuild of emitting packages; both targets when the API surface changed; `VITE_*` present at build time; `migrate deploy` against the intended database; secret parity; smoke against preview exercising the changed path; a named rollback.
+- **Production:** never on its own initiative — an explicit go from {{OWNER}}, for that change.
+
+---
+
+## Handoff discipline
+
+Each stage produces a **written artifact** — spec, diff, review comments. The next stage consumes the artifact, **not** the original user message. If you find yourself re-reading the original user message at stage 3, something is wrong at stage 2.
+
+---
+
+## Examples
+<!-- nina:slot project.3 worked-example-a -->
+<!-- nina:slot project.4 worked-example-b -->
+
+### Example C — Trivial fix
+
+User: "Fix the typo in the dashboard page title."
+
+No planner, no architect. Implementer fixes, typecheck passes, reviewer verifies scope. → QA (only if a test file changed). Done.
+
+---
+
+## When the pipeline breaks
+
+- **Reviewer rejects for design issue** → loop back to architect.
+- **Architect realizes plan is wrong** → loop back to planner.
+<!-- nina:slot db.3 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot money.2 -->
+- **Implementer hits an unknown unknown** → stop, escalate. Don't guess.

package/releases/0.8.0/core/tree/.claude/retrieval.md

@@ -0,0 +1,88 @@
+# Retrieval Map (RAG for workflow)
+
+Which documents to pull into context for a given task type. Goal: **avoid loading all docs on every task** — that wastes tokens and crowds out the actual work.
+
+This is the closest thing the harness has to RAG for development. Treat it as authoritative.
+
+---
+
+## Always loaded (by Claude Code itself)
+- `CLAUDE.md` — loads automatically. Don't re-read.
+
+## Pills (per-agent behavioral corrections — loaded by the agent itself)
+
+`.claude/pills/<role>/*.md` + `.claude/pills/shared/*.md` hold hard-won corrections from past mistakes (a loop-back, a rejected diff, a blocked milestone, a user correction). **Each subagent reads its own pills before acting** (the instruction is in every `.claude/agents/<role>.md`). Distinct from the surfaces above: pills capture *agent behavior* ("the implementer did X wrong"), not codebase conventions (→ `patterns.md`) or library premises (→ `integrations/`). The orchestrator writes a pill on every loop-back or user correction. Graduation: when a pill becomes law, move it to `patterns.md`/`CLAUDE.md` and mark the pill `retired`. Format + guardrails: `.claude/pills/README.md`.
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot project.1 integration-doc-list -->
+<!-- nina:slot integrations.2 -->
+
+## Code map (load first for file-location tasks)
+
+**Rule:** Before grepping the repo to find which files participate in a domain, load `.claude/code-map.md`. Two layers:
+
+- **`.claude/code-map.md`** — hand-curated. Purpose, invariants, the two money paths, what to reuse. **Read this one.**
+- **`.claude/code-map.generated.md`** — the exhaustive mechanical inventory (every module, its exports, its test) plus the dead-export and untested-module reports. Produced by `pnpm code-map`. Go here when you need the full list.
+
+`pnpm code-map:check` fails when the curated map has drifted from the tree, and a Stop hook runs it automatically. **A "does this helper already exist?" question is answered here, not by writing a second one.**
+
+## Load on demand
+
+### Task types
+
+| Task type | Load these docs | Dispatch |
+|---|---|---|
+| New API endpoint | `.claude/architecture.md` § *API*, § *Layering*, `.claude/patterns.md` § *API conventions* | architect → implementer → reviewer → qa |
+<!-- nina:slot db.1 -->
+<!-- nina:slot db.2 -->
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot frontend.1 -->
+<!-- nina:slot frontend.2 -->
+<!-- nina:slot edge-cf.3 -->
+| Performance investigation | `.claude/architecture.md` § *Performance targets*, relevant source | architect → implementer |
+
+### Meta tasks
+
+| Task type | Load these docs | Dispatch |
+|---|---|---|
+| New subagent role | `.claude/pipeline.md`, `.claude/router.md`, existing `.claude/agents/*.md` | human decision |
+| Package / route / service / DO method added or removed | `.claude/code-map.md` — update the curated map, then run `pnpm code-map:check` | whoever shipped the change, at the close of the step |
+| Update this map | this file | architect (light) → reviewer |
+
+---
+
+## How to scope loads
+
+- **Load a section, not a full doc, when possible.** Architecture and patterns docs have headings; jump to the relevant one.
+- **Don't preload.** Only read a doc when the task actually requires it.
+- **Re-read existing code before editing it**, even if read this session — it may have changed.
+
+---
+
+## Anti-patterns
+
+- ❌ Loading `.claude/architecture.md` in full for a 3-line bug fix.
+- ❌ Loading `.claude/patterns.md` when the task is a pure design discussion (no code yet).
+- ❌ Loading every subagent spec manually — they load automatically when dispatched via Agent.
+- ❌ Re-reading `CLAUDE.md` after Claude Code has loaded it.
+- ❌ Skipping the retrieval map and loading "everything just in case."
+
+---
+
+## When unsure
+
+1. Read the **first 50 lines** of `.claude/architecture.md` (table of contents).
+2. Identify the relevant section.
+3. Read that section only.
+4. If still unclear, escalate to the user — don't guess with more tokens.
+
+---
+
+## Updating this map
+
+When a new kind of task appears that isn't in the table:
+1. Add a row here first.
+2. Commit the update alongside the change it describes.
+3. Don't let the map rot — a stale retrieval map is worse than no map.

package/releases/0.8.0/core/tree/.claude/router.md

@@ -0,0 +1,150 @@
+# Agent Router
+
+Decides which subagent (or chain) to dispatch for a given task. Subagent definitions live in `.claude/agents/`.
+
+<!-- nina:slot project.1 track-summary -->
+
+---
+
+## Decision tree
+
+<!-- nina:slot project.2 decision-tree -->
+
+---
+
+## Track flow
+
+<!-- nina:slot project.3 track-flow-diagram -->
+
+`dba` and `integration-tester` may run in parallel after the implementer — both must approve before the reviewer can. `qa` runs after the reviewer approves.
+
+### Milestone gate
+
+```
+… last sub-step: → reviewer → qa ─┬─▶ devops (preview deploy + smoke) ─┐
+                                   │                                    ├─▶ milestone done
+   (entire spec-SET like 6.* )  ───┴─▶ secops (whole-set audit) ────────┘
+                                            │
+                                            └─ BLOCKED (CRITICAL/HIGH) → architect / implementer → re-audit
+```
+
+**secops** is a MILESTONE gate, not a per-sub-step stage. When the LAST sub-step of a numbered set (`6.*`) or phase (one package's build-out) passes qa, dispatch **secops** to audit the whole assembled surface for cross-cutting security/privacy gaps. The set is not "done" until secops returns `SECURE`. Do NOT run secops per sub-step — only at set boundaries.
+
+---
+
+## Rules
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+
+### 2. Planner only for ambiguous, multi-step, or multi-package work
+If the task fits in one head and lives in a single package, skip to architect (or implementer for trivial things). Don't dispatch planner for "change the button color" or "add a `label` field to `DestinationAccount`."
+
+### 3. Architect output is a spec, not code
+Architect produces a TS spec; implementer consumes the spec; they do not re-read the original user message.
+
+### 4. Reviewer audits; QA runs tests
+Reviewer runs `pnpm typecheck` / `pnpm lint` (and `pnpm build` for frontend) and verifies clean, confirms guardrails ran, but **does not run vitest**. QA runs vitest once after approval.
+
+### 5. Pipeline is not sacred
+If reviewer finds a design flaw, loop back to the architect. Don't paper over with implementation hacks.
+
+### 6. Plugin skills are part of the pipeline
+<!-- nina:slot edge-cf.7 -->
+Retrieval-first skills registered for this stack are inherited by every subagent — invoke via the `Skill` tool. Mandatory triggers (mirrors CLAUDE.md):
+
+| Diff touches… | Skill |
+|---|---|
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot edge-cf.3 -->
+<!-- nina:slot edge-cf.4 -->
+<!-- nina:slot frontend.1 -->
+| **secops** auditing any milestone | **`security-audit`** (guidance mode — full-audit mode only on an explicit whole-tree request) |
+<!-- nina:slot edge-cf.5 -->
+<!-- nina:slot db.2 -->
+<!-- nina:slot db.3 -->
+
+The architect cites which skill informed the spec. The reviewer rejects a spec touching a surface with a mandatory skill that doesn't cite one OR justify why it wasn't needed. Same rigor as the `node_modules:<line>` premise rule.
+<!-- nina:slot edge-cf.6 -->
+
+### 6b. Devops owns the deploy
+Invoke **devops** after **qa PASS** on any step that changes a deployed surface (API, frontend, schema, deploy config, secrets, platform bindings). It is the stage that executes Hard Rule #14 — the reviewer only checks that the spec *has* a preview-deploy plan. Skip it for steps that touch only tests, docs, or the harness. **Preview and staging it deploys on its own; production needs an explicit go from {{OWNER}} for that specific change.**
+<!-- nina:slot frontend.2 -->
+
+### 7. Write a pill on every loop-back or correction
+
+When a stage loops back (qa → implementer on a test failure, reviewer rejects a diff, dba/secops blocks) **or** the user corrects something, the orchestrator distills the lesson into a pill under `.claude/pills/<role>/` (or `shared/` if it spans roles) so the responsible agent does not repeat it. This is a named step, not optional. Skip it only if the lesson is really a code convention (→ `patterns.md`/`CLAUDE.md`) or a library premise (→ `integrations/<lib>.md`) — those surfaces own it, and a recurring pill should eventually **graduate** there and be marked `retired`. If the lesson already has a pill, do **not** write a second one — increment that pill's `occurrences`, which is the counter that decides when a correction has recurred often enough to graduate into a rule. Each subagent already reads its own pills before acting, and `nina pills` checks that what was written is well formed and filed where its audience will actually read it (see `.claude/pills/README.md`).
+
+---
+
+## Parallelization
+
+**The rule that decides everything here: a stage that only reads can always run beside another
+stage that only reads. A stage that writes files owns those files alone.** Most of this pipeline is
+read-only, so most of it can overlap — the default of running all nine stages nose-to-tail is a
+habit, not a constraint.
+
+Dispatch concurrent agents **in a single message with multiple Agent tool calls**. Separate messages
+run them one after another and buy nothing.
+
+### Run these in parallel
+
+| Together | Why it is safe | What it buys |
+|---|---|---|
+| **`reviewer` ∥ `dba` ∥ `integration-tester`** after the implementer | all three are read-only + Bash | the two gates stop being a serial prefix to the review |
+| **`reviewer` fanned out by dimension** — one per axis of risk the diff carries, such as tenant isolation, patterns and spec-scope | read-only; they never touch the same output | **the biggest single win.** One reviewer carrying ~15 checklists over a 500-line diff misses things; three narrow ones do not. Faster *and* better |
+| **`architect` across the sibling specs of one milestone** (`retention-spec1..8`) | each writes its own file under `.claude/plans/specs/` | the specs share context, so designing them together is more coherent than one-at-a-time, and the whole milestone is specced in one pass |
+| **`secops` ∥ `qa`** at the end of a milestone | secops is read-only by definition | removes the audit from the critical path |
+| **`devops` ∥ `secops`** at the end of a milestone | devops only reads code; what it writes is a deploy target, not the tree | the audit and the preview deploy stop being sequential |
+| **`Explore` fan-out** for "where does X live" | read-only | one search instead of every stage re-grepping the tree |
+
+### Implementers: one per package, worktree-isolated, never the same file
+
+Two implementers writing the same checkout will clobber each other. If you want them concurrent:
+
+- Dispatch each with **`isolation: "worktree"`** so it gets its own git worktree.
+- **One implementer per package, maximum.** `{{API_DIR}}` and `{{APP_DIR}}` are fine together; two inside
+  `{{API_DIR}}` are not.
+- Their specs' "Files to touch" lists must be **disjoint** — the planner marks the subtasks
+  `PARALLEL-SAFE` only after checking that, and the architect's binding file list is what makes the
+  check possible.
+- The orchestrator sequences the merge. Never let two agents merge.
+
+### Keep these serial
+
+- **`qa`.** Vitest is ~2–3 GB per worker; concurrent invocations take the machine down. One run, at
+  the end. This is not negotiable and is not a speed problem — the suites are seconds, except the
+  `{{API_DIR}}` integration suite, which is slow for its own reasons (real DB).
+- **The merge**, always.
+- **A loop-back.** When a stage rejects, fix and re-run that stage; do not fan out around a failure.
+
+### Right-sizing beats parallelism
+
+Before parallelizing a chain, ask whether the chain should be that long at all. The
+proportional-dispatch table above is worth more than any fan-out: a display change that takes
+`implementer → reviewer` is already faster than the same change parallelized across five stages.
+
+---
+
+## What NOT to use subagents for
+
+- Trivial edits (rename variable, fix typo, add a log line).
+- Reading code to answer a user question.
+- Running a single command.
+- Pure research / exploration.
+
+The subagent overhead isn't worth it for sub-5-minute tasks. Do it directly.
+
+---
+
+## Examples
+
+| User request | Pipeline |
+|---|---|
+<!-- nina:slot project.5 dispatch-examples -->
+
+---
+
+## Quick triage
+
+When dispatch is ambiguous, escalate one notch (heavier chain). The cost of an extra stage is low; the cost of skipping dba or integration-tester on a money-movement regression is a production incident with real money.

package/releases/0.8.0/core/tree/.claude/templates/integration.md

@@ -0,0 +1,45 @@
+<!-- nina:requires integrations -->
+# <Name> — premises
+
+> One integration, one doc. The **integration-tester** creates it on first contact with the
+> dependency and appends to it whenever it observes behavior this file does not yet carry.
+> Everything below is evidence. A claim you cannot cite belongs in *Open questions*, not in a
+> premise — a premise that turns out to be a guess is how an integration regression ships.
+
+- **Kind:** `installed-library` · `live-api` · `platform-binding` — pick one; it decides what counts as evidence.
+- **Boundary:** the one module that speaks to this dependency. Nothing else may.
+- **Skill:** the installed skill covering it, or *none* — do not invent one.
+
+## Premise index
+
+Read this table and the sections your task actually cites. Not the whole file.
+
+| Premise | Evidence | Claim |
+|---|---|---|
+| P1 | `<citation>` | one sentence |
+
+---
+
+## P1 — <the claim, as a sentence>
+
+**Claim.** What the dependency does, in one sentence, stated specifically enough to be wrong.
+
+**Evidence.** The form depends on the kind:
+
+- `installed-library` — `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>`, with the lines that
+  prove it quoted. From the version actually installed here, not the latest release.
+- `live-api` — the request sent and the response received, verbatim, or the contract-test case that
+  pins it. The vendor's documentation is not evidence: it describes what they intend, and you are
+  depending on what they do.
+- `platform-binding` — what the local emulator did when driven, plus the platform's installed types.
+
+**Why it matters here.** Which code depends on this being true, and what breaks if it is not.
+
+**Checked.** `<date>` against `<version / environment>`.
+
+---
+
+## Open questions
+
+Behavior this doc does not settle yet, and what would settle it. A question here is honest work;
+the same uncertainty written as a premise is a defect waiting for a deploy.

package/releases/0.8.0/core/tree/CLAUDE.md

@@ -0,0 +1,128 @@
+<!-- nina:slot project.1 title -->
+
+<!-- nina:slot project.2 mission -->
+
+<!-- nina:slot project.3 stack -->
+<!-- nina:slot edge-cf.1 -->
+
+> **A subagent can only invoke a skill if `Skill` is in its `tools:` list.** That field is an allowlist, not a hint: for the harness's first three months it omitted `Skill` on all nine roles, so every mandatory-skill rule here was unenforceable and the measured invocation count was 2 in 743 runs — both from built-in agents that carry the full tool set. Any new role that binds a skill must grant `Skill`. The `tools:` field is read when the agent is registered, so a change to it needs a new session; the spec body is re-read on every dispatch.
+
+Mandatory triggers:
+
+| When you are about to… | Invoke skill | Why |
+|---|---|---|
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot edge-cf.3 -->
+<!-- nina:slot edge-cf.4 -->
+<!-- nina:slot edge-cf.5 -->
+<!-- nina:slot frontend.1 -->
+| Run the **secops** milestone gate | `security-audit` | the attack-class corpus; guidance mode — its full six-phase workflow is for an explicit whole-tree audit only |
+<!-- nina:slot edge-cf.6 -->
+<!-- nina:slot db.1 -->
+<!-- nina:slot db.2 -->
+
+**Each agent spec now carries its own binding table** (`.claude/agents/<role>.md` § *Skills you MUST consult*), because a rule that lives only here was invoked 2 times in 743 subagent runs. `qa` and `planner` have no skill bound — none of the installed skills covers vitest or decomposition, and an invented binding is worse than none.
+<!-- nina:slot edge-cf.7 -->
+
+Reviewer rejects any architect spec that touches the platform runtime or its deploy config without citing which skill it consulted, OR explaining why the skill was not needed. Same standard as the premise rule below: retrieval beats recall.
+
+## Where things live
+- Full architecture → `.claude/architecture.md`
+- Code conventions → `.claude/patterns.md`
+- Agent dispatch rules → `.claude/router.md`
+- Which docs to load per task → `.claude/retrieval.md`
+- Agent pipeline overview → `.claude/agents-overview.md`
+- Stage contracts + examples → `.claude/pipeline.md`
+- Subagent role specs → `.claude/agents/` (dispatchable via Agent tool)
+<!-- nina:slot project.4 product-docs -->
+
+**Generated files — edit the layer, not the output.** A file that opens with a
+`<!-- nina:generated -->` comment was composed by `nina compose` from the harness core, the
+surfaces this project declares in `.nina/profile.json`, and this project's own fragments in
+`.nina/project/tree/`. Most of the docs above open with one, and so does this file. The
+comment names the layer to edit instead — or says the text belongs to the harness and cannot
+be changed from this project, in which case **report it rather than editing it**. A hand edit
+is reported as drift by `pnpm harness:check` and overwritten by the next compose, which is
+how a correction written in the wrong place disappears without anyone being told.
+
+**The rule is the marker, not the directory.** Most of `.claude/` is yours to write and is
+never composed: `architecture.md`, the code map, `integrations/*`, everything under
+`plans/**`, and the pills under `pills/<role>/`. Do not stop writing those.
+
+## ⚠️ Agent pipeline — MANDATORY
+
+> **Dispatch the subagent chain that fits the task's size and blast radius — before executing anything non-trivial.**
+> The pipeline is **proportional, not one-size-fits-all.** Money movement, the database, auth, integration boundaries, and substantial multi-file features get the full chain. Small read-only / display / UI-copy changes get a light chain — or a direct edit. **Under-gating a money/database/auth/integration change is a protocol violation. Over-gating a one-file label or list change wastes hours — that is also a failure.**
+
+### Procedure — follow this every time
+
+1. **Classify the task** using the table below *before* touching any file.
+2. **Dispatch the first subagent** in the required chain via the Agent tool.
+3. Each stage hands off a written artifact (spec / diff / review) to the next.
+4. **Run the read-only stages concurrently.** A stage that only reads can run beside any other stage that only reads, so `reviewer`, `dba` and `integration-tester` go out together after the implementer — in ONE message with multiple Agent calls — and `secops` runs alongside `qa` at a milestone's end. For a diff over ~200 lines, fan the reviewer out by dimension — one reviewer per axis of risk the diff actually carries — instead of asking one agent to carry every checklist. Concurrent **implementers** are the exception: they write, so each needs `isolation: "worktree"`, one per package, with disjoint file lists. `qa` is always alone (vitest memory). Full rules: `.claude/router.md` § *Parallelization*.
+5. The **reviewer** must verify every required stage ran — including the database gate if the schema or a query was touched — before approving.
+6. **Honor the planner's `ONE-SPEC` / `ONE-REVIEW` grouping.** Sibling steps that change no observable behavior on their own get **one** architect spec and **one** reviewer pass over the combined diff, while still being implemented one step at a time. Small steps are good; eight full pipelines to ship one feature are not. This never relaxes a gate — dba / integration-tester / secops fire on the surface touched, however the specs were grouped.
+7. **Right-size before dispatching.** Match the chain to blast radius (see table). A change that touches no money path, no database, no auth or integration surface, and ≤2 files takes the light chain — or a direct edit when a subagent adds nothing (a label, a copy tweak, a list render). Do NOT run planner/architect/secops on that. The money/database/auth/integration gates below are never optional.
+8. **At the END of a spec-SET / milestone** (e.g. all of `6.*`), after the last sub-step's qa, dispatch **secops**. The milestone is not done until secops returns `SECURE`. This is a milestone gate, NOT a per-sub-step stage. **Scope secops to the milestone's diff by default.** A whole-tree sweep surfaces pre-existing debt mid-task and causes scope-creep — run it ONLY when explicitly requested, as a deliberate choice, never as the default.
+
+### Required chain by task shape
+
+| Task shape | Required dispatch |
+|---|---|
+| Question / exploration / Q&A | none — answer directly |
+| Trivial edit (rename, typo, 1-line log fix) | none — edit directly |
+| **Small read-only / display / UI-copy change** (≤2 files, no money path, no database, no auth or integration boundary) | **implementer → reviewer** — or a direct edit if a subagent adds no value; qa runs ONLY the affected test file. No planner, no secops. |
+| Single-file bug fix (TS) | **implementer → reviewer → qa** |
+| Refactor TS (no new behavior) | **architect → implementer → reviewer → qa** |
+| New TS feature / multi-file change (money path, schema, auth, or ≥3 files with logic) | **planner → architect → implementer → reviewer → qa** |
+<!-- nina:slot db.3 -->
+<!-- nina:slot integrations.1 -->
+| **ANY step that changes a deployed surface** (API, frontend, schema, deploy config, secrets, bindings) | **+ devops after qa** — preview deploy + smoke; prod only on an explicit go |
+<!-- nina:slot frontend.2 -->
+| **END of a spec-SET / milestone** (a numbered set like `6.*`, or a phase like one package's build-out) | **+ secops after the last sub-step's qa** — milestone security gate; `SECURE` required before the milestone is declared done |
+
+**Test execution policy:** vitest is **only** invoked by the **qa** stage, which runs once at the end of the pipeline (after reviewer approves). Implementer writes tests but does NOT execute them. Reviewer does NOT run tests. This prevents the workspace-machine memory blowups from concurrent vitest invocations (vitest is ~2–3 GB per worker). Configs enforce single-fork; the root `pnpm test` uses `turbo run test --concurrency=1`.
+
+**Test scoping (speed — this is the single biggest time sink).** qa runs ONLY the test files / packages the diff actually touches during the build→fix loop — never the full suite per cycle. The `{{API_DIR}}` integration suite hits a real Accelerate DB via real magic-link flows and takes **~18 min** (and is flaky under load). Run it targeted per file while iterating; run the **full** package suite exactly ONCE, right before opening the PR / merging, as the final gate. Vitest stays single-fork and non-concurrent.
+
+### If you are uncertain which chain applies
+→ If the doubt is whether a **money / database / auth / integration** surface is touched → treat it as the heavier shape and gate it. If the task is clearly none of those and the only question is "how much ceremony" → take the **lighter** chain; an extra planner/secops pass on a display change costs hours, not minutes.
+
+<!-- nina:slot project.5 roles-heading -->
+
+- **planner** → decompose ambiguous or multi-step tasks into ordered subtasks
+- **architect** → design the TS technical approach AND cite external-library premises (`node_modules/.pnpm/<lib>/.../<file>:<line>`); write a spec before code exists
+- **implementer** → write TS code AND test files strictly to spec; runs typecheck/lint/build only (NOT vitest)
+<!-- nina:slot db.4 -->
+<!-- nina:slot integrations.3 -->
+- **reviewer** → verify diff matches spec, run typecheck/lint/build (NOT vitest), confirm dba and integration-tester ran when applicable, confirm spec has a preview-deploy plan
+- **qa** → runs vitest once at the END of the pipeline (after reviewer approves) for the affected packages; loops back to implementer on failures
+- **devops** → **deploy owner.** Runs after **qa PASS** on any step that changes a deployed surface. Staging FE goes to Pages `--branch staging` (a preview deploy); `--branch main` is production and needs an explicit go. Smokes the deployed preview for a blank page and a clean console — judging whether the screen is *right* is the reviewer's job, not his. Executes Hard Rule #14: clean build, both targets (staging Worker + Pages), build-time env, migrations in order against the right DB, secret parity, **smoke against preview**, named rollback. Deploys preview/staging on its own; **a production deploy requires an explicit go from {{OWNER}} for that change.** Read-only on code — a failed deploy caused by bad code loops back, it does not get patched here.
+- **secops** → **milestone security gate.** Runs once at the END of a completed spec-SET (a numbered milestone like `6.*`, or a phase like one package's build-out), after the last sub-step's qa — NOT per sub-step. Audits as an attacker and a privacy auditor (auth/session, tenant isolation, secrets and config exposure, PII leakage, abuse of any irreversible operation and its idempotency seams, injection/SSRF, dependency and binding posture). **Scoped to the milestone diff by default; a whole-tree sweep runs only on explicit request** (it surfaces pre-existing debt mid-task → scope-creep). Read-only; CRITICAL/HIGH findings in the milestone's own surface BLOCK it and loop back until re-audited.
+
+<!-- nina:slot project.6 doc-pointers -->
+
+## Hard rules (non-negotiable)
+
+1. **Run the subagent chain proportional to the task (see the pipeline table).** Under-gating a money-movement, database, auth, or integration change is a protocol violation — those gates are never skipped, and when uncertain whether such a surface is touched, gate it. But small read-only / display / UI-copy changes (≤2 files, none of those surfaces) take the light chain or a direct edit — over-gating them wastes hours and is also a failure.
+<!-- nina:slot db.5 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot money.3 -->
+<!-- nina:slot db.6 -->
+<!-- nina:slot db.7 -->
+<!-- nina:slot pii.1 -->
+9. **TSDoc is mandatory on every TS declaration** (function, type, interface, class, method, enum) — exported or not. Enforced in review.
+<!-- nina:slot edge-cf.8 -->
+<!-- nina:slot integrations.4 -->
+<!-- nina:slot integrations.5 -->
+<!-- nina:slot integrations.6 -->
+14. **Preview-first deploy. Smoke runs against preview, NEVER prod first.** The **devops** stage owns executing this; the reviewer only verifies the plan exists. Any change that culminates in a production deploy must name a preview URL (a preview deployment for `{{APP_DIR}}`; a staging route for the API) in the architect's spec. Smoke runs against preview FIRST. A spec without a preview-deploy plan is rejected by the reviewer.
+15. **Relative imports use the `.js` extension in `.ts`/`.tsx` source — this is intentional ESM, NOT a mistake.** `import { x } from './client.js'` (never `'./client'` or `'./client.ts'`). TypeScript does not rewrite specifiers; emitting packages ({{EMITTING_PKGS}}) ship real `dist/*.js`, so the `.js` form is the only one that resolves at runtime, and the bundlers map it back to `.ts` source transparently. Stripping or `.ts`-ifying the extension breaks the build — do not "fix" it. Full rationale: `.claude/patterns.md` § *Relative imports carry a `.js` extension*.
+
+## Common commands
+
+<!-- nina:slot project.7 common-commands -->
+
+## When in doubt
+Consult `.claude/retrieval.md` to decide which docs to load before acting.

package/releases/0.8.0/surfaces/db/tree/.claude/agents/architect.md

@@ -0,0 +1,8 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+6. **Tenant-scope impact** — explicitly state where `userId` is enforced. Every new Prisma query in app code includes `userId` (or its model-specific FK equivalent) in the `where` clause. The only exempt tables are the {{AUTH_LIB}} system tables.
+
+<!-- nina:slot db.3 -->
+10. **Prisma flag** — if `schema.prisma` or a new Prisma query is touched, mark **"DBA REQUIRED"** prominently at the top of the spec. Specify the proposed `cacheStrategy`, or **`NO_CACHE`** for any read that feeds a write whose correctness depends on it being fresh — a stale row contaminates every decision made from it.

package/releases/0.8.0/surfaces/db/tree/.claude/agents/dba.md

@@ -0,0 +1,84 @@
+<!-- nina:slot db.1 -->
+| `prisma-cli` | **before ANY `prisma` CLI command** — `validate`, `format`, `migrate dev`, `migrate diff`, `migrate deploy`. Flags differ between versions, and one of them (`migrate diff --shadow-database-url` against a live database) destroys the database it points at |
+| `prisma-client-api` | auditing a new or changed query — filters, operators, `$transaction` semantics |
+
+<!-- nina:slot db.2 -->
+Neither skill covers a **caching or edge layer sitting on top of the client** — cache strategy,
+edge-client behaviour and the rule about never caching a read that authorizes a write belong to that
+layer's own integration doc, declared like any other integration. A skill does not replace it.
+
+<!-- nina:slot db.3 -->
+- Any change to `{{DB_PKG}}/prisma/schema.prisma`.
+- Any new Prisma query (`findUnique`, `findMany`, `create`, `update`, `delete`, `aggregate`, `$queryRaw`, etc.) anywhere in application code.
+- Any migration generated via `prisma migrate`.
+
+<!-- nina:slot db.4 -->
+- The Prisma diff (schema changes + generated migration SQL).
+- The application code that uses the new or modified queries.
+
+<!-- nina:slot db.5 -->
+**Read `.claude/code-map.md`** when the change touches new query patterns — it lists which services consume which Prisma models, so you can spot N+1 risk and consumer-side cache implications without re-grepping. (Greenfield phase: fall back to `.claude/architecture.md` § *Database* for the planned schema — the model table, monetary conventions, and the Accelerate cache-policy table are canonical there.)
+
+<!-- nina:slot db.6 -->
+1. **Schema validates.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`. Must pass.
+
+<!-- nina:slot db.7 -->
+2. **Migration diff.** Run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta:
+
+   ```
+   # Compare the PREVIOUS schema against the working one — pure file-to-file, no database.
+   git show HEAD:{{DB_PKG}}/prisma/schema.prisma > /tmp/schema-head.prisma
+   pnpm --filter {{DB_PKG_NAME}} exec prisma migrate diff \
+     --from-schema-datamodel /tmp/schema-head.prisma \
+     --to-schema-datamodel prisma/schema.prisma \
+     --script
+   ```
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without `--shadow-database-url`, which pushes you toward supplying a database
+   URL — the exact move that destroys databases (below). The two-datamodel form above answers the
+   same question with no database involved. Compare its output against the hand-written
+   `migration.sql` to confirm the declarative parts match.
+
+   ⛔ **NEVER pass `--shadow-database-url`, `--from-url`, `--to-url`, or `--from-schema-datasource` pointing at a real database — most of all not `DATABASE_URL` from `{{API_DIR}}/{{SECRETS_LOCAL}}`.** Prisma **executes** the entire migration history against whatever database those flags name, which **DESTROYS ALL DATA** in it. A shadow database must be a disposable, empty database and nothing else. This is not hypothetical, and it does not announce itself: the command completes with a reassuring "empty migration" result and no error, having already destroyed everything in the database it was pointed at. If the offline form above cannot answer your question, **STOP and report that to the orchestrator** instead of reaching for a database URL.
+
+<!-- nina:slot db.8 -->
+3. **Migration safety on large tables:**
+   - No `ALTER TABLE ... ADD COLUMN NOT NULL` without a safe default (causes lock + rewrite).
+   - No operations that hold long locks without an explicit batched strategy.
+   - Non-breaking for rolling deploy — old application code and new schema must coexist during the deploy window.
+
+<!-- nina:slot db.9 -->
+4. **Index coverage.** Every new query pattern (`WHERE`, `ORDER BY`, `JOIN`, `aggregate`) must be backed by an index. Use `@@index` in schema. Reject queries that would table-scan. The most-used compound index is `(<tenant>, <other>)` or, for models keyed by a parent entity, `(<parentId>, <other>)`; verify the leading column matches the query.
+
+<!-- nina:slot db.10 -->
+5. **userId scope.** Every query in app code must include `userId` in `where` (or the model's equivalent FK chain — `accountId`/`entryId`/`ruleId` resolving back to the owning user). The {{AUTH_LIB}} system tables are the only exemption. Reject any app query missing the scope.
+
+<!-- nina:slot db.11 -->
+6. **Cache strategy.** Every `findUnique` / `findMany` on a hot read path has an explicit `cacheStrategy` (Accelerate `ttl` / `swr`). **Implicit cache is a bug — reject.** Cross-check the policy against the cache-policy table in `.claude/architecture.md` § *Database*.
+
+<!-- nina:slot db.12 -->
+8. **N+1 patterns.** If the code fetches a list then queries per item, reject with "use `include` / `select` or batch."
+
+<!-- nina:slot db.13 -->
+12. **Secrets.** `DATABASE_URL` (Prisma Postgres / Accelerate URL) must come from `{{SECRETS_LOCAL}}` locally and `{{SECRETS_PROD}}` in production — never `.env` committed.
+
+<!-- nina:slot db.14 -->
+- **Run ANY command that can write to a real database.** You are a read-only gate. Against a live
+  `DATABASE_URL` you may run `SELECT`-only queries and nothing else. Explicitly forbidden, no
+  exceptions: `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`,
+  `db push`, `db execute`, `$executeRaw*`, and **any `prisma migrate diff` variant carrying a
+  database URL** (see check #2 — that one silently wipes the database it points at). If a check
+  seems to require writing, it does not: report the limitation to the orchestrator instead.
+
+<!-- nina:slot db.15 -->
+- Approve without actually running `prisma validate` and the offline `prisma migrate diff` of check #2.
+
+<!-- nina:slot db.16 -->
+- Wave through "small" schema changes. Small changes cause the worst production incidents.
+
+<!-- nina:slot db.17 -->
+- Approve a query missing `userId` scope (or its equivalent owning FK) in app code.
+
+<!-- nina:slot db.18 -->
+**Final report format:** ≤300 words if approved. Sections: Schema validation result, Migration SQL preview (verbatim if non-trivial), Index analysis, userId-scope check, Cache strategy verdict, Money-integrity check (idempotency-key uniqueness), Privacy check, Final verdict. If rejected, list each issue with required action — no length cap.

package/releases/0.8.0/surfaces/db/tree/.claude/agents/devops.md

@@ -0,0 +1,14 @@
+<!-- nina:slot db.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot db.2 -->
+4. **Migrations, in order, against the right database.** Apply with `prisma migrate deploy`. Confirm the target `DATABASE_URL` is the one you intend. Verify the migration is backward-compatible with the currently-deployed code, because the two are live together during the rollout.
+
+<!-- nina:slot db.3 -->
+- Run `prisma migrate diff --shadow-database-url <url>` against any live database. It **executes** the migration history against that database, destroying everything in it, and reports success. Use a disposable shadow database or don't run it.
+
+<!-- nina:slot db.4 -->
+- Run `prisma migrate reset` against a shared database, ever.
+
+<!-- nina:slot db.5 -->
+- **Migrations:** applied / none, with the database they hit.

package/releases/0.8.0/surfaces/db/tree/.claude/agents/implementer.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+- If you change `schema.prisma` or write a new Prisma query, flag it explicitly in the diff summary so the reviewer dispatches **dba** before approving.