@xhulz/nina 0.28.16

package/releases/0.2.1/core/tree/.claude/patterns.md

@@ -0,0 +1,202 @@
+# Patterns & Conventions
+
+Read this before writing code. Architects cite it in specs; implementers follow it; reviewers enforce it.
+
+---
+
+## Language & tooling
+
+- **TypeScript strict mode** everywhere. No `any` without a justifying comment.
+- **pnpm workspaces + Turborepo**. Never `npm` or `yarn`. Use `turbo run <task>` for orchestrated work.
+- **Biome** for format + lint. No ESLint / Prettier.
+- **Vitest** for unit tests. **Miniflare** for Worker integration tests.
+- **Zod** for runtime validation at all trust boundaries (API ingress, env loading, queue payload, DO RPC, webhook body, integration responses).
+
+### Relative imports carry a `.js` extension — this is intentional, do NOT "fix" it
+
+Relative imports in `.ts`/`.tsx` source MUST use the `.js` extension (e.g. `import { x } from './client.js'`, never `'./client'` or `'./client.ts'`). This looks wrong but is correct ESM-TypeScript and is load-bearing:
+
+- The repo is ESM (`"type": "module"`, `module: ESNext`, `moduleResolution: Bundler`, `verbatimModuleSyntax: true` in `packages/tsconfig/base.json`). **TypeScript never rewrites import specifiers** — what you write is what lands in the emitted `.js`.
+- Emitting packages ({{EMITTING_PKGS}}) compile with `tsc` to real `.js` in `dist/` and are consumed via their `exports` map (`./dist/*.js`). At runtime the file IS `client.js`; a source `'./client.ts'` would emit a dead `'./client.ts'` reference → broken import. The `.js` form is the only one that works for these.
+- Bundled apps (`{{API_DIR}}` via wrangler/esbuild, `{{APP_DIR}}` via Vite) resolve `'./x.js'` back to `./x.ts` source transparently, so the same convention works everywhere.
+- Switching to `.ts` extensions would require `allowImportingTsExtensions`, which only works with `noEmit` — it would break every emitting package. Do not propose it.
+
+This is the official TypeScript guidance for ESM. A reviewer/AI that "corrects" `.js` → `.ts` (or strips the extension) is introducing a bug, not a cleanup.
+
+---
+
+## Folder structure within a TS package
+
+```
+package/
+├── src/
+│   ├── index.ts          # public exports only — this is the package API
+│   ├── internal/         # not re-exported; no deep imports allowed from outside
+│   └── types.ts          # shared types
+├── test/                 # *.test.ts mirroring src/ structure
+└── package.json
+```
+
+- External code imports from `{{PKG_SCOPE}}/<name>` (barrel `index.ts`), never `{{PKG_SCOPE}}/<name>/src/internal/...`.
+
+---
+
+## `export` only what crosses a module boundary
+
+**`export` is a claim that something outside this file needs the symbol.** If nothing does, drop the
+keyword — the declaration stays, it just stops pretending to be API.
+
+This is not cosmetic. An unused export is invisible to every tool we have: TypeScript's
+`noUnusedLocals` and Biome's `noUnusedVariables` both stop at the file boundary, so an exported dead
+symbol is the one kind of dead code nothing flags. It also makes the symbol look load-bearing to the
+next reader, which is how a second implementation gets written next to the first.
+
+- A React component's `Props` type used only by that component is **not** exported. Export it only
+  when another module actually imports it.
+- The same goes for a service's internal result/input shapes, an error code union that never leaves
+  its module, and a constant only its own file reads.
+<!-- nina:slot project.1 library-packages -->
+- The standing report is `.claude/code-map.generated.md` § *Rot signals* (`pnpm code-map`). The
+  reviewer checks it for symbols the current diff introduced: **a new export nothing consumes is
+  dead on arrival.**
+
+---
+
+## Naming
+
+- **Files:** `kebab-case.ts` for modules, `PascalCase.tsx` for React components.
+- **Types / interfaces:** `PascalCase`. No `I` prefix.
+- **Functions / vars:** `camelCase`.
+- **Constants:** `SCREAMING_SNAKE_CASE` only for true compile-time constants.
+- **Env vars:** `SCREAMING_SNAKE_CASE`, loaded through a typed `env.ts` with Zod validation.
+<!-- nina:slot db.1 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot money.3 -->
+
+---
+
+## API (Cloudflare Worker / Hono) conventions
+
+### Layering: Route → Service → Data Objects
+
+Every request (and queue/webhook invocation) traverses three layers in order. **No layer may skip the next.** Full diagram in `.claude/architecture.md`.
+
+- **Route** (`{{API_DIR}}/src/routes/<resource>.ts`): Zod validation, auth + role extraction, envelope shaping, privacy-safe log, deps construction. Nothing else.
+<!-- nina:slot integrations.1 -->
+- **Service** (`{{API_DIR}}/src/services/<resource>.ts`): business orchestration, userId scoping, Date→ISO mapping, named-error taxonomy. HTTP-agnostic.
+- **Data Objects:** the database client, the platform bindings, and each integration's boundary module.
+
+**Hard rules (reviewer enforces):**
+
+<!-- nina:slot db.2 -->
+2. Routes must NOT call `.toISOString()` on service results — services do that.
+3. Services must NOT import Hono `Context`, call `c.json`, or reference status codes.
+<!-- nina:slot db.3 -->
+<!-- nina:slot db.4 -->
+<!-- nina:slot money.4 -->
+<!-- nina:slot money.5 -->
+<!-- nina:slot integrations.2 -->
+
+### Other API rules
+
+- **Zod validation at the request boundary.** No ad-hoc `if (!body.foo) return 400`.
+- Response shape is always `{ok: true, data: T} | {ok: false, error: {code, message}}`. No bare throws leaking to clients.
+- Custom errors: `class AppError extends Error { code: string; status: number }`. Each route maps known classes to HTTP codes.
+<!-- nina:slot money.6 -->
+<!-- nina:slot db.5 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot project.2 integration-error-types -->
+
+---
+
+## SDK / shared package conventions
+
+- **Tree-shakeable:** barrel `index.ts` only re-exports. No side effects at module top level.
+- Works in: modern browsers, Node 20+, Workers.
+- No `console.log` in production paths. Use a `debug(msg)` helper that's a no-op in prod, and never log PII.
+<!-- nina:slot frontend.1 -->
+
+---
+
+## Tests
+
+### Unit tests
+- Test **pure functions** directly. No mocks of our own code.
+<!-- nina:slot money.7 -->
+- Don't test implementation details. Test behavior at the module boundary.
+
+### Integration tests
+- **Miniflare** for Worker tests — real Cloudflare runtime, no mocks.
+<!-- nina:slot db.6 -->
+<!-- nina:slot integrations.4 -->
+
+### Fixtures
+<!-- nina:slot project.3 test-fixtures -->
+
+### Test files MUST be inside the typecheck program
+
+A package whose `tsconfig.json` has `include: ["src"]` **does not typecheck its own tests.** That is
+a false green, and an expensive one: the test still imports the symbol you deleted and still passes
+a fixture whose shape drifted, and you find out at vitest time — or never, if nobody runs that
+suite. It is the mechanism behind the pill *test-files-not-typechecked-on-symbol-removal*.
+<!-- nina:slot project.4 typecheck-current-state -->
+
+A package that emits (`build: tsc`, with `rootDir: "src"`) cannot simply add `test` to its build
+config. Give it a second config instead and point the script at it:
+
+```jsonc
+// tsconfig.typecheck.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": ".", "noEmit": true },
+  "include": ["src", "test"]
+}
+```
+```jsonc
+// package.json — build keeps using tsconfig.json, typecheck does not
+"typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+```
+<!-- nina:slot project.5 typecheck-coverage -->
+<!-- nina:slot project.6 typecheck-correction-note -->
+
+---
+
+## TSDoc — required on all TS declarations
+
+Every named declaration gets a TSDoc block (`/** ... */`) — exported or not: functions, classes + members, interfaces + members, type aliases, enums + members, and top-level constants whose name doesn't convey intent.
+
+### Structure
+- **First line:** a concise one-sentence summary.
+- **`@param`** when the purpose isn't fully encoded in name and type.
+- **`@returns`** when the return carries information the type alone doesn't convey.
+- **`@throws`** whenever the function can throw — name the error type and condition.
+- **`@example`** for non-trivially composed APIs.
+- **`@remarks`** for invariants, perf trade-offs, caveats.
+
+### What TSDoc is NOT
+- Not a restatement of the signature. Not a changelog. Not a crutch for bad naming.
+
+### Enforcement
+Reviewer verifies coverage. **Missing TSDoc on any new declaration = request changes.**
+
+---
+
+## Inline comments — default: none
+
+Separate from TSDoc. Regular `//` comments stay rare:
+- **Only** for non-obvious **WHY**: an invariant, a subtle perf trade-off, a workaround.
+- **Never** for WHAT — if code doesn't read clearly, fix the code.
+- **Never** reference callers, tickets, or PR history.
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot project.7 required-secrets -->
+<!-- nina:slot edge-cf.2 -->
+
+---
+
+## Commit / PR conventions
+
+- One logical change per PR. Multi-concern PRs get split by reviewer.
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
+- PR description answers **why**, not **what**.
+- Reviewer verifies: typecheck clean, Biome clean, dba approved (if Prisma touched), integration-tester approved (if an integration boundary was touched), no secret leaked, no PII in logs or tests.

package/releases/0.2.1/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 Prisma 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 Prisma 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 vitest/workerd 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.2.1/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.2.1/core/tree/.claude/router.md

@@ -0,0 +1,149 @@
+# 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. Cloudflare plugin skills are part of the pipeline
+The `cloudflare@cloudflare` plugin (user-scope) exposes retrieval-first skills. Subagents inherit them — 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 Workers/DO/Queues/wrangler-touching spec that doesn't cite a skill 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, wrangler config, secrets, 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`. Each subagent already reads its own pills before acting (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.2.1/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.