@xhulz/nina 0.79.0 → 0.81.0

package/releases/0.81.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.81.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.81.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.81.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.81.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.81.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.81.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.81.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.81.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.81.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. **A test that proves a value stays out matches by containment** (`String(v).includes(value)`), never by equality: a leak arrives inside an id, a message or a key. It gives each log call in the source a run, counts the console's calls by method and asserts each method the path must not use at zero, and reads at least what the console prints of each entry and each error the runs produce, recursively: every own key, symbols and non-enumerable ones too (`Reflect.ownKeys`), and the entries of every `Map`, `Set`, `Headers` and `URLSearchParams`, unless the spec rules one out in writing. Its controls put their value where the real emitter puts its own, past a call's first argument and among several, and the spec names the window its spy covers and why nothing logs after it. Its forbidden values are the run's own that § *Privacy* keeps out — where it lists what may be logged, every other value the run carries — each with a control that embeds it in a longer string under an allowed key and must fail the check, and no fixture value inside another's.<!-- nina:why --> In one project an allowlist check that refused only equal values passed a mutant logging `${id}:${amount}`; the next read `Object.keys` and missed an amount on a non-enumerable property and an info log no row inspected; the one after left out a class and four log paths.<!-- /nina:why --> Where what it claims to keep out names a class — an attribute, an amount — it covers every member: a surface with open-ended slots is read whole, never through a list of them — every attribute of every element a rendered page carries, just as every property of an error is — and a sweep that read nothing fails; each forbidden value is looked for in every form the code can give it, formatted and raw; and each state that shows, hides or replaces a value is swept on its own, the one built to withhold it most of all. One mutant puts the value in a slot the check does not name — `data-x` on a page; on an object or an error, a non-enumerable key, a symbol key, a nested object, a `Map` entry, `cause`, the end of `message` or `stack` — and one per field puts that field's raw value in each such slot, on every error the code throws, not only one it builds: one left green is a slot or a form the check misses. The implementer runs them on its mirror, as one block it reuses, before `DIFF-READY`, whatever the step lists, and reports one left green as the row the spec lacks (Hard Rule #17), adding it only in a file the step authorizes.<!-- nina:why --> In one project a walk of own keys missed a `Map`, a symbol key and a nested object, and every control put its value in a call's first argument, where the runtime's loggers put theirs second; then three steps in two days went back from review for a slot no listed mutant tried — an error's `cause`, its `stack`, a hidden key.<!-- /nina:why --><!-- nina:why --> In one project a sweep of `data-testid`, `aria-label` and `title`, proven by mutants in those three, stayed green with the label in a `data-label`; the next swept every attribute for the formatted amounts and missed their raw centavos; the one after swept only the state that shows the figure, and the row built to show none carried it in a `title`.<!-- /nina:why --> 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.81.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.81.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.81.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.81.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.81.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.81.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.81.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.81.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

@@ -17,7 +17,7 @@ import { HOOK_SCRIPTS, missingWiring, shippedScripts } from '../wiring.mjs';
 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 { PLACEHOLDER, defaultVocabulary, tierProblem } from '../vocabulary.mjs';
 import { missingNeeds } from '../surfaces.mjs';
 import { resolveCitation } from './pills.mjs';
 
@@ -489,7 +489,9 @@ export async function check(argv, ctx) {
 
   const referenced = await referencedVocabulary(resolved.dir, surfaces.filter((s) => available.includes(s)), target);
   const declared = profile.vocabulary ?? {};
-  const defaults = defaultVocabulary(resolved.dir);
+  const tierError = tierProblem(resolved.dir, profile.tier, profile.core);
+  if (tierError) problems.push(tierError);
+  const defaults = defaultVocabulary(resolved.dir, profile.tier);
   for (const name of [...referenced].sort()) {
     const unanswered = !(name in declared) ? !(name in defaults) : declared[name] === null || declared[name] === '';
     if (unanswered && expected.has(`{{${name}}}`)) notes.push(`vocabulary {{${name}}} is new in this core and still to fill`);

package/src/commands/compose.mjs

@@ -19,9 +19,9 @@
 import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { HARNESS, deferredWhy, layerRootFor, readProfile } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
-import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { NAME, PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
+import { NAME, PLACEHOLDER, defaultVocabulary, modelsLine, tierProblem } from '../vocabulary.mjs';
 
 export { layerRootFor };
 
@@ -426,7 +426,11 @@ export async function composeProject(target, ctx, options = {}) {
   const resolved = layerRootFor(ctx.root, profile.core);
   if (resolved.error) return { error: resolved.error, written, differ, unfilled: [], skipped };
   const layerRoot = resolved.dir;
-  const defaults = defaultVocabulary(layerRoot);
+  // A tier the pinned release does not have is refused rather than composed as the release's default: the
+  // project asked for other models, and composing these without a word would run every stage on the wrong one.
+  const tierError = tierProblem(layerRoot, profile.tier, profile.core);
+  if (tierError) return { error: tierError, written, differ, unfilled: [], skipped };
+  const defaults = defaultVocabulary(layerRoot, profile.tier);
 
   const coreTree = join(layerRoot, 'core', 'tree');
   const layers = [
@@ -579,16 +583,60 @@ export async function composeProject(target, ctx, options = {}) {
   return { written, differ, unfilled, skipped, malformed, removed };
 }
 
+/**
+ * Records a tier in a project's profile, once the release it pins is known to have it.
+ *
+ * The tier lives in the profile, not on the command line: a flag that only composed would be undone by the
+ * next `compose` without it, and every hook that recomposes runs without it. `tier` goes after `core`, the
+ * release whose tiers it names; the rest of the profile keeps its order.
+ *
+ * @param {string} target - The project directory.
+ * @param {string} tier - The level asked for.
+ * @param {{root: string}} ctx - CLI context.
+ * @returns {{error: string} | {tier: string, from: string|undefined, line: string}}
+ */
+export function setTier(target, tier, ctx) {
+  const { path, profile, error } = readProfile(target);
+  if (error) return { error };
+  const layers = layerRootFor(ctx.root, profile.core);
+  if (layers.error) return { error: layers.error };
+  const problem = tierProblem(layers.dir, tier, profile.core);
+  if (problem) return { error: problem };
+  const from = profile.tier;
+  if (from !== tier) {
+    const entries = Object.entries(profile).filter(([key]) => key !== 'tier');
+    const at = entries.findIndex(([key]) => key === 'core') + 1;
+    entries.splice(at, 0, ['tier', tier]);
+    writeFileSync(path, `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`);
+  }
+  const declared = Object.fromEntries(Object.entries(profile.vocabulary ?? {}).filter(([, value]) => typeof value === 'string'));
+  return { tier, from, line: modelsLine({ ...defaultVocabulary(layers.dir, tier), ...declared }) };
+}
+
 /**
  * `nina compose` — the CLI wrapper around {@link composeProject}.
  *
- * @param {string[]} argv - Command arguments; `--project <dir>` selects the target.
+ * @param {string[]} argv - Command arguments; `--project <dir>` selects the target, `--tier <level>` records the
+ *   project's tier in its profile before composing.
  * @param {{root: string}} ctx - CLI context; `root` is the NINA install directory.
  * @returns {Promise<number>} Process exit code.
  */
 export async function compose(argv, ctx) {
   const target = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : '.');
   const check = argv.includes('--check');
+  const tier = argv.includes('--tier') ? argv[argv.indexOf('--tier') + 1] : undefined;
+  let moved = null;
+  if (tier !== undefined) {
+    if (check) {
+      console.error('  --tier writes the profile, and --check writes nothing: run them one at a time');
+      return 2;
+    }
+    moved = setTier(target, tier, ctx);
+    if (moved.error) {
+      console.error(`  ${moved.error}`);
+      return 1;
+    }
+  }
   const result = await composeProject(target, ctx, { check });
 
   if (result.error) {
@@ -639,6 +687,12 @@ export async function compose(argv, ctx) {
     return bad === 0 ? 0 : 1;
   }
   console.log(`composed ${result.written.length} file(s) → ${relative(process.cwd(), target) || '.'}`);
+  if (moved) {
+    console.log(`  tier ${moved.tier}${moved.from === moved.tier ? ', as it was' : `, was ${moved.from ?? 'not declared'}`} — ${moved.line}`);
+    // Claude Code registers each agent, its frontmatter included, when a session starts; a session left open may
+    // keep the models it registered.
+    if (moved.from !== moved.tier) console.log('  open a new Claude Code session before the next dispatch: one already open may keep the models it started with');
+  }
   if (result.removed.length > 0) {
     console.log(`  removed ${result.removed.length} file(s) composed for a surface this profile no longer declares — a copy of each is in ${REMOVED}/:`);
     for (const rel of result.removed) console.log(`    ${rel}`);

package/src/commands/eval.mjs

@@ -2,6 +2,7 @@
  * `nina eval` — does a release's reviewer catch more of a planted set of defects than another's?
  *
  *   nina eval --release 0.23.0 --release 0.24.0 [--repeat 2] [--model <m>] [--judge] [--keep]
+ *   nina eval --release 0.81.0 --tier low --tier high [--repeat 2]
  *   nina eval --release 0.24.0 --dry-run
  *   nina eval --regrade <reports dir> [--judge]
  *
@@ -57,9 +58,10 @@ const IGNORE = ['.claude/*', '!.claude/plans/', '!.claude/code-map.md', '!.claud
 /** How far a cited line may sit from a defect's anchor and still be that defect. */
 const TOLERANCE = 2;
 
-/** The vocabulary the fixture composes with: a plain project, no surfaces. */
-const PROFILE = (core) => ({
+/** The vocabulary the fixture composes with: a plain project, no surfaces, at the tier asked for if any. */
+const PROFILE = (core, tier) => ({
   core,
+  ...(tier !== undefined ? { tier } : {}),
   surfaces: [],
   vocabulary: { OWNER: 'the maintainer', API_DIR: 'src/server', APP_DIR: 'src/web', PKG_SCOPE: '@notes', EMITTING_PKGS: '`core`' },
 });
@@ -171,12 +173,13 @@ export function grade(report, defects) {
  * @param {string} fixture - The eval's directory.
  * @param {string} core - The release to compose.
  * @param {{root: string}} ctx - CLI context.
+ * @param {string} [tier] - The tier to compose it at; its own models when absent.
  * @returns {Promise<string>} The scratch project.
  */
-async function stage(fixture, core, ctx) {
+async function stage(fixture, core, ctx, tier) {
   const dir = mkdtempSync(join(tmpdir(), 'nina-eval-'));
   try {
-    return await build(dir, fixture, core, ctx);
+    return await build(dir, fixture, core, ctx, tier);
   } catch (error) {
     rmSync(dir, { recursive: true, force: true });
     throw error;
@@ -184,7 +187,7 @@ async function stage(fixture, core, ctx) {
 }
 
 /** Fills a scratch directory with the reviewer's world; `stage` removes it if this throws. */
-async function build(dir, fixture, core, ctx) {
+async function build(dir, fixture, core, ctx, tier) {
   cpSync(join(fixture, 'base'), dir, { recursive: true });
   writeFileSync(join(dir, '.gitignore'), IGNORE);
   const git = (...args) => spawnSync('git', ['-c', 'user.name=nina-eval', '-c', 'user.email=eval@nina.invalid', ...args], { cwd: dir, encoding: 'utf8' });
@@ -195,7 +198,7 @@ async function build(dir, fixture, core, ctx) {
   // reviewer reads is the change alone.
   cpSync(join(fixture, 'after'), dir, { recursive: true });
   mkdirSync(join(dir, '.nina'), { recursive: true });
-  writeFileSync(join(dir, '.nina', 'profile.json'), JSON.stringify(PROFILE(core), null, 2));
+  writeFileSync(join(dir, '.nina', 'profile.json'), JSON.stringify(PROFILE(core, tier), null, 2));
   const result = await composeProject(dir, ctx);
   if (result.error) throw new Error(result.error);
   if (!existsSync(join(dir, '.claude', 'agents', 'reviewer.md'))) throw new Error(`core ${core} composed no reviewer into ${dir}`);
@@ -472,6 +475,9 @@ export function reviewerCommand({ model, api }) {
  */
 export async function evalCommand(argv, ctx) {
   const releases = argv.flatMap((a, i) => (a === '--release' ? [argv[i + 1]] : []));
+  // Each release at each tier asked for, or at its own models when none is: an arm is one composition to measure.
+  const levels = argv.flatMap((a, i) => (a === '--tier' ? [argv[i + 1]] : []));
+  const arms = releases.flatMap((core) => (levels.length ? levels.map((tier) => ({ core, tier, label: `${core}@${tier}` })) : [{ core, label: core }]));
   const repeat = Number(argv.includes('--repeat') ? argv[argv.indexOf('--repeat') + 1] : 1);
   const options = {
     model: argv.includes('--model') ? argv[argv.indexOf('--model') + 1] : undefined,
@@ -483,10 +489,15 @@ export async function evalCommand(argv, ctx) {
   const reportsAt = argv.includes('--reports') ? argv[argv.indexOf('--reports') + 1] : null;
   const regrade = argv.includes('--regrade') ? argv[argv.indexOf('--regrade') + 1] : null;
   if ((releases.length === 0 && !regrade) || !Number.isInteger(repeat) || repeat < 1) {
-    console.error('  usage: nina eval --release <version> [--release <version>] [--repeat N] [--model m] [--judge] [--dry-run] [--keep] [--reports <dir>]');
+    console.error('  usage: nina eval --release <version> [--release <version>] [--tier <level>] [--repeat N] [--model m] [--judge] [--dry-run] [--keep] [--reports <dir>]');
     console.error('         nina eval --regrade <reports dir> [--judge]\n');
     return 2;
   }
+  // --model is passed to the reviewer over its spec's model line, so under it two tiers would differ in effort alone.
+  if (levels.length > 0 && options.model) {
+    console.error('  --model runs every reviewer on one model, which is half of what --tier compares: give one or the other\n');
+    return 2;
+  }
 
   const fixture = join(ctx.root, 'evals', 'reviewer');
   const defects = plantedDefects(fixture);
@@ -525,7 +536,7 @@ export async function evalCommand(argv, ctx) {
     return 0;
   }
   control();
-  console.log(`  ${defects.length} planted defects · ${releases.length} release(s) × ${repeat} run(s) · reviewer via \`claude -p\`` +
+  console.log(`  ${defects.length} planted defects · ${releases.length} release(s)${levels.length ? ` × ${levels.length} tier(s)` : ''} × ${repeat} run(s) · reviewer via \`claude -p\`` +
     (options.api ? ' with the API credentials in the environment' : ' on the login, never a per-token key') + '\n');
 
   // Every report is kept, whatever the grade said: a number is only as good as the text behind it, and
@@ -541,13 +552,13 @@ export async function evalCommand(argv, ctx) {
     writeFileSync(join(reports, name), text);
   };
   const results = [];
-  for (const core of releases) {
+  for (const { core, tier, label } of arms) {
     for (let n = 1; n <= repeat; n += 1) {
       let dir;
       try {
-        dir = await stage(fixture, core, ctx);
+        dir = await stage(fixture, core, ctx, tier);
       } catch (error) {
-        console.error(`  ✗ ${core}: ${error.message}`);
+        console.error(`  ✗ ${label}: ${error.message}`);
         return 1;
       }
       try {
@@ -555,7 +566,7 @@ export async function evalCommand(argv, ctx) {
         let report;
         let cost = null;
         if (dry) {
-          console.log(`  dry run — ${core} staged in ${dir}; would run: claude ${args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}`);
+          console.log(`  dry run — ${label} staged in ${dir}; would run: claude ${args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}`);
           report = readFileSync(join(fixture, 'sample-report.md'), 'utf8');
         } else {
           const run = spawnSync('claude', args, { cwd: dir, env, encoding: 'utf8', timeout: 1_800_000, maxBuffer: 64 * 1024 * 1024 });
@@ -563,18 +574,18 @@ export async function evalCommand(argv, ctx) {
           // A run that did not review — not logged in, rate-limited, out of turns — is a failure to report,
           // not a review that caught nothing: graded, it would drag its release's mean down.
           if (failed) {
-            console.error(`  ✗ ${core} run ${n}: ${failed}`);
+            console.error(`  ✗ ${label} run ${n}: ${failed}`);
             return 1;
           }
           const out = JSON.parse(run.stdout);
           report = out.result ?? '';
           cost = typeof out.total_cost_usd === 'number' ? out.total_cost_usd : null;
         }
-        keepReport(`${core}-${n}.md`, report);
+        keepReport(`${label}-${n}.md`, report);
         const graded = grade(report, defects);
         const judged = judging ? judge(defects, report, diff, options) : unjudged;
-        results.push({ core, n, ...graded, cost, judged });
-        console.log(describe(`${core} run ${n}`, graded, defects.length, cost, judged));
+        results.push({ arm: label, n, ...graded, cost, judged });
+        console.log(describe(`${label} run ${n}`, graded, defects.length, cost, judged));
       } finally {
         if (!dry) forgetProject(dir);
         if (!keep) rmSync(dir, { recursive: true, force: true });
@@ -584,28 +595,28 @@ export async function evalCommand(argv, ctx) {
 
   if (reports) console.log(`\n  reports: ${reports}`);
   else console.log('');
-  for (const core of releases) {
-    const runs = results.filter((r) => r.core === core);
+  for (const { label } of arms) {
+    const runs = results.filter((r) => r.arm === label);
     const mean = runs.reduce((a, r) => a + r.caught.length, 0) / runs.length;
     const always = defects.filter((d) => runs.every((r) => !r.caught.includes(d.id))).map((d) => d.id);
     const judged = runs.filter((r) => r.judged && !r.judged.failed && !r.judged.skipped);
     console.log(
-      `  ${core}: caught ${mean.toFixed(1)}/${defects.length} on average over ${runs.length} run(s)` +
+      `  ${label}: caught ${mean.toFixed(1)}/${defects.length} on average over ${runs.length} run(s)` +
         (judged.length
           ? `, ${(judged.reduce((a, r) => a + r.judged.found.length, 0) / judged.length).toFixed(1)} identified by the judge (${judged.length} of ${runs.length} judged${suspect ? ', suspect' : ''})`
           : '') +
         (always.length ? ` — never caught: ${always.join(', ')}` : ''),
     );
   }
-  // Each release against the first, with the widest spread any release showed between its own runs.
-  const counts = releases.map((core) => results.filter((r) => r.core === core).map((r) => r.caught.length));
+  // Each arm against the first, with the widest spread any arm showed between its own runs.
+  const counts = arms.map(({ label }) => results.filter((r) => r.arm === label).map((r) => r.caught.length));
   const mean = (xs) => xs.reduce((x, y) => x + y, 0) / xs.length;
   const spread = Math.max(...counts.map((xs) => Math.max(...xs) - Math.min(...xs)));
-  for (let i = 1; i < releases.length; i += 1) {
+  for (let i = 1; i < arms.length; i += 1) {
     const delta = mean(counts[i]) - mean(counts[0]);
     console.log(
-      `\n  ${releases[i]} − ${releases[0]}: ${delta >= 0 ? '+' : ''}${delta.toFixed(1)} defect(s)` +
-        (repeat > 1 ? `, against a run-to-run spread of ${spread} within a release` : ' — one run each cannot tell a difference from noise'),
+      `\n  ${arms[i].label} − ${arms[0].label}: ${delta >= 0 ? '+' : ''}${delta.toFixed(1)} defect(s)` +
+        (repeat > 1 ? `, against a run-to-run spread of ${spread} within one` : ' — one run each cannot tell a difference from noise'),
     );
   }
   return 0;

package/src/commands/init.mjs

@@ -20,7 +20,7 @@ import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { REQUIRES, SLOT, byVersion, closedGate, composedPaths, composeProject, defaultedSlots, layerRootFor, projectOwned, walk } from './compose.mjs';
 import { owedDocuments } from './check.mjs';
-import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
+import { PLACEHOLDER, defaultVocabulary, tierProblem, tiers } from '../vocabulary.mjs';
 import { DETECTABLE, missingNeeds } from '../surfaces.mjs';
 import { bold, dim, green, pink } from '../look.mjs';
 
@@ -309,6 +309,15 @@ export async function init(argv, ctx) {
     console.error(`  ${resolved.error}\n`);
     return 1;
   }
+  // Asked for, or kept from the profile it replaces; refused before anything is written when the pin has no such tier.
+  const tier = arg('--tier') ?? previous?.tier;
+  const tierError = tierProblem(resolved.dir, tier, core);
+  if (tierError) {
+    // One kept from the profile being replaced is not one the command named, so it says where it came from.
+    const kept = arg('--tier') === null ? ` — the profile being replaced holds it: ${Object.keys(tiers(resolved.dir)).length > 0 ? 'pass --tier with one it has, or ' : ''}take "tier" out of ${HARNESS}/profile.json` : '';
+    console.error(`  ${tierError}${kept}\n`);
+    return 1;
+  }
 
   // Everything below is read from the version this profile will pin — the surfaces that
   // exist, what each one costs, and the slots to fill — so the checklist describes the
@@ -377,7 +386,7 @@ export async function init(argv, ctx) {
 
   // A name the release supplies a default for is not asked: it composes as the default until the
   // project declares it, and the TODO says what the default is so a project on another stack can.
-  const defaults = defaultVocabulary(resolved.dir);
+  const defaults = defaultVocabulary(resolved.dir, tier);
   const defaulted = [...vocabulary].filter((name) => name in defaults).sort();
   for (const name of defaulted) vocabulary.delete(name);
   // What the profile being replaced had filled in, for a name these layers still use or one the release
@@ -388,11 +397,12 @@ export async function init(argv, ctx) {
 
   const profile = {
     core,
+    ...(tier !== undefined ? { tier } : {}),
     surfaces,
     ...(surfaces.includes('integrations') ? { integrations: keptIntegrations } : {}),
     vocabulary: Object.fromEntries([...[...vocabulary].map((name) => [name, null]), ...kept].sort(([a], [b]) => a.localeCompare(b))),
     // Anything else the profile said is the project's, and stays.
-    ...Object.fromEntries(Object.entries(previous ?? {}).filter(([key]) => !['core', 'surfaces', 'integrations', 'vocabulary'].includes(key))),
+    ...Object.fromEntries(Object.entries(previous ?? {}).filter(([key]) => !['core', 'tier', 'surfaces', 'integrations', 'vocabulary'].includes(key))),
   };
 
   await mkdir(join(harness, 'project', 'tree'), { recursive: true });
@@ -596,7 +606,7 @@ export async function init(argv, ctx) {
   for (const w of unwired) console.log(`    to wire    ${w}`);
   if (wired.length || unwired.length) console.log('');
   console.log(`    surfaces:  ${surfaces.join(', ') || '(none)'}`);
-  console.log(`    core:      ${profile.core}`);
+  console.log(`    core:      ${profile.core}${tier !== undefined ? `, tier ${tier}` : ''}`);
   console.log(`    to fill:   ${vocabulary.size} vocabulary entries, ${slots.length} project slots, ${owed.size} document(s)`);
   if (inTheWay.length > 0) {
     console.log(`    composed:  nothing — ${inTheWay.length} file(s) of yours sit where the harness composes one, and would be lost:`);

package/src/commands/status.mjs

@@ -14,10 +14,11 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
-import { readProfile } from '../paths.mjs';
+import { HARNESS, readProfile } from '../paths.mjs';
 import { costOf } from '../prices.mjs';
 import { runOf } from '../transcripts.mjs';
 import { missingWiring, shippedScripts } from '../wiring.mjs';
+import { defaultVocabulary, modelsLine, tierProblem, tiers } from '../vocabulary.mjs';
 import { amber, bold, dim, green, pink } from '../look.mjs';
 import { byVersion, layerRootFor } from './compose.mjs';
 import { filedRequests } from './learn.mjs';
@@ -114,6 +115,15 @@ export async function status(argv, ctx) {
   if (!layers.error) {
     const unwired = await missingWiring(target, await shippedScripts(layers.dir, profile.surfaces ?? []));
     row('hooks', unwired.length === 0 ? green('every hook its release needs is wired') : warn(`${unwired.length} missing — \`nina wire --apply\` merges them`));
+    // What each kind of stage runs on: the tier names it, and a model the project declared itself wins over it.
+    const tierError = tierProblem(layers.dir, profile.tier, pinned);
+    const declared = Object.fromEntries(Object.entries(profile.vocabulary ?? {}).filter(([, value]) => typeof value === 'string'));
+    row(
+      'models',
+      tierError
+        ? warn(`${tierError} — ${Object.keys(tiers(layers.dir)).length > 0 ? '`nina compose --tier <level>` sets one it has' : `take "tier" out of ${HARNESS}/profile.json`}`)
+        : `${profile.tier === undefined ? "the release's own" : `tier ${bold(profile.tier)}`} · ${modelsLine({ ...defaultVocabulary(layers.dir, profile.tier), ...declared })}`,
+    );
   } else {
     row('hooks', warn(layers.error));
   }