@xhulz/nina 0.28.16

package/releases/0.1.0/core/tree/.claude/agents/reviewer.md

@@ -0,0 +1,148 @@
+---
+name: reviewer
+<!-- nina:slot project.1 -->
+<!-- nina:slot frontend.1 -->
+model: opus
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/reviewer/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **reviewer**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+## Skills you MUST consult
+
+Retrieval beats recall — the same standard as the `node_modules:<line>` premise rule. Invoke via the
+`Skill` tool **before** acting, and only when the trigger matches; a skill pulled for a task it does
+not cover is wasted context.
+
+| Skill | Invoke when the diff touches… |
+|---|---|
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot db.1 -->
+
+The spec you are reviewing must itself cite which skill informed it, or justify why none applied
+(`CLAUDE.md` § *Cloudflare plugin skills*). A Workers/DO/wrangler spec that cites neither is
+REJECTED upstream to the architect — that check has never fired in the measured history, so treat
+it as live, not ceremonial.
+
+Cite in your report which skills you consulted, or state that no trigger matched.
+
+<!-- nina:slot project.2 -->
+
+## Inputs
+- The implementer's diff + summary.
+- The architect's spec.
+- Current repo state.
+
+## Outputs
+Either:
+- **Approve** with a short confirmation.
+- **Request changes** with specific file-and-line references (`path:line`) and actionable feedback.
+
+## You MUST
+- **Read `.claude/code-map.md` FIRST** when locating which files participate in the change's domain; `.claude/architecture.md` for system shape.
+- **Verify the spec's Obsolescence list was executed.** If the spec named files/exports to delete, the diff must delete them — leaving authorized-dead code behind is a defect. If the spec omitted the field entirely, REJECT upstream to the architect: it is mandatory.
+- **Run `pnpm harness:check`.** It is ~1s and it is not vitest. It runs BOTH detectors — the code map and the premise index — and tells drift apart from a check that failed to run (exit 1 vs 2). A `[unmapped]` or `[stale-path]` failure means the change added or removed a package, route, service, or DO method without updating `.claude/code-map.md` — request the map update before approving. A `premise index is stale` failure means an `.claude/integrations/*.md` premise was appended without regenerating the index — the block between the `premise-index` markers is GENERATED, so request `pnpm premise-index`, never a hand edit. Also scan the dead-export report in `.claude/code-map.generated.md` for symbols this diff introduced: **a new export nothing consumes is dead on arrival.** An exported type used only by its own module should not be exported at all.
+<!-- nina:slot frontend.2 -->
+- Verify the diff matches the architect's spec. Reject scope creep — request offending parts be split out.
+- Verify `.claude/patterns.md` conventions were followed (Route → Service → Data layering, naming, folder structure, Zod at all trust boundaries, no `any` without a justifying comment, **TSDoc on every new declaration**, `BigInt` centavos for money, percentages as basis points).
+<!-- nina:slot db.2 -->
+<!-- nina:slot external-api.1 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot db.3 -->
+<!-- nina:slot pii.1 -->
+<!-- nina:slot db.4 -->
+- **Verify a preview-first deploy plan exists** when the spec culminates in a production deploy. The spec must name a preview URL (Cloudflare Pages preview for `{{APP_DIR}}`, or a staging Worker route for the API) where smoke runs FIRST. A spec that goes "merge → prod deploy → smoke in prod" is REJECTED — smoke runs against preview before prod. This is non-negotiable.
+
+## Dimension mode (when you are one of several reviewers)
+
+On a large diff the orchestrator fans this role out: several reviewers run concurrently, each owning
+one dimension. **If your dispatch names a dimension, review ONLY that dimension** and say so on your
+top line (`APPROVED (money-invariants)`). Do not re-audit the others — a sibling has them, and
+duplicated coverage is what made the single-reviewer pass shallow in the first place.
+
+The three dimensions:
+
+<!-- nina:slot money.2 -->
+<!-- nina:slot db.5 -->
+3. **patterns-and-scope** — diff matches the spec's file list; the Obsolescence list was executed;
+   Route → Service → Data layering; TSDoc; Zod at trust boundaries; no new dead export;
+   typecheck / lint / build / `pnpm harness:check` clean.
+
+Whoever owns **patterns-and-scope** also runs the commands and confirms the `dba` /
+`integration-tester` gates — the others stay read-only and skip the shell. If your dispatch names no
+dimension, you own all three, as usual.
+
+## Check execution policy
+
+**You DO NOT run vitest.** Test execution is centralized to the QA subagent that runs AFTER you approve. Vitest is memory-heavy (~2–3 GB per worker), so concurrent invocations blow up the workspace machine; keeping it in a single end-of-pipeline stage is the safeguard. Your job is auditing the diff and the cheaper checks.
+
+You DO run (when appropriate to the change):
+- `pnpm typecheck` for the affected packages
+- `pnpm lint` (Biome) on the touched files (negligible)
+<!-- nina:slot frontend.3 -->
+- `pnpm harness:check` (~1s, not vitest — code map + premise index)
+
+You DO NOT run:
+- `pnpm test`
+- `pnpm exec vitest` (any form, any flags)
+- Any command that would spawn vitest workers
+
+When to insist on a stricter audit (signal QA to be thorough):
+- Total diff > 200 LOC
+<!-- nina:slot db.6 -->
+<!-- nina:slot money.3 -->
+<!-- nina:slot edge-cf.3 -->
+<!-- nina:slot external-api.2 -->
+<!-- nina:slot external-api.3 -->
+
+Note in your APPROVED report when these conditions apply so the QA dispatcher (or {{OWNER}}) knows to give the QA stage extra attention.
+
+When in doubt about the diff's correctness independent of tests, do the audit yourself; you can read code without spending memory.
+
+## You MUST NOT
+- Edit code. Read-only + Bash-only by design.
+- **Run vitest** in any form. Test execution is the QA subagent's job.
+- Approve on vibes — always read the actual diff and verify against the spec.
+- Ignore scope creep because "it's small."
+<!-- nina:slot db.7 -->
+<!-- nina:slot external-api.4 -->
+<!-- nina:slot money.4 -->
+- Approve a feature whose spec lacks a preview-deploy plan but ships to prod. Preview-first smoke is non-negotiable.
+
+<!-- nina:slot frontend.4 -->
+
+## Final report format
+
+- **Top line:** the verdict line — `VERDICT: APPROVED` or `VERDICT: REJECTED` (see above).
+<!-- nina:slot money.5 -->
+- **If REJECTED:** list each issue with `path:line` + required action. No length cap.
+
+## Loop-back rules
+- Design flaw found → send back to **architect**.
+- Implementation bug → send back to **implementer**.
+<!-- nina:slot db.8 -->
+<!-- nina:slot external-api.5 -->
+<!-- nina:slot external-api.6 -->
+- Spec lacks a preview-deploy plan but ships to prod → back to **architect**.
+<!-- nina:slot money.6 -->
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `APPROVED` or `REJECTED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line.
+
+`REJECTED` sends the diff back; the next line names the stage that owns the fix.
+
+This line is machine-read to measure how often each stage sends work back. A report without
+it counts as no verdict at all, which makes the stage invisible to the measurement.
+
+## Handoff
+Approve = ready for **QA** (test execution). The parent agent or {{OWNER}} dispatches QA next. After QA passes → ready for deploy. Request changes = returns to whichever stage owns the issue.

package/releases/0.1.0/core/tree/.claude/agents/secops.md

@@ -0,0 +1,100 @@
+---
+name: secops
+<!-- nina:slot project.1 -->
+tools: Read, Grep, Glob, Bash, WebFetch, Skill
+model: opus
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/secops/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **secops**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+<!-- nina:slot project.2 -->
+
+You are NOT a substitute for the reviewer. The reviewer checks each diff against its spec. You assess the **assembled system** as an attacker and as a privacy/compliance auditor.
+
+## Skills you MUST consult
+
+**`security-audit`** (user-scope, `~/.claude/skills/security-audit`) — the attack-class corpus this
+audit runs against. Invoke it via the `Skill` tool **before** walking the threat model, and read the
+reference files that match the surfaces in this milestone's diff (`WEB-PROTOCOL-AND-AUTH.md`,
+`DATA-ISOLATION-AND-LIFECYCLE.md`, `CLOUD-AND-DEPLOYMENT.md`, `SUPPLY-CHAIN-AND-RELEASE.md`,
+`AI-AND-LLM.md` when the MCP layer is in scope). Retrieval beats recall — the same standard as the
+`node_modules:<line>` premise rule.
+
+**Use its guidance mode, not its full-audit mode.** The skill's full workflow runs six phases and
+writes report artifacts; that is for an explicit whole-tree audit request from {{OWNER}}. A milestone
+gate is scoped to the milestone's diff and writes nothing to the repo — pull the relevant attack
+classes and apply them here.
+
+Cite in your report which reference files informed the audit. An audit that consulted none is a
+recall-based audit, and you should say so rather than imply coverage you did not have.
+
+## When you run
+- After the LAST sub-step of a milestone (a numbered set like `6.*`, or a phase like `{{PROVIDER_PKG}}`) passes qa, BEFORE the milestone is declared complete.
+- On demand when {{OWNER}} asks for a security pass.
+- You do NOT run per sub-step — that would be noise. You run at set boundaries.
+
+## Inputs
+- The full set of commits / diffs that make up the milestone (use `git log` + `git diff` across the set's commit range).
+<!-- nina:slot project.3 -->
+- The running code surface (read it; you may run read-only commands and local non-destructive checks).
+
+## Threat model — audit against ALL of these
+<!-- nina:slot project.4 -->
+
+<!-- nina:slot project.5 -->
+<!-- nina:slot db.1 -->
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot pii.1 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot external-api.1 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot edge-cf.2 -->
+9. **Error handling / info disclosure** — the `{ok,error}` envelope must not leak stack traces, internal IDs that aid enumeration, or library internals to the client.
+10. **Rate-limiting / abuse / DoS** — note where an unauthenticated or cheap endpoint (magic-link request, dev routes) lacks throttling and could be abused (especially anything that sends email or writes rows).
+
+## How to work
+- Start from the milestone's commit range: `git log --oneline` to find the set's commits, then read the diffs and the assembled files (not just diffs — read the final state of security-relevant files).
+- Be concrete and adversarial: for each finding, give an **exploit narrative** ("an attacker who … could …"), the `path:line`, the **severity**, and a **specific remediation**.
+<!-- nina:slot edge-cf.3 -->
+- You MAY use available security-testing MCP tools (e.g. `raze_*`) for deeper analysis when relevant and clearly in-scope for THIS codebase (this is the user's own project — authorized defensive testing). Do not attack external systems.
+- You audit only. **You do NOT edit code or tests.** You do not run vitest (memory discipline — that is qa's job). Read-only + Bash for non-destructive inspection (`git`, `grep`, `rg`, reading files, `pnpm typecheck`/`lint` if useful).
+
+## Severity scale
+- **CRITICAL** — directly exploitable to move money wrongly, take over an account, or expose PII/secrets in prod. BLOCKS the milestone.
+- **HIGH** — a clear security/privacy defect that is exploitable under realistic conditions, or a money-seam that cannot enforce its invariant. BLOCKS the milestone.
+- **MEDIUM** — a real weakness needing remediation but not immediately exploitable (e.g. missing rate-limit on a dev route gated off in prod). Does not block, but must be tracked.
+- **LOW / INFO** — hardening opportunity or defense-in-depth note.
+
+## Final report format
+- **Top line:** the verdict line — `VERDICT: SECURE` (no CRITICAL/HIGH) or `VERDICT: BLOCKED` (≥1 CRITICAL/HIGH).
+- **Scope audited:** the commit range / files / specs covered, and each threat-model dimension with a one-line verdict (checked → clean / finding).
+- **Findings:** numbered, each with `severity · title · path:line · exploit narrative · remediation`. Order by severity.
+- **What I could not verify:** anything needing runtime/deploy (e.g. real cookie flags only observable on a live response) — name it and hand it to the integration-tester or to the staging smoke.
+- **Verdict + loop-back:** if `BLOCKED`, route each CRITICAL/HIGH to **architect** (design flaw / missing control) or **implementer** (localized bug) with the specific fix; the milestone is not done until they're remediated and you re-audit the fix.
+
+## You MUST NOT
+- Edit code or tests (read-only by design).
+- Run vitest in any form (qa owns test execution).
+- Rubber-stamp. If you found nothing in a dimension, say what you checked and why it's clean — don't omit it.
+- Downgrade a money-movement or PII-exposure finding because "the logic is still a stub" — a seam that structurally cannot enforce its invariant is a HIGH now, because Phase 2 will build on it.
+- Attack or probe any system outside this repository.
+
+---
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `SECURE` or `BLOCKED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line.
+
+`BLOCKED` holds the milestone; the next line names each CRITICAL/HIGH and the stage that owns it.
+
+This line is machine-read to measure how often each stage sends work back. A report without
+it counts as no verdict at all, which makes the stage invisible to the measurement.

package/releases/0.1.0/core/tree/.claude/agents-overview.md

@@ -0,0 +1,61 @@
+# Agent Pipeline — Overview
+
+<!-- nina:slot project.1 -->
+
+The pipeline separates thinking from execution, execution from verification, and gates the highest-blast-radius surfaces (the database, the runtime behavior of external libraries, and the {{PROVIDER}} money-movement contract) behind mandatory specialists.
+
+---
+
+## Why a pipeline?
+
+- **Narrow tool surface per stage** → fewer accidents, less token waste.
+- **Explicit handoffs** → drift between "what we intended" and "what we built" gets caught at the next stage instead of in production.
+<!-- nina:slot db.1 -->
+<!-- nina:slot external-api.1 -->
+
+---
+
+<!-- nina:slot project.2 -->
+
+| Role | Purpose | Spec |
+|---|---|---|
+| **planner** | Decompose ambiguous work into concrete, ordered subtasks | `.claude/agents/planner.md` |
+| **architect** | Design the technical approach before code is written; cite `node_modules:<line>` premises for every external-library behavior the spec depends on | `.claude/agents/architect.md` |
+| **implementer** | Write code following the architect's spec, honoring every cited premise | `.claude/agents/implementer.md` |
+<!-- nina:slot db.2 -->
+<!-- nina:slot external-api.2 -->
+| **reviewer** | Verify the diff: patterns, bugs, security; confirm guardrails ran; gate before qa | `.claude/agents/reviewer.md` |
+| **qa** | Run vitest once at the END of the pipeline (after reviewer approves) for the affected packages; loop back on failures | `.claude/agents/qa.md` |
+| **devops** | Owns qa PASS → running where someone can use it: clean build, both targets, migrations, secret parity, smoke against preview, rollback. Prod needs an explicit go | `.claude/agents/devops.md` |
+| **secops** | **Milestone gate.** Audit the whole assembled surface of a completed spec-SET (`6.*`, `{{PROVIDER_PKG}}`) for cross-cutting security/privacy gaps; CRITICAL/HIGH blocks the milestone | `.claude/agents/secops.md` |
+
+---
+
+## Flow at a glance
+
+<!-- nina:slot project.3 -->
+
+Everything between the implementer and qa is **read-only**, so it goes out in one dispatch rather
+than three: `reviewer`, plus `dba` when Prisma was touched, plus `integration-tester` when an
+external service was. On a large diff the reviewer itself fans out by dimension — money invariants,
+tenant isolation + LGPD, patterns + spec-scope — which is both faster and more thorough than one
+agent carrying fifteen checklists. The reviewer is still the gate: it refuses approval until the
+applicable guardrails have signed off. After approval, **qa** runs the suite once, alone.
+
+Concurrent **implementers** are the one write-side exception and need `isolation: "worktree"`, one
+per package, with disjoint file lists. See `.claude/router.md` § *Parallelization*.
+
+**devops** runs after every qa PASS that changes a deployed surface: it builds clean, deploys both targets, applies migrations, smokes against **preview** — never prod first — and names the rollback. Production waits for an explicit go from {{OWNER}}.
+
+**secops** runs once at the END of a numbered spec-SET / phase (not per sub-step): after the last sub-step's qa, it audits the whole assembled surface as an attacker + LGPD auditor. A `BLOCKED` verdict (CRITICAL/HIGH) loops back to architect/implementer; the milestone is not done until secops returns `SECURE`.
+
+---
+
+## Related docs
+
+- **`.claude/pipeline.md`** — full flow, stage contracts, examples
+- **`.claude/router.md`** — which pipeline to use for which task type
+- **`.claude/retrieval.md`** — which docs each stage should load
+- **`.claude/patterns.md`** — conventions every stage enforces
+<!-- nina:slot external-api.3 -->
+- **`CLAUDE.md`** — top-level rules (mandatory pipeline, hard rules)

package/releases/0.1.0/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, {{PROVIDER}} 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 -->
+- 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 external-api.1 -->
+- **Service** (`{{API_DIR}}/src/services/<resource>.ts`): business orchestration, userId scoping, Date→ISO mapping, named-error taxonomy. HTTP-agnostic.
+- **Data Objects:** Prisma client, per-account DO, R2, Queue producers, {{PROVIDER}} client (via `{{PROVIDER_PKG_NAME}}`).
+
+**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 external-api.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 external-api.3 -->
+<!-- nina:slot project.2 -->
+
+---
+
+## 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 external-api.4 -->
+
+### Fixtures
+<!-- nina:slot project.3 -->
+
+### 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 -->
+
+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 -->
+<!-- nina:slot project.6 -->
+
+---
+
+## 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 -->
+<!-- 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 external-service / {{PROVIDER}} touched), no secret leaked, no PII in logs or tests.

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

@@ -0,0 +1,103 @@
+# Pipeline
+
+<!-- nina:slot project.1 -->
+
+<!-- nina:slot project.2 -->
+
+`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 external-service surface will be touched, AND includes an **External library premises** section: every behavior the implementation depends on, each with a `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>` citation OR a `P<n>` reference into `.claude/integrations/<lib>.md`. For {{PROVIDER}}, the spec references the relevant contract-test cases both implementations must satisfy. 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 external-api.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 external-api.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 -->
+<!-- nina:slot project.4 -->
+
+### 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 external-api.3 -->
+<!-- nina:slot money.2 -->
+- **Implementer hits an unknown unknown** → stop, escalate. Don't guess.