@xhulz/nina 0.28.16

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

@@ -0,0 +1,144 @@
+<!-- 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`
+- Pipeline graph — stages, edges, loop caps → `.claude/graph.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.
+
+**A generated line you cannot fix here is a change made upstream.** The harness lives in its own
+repository; this project composes a *frozen* version of it, pinned as `core` in `.nina/profile.json`.
+So a wrong composed line has one of two addresses, and saying which is part of reporting it. **This
+project's own fact** — a path, a provider, a duration, a package name — belongs in a fragment under
+`.nina/project/tree/`, and you can fix it now. **The harness's rule** — what a role must do, what a
+stage hands off, what a report must contain — cannot be changed from this project at all: report it as
+a request against the pinned version, quoting the composed file and line, and it arrives back through
+`nina upgrade`. A correction that names no layer is not actionable by anyone, however right it is.
+
+## ⚠️ 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 the `reviewer` and every gate the diff triggers 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 — the gates in `.claude/graph.md` 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 -->
+<!-- nina:slot blockchain.2 -->
+| **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. 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.
+
+<!-- nina:slot project.8 slow-suites -->
+
+### 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 -->
+<!-- nina:slot blockchain.3 -->
+- **reviewer** → verify diff matches spec, run typecheck/lint/build (NOT vitest), confirm every gate the diff triggered ran, 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*.
+<!-- nina:slot blockchain.1 -->
+17. **Every artifact you are handed is a hypothesis; the tree is the truth.** A file list, a line range, a test filter, a cited premise — each was derived by an earlier stage from a tree that may have moved since, so **the part you are about to rely on** is checked against the tree before you act on it. Where it diverges, **report the divergence, naming the stage that produced it**: a stage that quietly works around a wrong input hides the defect from the only stage that can fix it, and the next task inherits it intact. Acting on what the tree says **never widens what you were authorized to touch** — a wrong range inside a file you own is corrected and reported; a divergence that would take you outside your authorized files stops the work and goes back to the stage that drew the boundary. This is not diligence for its own sake. On one milestone three consecutive stages each found the artifact above them wrong — a test filter that covered two of six blocks gated on a live credential, a line range that missed a second block of orphaned mocks, a spec that named the wrong test as the one blocking a removal — and every one of the three found it only by going to look.
+
+## 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.22.0/core/tree/scripts/harness-check.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Runs this project's harness drift detectors.
+ *
+ * The mechanism lives in the NINA package — what counts as drift, what counts as a check
+ * that could not run, and how either reaches a Claude Code hook. Only the LIST is here,
+ * because only this project knows which detectors it has and what to do when one fires.
+ *
+ * Usage:
+ *   node scripts/harness-check.mjs            human-readable; exit 1 on drift, 2 on error
+ *   node scripts/harness-check.mjs --hook     JSON for a Stop hook — shown to the person; always exit 0
+ *   node scripts/harness-check.mjs --context  JSON for a UserPromptSubmit hook — read by the model
+ *                                             before it answers; always exit 0
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runDetectors } from '@xhulz/nina/detectors';
+
+const ROOT = resolve(dirname(dirname(fileURLToPath(import.meta.url))));
+
+process.exit(
+  runDetectors(
+    [
+      // Every composed project has this one, so the core carries it rather than asking each
+      // project to write the same nine lines. It disables itself where the project does not
+      // declare the npm script, like any other detector.
+      {
+        name: 'agent specs',
+        declaredBy: 'harness:compose:check',
+        bin: 'nina',
+        args: ['compose', '--check', '--drift', '--quiet'],
+        hint: 'these files are generated — run `nina where <file>` to see which layer owns it, then `nina compose`',
+        ignore: /^compose: current$/,
+      },
+      // What the project has not declared yet: vocabulary, its own layer, the documents the layers
+      // read, the wiring. On a new project this is the whole to-do list, and it reaches the model
+      // before its first answer — so the first conversation starts by filling it, unasked.
+      {
+        name: 'declaration',
+        bin: 'nina',
+        args: ['check', '--detector', '--quiet'],
+        hint: 'each line says what is missing — `.nina/TODO.md` lists the project’s own items, and `.nina/BRIEF.md`, where the interview wrote one, says what the project is; fill them, then `nina compose`',
+        ignore: /^check: declaration is sound/,
+      },
+      // The one link of the learning cycle that fails in silence: a role keeps being sent back
+      // and nothing is written down. It fires on the event — three loop-backs since that role's
+      // newest lesson — not on a rate, so it says something new when it speaks. A lesson learned
+      // a third time it sends to the harness itself, and says so once.
+      {
+        name: 'lessons',
+        bin: 'nina',
+        args: ['learn', '--check', '--quiet'],
+        hint: 'each line above says what it needs — `nina learn` shows the whole cycle',
+        ignore: /^learn: current$/,
+      },
+      // The loop gate holds the caps in .claude/graph.md from this project's hooks, and it lets every
+      // call through when it fails — so a gate that stopped working looks exactly like a pipeline with
+      // no loops. This asks it, every turn, whether it is wired and would still hold one.
+      {
+        name: 'loop gate',
+        bin: 'nina',
+        args: ['gate', '--selftest', '--quiet'],
+        hint: 'the caps in .claude/graph.md are not being held — `nina wire --apply` wires the gate; `nina gate --selftest` says what else is wrong',
+        ignore: /^gate: current$/,
+      },
+<!-- nina:slot project.1 detectors -->
+    ],
+    { root: ROOT, hook: process.argv.includes('--hook'), context: process.argv.includes('--context') },
+  ),
+);

package/releases/0.22.0/core/tree/scripts/loop-gate.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * The loop gate, run by this project's Claude Code hooks.
+ *
+ * `.claude/graph.md` caps every loop-back edge. This holds the cap: it records the verdict each stage
+ * reports, each dispatch that goes out and each time the owner speaks, and sends the dispatch that would
+ * make a round past its edge's cap to the owner to confirm — the graph's `human`. The owner's next
+ * message starts every count over. It keeps metadata only, under ~/.nina/gate/.
+ *
+ * The mechanism lives in the NINA package; this file only says which project it guards. It prints
+ * nothing unless it has a decision to report, and it lets every call through if anything goes wrong —
+ * `nina gate --selftest`, run by `pnpm harness:check`, is what says so.
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runGate } from '@xhulz/nina/gate';
+
+process.exitCode = await runGate({ root: resolve(dirname(dirname(fileURLToPath(import.meta.url)))) });

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents/architect.md

@@ -0,0 +1,5 @@
+<!-- nina:slot blockchain.1 -->
+| a contract, a proxy, or a contracts library component | **`develop-secure-contracts`** · **`upgrade-solidity-contracts`** when storage moves |
+
+<!-- nina:slot blockchain.2 -->
+11c. **Contract surface (MANDATORY when the spec reaches `{{CONTRACTS_DIR}}`).** Name which contracts are touched and whether each is deployed; for a deployed one, say whether this is an upgrade and what preserves the storage layout. State the access-control model in roles, not in adjectives: who may call each state-changing function, and how that role is granted and revoked. List the adversarial tests the implementation owes — re-entry, the unauthorized caller, the boundary amount, the second call that must fail. A spec that reaches a contract and leaves any of these to the implementer is rejected.

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents/devops.md

@@ -0,0 +1,5 @@
+<!-- nina:slot blockchain.1 -->
+- **`upgrade-solidity-contracts`** — before deploying a contract or executing a proxy upgrade, to check the storage layout against what is live.
+
+<!-- nina:slot blockchain.2 -->
+7b. **A contract deploy needs `solidity-auditor` `APPROVED` for this exact diff**, and its rollback named before it runs — which for a non-upgradeable contract is a redeploy plus a migration of state, not a revert. Say so *before* deploying. A deploy to a network carrying real value needs an explicit go from {{OWNER}} for that change, the same as production.

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents/reviewer.md

@@ -0,0 +1,5 @@
+<!-- nina:slot blockchain.1 -->
+- **The solidity-auditor gate ran and returned `APPROVED`** for any diff touching `{{CONTRACTS_DIR}}`, a deploy script, or a contracts library version. Its absence is a blocking finding on its own, whatever the diff looks like to you.
+
+<!-- nina:slot blockchain.2 -->
+- A contract change written by the implementer rather than **solidity-dev** is rejected on routing alone. The two roles carry different rules about what a defect costs, and the cheaper set is the wrong one here.

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,18 @@
+<!-- nina:slot blockchain.1 -->
+| **`develop-secure-contracts`** | any library component in the diff — to check the usage against the library's own guidance, not against memory |
+
+<!-- nina:slot blockchain.2 -->
+| **`upgrade-solidity-contracts`** | a proxy, an initializer, or a storage layout change |
+
+<!-- nina:slot blockchain.3 -->
+| **`security-audit`** | the off-chain half — deploy scripts, key handling, CI, RPC endpoints (guidance mode) |
+
+<!-- nina:slot blockchain.4 -->
+- The deployed addresses and role holders in play, where the change targets a live system.
+
+<!-- nina:slot blockchain.5 -->
+- **An event for every state change**, and that what it emits matches what was written. Off-chain
+  reconstruction is the only history there is, and a wrong event is worse than a missing one.
+
+<!-- nina:slot blockchain.6 -->
+- Approve a change to a live contract without stating the upgrade path and naming who can execute it.

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents/solidity-dev.md

@@ -0,0 +1,16 @@
+<!-- nina:slot blockchain.1 -->
+| **`setup-solidity-contracts`** | a new contract project, a dependency install, or import/remapping configuration |
+
+<!-- nina:slot blockchain.2 -->
+| **`develop-secure-contracts`** | any library component — token standards, access control, pausing, reentrancy protection |
+
+<!-- nina:slot blockchain.3 -->
+| **`upgrade-solidity-contracts`** | a proxy, an initializer, or anything that moves storage |
+
+<!-- nina:slot blockchain.4 -->
+- The contract's deployed state, where one exists. A change to a live contract is an upgrade with a
+  storage layout to preserve, not an edit.
+
+<!-- nina:slot blockchain.5 -->
+- Widen a function's visibility, or add an address to a role, to make a test pass. The test is
+  describing the access control; fix the test or reject the spec.

package/releases/0.22.0/surfaces/blockchain/tree/.claude/agents-overview.md

@@ -0,0 +1,6 @@
+<!-- nina:slot blockchain.1 -->
+- **Contract guardrail** → deployed code is immutable and permanently callable by anyone, so a defect is not a patch away and "nothing calls this" is not a property of it. Reentrancy, a state-changing function with no access control, a storage layout broken by an upgrade, and an audited component used against its own guidance are caught here.
+
+<!-- nina:slot blockchain.2 -->
+| **solidity-dev** | Write contract sources and their adversarial tests to spec; never deploys | `.claude/agents/solidity-dev.md` |
+| **solidity-auditor** | Mandatory gate on any contract diff; blocks reviewer and devops | `.claude/agents/solidity-auditor.md` |

package/releases/0.22.0/surfaces/blockchain/tree/.claude/graph.md

@@ -0,0 +1,11 @@
+<!-- nina:slot blockchain.1 -->
+- `solidity-dev` — writes contract code, which cannot be changed once it is live
+- `solidity-auditor` — gate: audits contract code as an attacker before anything deploys
+
+<!-- nina:slot blockchain.2 -->
+- `architect` → `solidity-dev` on `SPEC-READY` — the spec changes contract code
+- `solidity-dev` → `solidity-auditor` on `DIFF-READY`
+- `solidity-dev` → `architect` on `BLOCKED` — the change cannot be made safely as specified · max 2
+- `solidity-auditor` → `reviewer` on `APPROVED`
+- `solidity-auditor` → `solidity-dev` on `REJECTED` — a flaw in the contract code · max 2
+- `solidity-auditor` → `architect` on `REJECTED` — a flaw in the design · max 2

package/releases/0.22.0/surfaces/blockchain/tree/.claude/router.md

@@ -0,0 +1,9 @@
+<!-- nina:slot blockchain.1 -->
+
+### 1c. Solidity-auditor is a guardrail for contract changes
+Invoke **solidity-auditor** on any diff that touches `{{CONTRACTS_DIR}}`, a deploy script, or the version of a contracts library — regardless of where you are in the pipeline. No contract change merges without its approval, and none deploys without it. Reviewer verifies it ran; devops verifies it approved.
+
+Contract sources are written by **solidity-dev**, not the implementer. Route the work there when the spec's file list reaches `{{CONTRACTS_DIR}}`, and keep the implementer on the off-chain side of the same feature.
+
+<!-- nina:slot blockchain.2 -->
+| a contract source, a proxy, or a contracts library component | **`develop-secure-contracts`**, plus **`upgrade-solidity-contracts`** when storage moves |

package/releases/0.22.0/surfaces/blockchain/tree/CLAUDE.md

@@ -0,0 +1,9 @@
+<!-- nina:slot blockchain.1 -->
+16. **Every contract change goes through the solidity-auditor gate, and deployed code is never patched in place.** A diff touching a contract source, a deploy script, or the version of a contracts library does not reach the reviewer without `VERDICT: APPROVED` from **solidity-auditor**, and does not reach any network without it. Contract sources are written by **solidity-dev**, not by the implementer — the implementer's rules assume a defect is a patch away, and here it is a redeploy or a proxy upgrade at best. Private keys, mnemonics and funded accounts never enter the repository in any form, test fixtures included.
+
+<!-- nina:slot blockchain.2 -->
+| **ANY step touching a contract, a deploy script, or a contracts library version** | **architect → solidity-dev → solidity-auditor → reviewer → qa** — the auditor is mandatory and blocks the reviewer |
+
+<!-- nina:slot blockchain.3 -->
+- **solidity-dev** → write contract sources and their adversarial tests strictly to spec; never deploys, never widens access control to make a test pass
+- **solidity-auditor** → **mandatory gate** on any contract diff; `APPROVED` required before reviewer and before any deploy

package/releases/0.22.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.22.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.22.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.22.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.

package/releases/0.22.0/surfaces/db/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+| `prisma-cli` | a Prisma CLI command |
+
+<!-- nina:slot db.2 -->
+- Any new Prisma query against an Accelerate-cached read path — verify cache hit/`cacheStrategy` behavior live (dba covers schema; you cover runtime cache behavior)
+
+<!-- nina:slot db.3 -->
+If you find a Prisma issue mid-run (a query behaves differently against a real DB than the dba's static analysis suggested) — escalate to **dba**, do not fix yourself.
+
+<!-- nina:slot db.4 -->
+- **{{AUTH_LIB}}'s backing store is a real Postgres** — the dev DB Accelerate branch, the same
+  `DATABASE_URL` the implementer uses in `{{SECRETS_LOCAL}}`. A suite that is green against an
+  in-memory stand-in has not exercised the library, which is the whole point of this stage.

package/releases/0.22.0/surfaces/db/tree/.claude/agents/planner.md

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+4. **Prisma flag** — if any subtask may touch `schema.prisma` or create a new Prisma query, mark **"DBA REQUIRED"** on that subtask.

package/releases/0.22.0/surfaces/db/tree/.claude/agents/reviewer.md

@@ -0,0 +1,25 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+- **If Prisma was touched anywhere in the diff: confirm `dba` ran and approved. If not → dispatch `dba` now, or request changes. No approval without dba sign-off on Prisma changes.**
+
+<!-- nina:slot db.3 -->
+- Check for **single-user tenant scoping** in every new Prisma query in app code: the `where` clause must include `userId` (or its model-specific FK equivalent). No "global" queries except the {{AUTH_LIB}} system tables. Missing scope = request changes.
+
+<!-- nina:slot db.4 -->
+- Check for N+1 queries when the DB layer was touched.
+
+<!-- nina:slot db.5 -->
+- **tenant-and-privacy** — `userId` in every app query ({{AUTH_LIB}} tables are the only exemption);
+  no PII or secrets in logs; no cross-tenant read
+  or write reachable through a route, an MCP tool, a webhook, or a DO call.
+
+<!-- nina:slot db.6 -->
+- `{{DB_PKG}}/prisma/schema.prisma` touched (Prisma migration in play)
+
+<!-- nina:slot db.7 -->
+- Skip the dba check on Prisma changes "because it seems fine."
+
+<!-- nina:slot db.8 -->
+- Prisma touched but dba missed → dispatch **dba** now.

package/releases/0.22.0/surfaces/db/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+- **AuthZ / tenant isolation (Hard Rule #7)** — single-user tenancy: EVERY app-code Prisma query must scope by `userId` (or its FK). Hunt for any query, route, MCP tool, or DO/queue/webhook path where another user's data could be read or mutated (IDOR). The {{AUTH_LIB}} system tables are the only allowed unscoped reads — verify nothing else is.

package/releases/0.22.0/surfaces/db/tree/.claude/agents-overview.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+- **DBA guardrail** → Prisma / Postgres is the surface where a bad change causes hard-to-reverse damage. Schema mistakes, missing indexes, cache on reads that feed a correctness-critical write, missing `userId` scope — all caught here.
+
+<!-- nina:slot db.2 -->
+| **dba** | Mandatory gate on Prisma changes and new queries | `.claude/agents/dba.md` |

package/releases/0.22.0/surfaces/db/tree/.claude/graph.md

@@ -0,0 +1,8 @@
+<!-- nina:slot db.1 -->
+- `dba` — gate: runs when the schema, a migration or a query is touched
+
+<!-- nina:slot db.2 -->
+- `implementer` → `dba` on `DIFF-READY` — the diff touches the schema, a migration or a query
+- `dba` → `reviewer` on `APPROVED`
+- `dba` → `implementer` on `REJECTED` — a query or schema change in the diff is unsafe · max 2
+- `dba` → `architect` on `REJECTED` — the spec's migration or data design is unsafe · max 2

package/releases/0.22.0/surfaces/db/tree/.claude/patterns.md

@@ -0,0 +1,30 @@
+<!-- nina:slot db.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot db.2 -->
+1. Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}`. Only `createDbClient` and error classes.
+
+<!-- nina:slot db.3 -->
+4. `cacheStrategy` lives in `{{DB_PKG}}`. Services do not add, strip, or override cache policies.
+
+<!-- nina:slot db.4 -->
+5. **Every service query includes `userId` (tenant scope) in the `where` clause.** Missing scope = automatic CHANGES REQUESTED.
+
+<!-- nina:slot db.5 -->
+
+---
+
+## Prisma conventions (enforced by dba subagent)
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- **Every `findUnique` / `findMany` on a hot path defines `cacheStrategy`.** No implicit cache.
+- **NEVER cache a read that feeds a write whose correctness depends on it being fresh.** A stale row contaminates the decision made from it. Hard reject in dba review.
+- **Every query in app code includes `userId` in the `where` clause** (or its model-specific equivalent FK). Tenant isolation is in the data layer. The {{AUTH_LIB}} system tables are the only exemption.
+- Migrations reviewed by **dba** for: non-blocking on large tables, index coverage for new query patterns, backward compatibility during rolling deploy.
+- N+1 queries are a bug. Use `include` / `select` deliberately.
+- Monetary columns are `BigInt`. Reject `Decimal` / `Float` / `Int` for money.
+- `Prisma Postgres` is connected only via Accelerate. Local dev uses the same Accelerate URL pointed at a dev DB; never embed a direct connection string in code.
+
+<!-- nina:slot db.6 -->
+- Real Prisma (Accelerate against a test DB). Never mock Prisma.

package/releases/0.22.0/surfaces/db/tree/.claude/pipeline.md

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+
+### 4. DBA (mandatory for Prisma)
+
+- **Trigger:** any change in `schema.prisma`, any new Prisma query, any migration.
+- **Input:** Prisma diff + application code using the queries.
+- **Output:** approve or reject with specific issues.
+- **Tools:** Read, Grep, Glob, Bash (`prisma validate`, `prisma migrate diff`, query plan checks).
+- **Checks:** schema validates; migration safe on large tables; index coverage; explicit `cacheStrategy` on hot reads; **no cache on a read that feeds a correctness-critical write**; **`userId` scope in every query**; no N+1; money columns are `BigInt`; no raw PII without encryption; secrets via Wrangler.
+- **Position:** dispatched mid-pipeline by whoever detects Prisma. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+  - **If Prisma touched → dba approved.**

package/releases/0.22.0/surfaces/db/tree/.claude/retrieval.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+| Prisma schema change | `.claude/architecture.md` § *Database*, `{{DB_PKG}}/prisma/schema.prisma` | **dba** (mandatory) → reviewer → qa |
+
+<!-- nina:slot db.2 -->
+| New Prisma query in app code | `.claude/patterns.md` § *Prisma conventions* | **dba** (mandatory) → reviewer → qa |

package/releases/0.22.0/surfaces/db/tree/.claude/router.md

@@ -0,0 +1,10 @@
+<!-- nina:slot db.1 -->
+
+### 1. DBA is a guardrail, not a stage
+Invoke **dba** any time Prisma is touched — regardless of where you are in the pipeline. No Prisma change merges without dba approval. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+| any `prisma` CLI command | **`prisma-cli`** |
+
+<!-- nina:slot db.3 -->
+| a new or changed Prisma query | **`prisma-client-api`** (a caching or edge layer on top of the client is not covered — its own integration doc owns that) |

package/releases/0.22.0/surfaces/db/tree/CLAUDE.md

@@ -0,0 +1,20 @@
+<!-- nina:slot db.1 -->
+| Run any `prisma` CLI command (dba, devops, and the integration gate where there is one) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot db.2 -->
+| Write or audit a Prisma query (architect, implementer, dba, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |
+
+<!-- nina:slot db.3 -->
+| **ANY Prisma change (`*.prisma` or new query)** | **+ dba before reviewer** |
+
+<!-- nina:slot db.4 -->
+- **dba** → mandatory gate on Prisma schema changes, migrations, and new queries
+
+<!-- nina:slot db.5 -->
+2. **Every Prisma change goes through the dba subagent.** No exceptions. Reviewer must verify dba ran before approving.
+
+<!-- nina:slot db.6 -->
+6. **Every hot Prisma read defines a `cacheStrategy`** (Accelerate `ttl` / `swr`). Implicit cache is a bug. **Never cache a read that feeds a write whose correctness depends on it being fresh** — a stale row contaminates every decision made from it. User-scoped invalidation on every write.
+
+<!-- nina:slot db.7 -->
+7. **Tenant isolation is enforced in the data layer.** Every Prisma query in app code includes `userId` (the tenant) in the `where` clause. No "global" queries except the {{AUTH_LIB}} system tables. Reviewer rejects any query missing the scope.