@xhulz/nina 0.28.16

package/releases/0.23.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.23.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.23.0/core/vocabulary.json

@@ -0,0 +1,6 @@
+{
+  "BUILD_CMD": "pnpm build",
+  "LINT_CMD": "pnpm lint",
+  "TEST_CMD": "pnpm test",
+  "TYPECHECK_CMD": "pnpm typecheck"
+}

package/releases/0.23.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 -->
+- **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.23.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 -->
+- **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.23.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.23.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.23.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.23.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.23.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.23.0/surfaces/blockchain/tree/.claude/router.md

@@ -0,0 +1,9 @@
+<!-- nina:slot blockchain.1 -->
+
+### 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.23.0/surfaces/blockchain/tree/CLAUDE.md

@@ -0,0 +1,12 @@
+<!-- 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
+
+<!-- nina:slot blockchain.4 -->
+- **contract code**: a contract source, a deploy script, or the version of a contracts library

package/releases/0.23.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 -->
+- **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 -->
+- **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.23.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 -->
+- **Schema validates.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`. Must pass.
+
+<!-- nina:slot db.7 -->
+- **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 -->
+- **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 -->
+- **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 -->
+- **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 -->
+- **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 -->
+- **N+1 patterns.** If the code fetches a list then queries per item, reject with "use `include` / `select` or batch."
+
+<!-- nina:slot db.13 -->
+- **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 the *Migration diff* check — 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 the *Migration diff* check.
+
+<!-- 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, Privacy check, Final verdict. If rejected, list each issue with required action — no length cap.

package/releases/0.23.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 -->
+- **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.23.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.23.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.23.0/surfaces/db/tree/.claude/agents/planner.md

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

package/releases/0.23.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 an RPC between services.
+
+<!-- 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.23.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.23.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.23.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.23.0/surfaces/db/tree/.claude/patterns.md

@@ -0,0 +1,29 @@
+<!-- nina:slot db.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot db.2 -->
+- Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}`. Only `createDbClient` and error classes.
+
+<!-- nina:slot db.3 -->
+- `cacheStrategy` lives in `{{DB_PKG}}`. Services do not add, strip, or override cache policies.
+
+<!-- nina:slot db.4 -->
+- **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.
+- `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.23.0/surfaces/db/tree/.claude/pipeline.md

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+
+### 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; no raw PII without encryption; the connection secret comes from the environment, never from code.
+- **Position:** dispatched mid-pipeline by whoever detects Prisma. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+  - **If Prisma touched → dba approved.**

package/releases/0.23.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.23.0/surfaces/db/tree/.claude/router.md

@@ -0,0 +1,10 @@
+<!-- nina:slot db.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.23.0/surfaces/db/tree/CLAUDE.md

@@ -0,0 +1,23 @@
+<!-- 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.
+
+<!-- nina:slot db.8 -->
+- **the database**: the schema, a migration, or a query

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/architect.md

@@ -0,0 +1,14 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | `{{API_DIR}}/**` — routes, services, middleware, queue handlers |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | `{{API_DIR}}/src/do/**` or any DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:cloudflare` | Queues, R2 or KV |
+
+<!-- nina:slot edge-cf.4 -->
+| `cloudflare:wrangler` | `wrangler.toml` or any wrangler command |
+
+<!-- nina:slot edge-cf.5 -->
+- **Cloudflare skill flag** — if the spec touches `{{API_DIR}}/**` (Hono routes/services/queue handlers), the per-account Durable Object, Queues, R2/KV, or `wrangler` config, name which `cloudflare:*` plugin skill the implementer must consult (`cloudflare:workers-best-practices`, `cloudflare:durable-objects`, `cloudflare:cloudflare`, `cloudflare:wrangler`), or state why none applies. Retrieval beats recall — the reviewer rejects a spec that touches these surfaces without naming the skill.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot edge-cf.1 -->
+- **Edge runtime compatibility.** New code paths use `@prisma/client/edge`. `compatibility_flags = ["nodejs_compat"]` is set in `wrangler.toml`.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/devops.md

@@ -0,0 +1,31 @@
+<!-- nina:slot edge-cf.1 -->
+- **`cloudflare:wrangler`** — before running ANY `wrangler` command or reading `wrangler.toml`.
+  CLI flags and config fields churn between minor versions; pre-trained knowledge is stale.
+
+<!-- nina:slot edge-cf.2 -->
+- **`cloudflare:cloudflare`** — when the deploy touches R2, KV, Queues or Durable Object bindings.
+
+<!-- nina:slot edge-cf.3 -->
+- **Both targets, or neither.** A change to the API surface needs the **staging Worker** (`wrangler deploy --env staging`) *and* **Pages** (`pnpm --filter {{PKG_SCOPE}}/app deploy`). Deploying the frontend alone against an old API is the failure that renders new fields as "—". State explicitly which targets this change requires and why.
+
+<!-- nina:slot edge-cf.4 -->
+- **Secret and variable parity.** Everything the new code reads via `env.*` exists in the target environment (`wrangler secret list`). A missing secret fails at request time, not at deploy time.
+
+<!-- nina:slot edge-cf.5 -->
+
+## Pages: which branch, and why it matters
+
+`{{PAGES_PROJECT}}` is a **direct-upload** Pages project whose production branch is `main`. `wrangler pages
+deploy` decides production vs preview purely from `--branch`:
+
+- **Staging FE** → `--branch staging`. A preview deployment on its own URL. Production is untouched,
+  and this is the FE half of the staging pair with `{{API_STAGING}}`.
+- **Production FE** → `--branch main`. Only with an explicit go from {{OWNER}}, per the rule above.
+
+Deploying staging with `--branch=main` is a production deploy wearing a staging label — the
+permission classifier is right to stop it. Use the staging branch and the block disappears, because
+the block was correct.
+
+**`VITE_*` must be in the environment of the build command.** `[vars]` and `[env.*.vars]` in
+`{{APP_DIR}}/wrangler.toml` do NOT reach a Vite build — Vite inlines at build time, Pages vars apply at
+runtime to a project that has no server. A missing one ships a blank page with no error.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/implementer.md

@@ -0,0 +1,14 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | anything under `{{API_DIR}}/**` |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | anything under `{{API_DIR}}/src/do/**` or a DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:cloudflare` | a queue consumer, or R2 / KV access |
+
+<!-- nina:slot edge-cf.4 -->
+| `cloudflare:wrangler` | a change to `wrangler.toml` |
+
+<!-- nina:slot edge-cf.5 -->
+- Respect Workers conventions: secrets in `{{SECRETS_LOCAL}}` for local dev (never commit), `compatibility_flags = ["nodejs_compat"]` in `wrangler.toml`.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,11 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:durable-objects` | DO lifecycle, alarms, RPC, storage — the API surface drifts fast |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:cloudflare` | Queues, R2 or KV bindings |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:wrangler` | anything you run through the wrangler CLI |
+
+<!-- nina:slot edge-cf.4 -->
+- Any new Cloudflare binding read/write: R2, KV, Queues, Durable Objects — drive the binding via Miniflare and observe real I/O

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/qa.md

@@ -0,0 +1,3 @@
+<!-- nina:slot edge-cf.1 -->
+Here `$STRAY` is `vitest|workerd`: a Worker test boots a second runtime process alongside vitest,
+and it is the one that holds ~2 GB and survives a killed test run.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | `{{API_DIR}}/**` |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | `{{API_DIR}}/src/do/**` or a DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+- `{{API_DIR}}/src/do/`, a queue consumer, or a webhook receiver touched (serialization + idempotency surface)

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/agents/secops.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+- **Secrets & config exposure** — no secrets in committed files, logs, error messages, or generated artifacts (`worker-configuration.d.ts` must contain only types, never values). `{{SECRETS_LOCAL}}`/`.env` gitignored. `wrangler secret`/`[vars]` split correct. No secret echoed in a response or thrown error.
+
+<!-- nina:slot edge-cf.2 -->
+- **Dependency & binding posture** — obviously risky dependency usage; Cloudflare binding scoping (R2 bucket names, Queue, DO) — nothing over-privileged or world-exposed; `nodejs_compat` and compatibility flags sane.
+
+<!-- nina:slot edge-cf.3 -->
+- Prefer retrieval over recall for Cloudflare/{{AUTH_LIB}} specifics: consult the `cloudflare:*` skills and the installed `node_modules` source / `.claude/integrations/*.md` rather than assuming.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/patterns.md

@@ -0,0 +1,17 @@
+<!-- nina:slot edge-cf.1 -->
+
+---
+
+## Secrets
+
+- **Wrangler secrets** for Workers (`{{SECRETS_PROD}} X`). Never `.env` committed.
+- **Local dev:** `{{SECRETS_LOCAL}}` (gitignored).
+
+<!-- nina:slot edge-cf.2 -->
+- `compatibility_flags = ["nodejs_compat"]` in `wrangler.toml` is required for `@prisma/client/edge`.
+
+<!-- nina:slot edge-cf.3 -->
+- **Miniflare** for Worker integration tests.
+
+<!-- nina:slot edge-cf.4 -->
+- **Miniflare** for Worker tests — the real Cloudflare runtime, no mocks.

package/releases/0.23.0/surfaces/edge-cf/tree/.claude/retrieval.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+| New Durable Object behavior | `.claude/architecture.md` § *Durable Objects*, existing `{{API_DIR}}/src/do/` | architect → implementer → the integration gate, where there is one → reviewer → qa |
+
+<!-- nina:slot edge-cf.2 -->
+| New Queue handler | `.claude/architecture.md` § *Processing pipeline*, `{{API_DIR}}/src/queues/` | architect → implementer → the integration gate, where there is one → reviewer → qa |
+
+<!-- nina:slot edge-cf.3 -->
+| Wrangler / deploy / config | `CLAUDE.md` § *Common commands*, `{{API_DIR}}/wrangler.toml`, `.claude/patterns.md` § *Secrets* | reviewer (sanity check) |