@xhulz/nina 0.44.0 → 0.45.0

package/releases/0.45.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.45.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.45.0/core/vocabulary.json

@@ -0,0 +1,13 @@
+{
+  "ARCHITECT_EFFORT": "xhigh",
+  "BUILD_CMD": "pnpm build",
+  "DEEP_EFFORT": "high",
+  "DEEP_MODEL": "claude-opus-5-5",
+  "LINT_CMD": "pnpm lint",
+  "RUN_READ_WARN": "40",
+  "STEP_FILES": "15",
+  "TEST_CMD": "pnpm test",
+  "TYPECHECK_CMD": "pnpm typecheck",
+  "WORK_EFFORT": "xhigh",
+  "WORK_MODEL": "claude-sonnet-5-5"
+}

package/releases/0.45.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.45.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.45.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.45.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.45.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.45.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.45.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.45.0/surfaces/blockchain/tree/.claude/router.md

@@ -0,0 +1,6 @@
+<!-- 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.

package/releases/0.45.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.45.0/surfaces/db/tree/.claude/agents/architect.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.2 -->
+- **Tenant-scope impact** — state where `{{TENANT_KEY}}` is enforced. Every new query in app code filters by it, or reaches it through the model's foreign keys; only the auth library's own tables are exempt.
+
+<!-- nina:slot db.3 -->
+- **Database flag** — if the schema or a new query is touched, mark **"DBA REQUIRED"** prominently at the top of the spec, and name each new read's cache policy, or **`NO_CACHE`** for a read that feeds a write whose correctness depends on it being fresh — a stale row contaminates every decision made from it.

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

@@ -0,0 +1,50 @@
+<!-- nina:slot db.3 -->
+- Any change to the schema.
+- Any new query, or change to one, anywhere in application code.
+- Any migration.
+
+<!-- nina:slot db.4 -->
+- The schema diff, and the migration SQL it generates.
+- 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 models, so you can spot N+1 risk and consumer-side cache implications without re-grepping. (Before there is code, fall back to `.claude/architecture.md` § *Database* for the planned schema and its cache policies.)
+
+<!-- nina:slot db.6 -->
+- **The schema validates, and you read the migration's SQL** — offline, from files, with the project's own schema tooling. A check that seems to need a database URL is one you report as impossible, not one you run.
+
+<!-- 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 declared in the 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 -->
+- **Tenant scope.** Every query in app code filters by `{{TENANT_KEY}}`, or by the foreign-key chain that resolves back to it. The auth library's own tables are the only exemption. Reject any app query missing the scope.
+
+<!-- nina:slot db.11 -->
+- **Cache discipline.** A cached read names its policy explicitly — **an implicit cache is a bug: reject it** — checked against the cache policies in `.claude/architecture.md` § *Database*. A read that feeds a write whose correctness depends on it being fresh is never cached.
+
+<!-- nina:slot db.12 -->
+- **N+1 patterns.** If the code fetches a list then queries per item, reject with "fetch the related rows with the list, or batch."
+
+<!-- nina:slot db.13 -->
+- **Secrets.** The database's connection string comes from `{{SECRETS_LOCAL}}` locally and `{{SECRETS_PROD}}` in production — never a committed `.env`, never a literal in code.
+
+<!-- nina:slot db.14 -->
+- **Run anything that can write to a real database.** You are a read-only gate: against a live database you run read-only queries and nothing else. If a check seems to require writing, it does not — report the limitation to the orchestrator instead.
+
+<!-- nina:slot db.15 -->
+- Approve without validating the schema and reading the migration's SQL, offline, as *You MUST check* says.
+
+<!-- nina:slot db.16 -->
+- Wave through "small" schema changes. Small changes cause the worst production incidents.
+
+<!-- nina:slot db.17 -->
+- Approve a query in app code missing its `{{TENANT_KEY}}` scope, or the foreign key that owns it.
+
+<!-- nina:slot db.18 -->
+**Final report format:** ≤300 words if approved. Sections: Schema validation result, Migration SQL preview (verbatim if non-trivial), Index analysis, Tenant-scope check, Cache verdict, Privacy check, Final verdict. If rejected, list each issue with required action — no length cap.

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

@@ -0,0 +1,5 @@
+<!-- nina:slot db.2 -->
+- **Migrations, in order, against the right database.** Confirm the target is the database you intend, and that the migration is backward-compatible with the code already deployed, because the two are live together during the rollout.
+
+<!-- nina:slot db.5 -->
+- **Migrations:** applied / none, with the database they hit.

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

@@ -0,0 +1,2 @@
+<!-- nina:slot db.2 -->
+- If you change the schema or write a new query, flag it explicitly in the diff summary: it triggers the **dba** gate.

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

@@ -0,0 +1,10 @@
+<!-- nina:slot db.2 -->
+- A new query on a cached read path — verify the cache's behavior live (dba covers the schema; you cover how the cache behaves at runtime)
+
+<!-- nina:slot db.3 -->
+If a query behaves differently against a real database than the dba's static analysis suggested, escalate to **dba** — do not fix it yourself.
+
+<!-- nina:slot db.4 -->
+- **The auth library's backing store is a real database** — the development database, the same
+  connection the implementer uses from `{{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.45.0/surfaces/db/tree/.claude/agents/planner.md

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

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

@@ -0,0 +1,22 @@
+<!-- nina:slot db.2 -->
+- **If the schema, a migration or a query was touched anywhere in the diff: name `dba` on your Gates line.** Its approval is what a database change needs; yours does not stand in for it.
+
+<!-- nina:slot db.3 -->
+- Check for **tenant scoping** in every new query in app code: it filters by `{{TENANT_KEY}}`, or reaches it through the model's foreign keys. No "global" queries except the auth library's own tables. Missing scope = `REJECTED`.
+
+<!-- nina:slot db.4 -->
+- Check for N+1 queries when the DB layer was touched.
+
+<!-- nina:slot db.5 -->
+- **tenant-and-privacy** — `{{TENANT_KEY}}` in every app query (the auth library's own 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 -->
+- The schema touched (a migration in play)
+
+<!-- nina:slot db.7 -->
+- Leave `dba` off your Gates line on a database change "because it seems fine."
+
+<!-- nina:slot db.8 -->
+- Schema or query touched and `dba` not dispatched → name it on your Gates line; the orchestrator sends it.

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

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+- **AuthZ / tenant isolation (Hard Rule #7)** — EVERY query in app code scopes by `{{TENANT_KEY}}` (or its foreign key). Hunt for any query, route, MCP tool, or queue, webhook or background path where another tenant's data could be read or mutated (IDOR). The auth library's own tables are the only allowed unscoped reads — verify nothing else is.

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

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+- **DBA guardrail** → the database 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 tenant scope — all caught here.
+
+<!-- nina:slot db.2 -->
+| **dba** | Mandatory gate on schema changes, migrations and new queries | `.claude/agents/dba.md` |

package/releases/0.45.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` → `qa` on `APPROVED` — once the reviewer, and every other gate the diff went to, approved too
+- `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.45.0/surfaces/db/tree/.claude/patterns.md

@@ -0,0 +1,19 @@
+<!-- nina:slot db.2 -->
+- Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}` — only its client and its error classes.
+
+<!-- nina:slot db.4 -->
+- **Every service query filters by `{{TENANT_KEY}}` (tenant scope).** Missing scope = automatic `REJECTED`.
+
+<!-- nina:slot db.5 -->
+
+---
+
+## Database conventions (enforced by the dba subagent)
+
+- **A cached read names its policy, and a read that feeds a write whose correctness depends on it being fresh is NEVER cached.** A stale row contaminates the decision made from it. Hard reject in dba review.
+- **Every query in app code filters by `{{TENANT_KEY}}`** (or reaches it through the model's foreign keys). Tenant isolation is in the data layer. The auth library's own 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.
+
+<!-- nina:slot db.6 -->
+- A real database, never a mock of its client.

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

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+
+### DBA (mandatory for the database)
+
+- **Trigger:** any schema change, any new query, any migration.
+- **Input:** the schema diff and its migration SQL + the application code using the queries.
+- **Output:** `APPROVED`, or `REJECTED` with specific issues.
+- **Tools:** Read, Grep, Glob, Bash (schema validation, an offline migration diff, query-plan checks).
+- **Checks:** schema validates; migration safe on large tables; index coverage; an explicit policy on every cached read; **no cache on a read that feeds a correctness-critical write**; **tenant scope in every query**; no N+1; no raw PII without encryption; the connection secret comes from the environment, never from code.
+- **Position:** beside the reviewer, when a diff touches the schema, a migration or a query; `qa` waits for its `APPROVED`.
+
+<!-- nina:slot db.2 -->
+  - **If the schema or a query was touched → dba approved.**

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

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

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

@@ -0,0 +1,4 @@
+<!-- nina:slot db.1 -->
+
+### DBA is a guardrail, not a stage
+Invoke **dba** any time the schema, a migration or a query is touched — regardless of where you are in the pipeline. No such change reaches qa without dba approval; the reviewer names it on its Gates line.

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

@@ -0,0 +1,17 @@
+<!-- nina:slot db.3 -->
+| **ANY schema change, migration or new query** | **+ dba beside the reviewer** |
+
+<!-- nina:slot db.4 -->
+- **dba** → mandatory gate on schema changes, migrations, and new queries
+
+<!-- nina:slot db.5 -->
+2. **Every schema change, migration and new query goes through the dba subagent.** No exceptions. It runs beside the reviewer, which names it on its Gates line, and `qa` does not go out without its `APPROVED`.
+
+<!-- nina:slot db.6 -->
+6. **A cached read names its cache policy, and a read that feeds a write whose correctness depends on it being fresh is never cached.** An implicit cache is a bug, and a stale row contaminates every decision made from it. A write invalidates what it made stale.
+
+<!-- nina:slot db.7 -->
+7. **Tenant isolation is enforced in the data layer.** Every query in app code filters by `{{TENANT_KEY}}`, or reaches it through the model's foreign keys. No "global" queries except the auth library's own tables. Reviewer rejects any query missing the scope.
+
+<!-- nina:slot db.8 -->
+- **the database**: the schema, a migration, or a query

package/releases/0.45.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}}/**` (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.45.0/surfaces/edge-cf/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot edge-cf.1 -->
+- **Edge runtime compatibility.** A database client that runs at the edge uses its edge build, and `compatibility_flags = ["nodejs_compat"]` is set in `wrangler.toml`.

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

@@ -0,0 +1,32 @@
+<!-- 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*, where the project has one, the frontend's **Pages** deploy (`{{PAGES_PROJECT}}`). 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.
+
+**A variable the bundle reads must be in the environment of the build command.** `[vars]` and
+`[env.*.vars]` in `{{APP_DIR}}/wrangler.toml` do NOT reach the build — a bundler inlines them at build
+time, and 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.45.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.45.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.45.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.45.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.45.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.45.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 a database client that runs at the 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.45.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 → reviewer + the integration gate, where there is one → qa |
+
+<!-- nina:slot edge-cf.2 -->
+| New Queue handler | `.claude/architecture.md` § *Processing pipeline*, `{{API_DIR}}/src/queues/` | architect → implementer → reviewer + the integration gate, where there is one → qa |
+
+<!-- nina:slot edge-cf.3 -->
+| Wrangler / deploy / config | `CLAUDE.md` § *Common commands*, `{{API_DIR}}/wrangler.toml`, `.claude/patterns.md` § *Secrets* | implementer → reviewer → qa → devops |

package/releases/0.45.0/surfaces/edge-cf/tree/CLAUDE.md

@@ -0,0 +1,27 @@
+<!-- nina:slot edge-cf.1 -->
+
+### Cloudflare plugin skills — USE THEM
+
+The `cloudflare@cloudflare` plugin is installed at user scope and exposes skills that retrieve the **current** Cloudflare docs at invocation time. Pre-trained knowledge of Workers / Wrangler / DO / Queues / Cron APIs is stale — prefer the skill over recalling from memory.
+
+<!-- nina:slot edge-cf.2 -->
+| Write or review code under `{{API_DIR}}/**` (routes, services, middleware, webhook receivers, queue consumers) | `cloudflare:workers-best-practices` | catches floating promises, global-state misuse, missing `waitUntil`, streaming pitfalls |
+
+<!-- nina:slot edge-cf.3 -->
+| Touch `{{API_DIR}}/src/do/**` or any Durable Object call site | `cloudflare:durable-objects` | covers RPC, alarms, WebSocket, SQLite storage, lifecycle — DO API surface drifts fast |
+
+<!-- nina:slot edge-cf.4 -->
+| Touch `{{API_DIR}}/src/queues/**`, R2/KV usage | `cloudflare:cloudflare` | Queues, R2, KV decision tree |
+
+<!-- nina:slot edge-cf.5 -->
+| Author or modify `wrangler.toml` / `wrangler.jsonc` / run any `wrangler` CLI command | `cloudflare:wrangler` | CLI flags + config fields churn between minor versions |
+
+<!-- nina:slot edge-cf.6 -->
+| Run the **devops** deploy stage | `cloudflare:wrangler` (+ `cloudflare:cloudflare` for R2/KV/Queues/DO bindings) | deploy flags and binding config churn between versions |
+
+<!-- nina:slot edge-cf.7 -->
+
+The plugin's other skills — `cloudflare:agents-sdk`, `cloudflare:sandbox-sdk`, `cloudflare:cloudflare-email-service` — apply only where {{PROJECT}} adopts what they cover: an agent runtime, untrusted code execution, sending mail.
+
+<!-- nina:slot edge-cf.8 -->
+10. **Secrets in `{{SECRETS_LOCAL}}` for local dev, `{{SECRETS_PROD}}` for production.** Never `.env` committed. `compatibility_flags = ["nodejs_compat"]` is required in `wrangler.toml` for any database client that runs at the edge.

package/releases/0.45.0/surfaces/frontend/tree/.claude/agents/architect.md

@@ -0,0 +1,20 @@
+<!-- nina:slot frontend.1 -->
+| `cloudflare:web-perf` | a page-load performance question in `{{APP_DIR}}` |
+
+<!-- nina:slot frontend.2 -->
+
+## Visual acceptance — required in any spec touching `{{APP_DIR}}/**`
+
+A frontend spec that describes only structure produces a diff that only structure can verify, and
+structure is exactly what jsdom checks while being blind to the result. So state, as a short
+checklist, what must be TRUE ON THE SCREEN at **1440** and at **375**:
+
+- what is visible, and what must not be
+- what sits beside what, and what wraps or stacks at 375
+- the empty, loading and error states, if the change can produce them
+- anything that must not overflow, clip or overlap
+
+Each line must be checkable from a screenshot by someone who did not write the code — the **reviewer**
+checks the render against this list, and rejects on a mismatch. "Follows the design system" is not a
+criterion. A spec that touches `{{APP_DIR}}/**` without this section is incomplete, and the reviewer
+rejects it back to you.