@xhulz/nina 0.58.1 → 0.60.0

package/releases/0.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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.60.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/learn.mjs

@@ -281,14 +281,26 @@ function wilson(k, n) {
  *
  * A round is counted sent back once, however many loop-backs sent it: the checkers that run beside each other
  * each reject the same work, and one project's architect had 14 loop-backs on a day it ran 7 rounds, which the
- * share read as 100% sent back where 5 of the 7 were. Loop-backs that the same dispatch took back are one.
+ * share read as 100% sent back where 5 of the 7 were. Each loop-back is charged to the round its work came from:
+ * the stage's newest round before it, in its session.
+ *
+ * The change is read on first attempts: the rounds that did not take back work sent back to the stage. A fix is
+ * sent back far more often than new work, and how many of a stage's rounds are fixes moves with the work — one
+ * project's architect wrote first specs the week before its lessons and corrected hard ones the week after, 22 of
+ * 23 rounds, and its share went from 14% to 84%, read as the lessons making it worse, while its corrections were
+ * sent back as often as before (60% and 55%). Nor can the two be read side by side: a fix exists because a round
+ * before it failed, so a lesson that works leaves fewer of them, and a comparison that waited on both read the
+ * lessons that worked as unclear. The fixes are shown, not judged.
  *
  * @param {object[]} records - Recorded dispatches.
  * @param {Awaited<ReturnType<typeof lessons>>} known - The project's pills.
  * @param {{owners?: ReturnType<typeof sentBackTo>, targets?: Set<string>|null}} [graph] - Who each loop-back sent
  *   work back to, and the stages the graph sends work back to at all.
  * @returns {{rel: string, date: string, role: string, comparable: boolean, why?: string, on?: string|null,
- *   was?: string, before?: Side, after?: Side, change?: 'lower'|'higher'|'unclear', control?: {before: Side, after: Side}}[]}
+ *   was?: string, before?: Side, after?: Side, first?: {before: Side, after: Side}, fixes?: {before: Side, after: Side},
+ *   thin?: boolean, change?: 'lower'|'higher'|'unclear', control?: {before: Side, after: Side}}[]}
+ *   `before` and `after` are all its rounds, `first` its first attempts, `fixes` the rounds that took back its work;
+ *   `thin` says the first attempts were too few either side to read a change, which is then `unclear`.
  *   A `Side` is `{n, loops, span}`: the stage's rounds, how many were sent back, and the first and last day a round
  *   of it was recorded on, since a project younger than the window has fewer days than fourteen to show.
  */
@@ -296,6 +308,8 @@ export function verified(records, known, { owners = new Map(), targets = null }
   const out = [];
   const ownerOf = (r) => chargedTo(owners, r);
   const sentBack = records.filter((r) => readable(r.verdict) && isLoopBack(r.verdict));
+  const fixes = new Set([...owners.values()].map((o) => o.fix).filter(Boolean));
+  const byTime = (a, b) => String(a.ts).localeCompare(String(b.ts));
   const sideOf = (these, backs) => {
     const days = these.map((r) => day(r.ts)).sort();
     return { n: these.length, loops: Math.min(these.length, sendings(owners, backs)), span: [days[0] ?? null, days.at(-1) ?? null] };
@@ -312,8 +326,21 @@ export function verified(records, known, { owners = new Map(), targets = null }
         out.push({ ...base, comparable: false, why: `nothing in the graph sends work back to ${role}` });
         continue;
       }
-      const rounds = records.filter((r) => r.role === role && readable(r.verdict));
+      const rounds = records.filter((r) => r.role === role && readable(r.verdict)).sort(byTime);
       const backs = sentBack.filter((r) => ownerOf(r) === role);
+      // The round a loop-back sent back: its own record, where the graph routes it nowhere and it is charged to the stage
+      // that gave it; else the stage's round that had finished, in its session, when the loop-back's stage began — read
+      // over every round of it, so one whose verdict cannot be read takes the charge, uncounted, rather than an older one.
+      const all = records.filter((r) => r.role === role).sort(byTime);
+      const sourceOf = (b) => {
+        if (!owners.has(b)) return b;
+        return all.findLast((r) => r.session && r.session === b.session && String(r.result_ts ?? r.ts) <= String(b.ts)) ?? null;
+      };
+      const sentRounds = new Set(backs.map(sourceOf).filter(Boolean));
+      const counted = (these) => {
+        const days = these.map((r) => day(r.ts)).sort();
+        return { n: these.length, loops: these.filter((r) => sentRounds.has(r)).length, span: [days[0] ?? null, days.at(-1) ?? null] };
+      };
       const side = (pick, mine) => sideOf(mine.filter(pick), backs.filter(pick));
       if (side(pre, rounds).n < VERIFY_MIN || side(post, rounds).n < VERIFY_MIN) {
         const [b, a] = [side(pre, rounds).n, side(post, rounds).n];
@@ -326,21 +353,24 @@ export function verified(records, known, { owners = new Map(), targets = null }
       for (const r of rounds.filter(post)) if (ranOn(r)) tally.set(ranOn(r), (tally.get(ranOn(r)) ?? 0) + 1);
       const on = [...tally].sort((x, y) => y[1] - x[1])[0]?.[0] ?? null;
       const mine = on ? rounds.filter((r) => ranOn(r) === on) : rounds;
-      const before = side(pre, mine);
-      const after = side(post, mine);
+      const before = counted(mine.filter(pre));
+      const after = counted(mine.filter(post));
       if (before.n < VERIFY_MIN || after.n < VERIFY_MIN) {
         const was = [...new Set(rounds.filter(pre).map(ranOn).filter(Boolean))].join(', ') || 'no recorded model';
         out.push({ ...base, on, was, comparable: false, why: `${role} ran on ${on} after it, and before it on ${was}` });
         continue;
       }
-      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 first = { before: counted(mine.filter((r) => pre(r) && !fixes.has(r))), after: counted(mine.filter((r) => post(r) && !fixes.has(r))) };
+      const fixed = { before: counted(mine.filter((r) => pre(r) && fixes.has(r))), after: counted(mine.filter((r) => post(r) && fixes.has(r))) };
+      const thin = first.before.n < VERIFY_MIN || first.after.n < VERIFY_MIN;
+      const [bLo, bHi] = wilson(first.before.loops, first.before.n);
+      const [aLo, aHi] = wilson(first.after.loops, first.after.n);
+      const change = thin ? 'unclear' : aHi < bLo ? 'lower' : aLo > bHi ? 'higher' : 'unclear';
       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));
-      out.push({ ...base, comparable: true, on, before, after, change, control: { before: control(pre), after: control(post) } });
+      out.push({ ...base, comparable: true, on, before, after, first, fixes: fixed, thin, change, control: { before: control(pre), after: control(post) } });
     }
   }
   return out;
@@ -1184,10 +1214,11 @@ export async function learn(argv, ctx) {
   const unmeasured = checks.filter((c) => !c.comparable);
   if (measured.length === 0) console.log(`  verify    no lesson could be measured yet — ${VERIFY_MIN}+ rounds of its stage on the same model are needed in the ${VERIFY_DAYS} days either side of its date`);
   measured.forEach((c, i) => {
-    const said = { lower: 'sent back less since', higher: 'sent back more since', unclear: 'no clear change' }[c.change];
+    const said = c.thin ? 'too few first attempts to tell' : { lower: 'sent back less since', higher: 'sent back more since', unclear: 'no clear change' }[c.change];
     console.log(
       `  ${i === 0 ? 'verify  ' : '        '}  ${c.rel.replace(/^\.claude\/pills\//, '')} (${c.date}) · ${c.role}${c.on ? `, on ${c.on}` : ''}: ` +
-        `${pct(c.before.loops, c.before.n)} → ${pct(c.after.loops, c.after.n)} of its rounds sent back (n ${c.before.n} → ${c.after.n}) — ${said}; ` +
+        `${pct(c.first.before.loops, c.first.before.n)} → ${pct(c.first.after.loops, c.first.after.n)} of its first attempts sent back (n ${c.first.before.n} → ${c.first.after.n}) — ${said}; ` +
+        `its fixes ${pct(c.fixes.before.loops, c.fixes.before.n)} → ${pct(c.fixes.after.loops, c.fixes.after.n)}; ` +
         `the other stages ${pct(c.control.before.loops, c.control.before.n)} → ${pct(c.control.after.loops, c.control.after.n)}`,
     );
   });

package/src/commands/upgrade.mjs

@@ -13,7 +13,7 @@ import { readFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { describeMove, HARNESS, interruptedMove, movedFrom, moveJournal, readProfile, surfacesIn } from '../paths.mjs';
 import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { REMOVED, composeProject, composedPaths, defaultedSlots, layerRootFor, walk } from './compose.mjs';
 import { detected, missingNeeds } from '../surfaces.mjs';
 import { filledSlots, projectSlots, referencedVocabulary } from './check.mjs';
@@ -22,6 +22,7 @@ import { closeAnswered } from './learn.mjs';
 import { tidyRetired } from './pills.mjs';
 import { lacksPackage, missingFragment, missingWiring, shippedScripts } from '../wiring.mjs';
 import { runSteps } from '../steps.mjs';
+import { granted } from '../tools.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
 
 /** What stops a move from outside it: Ctrl-C, a `kill`, the terminal closing. */
@@ -641,6 +642,27 @@ export async function upgrade(argv, ctx) {
       console.log(`\n  ${newVocab.length} vocabulary name(s) ${to} asks for and this profile does not answer — fill each, or defer it with why:`);
       console.log(`      ${newVocab.join(', ')}`);
     }
+    // Claude Code reads which agents exist, and each one's tools, when a session starts, and an agent's body on every
+    // dispatch. A session left open runs the new specs with the old tools, and a rule that asks for a tool its stage was
+    // only now given goes unfollowed without a word.
+    const restaged = [];
+    for (const p of [...pathsAfter].sort()) {
+      const rel = p.split(sep).join('/');
+      if (!/^\.claude\/agents\/[^/]+\.md$/.test(rel) || !entryAt(p)) continue;
+      const role = rel.slice('.claude/agents/'.length, -'.md'.length);
+      if (!pathsBefore.has(p) || !saved.has(p)) {
+        restaged.push(`${role}: a new stage`);
+        continue;
+      }
+      const was = granted(saved.get(p).toString('utf8'));
+      const now = granted(readFileSync(join(target, p), 'utf8'));
+      const change = [...now.filter((t) => !was.includes(t)).map((t) => `+${t}`), ...was.filter((t) => !now.includes(t)).map((t) => `-${t}`)];
+      if (change.length > 0) restaged.push(`${role}: ${change.join(', ')}`);
+    }
+    if (restaged.length > 0) {
+      console.log(`\n  ${restaged.length} stage(s) a session already open does not have as ${to} composes them — Claude Code reads which agents exist, and their tools, when a session starts. Open a new one before the next dispatch:`);
+      for (const r of restaged) console.log(`      ${r}`);
+    }
     console.log('');
     return 0;
   }

package/src/dashboard.html

@@ -232,7 +232,8 @@ const RENDER = {
     // Lessons written the same day for the same stage are read over the same rounds, so they are one comparison, not
     // a row each repeating its numbers.
     const groups = [];
-    for (const c of d.checks.filter((x) => x.before)) {
+    // A payload from before first attempts were read: its rounds stand in for them, and none is marked a fix.
+    for (const c of d.checks.filter((x) => x.before).map((x) => ({ fixes: { before: { n: 0, loops: 0, span: [null, null] }, after: { n: 0, loops: 0, span: [null, null] } }, first: { before: x.before, after: x.after }, ...x }))) {
       const same = groups.find((g) => g.role === c.role && g.date === c.date && g.on === c.on);
       if (same) same.lessons.push(c.rel);
       else groups.push({ ...c, lessons: [c.rel] });
@@ -247,11 +248,14 @@ const RENDER = {
     // The share is of work sent back, so up is worse. A move the rounds are too few to tell from chance still says
     // which way it went: "could be chance" alone read, beside 33% → 67%, as if the larger number were the better one.
     const share = (side) => (side.n ? Math.round((100 * side.loops) / side.n) : 0);
+    // Read on first attempts: a fix is sent back more often than new work, and a week of fixes after a week of first
+    // specs read as a lesson making its stage worse.
     const verdict = (g) =>
-      g.change === 'lower' ? ['ok', '▼ better: sent back less']
+      g.thin ? ['faint', '≈ too few first attempts to tell']
+      : g.change === 'lower' ? ['ok', '▼ better: sent back less']
       : g.change === 'higher' ? ['bad', '▲ worse: sent back more']
-      : share(g.after) > share(g.before) ? ['faint', '▲ sent back more, but could be chance']
-      : share(g.after) < share(g.before) ? ['faint', '▼ sent back less, but could be chance']
+      : share(g.first.after) > share(g.first.before) ? ['faint', '▲ sent back more, but could be chance']
+      : share(g.first.after) < share(g.first.before) ? ['faint', '▼ sent back less, but could be chance']
       : ['faint', '≈ no change'];
 
     const answer = !groups.length
@@ -277,9 +281,12 @@ const RENDER = {
         g.on ? el('span', { class: 'faint mono' }, g.on) : null,
         el('span', { class: `verdict ${verdict(g)[0]}` }, verdict(g)[1]),
       ),
-      el('div', { class: 'faint', style: 'font-size:12px;margin:0 0 2px' }, `share of the ${g.role}'s rounds sent back to it · lower is better`),
-      meter('before', g.before),
-      meter('after', g.after),
+      el('div', { class: 'faint', style: 'font-size:12px;margin:0 0 2px' }, `share of the ${g.role}'s first attempts sent back to it · lower is better`),
+      // Too few to tell is drawn faint, so a 100% of one round does not read as a result.
+      el('div', { style: g.thin ? 'opacity:.45' : '' }, meter('before', g.first.before), meter('after', g.first.after)),
+      el('div', { class: 'faint', style: 'font-size:12px;margin:6px 0 0' },
+        `its fixes of work sent back, shown, not judged: ${pct(g.fixes.before.loops, g.fixes.before.n)} of ${g.fixes.before.n} → ${pct(g.fixes.after.loops, g.fixes.after.n)} of ${g.fixes.after.n}. ` +
+          'A fix is sent back more often than new work, and a lesson that works leaves fewer of them.'),
       el('div', { class: 'faint', style: 'margin:6px 0 8px' }, `for reference, the other stages over the same days: ${pct(g.control.before.loops, g.control.before.n)} → ${pct(g.control.after.loops, g.control.after.n)}`),
       el('div', { class: 'chips' }, g.lessons.map(lessonChip)),
     );
@@ -310,7 +317,7 @@ const RENDER = {
       ),
       d.late.length ? [el('h3', {}, 'capture · sent back with nothing written down'), d.late.map((o) => el('div', { class: 'note' }, el('span', { class: 'role' }, o.role), ` sent back ${o.count} time(s) ${o.since ? `since its newest lesson (${o.since})` : 'and no lesson at all'}`, el('ul', { class: 'list soft' }, o.recent.map((r) => el('li', {}, `${when(r.ts)} · ${r.desc ?? '(no description)'}`)))))] : null,
       el('h3', {}, 'verify · is each stage sent back less since its lessons?'),
-      el('p', { class: 'note soft', style: 'margin-bottom:12px' }, `For each lesson, the share of its stage's rounds that a later stage sent back, in the ${d.window} days before it was written and the ${d.window} after — lower is better. A change is called only when it is larger than chance moves a share at that many rounds. The other stages, over the same days, say whether everything moved at once: then it was the work that changed, not the lesson.`),
+      el('p', { class: 'note soft', style: 'margin-bottom:12px' }, `For each lesson, the share of its stage's first attempts that a later stage sent back, in the ${d.window} days before it was written and the ${d.window} after — lower is better. First attempts, because a fix of work already sent back is sent back more often, and a week of fixes after a week of new work would read as the lesson making things worse. A change is called only when it is larger than chance moves a share at that many rounds. The other stages, over the same days, say whether everything moved at once: then it was the work that changed, not the lesson.`),
       groups.length ? groups.map(comparison) : el('p', { class: 'note faint' }, 'No lesson could be measured yet.'),
       d.owed.length ? [el('h3', {}, 'to graduate · here or in the harness'), d.owed.map((o) => el('p', { class: 'note' }, el('span', { class: 'mono' }, o.rel), o.declined ? el('span', { class: 'soft' }, ` — declined by the harness${o.declined.in ? ` in ${o.declined.in}` : ''}: ${o.declined.why}`) : el('span', { class: 'soft' }, ` — recurred ${o.occurrences} times`)))] : null,
       d.open.length ? [el('h3', {}, 'requests open in the harness'), table(['since', 'pill', 'proposed for'], d.open.map((r) => [el('span', { class: 'mono soft' }, r.date), el('span', { class: 'mono' }, r.pill), r.target]))] : null,

package/src/dashboard.mjs

@@ -87,7 +87,7 @@ export function dashboardTabs(target, ctx) {
         madeHere: d.madeHere,
         relapses: d.relapses.map(({ lesson, request, recurred, due }) => ({ rel: lesson.rel, recurred, due, target: request.target, rule_in: request.rule_in, answered_in: request.answered_in })),
         use: d.use,
-        checks: d.checks.map((c) => (c.comparable ? { rel: c.rel, role: c.role, date: c.date, on: c.on ?? null, before: c.before, after: c.after, change: c.change, control: c.control } : { rel: c.rel, role: c.role, why: c.why })),
+        checks: d.checks.map((c) => (c.comparable ? { rel: c.rel, role: c.role, date: c.date, on: c.on ?? null, before: c.before, after: c.after, first: c.first, fixes: c.fixes, thin: c.thin, change: c.change, control: c.control } : { rel: c.rel, role: c.role, why: c.why })),
         activity: d.activity,
         gated: d.gated,
       };

package/src/office.html

@@ -1196,7 +1196,7 @@ function drawScreen(now) {
   }
   {
     const [x, y] = at(COUNTER.x + COUNTER.w / 2, COUNTER.y + 6);
-    plate('reception', x, y, label, '#fff8e8', (COUNTER.w - 8) * scale);
+    plate('orchestrator', x, y, label, '#fff8e8', (COUNTER.w - 8) * scale);
     // NINA's name goes with her, beside her head, wherever she carries the work.
     const [ninaX, ninaY] = at(boss.x + 7, boss.y - 9);
     s.font = `600 ${label}px ${SANS}`;