@xhulz/nina 0.53.3 → 0.55.0

package/releases/0.55.0/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 -->
+- **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 -->
+- **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.55.0/surfaces/money/tree/.claude/pipeline.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+  - **Money invariants respected** — a distribution never exceeds the amount; a shortfall is parked, not distributed; transfers idempotent; every transition audited.

package/releases/0.55.0/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.55.0/surfaces/money/tree/CLAUDE.md

@@ -0,0 +1,11 @@
+<!-- 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.
+
+<!-- nina:slot money.4 -->
+- **money movement**: anything that creates, moves, settles or records a balance

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

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **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.55.0/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.55.0/surfaces/pii/tree/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+- Check for privacy regressions: **no sensitive value in a log, an error message — a library's own included — 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.
+
+<!-- nina:slot pii.2 -->
+- **privacy** — the privacy check above, in full: no sensitive value in a log, an error message, a
+  URL or a test fixture; document bytes only in the object store; no leaked secret. Where
+  **tenant-and-privacy** is dispatched, its reviewer owns this too and there is no separate one; where
+  it is not, this is a dimension of its own. Either way it is never nobody's.

package/releases/0.55.0/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 — and what the libraries on them print or carry in their own errors, bound values included.

package/releases/0.55.0/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.55.0/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- 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. That includes what a library puts in its own errors and prints itself: a database client's error can carry the query and every bound value, and a framework can log a whole error past the logger it was given. A database error is mapped at the data layer to a typed error from a closed list before anything logs or returns it, and a test proves that a bound value it writes reaches no thrown error. Document bytes live only in the object store, referenced by key, never in the database in clear text.
+
+<!-- nina:slot pii.2 -->
+- **personal data**: where it is collected, stored, logged or sent

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/architect.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/dba.md

@@ -0,0 +1,42 @@
+<!-- nina:slot prisma.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. Through a driver adapter, cite the adapter's installed source for what a transaction does: the skill describes the default engine, and an adapter can roll back less |
+
+<!-- nina:slot prisma.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 prisma.3 -->
+- **With Prisma, both offline.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`; it must pass. Then run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta. Its flags changed in Prisma 7, so read the installed major (`prisma --version`) before writing the command:
+
+   ```
+   # Prisma 6. 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
+   ```
+
+   From Prisma 7 the two flags are `--from-schema` and `--to-schema`, and the schema engine starts from the
+   datasource in `prisma.config.ts` even for this diff: with none there, it prints nothing and exits 0. For
+   SQLite a placeholder the diff never opens is enough, a `file:` URL under a gitignored directory; for any
+   other provider, find out what the diff opens before you give it one. Never a real database's URL. A first schema has nothing at `HEAD`: diff it `--from-empty`. Compare the output against the
+   hand-written `migration.sql` to confirm the declarative parts match.
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without a shadow database (`--shadow-database-url`, or from Prisma 7 a
+   `shadowDatabaseUrl` in `prisma.config.ts`), which pushes you toward supplying a database URL — the exact move that destroys databases (below). The file-to-file form above answers the
+   same question with no database involved.
+
+   ⛔ **NEVER point `--shadow-database-url`, `--from-url`, `--to-url`, `--from-schema-datasource` — or, from Prisma 7, a `shadowDatabaseUrl` or the config datasource behind `--from-config-datasource` — at a real database, most of all not the one `{{SECRETS_LOCAL}}` names.** 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. 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 prisma.4 -->
+- **Where reads are cached through Prisma Accelerate,** every `findUnique` / `findMany` on a hot read path names its `cacheStrategy` (`ttl` / `swr`), and one that feeds a correctness-critical write names none.
+
+<!-- nina:slot prisma.5 -->
+- **On an edge runtime,** new Prisma code paths use the edge client of the installed major: `@prisma/client/edge` up to Prisma 6; from 7, the client the `prisma-client` generator writes with the platform's `runtime` set, imported from where it is generated — `@prisma/client/edge` fails there with `MODULE_NOT_FOUND`.
+
+<!-- nina:slot prisma.6 -->
+- Run a Prisma command that writes to a real database — `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`, `db push`, `db execute`, `$executeRaw*` — or **any `prisma migrate diff` variant carrying a database URL**, which silently wipes the database it points at.

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/devops.md

@@ -0,0 +1,11 @@
+<!-- nina:slot prisma.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot prisma.2 -->
+- **Prisma migrations go out with `prisma migrate deploy`**, and nothing else changes a shared database's schema.
+
+<!-- nina:slot prisma.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 prisma.4 -->
+- Run `prisma migrate reset` against a shared database, ever.

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.55.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.55.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.55.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, 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 prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, 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 |

package/src/commands/check.mjs

@@ -14,11 +14,12 @@ import { expectedUnfilled } from '../expected.mjs';
 import { parseGraph, validateGraph } from '../graph.mjs';
 import { frontmatterFindings, installedSkills, modelFindings, toolFindings } from '../tools.mjs';
 import { HOOK_SCRIPTS, missingWiring, shippedScripts } from '../wiring.mjs';
-import { existsSync, readdirSync, realpathSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { SLOT, closedGate, defaultedSlots, layerRootFor, noticeOf, readLayerText, stripWhy, walk } from './compose.mjs';
 import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
 import { missingNeeds } from '../surfaces.mjs';
+import { resolveCitation } from './pills.mjs';
 
 /** Fields every declared integration must carry, and why each one matters. */
 const INTEGRATION_FIELDS = {
@@ -260,6 +261,34 @@ function liveStoreDirs(target) {
   return live;
 }
 
+/**
+ * A text with its fenced blocks blanked. What a command printed, quoted as evidence, cites nothing: re-citing a path
+ * in it would falsify the evidence, and a note that cannot be cleared trains its reader to skip the check, the
+ * citations it is right about included. One project's `readlink` transcript held a store directory a peer change
+ * had since renamed. A fence left open runs to the end, as Markdown reads it.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function outsideFences(text) {
+  let fence = null;
+  return text
+    .split('\n')
+    .map((line) => {
+      if (fence) {
+        const close = /^\s*(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+        if (close && close[0] === fence[0] && close.length >= fence.length) fence = null;
+        return '';
+      }
+      // Indented any depth, since a list item's fence is indented past the marker; and a backtick run whose rest
+      // holds a backtick is code in a line, not a fence.
+      const [, open, info] = /^\s*(`{3,}|~{3,})(.*)$/.exec(line) ?? [];
+      fence = open && !(open[0] === '`' && info.includes('`')) ? open : null;
+      return fence ? '' : line;
+    })
+    .join('\n');
+}
+
 /**
  * The paths into the package manager's store that a text cites and the install no longer uses. Only the store: its
  * directory names carry a suffix per peer, renamed when an unrelated dependency changes one, and the old directory
@@ -269,7 +298,8 @@ function liveStoreDirs(target) {
  * package's own link, or one written from some package's directory, cannot be told stale from here. A line number
  * after a path is not part of it; an elision (`...`, `…`), a template and a URL are not citations. Each occurrence of
  * the store is read outwards, and the next is looked for past it, so the text is read once. A directory that is not
- * `<name>@<version>` is a mention of the store, not a citation, except its hoisting `node_modules`.
+ * `<name>@<version>` is a mention of the store, not a citation, except its hoisting `node_modules`. A path in a fenced
+ * block is quoted output, not a citation (`outsideFences`).
  *
  * @param {string} text
  * @param {string} target - The project directory.
@@ -277,7 +307,8 @@ function liveStoreDirs(target) {
  *   the docs of one run so the store is walked once.
  * @returns {string[]} Each stale path once, in the order cited.
  */
-export function unresolvedCitations(text, target, reached = new Map()) {
+export function unresolvedCitations(written, target, reached = new Map()) {
+  const text = outsideFences(written);
   const cited = new Set();
   let at = text.indexOf(STORE);
   while (at !== -1) {
@@ -321,6 +352,69 @@ export function unresolvedCitations(text, target, reached = new Map()) {
   return [...cited].filter(stale);
 }
 
+/**
+ * `<package dir>/node_modules/<parent> → <lib>@<version>/<file>[:<line>]`: a library no package of the project links,
+ * cited through the package that depends on it.
+ */
+const TRANSITIVE = /(\/?(?:[\w.@+-]+\/)*node_modules\/(?:@[\w.-]+\/)?[\w.-]+)\s*(?:→|->)\s*((?:@[\w.-]+\/)?[\w.-]+)@(\d[\w.+-]*)\/([^\s:`|),;]*[^\s:`|),;.])(?::(\d+))?/g;
+
+/**
+ * Where Node finds a library from a directory: the `node_modules` beside each directory up from it, one that is a
+ * `node_modules` itself skipped. From a package's real path in the store, that is the directory its dependencies are
+ * linked in.
+ *
+ * @param {string} from - A real path.
+ * @param {string} lib - The library's name, scoped or not.
+ * @returns {string|null} The library's real path.
+ */
+function resolveFrom(from, lib) {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'node_modules', lib);
+    if (basename(dir) !== 'node_modules' && existsSync(join(candidate, 'package.json'))) return realpathSync(candidate);
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/**
+ * The citations of a library through its parent's link that do not resolve as written. A dependency of a dependency
+ * has no link of its own in any package — the emulator one project's every database premise was about is a dependency
+ * of its CLI, not of the project — and its only other path is a store directory a peer change renames. So it is cited
+ * through the parent's link, and resolved from where that link really leads, as Node resolves it: the parent there,
+ * the library found from it at the version written, the file in it, and the line within it.
+ *
+ * @param {string} text
+ * @param {string} target - The project directory the package directories are relative to.
+ * @returns {string[]} Each citation that does not resolve, with why, once.
+ */
+export function transitiveCitations(text, target) {
+  const wrong = new Map();
+  for (const [cited, parent, lib, version, file, line] of outsideFences(text).matchAll(TRANSITIVE)) {
+    if (wrong.has(cited)) continue;
+    let real;
+    try {
+      real = realpathSync(isAbsolute(parent) ? parent : join(target, parent));
+    } catch {
+      wrong.set(cited, `${parent} is not there`);
+      continue;
+    }
+    const found = resolveFrom(real, lib);
+    let installed = null;
+    try {
+      installed = found ? JSON.parse(readFileSync(join(found, 'package.json'), 'utf8')).version ?? null : null;
+    } catch {
+      // A manifest that does not parse says no version.
+    }
+    if (!found) wrong.set(cited, `${lib} does not resolve from it`);
+    else if (installed !== version) wrong.set(cited, `${lib} resolves to ${installed ?? 'no version'} there`);
+    else {
+      const at = resolveCitation(found, line ? `${file}:${line}` : file);
+      if (at.state === 'gone') wrong.set(cited, `${file} is not in ${lib}@${version}`);
+      else if (at.state === 'truncated') wrong.set(cited, `${file} has ${at.lines} line(s)`);
+    }
+  }
+  return [...wrong].map(([cited, why]) => `${cited}: ${why}`);
+}
+
 /**
  * `nina check`.
  *
@@ -452,10 +546,17 @@ export async function check(argv, ctx) {
   const reached = new Map();
   for (const doc of docs.filter((name) => name.endsWith('.md')).sort()) {
     const key = `.claude/integrations/${doc}`;
-    const gone = unresolvedCitations(await readFile(join(target, key), 'utf8').catch(() => ''), target, reached);
+    const text = await readFile(join(target, key), 'utf8').catch(() => '');
+    const gone = unresolvedCitations(text, target, reached);
     if (gone.length > 0) {
       notes.push(
-        `${key} cites ${gone.length} path(s) in the package manager's store that the install no longer uses — ${gone[0]}${gone.length > 1 ? ', …' : ''}: a peer change renames those directories, and the old one stays on disk linked by nothing; re-cite each from the depending package's own node_modules link, with its version beside it`,
+        `${key} cites ${gone.length} path(s) in the package manager's store that the install no longer uses — ${gone[0]}${gone.length > 1 ? ', …' : ''}: a peer change renames those directories, and the old one stays on disk linked by nothing; re-cite each from the depending package's own node_modules link, with its version beside it — or, for a library no package links, through the one that depends on it: \`<package dir>/node_modules/<parent> → <lib>@<version>/<file>:<line>\``,
+      );
+    }
+    const wrong = transitiveCitations(text, target);
+    if (wrong.length > 0) {
+      notes.push(
+        `${key} cites ${wrong.length} librar${wrong.length > 1 ? 'ies' : 'y'} through a parent's link that ${wrong.length > 1 ? 'do' : 'does'} not resolve as written — ${wrong[0]}${wrong.length > 1 ? '; …' : ''}: read where the parent's link leads, and cite the version, file and line found there`,
       );
     }
   }

package/src/commands/learn.mjs

@@ -38,7 +38,7 @@ import { deepLearn, transcriptsOf } from '../deep.mjs';
 import { autoExport } from './export.mjs';
 import { beforeModel } from '../detectors.mjs';
 
-/** Loop-backs from one role, since its newest lesson, that make a lesson overdue. */
+/** Times one stage's work was sent back, since its newest lesson, that make a lesson overdue. */
 export const CAPTURE_AT = 3;
 
 /**
@@ -111,12 +111,16 @@ const SENT_BACK_HOURS = 24;
 
 /**
  * The stage each loop-back sent work back to: the next one dispatched in its session, after it reported, among
- * the stages the project's graph routes that verdict of that stage to — or the only one it routes it to.
+ * the stages the project's graph routes that verdict of that stage to — or the only one it routes it to. One the
+ * graph routes to several, none of which has taken it back yet, went to no stage that can be told: it is charged to
+ * none, where it was charged to the stage that gave it — a gate that rejected work, doing its job, read as a stage
+ * sent back, and asked every turn for a lesson that was not its own.
  *
  * @param {object[]} records - Recorded dispatches.
  * @param {Map<string, Map<string, Map<string, number>>>|null} loops - The graph's capped loop-back edges.
- * @returns {Map<object, {to: string, fix: object|null}>} Loop-back record → the stage it sent work back to, where
- *   one can be told, and the dispatch of that stage that took the work back, where one was found.
+ * @returns {Map<object, {to: string|null, fix: object|null}>} Loop-back record → the stage it sent work back to, null
+ *   while that cannot be told, and the dispatch of that stage that took the work back, where one was found. A
+ *   loop-back the graph does not route is not in it.
  */
 export function sentBackTo(records, loops) {
   const out = new Map();
@@ -134,11 +138,32 @@ export function sentBackTo(records, loops) {
     const within = (x) => Date.parse(x.ts) - Date.parse(back) <= SENT_BACK_HOURS * 3_600_000;
     const next = (bySession.get(r.session) ?? []).find((x) => String(x.ts) > back && within(x) && targets.has(x.role));
     const to = next?.role ?? (targets.size === 1 ? [...targets.keys()][0] : null);
-    if (to) out.set(r, { to, fix: next ?? null });
+    out.set(r, { to, fix: next ?? null });
   }
   return out;
 }
 
+/**
+ * The stage a loop-back is charged to: where it sent work back (`sentBackTo`), none while that cannot be told, and
+ * the stage that gave it only where the graph routes it nowhere.
+ *
+ * @param {ReturnType<typeof sentBackTo>} owners
+ * @param {object} r - A loop-back record.
+ * @returns {string|null}
+ */
+const chargedTo = (owners, r) => (owners.has(r) ? owners.get(r).to : r.role);
+
+/**
+ * How many rounds some loop-backs sent back: those one dispatch took back are one, since the checkers that run beside
+ * each other each reject the same work. One no dispatch took back counts on its own, since nothing then says which
+ * work it rejected.
+ *
+ * @param {ReturnType<typeof sentBackTo>} owners
+ * @param {object[]} loops - Loop-back records.
+ * @returns {number}
+ */
+const sendings = (owners, loops) => new Set(loops.map((r) => owners.get(r)?.fix ?? r)).size;
+
 /**
  * Roles that looped back often enough, since their newest lesson, that one is overdue.
  *
@@ -156,7 +181,7 @@ export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS, o
   // A loop-back is the lesson of the stage it sent work back to, where that is known (`sentBackTo`): charged
   // to the stage that gave the verdict, the reviewer owed the implementer's lessons, and only a pill naming
   // every checker in its applies_to ever settled the count.
-  const ownerOf = (r) => owners.get(r)?.to ?? r.role;
+  const ownerOf = (r) => chargedTo(owners, r);
   const roles = [...new Set(records.map(ownerOf).filter(Boolean))];
   const out = [];
   for (const role of roles) {
@@ -176,12 +201,17 @@ export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS, o
     const at = floor === newest ? taught?.at ?? null : null;
     const after = (r) => day(r.ts) > floor || (at !== null && day(r.ts) === floor && String(r.ts) > at);
     const loops = records.filter((r) => ownerOf(r) === role && readable(r.verdict) && isLoopBack(r.verdict) && after(r));
-    if (loops.length >= CAPTURE_AT) {
+    // Rounds sent back, not loop-backs: three reviewers beside each other rejecting one change sent it back once.
+    const count = sendings(owners, loops);
+    if (count >= CAPTURE_AT) {
+      // One per round sent back, as the count is: three reviewers beside each other are one entry, not three.
+      const listed = new Set();
       const recent = loops
         .sort((a, b) => String(b.ts).localeCompare(String(a.ts)))
+        .filter((r) => !listed.has(owners.get(r)?.fix ?? r) && listed.add(owners.get(r)?.fix ?? r))
         .slice(0, 3)
         .map((r) => ({ ts: day(r.ts), desc: r.desc ?? '', session: String(r.session ?? '').slice(0, 8) }));
-      out.push({ role, count: loops.length, since: newest, recent });
+      out.push({ role, count, since: newest, recent });
     }
   }
   return out.sort((a, b) => b.count - a.count);
@@ -264,14 +294,11 @@ function wilson(k, n) {
  */
 export function verified(records, known, { owners = new Map(), targets = null } = {}) {
   const out = [];
-  const ownerOf = (r) => owners.get(r)?.to ?? r.role;
+  const ownerOf = (r) => chargedTo(owners, r);
   const sentBack = records.filter((r) => readable(r.verdict) && isLoopBack(r.verdict));
-  // The rounds these loop-backs sent back: those one dispatch took back are one. One no dispatch took back counts on
-  // its own, since nothing then says which work it rejected.
-  const sendings = (backs) => new Set(backs.map((r) => owners.get(r)?.fix ?? r)).size;
   const sideOf = (these, backs) => {
     const days = these.map((r) => day(r.ts)).sort();
-    return { n: these.length, loops: Math.min(these.length, sendings(backs)), span: [days[0] ?? null, days.at(-1) ?? null] };
+    return { n: these.length, loops: Math.min(these.length, sendings(owners, backs)), span: [days[0] ?? null, days.at(-1) ?? null] };
   };
   const ranOn = (r) => (r.usage_model ? `${r.usage_model}${r.effort ? ` · ${r.effort}` : ''}` : null);
   for (const lesson of known.filter((l) => l.date)) {
@@ -309,7 +336,7 @@ export function verified(records, known, { owners = new Map(), targets = null }
       const [bLo, bHi] = wilson(before.loops, before.n);
       const [aLo, aHi] = wilson(after.loops, after.n);
       const change = aHi < bLo ? 'lower' : aLo > bHi ? 'higher' : 'unclear';
-      const others = [...(targets ?? new Set(sentBack.map(ownerOf)))].filter((x) => x !== role);
+      const others = [...(targets ?? new Set(sentBack.map(ownerOf)))].filter((x) => x && x !== role);
       const theirs = records.filter((r) => others.includes(r.role) && readable(r.verdict));
       const otherBacks = sentBack.filter((r) => others.includes(ownerOf(r)));
       const control = (pick) => sideOf(theirs.filter(pick), otherBacks.filter(pick));
@@ -1057,7 +1084,7 @@ export async function learn(argv, ctx) {
     }
     for (const o of late) {
       console.log(
-        `  ${o.role}: ${o.count} loop-back(s) in the last ${days} days ` +
+        `  ${o.role}: sent back ${o.count} time(s) in the last ${days} days ` +
           (o.since ? `since its newest lesson (${o.since})` : 'and no lesson at all') +
           ' — the newest:',
       );
@@ -1119,10 +1146,10 @@ export async function learn(argv, ctx) {
       ? `  observe   ${learning.runs} run(s) in ${records.length} round(s) recorded, ${span}`
       : '  observe   ✗ nothing recorded — no transcripts found for this project, so no link below can be measured',
   );
-  if (late.length === 0) console.log(`  capture   ✓ no role has looped back ${CAPTURE_AT}+ times without a lesson in the last ${days} days`);
+  if (late.length === 0) console.log(`  capture   ✓ no role has been sent back ${CAPTURE_AT}+ times without a lesson in the last ${days} days`);
   late.forEach((o, i) => {
     console.log(
-      `  ${i === 0 ? 'capture ' : '        '}  ✗ ${o.role}: ${o.count} loop-back(s) ` +
+      `  ${i === 0 ? 'capture ' : '        '}  ✗ ${o.role}: sent back ${o.count} time(s) ` +
         (o.since ? `since its newest lesson (${o.since})` : 'and no lesson at all'),
     );
   });

package/src/commands/pills.mjs

@@ -12,6 +12,7 @@
 
 import { mkdir, readFile, readdir, rename } from 'node:fs/promises';
 import { HARNESS, readProfile } from '../paths.mjs';
+import { localDay } from '../store.mjs';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
@@ -124,7 +125,7 @@ export function list(value) {
  * @param {string} citation - `path` or `path:line`.
  * @returns {{state: 'ok'|'gone'|'truncated', path: string, line: number|null, lines?: number}}
  */
-function resolveCitation(target, citation) {
+export function resolveCitation(target, citation) {
   const at = /^(.*):(\d+)$/.exec(citation);
   const path = at ? at[1] : citation;
   const line = at ? Number(at[2]) : null;
@@ -350,7 +351,10 @@ export async function pillsData(target, ctx) {
     .filter((f) => f.endsWith('.md'))
     .map((f) => f.replace(/\.md$/, ''))
     .sort();
-  const today = new Date().toISOString().slice(0, 10);
+  // The day where this machine is, the one the capture detector counts loop-backs by and names its requests with: read
+  // in UTC, for an hour after midnight at UTC+1 a lesson dated today was refused as in the future, and the loop-backs
+  // it answered, dated today, went on being reported.
+  const today = localDay(new Date().toISOString());
   const files = existsSync(pillsDir) ? await pillFiles(pillsDir) : [];
 
   if (files.length === 0) return { files: 0, active: 0, retired: 0, problems: [], notes: [], pills: [] };