@xhulz/nina 0.28.16

package/releases/0.17.1/surfaces/integrations/tree/.claude/patterns.md

@@ -0,0 +1,38 @@
+<!-- nina:slot integrations.1 -->
+- **Queue** (`{{API_DIR}}/src/queues/<q>.ts`) / **Webhook** (`{{API_DIR}}/src/routes/<source>-webhook.ts`): same discipline — validate the input, build deps, call one service function.
+
+<!-- nina:slot integrations.2 -->
+8. **Every integration is reached through its boundary module.** Services import the boundary's typed interface; they never construct an HTTP client, an SDK instance or a binding handle themselves.
+
+<!-- nina:slot integrations.3 -->
+
+---
+
+## Integrations (enforced by integration-tester + reviewer)
+
+An **integration** is a dependency whose behavior this project does not define. Each one is declared in `.nina/profile.json` with a `kind`, and the kind decides what counts as evidence:
+
+| kind | what it is | a premise is settled by |
+|---|---|---|
+| `installed-library` | code on disk under `node_modules` | `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>` |
+| `live-api` | a third-party HTTP API | a contract-test case, or a response observed against the service and captured verbatim |
+| `platform-binding` | a runtime the host provides | behavior observed under the local emulator, plus the platform's installed types |
+
+- **One boundary per integration.** All access goes through the module named as its `boundary`. A service, route, queue consumer or scheduled handler that reaches the dependency directly is a hard reject: there is then no single place to mock it, retry it, log it, or fix it.
+- **A `live-api` gets two implementations behind one interface** — the real client, and a deterministic in-memory mock. One **contract-test suite** exercises the interface and **BOTH** must pass it. The mock passing alone proves nothing about production; when the two disagree, the mock is wrong, never the other way round.
+- **Validate responses at the boundary**, in both implementations, so drift in the dependency surfaces structurally instead of as a type error three layers downstream.
+- **Typed errors at the boundary.** It maps the dependency's failures to this project's own error types; callers never handle a raw HTTP status or a vendor error code.
+
+### Adding an integration
+
+Four things, and none of them is optional:
+
+1. **The doc** — `.claude/integrations/<slug>.md`, from `.claude/templates/integration.md`. It opens with a premise index, then one `## P<n>` section per premise: a one-sentence claim, and the evidence that settles it in the form its kind requires.
+2. **The boundary** — one module, named in the profile entry. For a `live-api`: the interface, both implementations, and the contract suite.
+3. **The profile entry** — `slug`, `name`, `kind`, `boundary` and `skill` in `.nina/profile.json`. This is what makes the integration visible to the gates; an integration that is not declared is not gated.
+4. **The skill binding, when one exists.** If an installed skill covers this dependency, name it in the entry's `skill` field and add its row to the *Skills you MUST consult* table of every agent that touches the surface — and confirm `Skill` is in that agent's `tools:` list, which is an allowlist, not a hint. **If no installed skill covers it, bind none:** an invented binding is worse than none, because it reads as retrieval while being recall.
+
+The **integration-tester** owns the doc: it creates it on first contact and appends a premise whenever it observes behavior the doc does not yet carry. The architect cites it, the implementer honors it, and the reviewer refuses a spec that touches the surface without it.
+
+<!-- nina:slot integrations.4 -->
+- **`live-api` integrations:** the contract-test suite for the boundary runs against BOTH implementations. Tests elsewhere inject the mock; the integration gate exercises the real service.

package/releases/0.17.1/surfaces/integrations/tree/.claude/pipeline.md

@@ -0,0 +1,19 @@
+<!-- nina:slot integrations.1 -->
+
+### 4b. Integration-tester (mandatory for integration boundaries)
+
+- **Trigger:** any diff touching the boundary module of a declared integration, or adding a call into one.
+- **Input:** architect spec (with its **Integration premises** section) + implementer diff + repo state.
+- **Output:** approve or reject. Approve includes a verified-premise table (premise → verdict → citation). Reject identifies which premise or contract case failed, and whether the fix is upstream (respec) or in code.
+- **Tools:** Read, Write, Edit, Glob, Grep, Bash. Edits scoped to integration/contract test dirs and `.claude/integrations/**`.
+- **Checks:**
+  - **`installed-library` / `platform-binding`:** run the real flow against the real dependency. Read `.claude/integrations/<slug>.md` and probe each premise it lists.
+  - **`live-api`:** run the **contract-test suite** for that boundary against **both** implementations. A mock that is green while the real client is not is a lie. Confirm nothing reaches the service outside its boundary module.
+  - Update `.claude/integrations/<slug>.md` when new behavior is observed.
+- **Position:** after implementer, in parallel with dba when both apply. Reviewer verifies both gates ran.
+
+<!-- nina:slot integrations.2 -->
+  - **If an integration boundary was touched → integration-tester approved.**
+
+<!-- nina:slot integrations.3 -->
+- **Integration-tester falsifies a premise or contract case** → loop back to architect (premise wrong → respec) OR implementer (premise right but code doesn't honor it). Update `.claude/integrations/<slug>.md` with the corrected premise.

package/releases/0.17.1/surfaces/integrations/tree/.claude/retrieval.md

@@ -0,0 +1,16 @@
+<!-- nina:slot integrations.1 -->
+
+## Integration docs (load whenever an integration is touched)
+
+`.claude/integrations/<slug>.md` holds the verified premises for one integration. The architect MUST cite premises from it — or add new ones, carrying the evidence the integration's kind requires — in any spec that touches the boundary. The integration-tester probes each cited premise before the reviewer can approve.
+
+This project's integrations:
+
+<!-- nina:slot integrations.2 -->
+
+The integration-tester owns these docs. It creates one on first contact with a dependency and appends a premise whenever it observes behavior the doc does not yet carry, written against the version actually installed here or the response actually observed — never against the vendor's documentation.
+
+Read the doc's index and the premise sections your task cites. **Not the whole file:** an integration doc for a large dependency runs to thousands of lines, and reading it end to end is one of the biggest time sinks in this pipeline.
+
+<!-- nina:slot integrations.3 -->
+| Integration boundary change | `.claude/integrations/<slug>.md`, and the boundary module named in the profile | architect (cites premises) → implementer → **integration-tester** → reviewer → qa |

package/releases/0.17.1/surfaces/integrations/tree/.claude/router.md

@@ -0,0 +1,6 @@
+<!-- nina:slot integrations.1 -->
+
+### 1b. Integration-tester is a guardrail for integration boundaries
+Invoke **integration-tester** any time the diff touches the boundary module of a declared integration, or adds a call into one. It runs the real dependency, never a mock of it; for a `live-api` it runs the **contract-test suite against BOTH implementations**, so the mock can never pass while the live path is broken. No such change merges without its approval.
+
+The architect's spec MUST carry an **Integration premises** section: every behavior the implementation relies on, each with the evidence its kind requires — `node_modules/.pnpm/<lib>@<version>/...:<line>` for an installed library, a contract case or an observed response for a live API, the local emulator for a platform binding. Never by inference.

package/releases/0.17.1/surfaces/integrations/tree/CLAUDE.md

@@ -0,0 +1,14 @@
+<!-- nina:slot integrations.1 -->
+| **ANY integration surface** (the boundary module of a declared integration, or a new call into one) | architect cites a premise, with the evidence its kind requires, for every dependency behavior the code relies on; **+ integration-tester before reviewer** |
+
+<!-- nina:slot integrations.3 -->
+- **integration-tester** → mandatory gate on any integration boundary; runs the real dependency rather than a mock of it, and for a `live-api` runs the contract-test suite against both implementations so they cannot diverge; verifies every cited premise; keeps `.claude/integrations/<slug>.md` current
+
+<!-- nina:slot integrations.4 -->
+11. **Every integration has one boundary and one doc.** A dependency whose behavior you do not define — an installed library, a live third-party API, a platform binding — is reached through exactly ONE module, and nothing else speaks to it: no raw HTTP, SDK instance or binding handle in a route, service, queue consumer or scheduled handler. Each is declared in `.nina/profile.json` with its `kind` and `boundary`, and documented at `.claude/integrations/<slug>.md`. A `live-api` carries two implementations behind one interface — the real client and a deterministic mock — and one contract-test suite that BOTH must pass; a mock that is green while the real client is not is a lie, and a hard reject.
+
+<!-- nina:slot integrations.5 -->
+12. **A premise about an integration requires a citation, and the form depends on the kind.** The architect MAY NOT state a dependency's behavior as fact without evidence: for an `installed-library`, `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>` from the version actually installed here; for a `live-api`, a contract-test case or a response observed against the service and captured verbatim; for a `platform-binding`, behavior observed under the local emulator. Vendor docs, a README, a changelog and recall are NOT citations. An uncited premise is an assumption, and the spec is rejected by the reviewer.
+
+<!-- nina:slot integrations.6 -->
+13. **Integration boundaries require the integration-tester gate before reviewer.** Any diff touching a boundary module, or adding a call into one, MUST pass the integration-tester before the reviewer can approve. Unit-test mocks honor the spec, not the dependency — a mock is green because we wrote it that way. Only a run against the real thing, or a contract suite both implementations pass, catches drift.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/architect.md

@@ -0,0 +1,12 @@
+<!-- nina:slot money.1 -->
+11. **Money invariants** — if the spec touches distribution, transfer generation, or a send to the payment integration, explicitly confirm the design honors:
+    - Money is integer {{MINOR_UNIT}} end to end; percentages are basis points. Never a floating-point type.
+    - A distribution may NEVER exceed the amount → **block** (reject the operation, do not clamp it).
+    - A distribution **less** than the amount → **allow**, surface the shortfall, leave the remainder **parked** — never silently distributed.
+    - Transfers are **idempotent** — never sent twice. Dedupe happens at the serialization point, via the key, before the side effect.
+    - Every legal state transition writes an audit row (who / when / from → to). Illegal transitions throw.
+
+    If the design cannot satisfy all of these, redesign before submitting the spec.
+
+<!-- nina:slot money.2 -->
+- Design a money movement that can exceed the amount it distributes, silently absorb a shortfall, or send a transfer twice. If the design needs monetary computation, that computation lives in `{{CORE_PKG}}` as a pure function — never inline in a service or route.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/dba.md

@@ -0,0 +1,14 @@
+<!-- nina:slot money.1 -->
+7. **No cache on a read that feeds a money write.** Anything that loads an amount or a balance before computing, approving or dispatching a transfer MUST NOT carry a `cacheStrategy`. A stale amount contaminates a real money movement, and that damage is not undone by fixing the cache afterwards. **Hard reject if violated.**
+
+<!-- nina:slot money.2 -->
+9. **Monetary columns are integer.** Money is stored as an integer of the currency's minor unit ({{MINOR_UNIT}}); percentages are basis points. Reject `Decimal`, `Float`, or any type that can hold a fraction of the minor unit.
+
+<!-- nina:slot money.3 -->
+10. **Money-integrity constraints.** When the change touches the record of an outbound transfer, verify the **unique constraint on its idempotency key** exists (`@unique` in the schema → `UNIQUE` in the migration SQL). That constraint is what still holds when the application-level guard fails; a missing or dropped one is a **hard reject**. Verify likewise any uniqueness the ownership model depends on.
+
+<!-- nina:slot money.4 -->
+- Approve a query annotated with `cacheStrategy` if it feeds a money write.
+
+<!-- nina:slot money.5 -->
+- Approve a change to an outbound-transfer record that lacks the unique constraint on its idempotency key.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/implementer.md

@@ -0,0 +1,11 @@
+<!-- nina:slot money.1 -->
+
+## Money invariants you MUST honor
+- **A distribution may NEVER exceed the amount** → block. Implement the reject; never clamp and continue.
+- **A shortfall is parked, not distributed.** Surface it and leave the remainder where it is — never auto-distribute it, never absorb it quietly.
+- **Transfers are idempotent — never sent twice.** Dedupe at the serialization point via the key, *before* the side effect. A retry, a re-delivered message or a double-click must not produce a second transfer.
+- **Every state transition writes an audit row** (entity, from → to, actor). No transition without a trail.
+- The deterministic money logic lives in `{{CORE_PKG}}` — call it as a pure function; never embed the arithmetic in a service.
+
+<!-- nina:slot money.2 -->
+- Embed money arithmetic (sums, deltas, value comparisons, distribution math) inline in a service. Computation lives in `{{CORE_PKG}}`.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,3 @@
+<!-- nina:slot money.1 -->
+- **Confirm idempotency holds end to end.** Two sends with the same key → one logical transfer, no double send, and the serialization point refuses the second. This is the highest-blast-radius invariant in the system — drive it explicitly against the real service; do not infer it from reading the code.
+- **Confirm money crosses the boundary as an integer of the minor unit**, and that conversion happens only in the module that owns it — never in a service, never through a floating-point type.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/reviewer.md

@@ -0,0 +1,23 @@
+<!-- nina:slot money.1 -->
+- **Enforce the money invariants. Each violation is a HARD REJECT → loop back to architect:**
+  - **A distribution may NEVER exceed the amount.** It is blocked, not clamped. A retention is just another destination — same arithmetic, in integer {{MINOR_UNIT}}.
+  - **A shortfall must be parked, not silently distributed.** The remainder stays where it is, and the shortfall is surfaced to whoever is owed it.
+  - **Transfers must be idempotent — never sent twice.** Every transfer carries a key, and dedupe happens at the serialization point before the side effect. A retry, a re-delivered message or a double-click must never produce a second transfer.
+  - **Every state transition writes an audit row** (entity type, id, from, to, actor) and follows the transitions declared in `.claude/architecture.md`. An undeclared transition, or one missing its audit row, is a hard reject.
+
+<!-- nina:slot money.2 -->
+1. **money-invariants** — a distribution never exceeds the amount; a shortfall is parked, never
+   distributed; transfers idempotent at the serialization point; an audit row on every transition;
+   integer {{MINOR_UNIT}} and basis points; no arithmetic outside `{{CORE_PKG}}`.
+
+<!-- nina:slot money.3 -->
+- `{{CORE_PKG}}` money logic touched (distribution and transfer generation are high-blast-radius)
+
+<!-- nina:slot money.4 -->
+- Approve a change that lets a distribution exceed the amount, silently distributes a shortfall, sends a transfer without idempotent dedupe, or skips an audit row — those are hard rejects, loop back to architect.
+
+<!-- nina:slot money.5 -->
+- **If APPROVED:** ≤300 words. Sections: Verification commands run (typecheck/lint/build only — NEVER vitest), Spec-match (✅/❌ per item), Hard-rule checks (tenant scoping ✅, integer {{MINOR_UNIT}} / bps ✅, dba ✅ if applicable, integration-tester ✅ if applicable, money invariants ✅ — distribution ≤ amount, shortfall parked, idempotent transfer, audit row on transition), QA-attention flags (list any condition from the "stricter audit" list so QA knows what to focus on), Final verdict.
+
+<!-- nina:slot money.6 -->
+- Money invariant violated (distribution exceeds the amount, shortfall silently distributed, non-idempotent transfer, missing audit row) → back to **architect** for redesign.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/secops.md

@@ -0,0 +1,5 @@
+<!-- nina:slot money.1 -->
+- **Money-movement abuse (Hard Rules #3, #4, #5)** — **the money path reaches a real service; this is not a stub audit.** Is the idempotency contract actually enforced at the seam — the unique key, the serialization point, and the dedupe happening *before* the side effect? Can a replay, a double-click, a queue redelivery, or a manual reset of processed state cause a double send? Can a distribution exceed the amount, or a shortfall be silently distributed? Is whatever authorizes money OUT forgeable — a webhook without a verified signature, a callback trusted on its word? Is every state transition forced through an audit write? Flag any seam that is structurally unable to enforce its invariant, even where nothing has exploited it yet.
+
+<!-- nina:slot money.2 -->
+- **Idempotency-key & replay surface** — keys unguessable and collision-resistant where it matters; dedup enforced before the side effect, not after.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,4 @@
+<!-- nina:slot money.1 -->
+- **The conservation property, asserted rather than argued.** Find the test that proves in equals
+  out plus retained, and check it holds on the adversarial paths too, not only the intended one.
+  Rounding that always favours the same party is a finding; so is a fee path with no upper bound.

package/releases/0.17.1/surfaces/money/tree/.claude/agents/solidity-dev.md

@@ -0,0 +1,4 @@
+<!-- nina:slot money.1 -->
+- **State the conservation property and assert it in the suite.** A contract that holds or routes an
+  amount has one — what goes in equals what goes out plus what is retained — and it belongs in a
+  test, not in a comment. Rounding is part of it: say which way it goes and who it favours.

package/releases/0.17.1/surfaces/money/tree/.claude/patterns.md

@@ -0,0 +1,49 @@
+<!-- nina:slot money.1 -->
+
+---
+
+## Monetary values & percentages
+
+- **Money is an integer of the currency's minor unit**, end to end — {{MINOR_UNIT}}, never a float, never a type that can hold a fraction of one. Source of precision: `{{MONEY_MODULE}}`.
+- **Percentages are basis points** (`40% → 4000`, `100% → 10000`) so a distribution is exact without floating point.
+- **Parsing, formatting and percentage arithmetic live in one module and nowhere else.** A second place that turns a string into money is a second rounding rule, and the two will disagree on a value somebody is owed.
+- **Never** convert to a floating-point type before formatting, and never let a display format round a stored value.
+- Monetary database columns are integer. JSON responses serialize them as **strings**, not numbers, so no client parses them into a float. The service owns the conversion.
+
+<!-- nina:slot money.2 -->
+
+---
+
+## Distribution invariants (enforced by reviewer + unit tests)
+
+The distribution engine lives in `{{CORE_PKG}}`. It is pure and total over integer {{MINOR_UNIT}}:
+
+- A destination is either a percentage (basis points of the amount) or a fixed value.
+- `total = Σ destinations`, computed in {{MINOR_UNIT}}.
+- `total > amount` → **reject.** Never clamp, never distribute what is not there.
+- `total < amount` → **allow**, surface the shortfall, and leave the remainder **parked**. Silence is the defect here: an unexplained remainder is indistinguishable from a bug.
+- `total = amount` → OK.
+- A retention is just another destination — the same arithmetic applies to it, with no special case.
+
+<!-- nina:slot money.3 -->
+
+---
+
+## State machines & idempotency (enforced by reviewer)
+
+- **Every money-moving entity is a state machine.** Its states and legal transitions are declared in `.claude/architecture.md`; the code follows the declaration, not the other way round. Illegal transitions throw; they are never silently coerced.
+- **Every transition writes an audit row** (entity type, entity id, from, to, actor). No transition without a trail — the trail is what makes a money bug diagnosable after the money has moved.
+- **Outbound transfers are idempotent.** Each carries a unique key, and dedupe happens before the side effect, at the serialization point.
+- **One serialization point per balance.** Whatever computes and dispatches against a single balance never runs concurrently with itself. Two concurrent runs over one balance is how a double send happens even when every individual write is correct.
+
+<!-- nina:slot money.4 -->
+6. **Money computation and dispatch go through the serialization point.** Routes, queue consumers and tools never run a distribution or a transfer synchronously in the request path.
+
+<!-- nina:slot money.5 -->
+7. **The distribution engine lives in `{{CORE_PKG}}`.** Services call it as a pure function; they do not embed money logic inline.
+
+<!-- nina:slot money.6 -->
+- Idempotency on money-moving writes: the record carries an idempotency key, and the serialization point refuses the second attempt *before* the side effect.
+
+<!-- nina:slot money.7 -->
+- `{{CORE_PKG}}` is the most-tested package — pure functions over fixtures. Cover the distribution invariants exhaustively: over, under, exact, mixed percentage and fixed, and rounding.

package/releases/0.17.1/surfaces/money/tree/.claude/pipeline.md

@@ -0,0 +1,5 @@
+<!-- nina:slot money.1 -->
+  - **Money invariants respected** — a distribution never exceeds the amount; a shortfall is parked, not distributed; transfers idempotent; every transition audited.
+
+<!-- nina:slot money.2 -->
+- **Reviewer flags a money invariant violation** (distribution exceeds the amount, shortfall silently distributed, non-idempotent transfer, missing audit row) → loop back to architect.

package/releases/0.17.1/surfaces/money/tree/.claude/retrieval.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+| New distribution / transfer logic | `.claude/architecture.md` § *Money*, `.claude/patterns.md` § *Distribution invariants*, `{{CORE_PKG}}/` | architect → implementer → reviewer → qa |

package/releases/0.17.1/surfaces/money/tree/CLAUDE.md

@@ -0,0 +1,8 @@
+<!-- nina:slot money.1 -->
+3. **An outbound transfer is idempotent — it is NEVER sent twice.** Every transfer carries an idempotency key, and deduplication happens at a single serialization point **before** the side effect, never after it. A retry, a re-delivered queue message, a double-click and a replayed webhook must all collapse to one transfer. This is the highest-blast-radius invariant in the system: almost everything else can be corrected afterwards, and a duplicated transfer cannot.
+
+<!-- nina:slot money.2 -->
+4. **Conservation — what comes in equals what goes out plus what is retained.** A distribution may NEVER exceed the amount it distributes → **block**. If it is **less**, **alert** and leave the remainder **parked** and visible — never silently distributed, never silently absorbed. All arithmetic is integer {{MINOR_UNIT}}; percentages are basis points. The LLM never computes a monetary value.
+
+<!-- nina:slot money.3 -->
+5. **State-machine integrity.** Every money-moving entity has an explicit set of states and legal transitions, declared in `.claude/architecture.md` § *State machines* — not inferred from whatever code happens to exist. Only declared transitions are legal; an illegal one throws and is never silently coerced. **Every transition writes an audit row** (entity, id, from → to, actor, when). Skipping a state, inventing one, or landing a transition with no audit row is a hard reject.

package/releases/0.17.1/surfaces/pii/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+11. **Privacy.** No sensitive value in clear text where it must not be. The categories are declared in `.claude/architecture.md` § *Privacy* — they are not decided per query, and not decided by you. **Document bytes live only in the object store, referenced by key: the column holds the key, never the bytes.** Any column the architect's spec flagged for masking must be encrypted at rest. Reject a schema that widens what is stored in the clear.

package/releases/0.17.1/surfaces/pii/tree/.claude/agents/devops.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+
+**Point it at an UNAUTHENTICATED route — a sign-in page is the right one.** Never sign in, and never
+screenshot a signed-in page. Accounts on deployed environments hold real personal data, and a
+screenshot or a console dump pulls it into agent transcripts and logs, where it persists and nobody
+ever looks for it again. That is a privacy leak with no upside here: the sign-in page proves
+everything this check is for. It renders from the same bundle, it exercises the same build-time env
+inlining (a missing variable blanks it identically), and it needs no session.

package/releases/0.17.1/surfaces/pii/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- Check for privacy regressions: **no sensitive value in a log, an error message, a URL or a test fixture**, per the categories in `.claude/architecture.md` § *Privacy*; document bytes only in the object store, never plaintext in the database; no leaked secret.

package/releases/0.17.1/surfaces/pii/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **Privacy (Hard Rule #8)** — the categories declared in `.claude/architecture.md` § *Privacy* must never appear in logs, in responses that do not need them, in error paths, or in the database in clear text. Check every endpoint that returns a person's record for fields it includes by accident: a `select` that quietly grew a column is the usual way this leaks. Check the error paths too — they are written last and reviewed least.

package/releases/0.17.1/surfaces/pii/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+- **Nothing personal reaches the chain.** What is written on-chain is public, permanent, and beyond
+  deletion by anyone — including by you, and including after a subject asks. A hash of a personal
+  identifier is not a protection: it is a lookup table for whoever holds the input set. Reject a
+  personal datum stored in state, emitted in an event, or passed as calldata.

package/releases/0.17.1/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+8. **Sensitive personal data is classified, and the classification is enforced.** What counts as sensitive here — identity documents, financial identifiers, anything a person would not expect to be readable by whoever can read a log — is declared in `.claude/architecture.md` § *Privacy*, along with the regime that governs it ({{PRIVACY_REGIME}}). Encrypted at rest. **No sensitive value in a log, an error message, a URL, an analytics event, or an agent transcript** — the places nobody thinks about are exactly the ones that persist. Document bytes live only in the object store, referenced by key, never in the database in clear text.

package/releases/0.18.0/core/GAPS.md

@@ -0,0 +1,105 @@
+# Known gaps
+
+The harness was extracted by slicing one live project, and a slice cannot be cleaner than the
+thing it was cut from. This file tracks what is still shaped by that origin.
+
+## Closed
+
+**Domain examples in the core.** The extraction had to leave money and PII nouns in otherwise
+invariant rules, because byte-exact recomposition was the proof that nothing was lost and
+rewriting a line broke it. Once projects started pinning a release, that constraint lifted:
+the core no longer names payouts, escrow, KYC, PIX, CPF or a single provider, and the
+`db` surface no longer assumes the write it protects is a money movement. `fixtures/acme`
+holds the line — it declares no `money` and no `pii` surface, and the test fails on any of
+those words reappearing.
+
+**The single-provider assumption.** `external-api` became `integrations`, plural, cut by how
+a premise is settled (`installed-library` / `live-api` / `platform-binding`) rather than by
+one project's payment provider.
+
+**The `money` surface was one project's money path.** It shipped that project's state machine
+(`DETECTADA → CASADA | DIVERGENTE | SEM_REGRA`) as a harness rule, named its models, its
+currency and its escrow vocabulary, and assumed one payment provider. It now states the
+invariants and nothing else: conservation, idempotency of an irreversible send, one
+serialization point per balance, integer minor units, and a state machine the **project**
+declares in its own `.claude/architecture.md`. `fixtures/ledger` holds that line — a money
+project whose minor unit is `cents`, whose engine is `packages/settlement`, and whose deny
+list fails on `escrow`, `centavos`, `Payout`, `DETECTADA` or any of the rest reappearing.
+
+**The `pii` surface was one country's regime.** It named CPF/CNPJ, PIX keys, KYC documents, LGPD,
+R2 and Postgres as if they were universal categories. It now says that sensitive categories are
+**declared by the project** in its own `.claude/architecture.md`, and states what is invariant:
+classified, encrypted at rest, never in a log, an error, a URL, an analytics event or an agent
+transcript, and document bytes only in the object store. `fixtures/ledger` declares `pii` with a
+`GDPR` regime and fails on any of the old words returning.
+
+**Incident dates that read as false history.** Five places told a rule through a date it happened
+on — a wiped database on 2026-09-16, a blocked deploy on 2026-09-21, specs split across two
+directories before 2026-09-04. In the project where it happened that is provenance; in a new one it
+is a claim about a past it does not have, and an agent will go looking for it. The rules keep their
+force without the date: *"the command completes with a reassuring 'empty migration' result and no
+error, having already destroyed everything in the database it was pointed at."*
+
+**A rule cross-reference that pointed at nothing.** The hard rules are one numbered list assembled
+from several layers, so a project that declares no `integrations` surface has no rule 12 — while the
+core still said "the premise rule (#12 below)". `compose-test` now checks every `Hard Rule #N`
+against the rules the project actually composed, and `fixtures/plain` declares no surface at all, so
+the most reduced case is exercised on every run.
+
+**Invariant rules that landed in the project layer.** Four rules were generically valuable but were
+stated through an incident or an inventory belonging to one project, so the project layer swallowed
+them and a new project got nothing. Each was restated in the layer that actually owns it:
+
+| Spec | What it got back |
+|---|---|
+| secops | the **AuthN / session** dimension is now core: credential issuance and consumption, cookie flags, fixation across a privilege change, origin allowlist, and any dev bypass that could reach production. The project slot survives for the auth library and the bypasses that project actually has. |
+| qa | the *"pre-existing failure"* traps moved to `surfaces/frontend` — they are facts about a jsdom + vitest harness, not about one feature. The project slot held only the provenance, so it was dropped. |
+| architect, implementer | both specs now state the Route → Service → Data rule themselves instead of only `patterns.md` stating it. The project slot survives for the package names. |
+| patterns | *"when correcting a document, delete what you are correcting"* is now a core section. |
+
+**The threat model was numbered, and the numbers came from slots.** Dimensions 1–8 lived in surface
+fragments and 9–10 in the core, so a project declaring every surface got 1–10 and everyone else got
+a list with holes: `acme` read `2, 3, 6, 8, 9, 10`, and a surfaceless project began at **9**. The
+list is bullets now, valid under any combination. The core's rate-limiting dimension also named one
+project's auth strategy (`magic-link request, dev routes`); it says `issues a credential` instead.
+
+**A surface's technology was named in files nothing gated.** The item above used to bundle two
+different things under "stack-specific", and only one of them was a choice. `Prisma` appeared in 7
+ungated core files and Cloudflare's runtime in 10 — technologies that already *have* surfaces, named
+in text every project composes. A frontend-only project read a `CLAUDE.md` that discussed Prisma, a
+`patterns.md` headed *API (Cloudflare Worker / Hono) conventions*, and a qa spec telling it to kill
+stray `workerd` processes that could not exist. The reviewer even pointed at `CLAUDE.md` §
+*Cloudflare plugin skills*, a section that lives in the edge-cf surface — a dangling cross-reference
+of exactly the kind already closed once here.
+
+42 sites were fixed by saying what the rule means rather than which product implements it: "if the
+database was touched" instead of "if Prisma touched", "deploy config" instead of "wrangler config",
+"the local emulator" instead of "Miniflare". None of it lost precision, because the instruction was
+never about the product. Where a genuine specific was worth keeping it moved into `surfaces/edge-cf`
+behind a slot.
+
+The deny lists never caught this, and could not: they guard one fixture's output against *domain*
+leaks, and a substring match makes a word like `Hono` unusable because it fires on `Honor`. The
+guard is now a layer audit in `compose:test` — for every core file, a surface's technology may be
+named only if the file is gated on that surface. It asks the question once, of everything, instead
+of only of what a fixture happens to compose.
+
+## Open
+
+**The core is domain-agnostic, not stack-agnostic — deliberately.** It still names `pnpm` (49),
+`vitest` (50), `TSDoc` (12), `TypeScript` (6), `Biome` (4) and `turbo` (4). That is the single track
+this harness is for, and most of it is load-bearing: the qa spec's memory discipline is a fact about
+vitest, not about testing. Unlike the surface leak above, this is not a defect — there is no
+`pnpm` surface a project could decline. It becomes a gap only when a project on another stack
+appears. The `.js`-extension and barrel-export rules are the sharpest case — they assume a
+TypeScript monorepo that emits `dist/`, and `fixtures/plain` needs `PKG_SCOPE` and `EMITTING_PKGS`
+in its vocabulary to compose at all. If a second stack ever arrives, those are a `ts-monorepo`
+surface, not core.
+
+**A composed project is not a finished project — by design.** With no project layer, `CLAUDE.md`
+still opens with blank lines and no title, mission or stack. That is not a defect to fix in the
+core: the missing text is the part only this project can say. `init` conducts the interview and
+writes it to `.nina/TODO.md`, and it deliberately writes **no stub fragments**, because a stub is
+a filled slot as far as every tool is concerned — a tree of TODOs would compose and check clean
+while saying nothing. So `compose` keeps naming the unfilled slots until a person fills them, and
+the blank opening is that list being honest rather than the core being incomplete.

package/releases/0.18.0/core/tree/.claude/agents/architect.md

@@ -0,0 +1,108 @@
+---
+name: architect
+description: Use after the planner, or directly for a well-scoped single-component change. Designs the technical approach and produces a written spec (files, signatures, data flow, tests) that the implementer can code from without re-planning. Do NOT use for trivial edits or pure Q&A.
+tools: Read, Write, Edit, Grep, Glob, WebSearch, WebFetch, Skill
+model: opus
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/architect/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **architect**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+## Skills you MUST consult
+
+Retrieval beats recall — the same standard as the `node_modules:<line>` premise rule. Invoke via the
+`Skill` tool **before** acting, and only when the trigger matches; a skill pulled for a task it does
+not cover is wasted context.
+
+| Skill | Invoke when the spec will touch… |
+|---|---|
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot edge-cf.3 -->
+<!-- nina:slot edge-cf.4 -->
+<!-- nina:slot db.1 -->
+<!-- nina:slot frontend.1 -->
+<!-- nina:slot blockchain.1 -->
+
+Cite in your report which skills you consulted, or state that no trigger matched.
+
+<!-- nina:slot project.1 role-intro -->
+
+<!-- nina:slot project.2 scope -->
+
+## Inputs
+- A single subtask from the planner, OR a direct user request that is already well-scoped for a single change, OR a **group of sibling steps the planner marked `ONE-SPEC`** (steps that change no observable behavior on their own).
+
+For a `ONE-SPEC` group, write **one** spec covering the whole group, with the "Files to touch" list
+numbered per step so the implementer still lands them one at a time and each step stays small and
+auditable. If the group's combined diff would exceed ~400 lines, push back — it was not a group.
+
+If the planner marked the subtask as **L** or **XL** without further decomposition, push back: ask the planner to decompose further before you spec it. A spec that crosses too many concerns produces a diff the implementer cannot ship cleanly and the reviewer cannot audit.
+
+## Outputs
+A **technical spec** containing:
+1. **Goal** — 1–2 sentences.
+2. **Files to touch** — absolute paths, each marked `new` / `modify` / `delete`. **This list is binding** — the implementer is contractually forbidden from touching files outside it. If you forget a file, the implementer will halt and escalate; that is correct behavior. Be exhaustive.
+3. **Out-of-scope guardrail** — explicit list of nearby files / concerns that this spec must NOT touch (so the implementer doesn't drift into adjacent work).
+4. **Function / module signatures** — types, inputs, outputs, error cases.
+5. **Data flow** — how data moves through the change. The layering must be explicit; where the change is one stage of a longer pipeline, say which stage, what triggers it, and what serializes it against concurrent runs.
+<!-- nina:slot db.2 -->
+7. **Edge cases** — explicit list of what can go wrong.
+8. **Tests to add** — unit tests for the pure logic, naming the invariants to cover exhaustively rather than the happy path alone; integration tests against the real runtime, not a mock of it; and the fixtures they need, with realistic values. For a `live-api`, the contract-test cases BOTH implementations must satisfy.
+9. **Patterns to follow** — cite specific sections of `.claude/patterns.md`.
+<!-- nina:slot db.3 -->
+<!-- nina:slot money.1 -->
+
+11b. **Obsolescence list (MANDATORY).** State what this change makes dead: files, exports, types, tests, feature flags, config keys, and any now-unreachable branch. Mark each `delete` in the "Files to touch" list. **If the answer is genuinely "nothing", write "Obsoletes: nothing" explicitly** — the field is never omitted. Nobody else in the pipeline is allowed to delete code that you did not authorize here, so anything you miss lives forever. Run `pnpm code-map` and check the dead-export report when a change removes or replaces a call site.
+<!-- nina:slot blockchain.2 -->
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot edge-cf.5 -->
+15. **Preview deploy plan** — if the spec culminates in a feature that will be deployed, explicitly name the preview URL pattern where smoke runs FIRST (a preview deployment for `{{APP_DIR}}`; a staging route for the API). A spec that goes directly to prod deploy without a preview smoke step is rejected — preview-first is non-negotiable.
+
+## You MUST
+- Read the planner's artifact (if any) in full before starting.
+- Consult `.claude/retrieval.md` and read only the doc sections that apply.
+- Read `.claude/architecture.md` when your task involves locating which files participate in a domain or confirming the planned layout.
+<!-- nina:slot project.3 integration-docs-to-read -->
+- Verify current code state with `Read` / `Grep` before specifying changes — do not assume.
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot project.4 code-map-and-helpers -->
+- **Cite the existing code you are extending.** Every claim about how the current system behaves carries a `path:line` reference, the same way external-library premises carry `node_modules:<line>`. "The service already does X" without a citation is an assumption, and assumptions are how a second seam gets built next to the first one.
+- **Respect the Route → Service → Data layering** that `.claude/patterns.md` defines: a route never
+  reaches past the service into the data layer, and a service never touches the HTTP context. A spec
+  that puts a query in a route is where the second seam starts, and the second seam is what every
+  later inconsistency is built on.
+<!-- nina:slot project.5 layering-rule -->
+- Keep the spec self-sufficient: the implementer should never need to re-read the original user request or planner output.
+- **Write the spec directly** to `.claude/plans/specs/<feature>-spec.md` **in the repo** — never to `~/.claude/plans/`. Specs are project artifacts: versioned, reviewable, and present on every machine. Use the `Write` tool. Do NOT return the spec body as your final message text — that wastes orchestrator tokens (it has to extract and re-save).
+- **Final message:** 1-line confirmation of file written + ≤5-bullet summary of key decisions + flag any open question. Cap at ~200 words.
+<!-- nina:slot frontend.2 -->
+
+## You MUST NOT
+- Write or edit application code — your `Write`/`Edit` access is scoped to `.claude/plans/**` (specs and planning artifacts) and `.claude/integrations/**` (when you verify a new premise during spec work, you may extend the integration doc).
+<!-- nina:slot integrations.4 -->
+- Leave ambiguity ("figure it out", "probably"). If you don't know, flag it as a risk with a proposed resolution path.
+- Introduce abstractions beyond what the task requires.
+- Design for hypothetical future requirements.
+<!-- nina:slot money.2 -->
+- Dump the full spec body in your final message. Save it to disk and link to it.
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `SPEC-READY` or `BLOCKED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line.
+
+`BLOCKED` means the design cannot be settled — an unverifiable premise, a missing decision; say which.
+
+This line is machine-read to measure how often each stage sends work back. A report without
+it counts as no verdict at all, which makes the stage invisible to the measurement.
+
+## Handoff
+<!-- nina:slot project.6 handoff -->

package/releases/0.18.0/core/tree/.claude/agents/dba.md

@@ -0,0 +1,92 @@
+<!-- nina:requires db -->
+---
+name: dba
+<!-- nina:slot project.1 description -->
+tools: Read, Grep, Glob, Bash, Skill
+model: sonnet
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/dba/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **dba**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+## Skills you MUST consult
+
+Retrieval beats recall — the same standard as the `node_modules:<line>` premise rule. Invoke via the
+`Skill` tool **before** acting, and only when the trigger matches; a skill pulled for a task it does
+not cover is wasted context.
+
+| Skill | Invoke when… |
+|---|---|
+<!-- nina:slot db.1 -->
+
+<!-- nina:slot db.2 -->
+
+Cite in your report which skills you consulted, or state that no trigger matched.
+
+<!-- nina:slot project.2 role-intro -->
+
+## When you are dispatched
+<!-- nina:slot db.3 -->
+
+You may be invoked at any stage — architect, implementer, or reviewer can dispatch you. Reviewer will refuse final approval without your sign-off.
+
+## Inputs
+<!-- nina:slot db.4 -->
+
+## Outputs
+Either:
+- **Approve** with confirmation that all checks below passed.
+- **Reject** with specific issues and required fixes.
+
+## You MUST consult first
+<!-- nina:slot db.5 -->
+
+## The {{PROJECT}} data model you reason about
+<!-- nina:slot project.3 data-model -->
+
+## You MUST check (every time)
+
+<!-- nina:slot db.6 -->
+<!-- nina:slot db.7 -->
+<!-- nina:slot db.8 -->
+<!-- nina:slot db.9 -->
+<!-- nina:slot db.10 -->
+<!-- nina:slot db.11 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot db.12 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot money.3 -->
+<!-- nina:slot pii.1 -->
+<!-- nina:slot db.13 -->
+<!-- nina:slot edge-cf.1 -->
+
+## You MUST NOT
+- Edit code — read-only + Bash only.
+<!-- nina:slot db.14 -->
+<!-- nina:slot db.15 -->
+<!-- nina:slot db.16 -->
+<!-- nina:slot money.4 -->
+<!-- nina:slot db.17 -->
+<!-- nina:slot money.5 -->
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `APPROVED` or `REJECTED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line.
+
+`REJECTED` blocks the reviewer; list each issue with the schema or query it concerns.
+
+This line is machine-read to measure how often each stage sends work back. A report without
+it counts as no verdict at all, which makes the stage invisible to the measurement.
+
+## Handoff
+Your decision goes back to whoever dispatched you (architect, implementer, or reviewer). Reviewer verifies your approval before final sign-off.
+
+<!-- nina:slot db.18 -->