@xhulz/nina 0.62.0 → 0.63.1

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

package/releases/0.63.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.63.1/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.63.1/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.63.1/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.63.1/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.63.1/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.63.1/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.63.1/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.63.1/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.63.1/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/sizes.mjs

@@ -0,0 +1,356 @@
+/**
+ * `nina sizes` — each step's forecast against what it landed: the `Size:` line its step file carried before it was
+ * built, beside the lines of code its commits added, the rate that measures, and the steps still to land forecast
+ * again at it.
+ *
+ * The architect forecasts each step (`Size: ~N lines in M files`) and splits past the step limit, and until this
+ * nothing compared a forecast with what landed. In the project that asked for it, two steps landed about 1.5× their
+ * forecasts before a reviewer worked the factor out by hand, and a whole architect run — 28 minutes, 375k tokens —
+ * then re-derived the rates from `git diff --numstat` to re-forecast six steps. Measured at each commit, that is a
+ * line; and as a detector (`--check`) it speaks when the newest step overran and the steps after it still carry the
+ * forecasts made before it landed, so the re-forecast is set off by the data rather than noticed.
+ *
+ * A step is its file, `.claude/plans/specs/<spec>.step-<n>.md`; its commits are those whose message names the spec and
+ * `step <n>`, as the router asks a commit to; what it landed is the lines they added outside the harness's own files.
+ *
+ *   nina sizes [--project <dir>] [--check]
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HARNESS } from '../paths.mjs';
+import { defaultVocabulary } from '../vocabulary.mjs';
+import { amber, bold, dim, pink } from '../look.mjs';
+
+const PACKAGE = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** Where the architect writes a spec's steps. */
+const SPECS = join('.claude', 'plans', 'specs');
+
+/** A landed step past its forecast by more than this sets off the detector. */
+export const OVERRUN = 1.25;
+
+/** How many of a spec's newest landed steps its rate is measured over. */
+const RATE_OVER = 5;
+
+/** Files a step's commit carries that are not the step's code: the harness's own, and lockfiles. */
+const NOT_CODE = /^(\.claude\/|\.nina\/|CLAUDE\.md$)|(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?)$/;
+
+/**
+ * The forecast a step file states, from its `Size:` line.
+ *
+ * @param {string} text - A step file.
+ * @returns {{lines: number, files: number|null}|null}
+ */
+export function forecastIn(text) {
+  const m = /\bSize:[*_\s]*~?\s*(\d[\d,]*)\s*lines?\b([^\n]*)/i.exec(text);
+  if (!m) return null;
+  const files = /^[^.;]*?\bin\s+(\d+)\s+files?\b/i.exec(m[2]);
+  return { lines: Number(m[1].replace(/,/g, '')), files: files ? Number(files[1]) : null };
+}
+
+/** Runs git in the project, or says it could not. */
+function git(dir, args) {
+  const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+/**
+ * Many files at many revisions, read by one git process: `<rev>:<path>` → its text, or null where it did not exist.
+ * The detector runs on every turn, and a process a version came to most of its second.
+ *
+ * @param {string} dir
+ * @param {string[]} wanted
+ * @returns {Map<string, string|null>}
+ */
+function blobs(dir, wanted) {
+  const keys = [...new Set(wanted)];
+  const out = new Map(keys.map((k) => [k, null]));
+  if (keys.length === 0) return out;
+  const r = spawnSync('git', ['-C', dir, 'cat-file', '--batch'], { input: `${keys.join('\n')}\n`, maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) return out;
+  const buffer = r.stdout;
+  let at = 0;
+  for (const key of keys) {
+    const end = buffer.indexOf(10, at);
+    if (end === -1) break;
+    const header = /^\S+ (\S+) (\d+)$/.exec(buffer.toString('utf8', at, end));
+    at = end + 1;
+    // `<rev>:<path> missing` carries no body.
+    if (!header) continue;
+    const size = Number(header[2]);
+    if (header[1] === 'blob') out.set(key, buffer.toString('utf8', at, at + size));
+    at += size + 1;
+  }
+  return out;
+}
+
+/** Each commit's code: the lines it added to each file that is not the harness's own, read by one git process. */
+function codeOf(dir, hashes) {
+  const out = new Map(hashes.map((h) => [h, new Map()]));
+  if (hashes.length === 0) return out;
+  for (const block of (git(dir, ['show', '--no-renames', '--numstat', '--format=%x00%H', ...hashes]) ?? '').split('\0').filter((b) => b.trim())) {
+    const [hash, ...rows] = block.split('\n');
+    const code = out.get(hash.trim());
+    if (!code) continue;
+    for (const row of rows) {
+      const [added, , path] = row.split('\t');
+      if (!path || added === '-' || NOT_CODE.test(path)) continue;
+      code.set(path, (code.get(path) ?? 0) + Number(added));
+    }
+  }
+  return out;
+}
+
+/** The commits that changed each of these files, newest first, read by one git process. */
+function changesTo(dir, paths) {
+  const out = new Map(paths.map((p) => [p, []]));
+  if (paths.length === 0) return out;
+  for (const block of (git(dir, ['log', '--no-renames', '--format=%x00%H%x09%ct', '--name-only', 'HEAD', '--', ...paths]) ?? '').split('\0').filter((b) => b.trim())) {
+    const [head, ...names] = block.split('\n');
+    const [hash, seconds] = head.split('\t');
+    for (const name of names) out.get(name.trim())?.push({ hash, t: Number(seconds) * 1000 });
+  }
+  return out;
+}
+
+/** A text as a pattern that matches it literally. */
+const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Whether a commit message names this step of this spec: `step 10e2` names neither `step 10e2a` nor `step 10`, and
+ * `1.6-spec-c` is not `1.6-spec-c2`.
+ */
+export function names(subject, spec, step) {
+  const whole = '(?![\\w.-]*\\w)';
+  return (
+    new RegExp(`(^|[^\\w.-])${literal(spec)}${whole}`, 'i').test(subject) && new RegExp(`\\bstep[\\s-]+${literal(step)}${whole}`, 'i').test(subject)
+  );
+}
+
+/** The step files in the working tree, as `{path, spec, step}`, in their natural order. */
+function stepFiles(dir) {
+  const root = join(dir, SPECS);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const entry of readdirSync(root, { recursive: true })) {
+    const m = /^(.*)\.step-([^/\\]+)\.md$/.exec(String(entry).split(/[/\\]/).at(-1));
+    if (!m) continue;
+    out.push({ path: relative(dir, join(root, String(entry))).split(/[/\\]/).join('/'), spec: m[1], step: m[2] });
+  }
+  return out.sort((a, b) => a.spec.localeCompare(b.spec) || a.step.localeCompare(b.step, undefined, { numeric: true }));
+}
+
+/** The middle value. */
+const median = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+/**
+ * Every step with a forecast, landed or not: what it was forecast before it was built, and what its commits added.
+ *
+ * @param {string} dir - The project.
+ * @returns {{steps: object[], limit: number}|null} Null outside a git repository.
+ */
+export function measure(dir) {
+  const profile = (() => {
+    try {
+      return JSON.parse(readFileSync(join(dir, HARNESS, 'profile.json'), 'utf8'));
+    } catch {
+      return {};
+    }
+  })();
+  const limit = Number(profile?.vocabulary?.STEP_LINES) || Number(defaultVocabulary(PACKAGE).STEP_LINES) || 400;
+  // It runs every turn: a project with no step file does not pay for its history.
+  const files = stepFiles(dir);
+  if (files.length === 0) return git(dir, ['rev-parse', '--verify', '--quiet', 'HEAD']) === null ? null : { steps: [], limit };
+  const log = git(dir, ['log', '--format=%H%x09%ct%x09%cI%x09%s', 'HEAD']);
+  if (log === null) return null;
+  // Times as instants: an ISO time carries its zone, and two zones compared as text order wrongly.
+  const commits = log
+    .split('\n')
+    .filter(Boolean)
+    .map((row) => {
+      const [hash, seconds, at, ...rest] = row.split('\t');
+      return { hash, t: Number(seconds) * 1000, at, subject: rest.join('\t') };
+    })
+    .reverse();
+  const order = new Map(commits.map((c, i) => [c.hash, i]));
+  const named = new Map(files.map((f) => [f.path, commits.filter((c) => names(c.subject, f.spec, f.step))]));
+  const code = codeOf(dir, [...new Set([...named.values()].flat().map((c) => c.hash))]);
+  const changes = changesTo(dir, files.map((f) => f.path));
+  const wanted = [];
+  for (const f of files) {
+    wanted.push(`HEAD:${f.path}`);
+    for (const c of changes.get(f.path)) wanted.push(`${c.hash}:${f.path}`);
+    for (const c of named.get(f.path)) wanted.push(`${c.hash}^:${f.path}`, `${c.hash}:${f.path}`);
+  }
+  const text = blobs(dir, wanted);
+  const at = (rev, path) => forecastIn(text.get(`${rev}:${path}`) ?? '');
+  // When a forecast was written: the oldest commit of the newest run, before a point in history, that carried it. An
+  // edit to the rest of the step file is not a forecast. Null where no commit is found to carry it.
+  const writtenAt = (path, before, lines) => {
+    let when = null;
+    for (const c of changes.get(path)) {
+      if ((order.get(c.hash) ?? -1) >= before) continue;
+      if (at(c.hash, path)?.lines !== lines) break;
+      when = c.t;
+    }
+    return when;
+  };
+  const steps = [];
+  for (const file of files) {
+    const now = forecastIn(readFileSync(join(dir, file.path), 'utf8'));
+    const landings = named.get(file.path).filter((c) => code.get(c.hash)?.size > 0);
+    if (landings.length === 0) {
+      if (!now) continue;
+      // Forecast again in the working tree, it is newer than every commit.
+      const since = at('HEAD', file.path)?.lines === now.lines ? writtenAt(file.path, Infinity, now.lines) : Infinity;
+      steps.push({ ...file, landed: false, forecast: now, since });
+      continue;
+    }
+    // The forecast the step was built to: its file before its first commit, or as that commit wrote it.
+    const first = landings[0];
+    const before = at(`${first.hash}^`, file.path);
+    const forecast = before ?? at(first.hash, file.path);
+    if (!forecast) continue;
+    const since = (before ? writtenAt(file.path, order.get(first.hash), forecast.lines) : null) ?? first.t;
+    const lines = new Map();
+    for (const c of landings) for (const [path, added] of code.get(c.hash)) lines.set(path, (lines.get(path) ?? 0) + added);
+    const total = [...lines.values()].reduce((a, n) => a + n, 0);
+    const last = landings.at(-1);
+    // A forecast changed while the step was built — a fix round's spec — is shown, and the step measured against the first.
+    const revised = at(last.hash, file.path);
+    steps.push({
+      ...file,
+      landed: true,
+      forecast,
+      revised: revised && revised.lines !== forecast.lines ? revised : null,
+      since,
+      lines: total,
+      files: lines.size,
+      ratio: total / forecast.lines,
+      t: last.t,
+      at: last.at,
+      hash: last.hash,
+    });
+  }
+  return { steps, limit };
+}
+
+/**
+ * The rate to forecast a step again at: the median actual over forecast of its spec's newest landed steps forecast no
+ * earlier than it was. A step forecast before the last re-forecast was measured against the old rates, which that
+ * re-forecast already corrected for, and counting it would correct for them twice.
+ *
+ * @param {object[]} steps
+ * @param {{spec: string, since?: string}} step - Its spec, and when its own forecast was written.
+ * @returns {{rate: number, over: number}|null}
+ */
+export function rateOf(steps, { spec, since }) {
+  // A forecast not known to be written when is measured by nothing, rather than by everything.
+  if (since === null || since === undefined) return null;
+  const landed = steps
+    .filter((s) => s.landed && s.spec === spec && s.since >= since)
+    .sort((a, b) => a.t - b.t)
+    .slice(-RATE_OVER);
+  return landed.length ? { rate: median(landed.map((s) => s.ratio)), over: landed.length } : null;
+}
+
+/**
+ * What the detector says: the newest landed step, when it overran, and the steps of its spec still forecast as they
+ * were when it landed.
+ *
+ * @param {string} dir
+ * @param {{steps: object[], limit: number}} measured
+ * @returns {{step: object, rate: {rate: number, over: number}, stale: object[]}|null}
+ */
+export function overrun({ steps }) {
+  const newest = steps.filter((s) => s.landed).sort((a, b) => a.t - b.t).at(-1);
+  if (!newest || newest.ratio <= OVERRUN) return null;
+  // Forecast no later than the overrun step was, so its rate measures them: forecast again since, they are not stale.
+  const stale = steps.filter((s) => !s.landed && s.spec === newest.spec && s.since !== null && s.since <= newest.since);
+  return stale.length ? { step: newest, rate: rateOf(steps, stale[0]), stale } : null;
+}
+
+const times = (x) => `×${x.toFixed(2)}`;
+
+/**
+ * `nina sizes`.
+ *
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+export async function sizes(argv) {
+  const arg = (name) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : null);
+  const dir = resolve(arg('--project') ?? '.');
+  const check = argv.includes('--check');
+  if (!existsSync(join(dir, HARNESS, 'profile.json'))) {
+    console.error(`  no ${HARNESS}/profile.json under ${dir} — run it inside a project, or name one with --project\n`);
+    return check ? 0 : 1;
+  }
+  const measured = measure(dir);
+  if (measured === null) {
+    if (check) console.log('sizes: current');
+    else console.error('  not a git repository, or one with no commit yet: a step is measured by its commits\n');
+    return check ? 0 : 1;
+  }
+  const { steps, limit } = measured;
+  if (check) {
+    // During `nina upgrade --apply`: a step that overran is the project's history, not the move — and the release that
+    // first shipped this detector rolled itself back in the project that asked for it. The move says it after.
+    if (process.env.NINA_UPGRADE) {
+      console.log('sizes: current');
+      return 0;
+    }
+    const found = overrun(measured);
+    if (!found) {
+      console.log('sizes: current');
+      return 0;
+    }
+    const { step, rate, stale } = found;
+    const again = stale.slice(0, 4).map((s) => {
+      const next = Math.round(s.forecast.lines * rate.rate);
+      return `${s.step} ~${s.forecast.lines} → ~${next}${next > limit ? ` (past ${limit}: split)` : ''}`;
+    });
+    console.log(
+      `step ${step.step} of ${step.spec} landed ${step.lines} lines against ~${step.forecast.lines} (${times(step.ratio)}); ` +
+        `${stale.length} step(s) forecast when it was have not been forecast again — at ${times(rate.rate)}, over ${rate.over} landed step(s) forecast the same way: ` +
+        `${again.join(', ')}${stale.length > again.length ? ', …' : ''}`,
+    );
+    return 1;
+  }
+  if (steps.length === 0) {
+    console.log(`  no step file under ${SPECS} states a \`Size:\` line yet\n`);
+    return 0;
+  }
+  for (const spec of [...new Set(steps.map((s) => s.spec))]) {
+    const mine = steps.filter((s) => s.spec === spec);
+    console.log(`\n  ${bold(pink(spec))}${dim(`  landed against the forecast it was built to; limit ${limit} lines`)}`);
+    for (const s of mine.filter((x) => x.landed).sort((a, b) => a.t - b.t)) {
+      const mark = s.ratio > OVERRUN ? amber(times(s.ratio)) : times(s.ratio);
+      const files = s.forecast.files === null ? `${s.files} file(s)` : `${s.files} file(s) of ${s.forecast.files}`;
+      const revised = s.revised ? `, revised to ~${s.revised.lines} while built` : '';
+      console.log(`    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} → ${String(s.lines).padEnd(5)} ${mark}  ${dim(`${files}${revised} · ${s.hash.slice(0, 7)} ${s.at.slice(0, 10)}`)}`);
+    }
+    for (const s of mine.filter((x) => !x.landed)) {
+      const rate = rateOf(steps, s);
+      if (!rate) {
+        console.log(`    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} ${dim('to land — forecast after every step that landed, so none measures it yet')}`);
+        continue;
+      }
+      const next = Math.round(s.forecast.lines * rate.rate);
+      console.log(
+        `    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} → ~${String(next).padEnd(5)} ` +
+          dim(`to land, at ${times(rate.rate)} over ${rate.over} step(s) forecast as it was`) +
+          (next > limit ? amber(`  past ${limit}: split`) : ''),
+      );
+    }
+  }
+  console.log('');
+  return 0;
+}

package/src/commands/upgrade.mjs

@@ -631,6 +631,11 @@ export async function upgrade(argv, ctx) {
       console.log('\n  the learning cycle has something to act on — not caused by this move, now visible:');
       for (const line of lessons.out.trim().split('\n')) console.log(`    ${line}`);
     }
+    const forecasts = nina(ctx, target, ['sizes', '--project', target, '--check']);
+    if (!forecasts.ok && forecasts.out.trim()) {
+      console.log('\n  a step landed past its forecast — not caused by this move, now visible:');
+      for (const line of forecasts.out.trim().split('\n')) console.log(`    ${line}`);
+    }
     // The move is done and the tree is sound, but it is not finished: until these are written
     // the composed text is quietly missing what they carry, which is the failure this harness
     // exists to remove. A success line that did not say so would be the same silence.