@xhulz/nina 0.28.16

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Marcos Schulz. All rights reserved.
+
+The source code in this repository is published so it can be read. No license is granted to use, copy,
+modify, merge, publish, distribute, sublicense or sell it, in whole or in part, without the author's prior
+written permission.
+
+Forking this repository on GitHub is permitted by GitHub's Terms of Service. A fork does not grant any of the
+rights above.

package/README.md

@@ -0,0 +1,406 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="NINA: harness orchestration" width="464">
+</p>
+
+NINA is a command-line compiler for the multi-agent pipeline I run inside Claude Code. It composes that
+pipeline into each project from versioned layers, and it uses hooks to enforce the rules a prompt can only ask
+for. It reads Claude Code's own transcripts to measure what the pipeline did. When the pipeline keeps making
+the same mistake, NINA turns the lesson into a rule in the next release.
+
+## At a glance
+
+- Projects don't copy the harness anymore. Each one pins a frozen release and composes from it. `nina upgrade`
+  moves it forward, checks the result with the project's own detectors, and undoes the move if a check fails.
+- The pipeline is declared as a graph of stages, verdicts and edges, and it's validated on every check. Every
+  loop-back edge has a cap.
+- Hooks count the rounds of each loop. When a dispatch would go past a cap, Claude Code asks the owner first,
+  even in auto mode.
+- The numbers come from transcripts. That's how I found a "mandatory" rule that had been followed 2 times in
+  743 runs, and a loop counter whose cap fired 8 times when only one of those was a real repeat.
+- A lesson the pipeline learns three times becomes a request to the harness. The answer ships as a rule in a
+  release, and the upgrade that installs it closes the request.
+
+## Why
+
+My agent harness (the `CLAUDE.md`, the subagent specs, the routing rules) used to move between projects by
+copy-paste, and each copy started drifting the day it was made. I'd fix a rule in one project and it stayed
+broken in the others. After a while I couldn't tell which copy was current. NINA turns the harness into
+something a project composes and pins.
+
+I built it one rung at a time, and every rung ended up as working code:
+
+| Rung | In NINA |
+|---|---|
+| Prompts | rules written once, split into layers: core, surfaces, project |
+| Harness | the layers composed into a project and pinned to a frozen release |
+| Loops | stages that send work back, with a cap on every loop that hooks enforce |
+| Graphs | the pipeline declared once as data, and validated on every check |
+| Self-improving system | lessons that graduate into rules, with their effect measured |
+
+## The pipeline it composes
+
+There are eleven subagents, and a project gets the ones its risks call for. Every project gets `planner`,
+`architect`, `implementer`, `reviewer`, `qa`, `devops` and `secops`. A database adds `dba`, external services
+add `integration-tester`, and smart contracts add `solidity-dev` and `solidity-auditor`, since contract code
+can't be patched once it ships. The chain also scales with the change. A one-file label fix gets a light chain
+or a direct edit, and anything on a critical path (auth, plus what the project's surfaces add: money, the
+database, an integration) goes through every gate.
+
+```mermaid
+flowchart LR
+    planner -->|PLAN-READY| architect
+    architect -->|SPEC-READY| implementer
+    implementer -->|DIFF-READY| reviewer
+    reviewer -->|APPROVED| qa
+    qa -->|PASS| devops
+    qa -->|PASS| secops
+    qa -->|PASS| done((done))
+    devops -->|DEPLOYED| done
+    secops -->|SECURE| done
+    reviewer -.->|"REJECTED · max 2"| implementer
+    qa -.->|"FAIL · max 2"| implementer
+    implementer -.->|"BLOCKED · max 2"| architect
+    architect -->|BLOCKED| owner((owner))
+```
+
+<sub>Simplified. The core graph has 22 edges, 11 of them capped loop-backs (the dotted ones), and each surface
+adds its own stage and edges.</sub>
+
+In a project, the graph lives in one file with one edge per line, and `nina check` validates it:
+
+```text
+- `reviewer` → `implementer` on `REJECTED` — an implementation bug · max 2
+- `reviewer` → `architect` on `REJECTED` — a design flaw, or no preview-deploy plan · max 2
+```
+
+Every stage needs a spec and every spec needs to be a stage. An edge has to leave on a verdict its stage can
+actually emit, every verdict has to go somewhere, and every loop-back needs a cap. A spec's prose can only
+mention a route the graph has.
+
+## How it works
+
+### Composition from layers
+
+| Layer | Holds |
+|---|---|
+| core | what's true for every project |
+| surface | what's true for projects that have it: `db`, `money`, `integrations`, `frontend`, `pii`, `edge-cf`, `blockchain` |
+| project | what's true for one project only, kept in that project's repo |
+
+Each layer mirrors the project's file tree, and `nina compose` merges them:
+
+- `<!-- nina:slot db.1 -->` in a core file is a hole the `db` surface fills. A project with no database drops
+  the slot, so its agents never read a word about Prisma.
+- `<!-- nina:requires db -->` on a file's first line makes the whole file conditional. That's why a
+  frontend-only project gets seven agent specs instead of eleven.
+- `{{PLACEHOLDERS}}` get filled from the project's profile, so the core can state a rule without naming one
+  project's provider, packages or models. A release can answer a name itself, like the typecheck and test
+  commands, and a project declares it only to change it.
+- `core/defaults/` holds the release's own text for a project slot a file can't do without. The one that
+  needed it is an agent's `description:`, which Claude Code requires before it loads the agent at all. The
+  project's own text still wins; until it writes some, the default composes, and nothing counts it as owed.
+  An empty default marks a place a project may add to, like the last rows of each agent's skills table.
+- A passage marked `<!-- nina:why -->` tells how a rule came to be. It stays in the layers for whoever
+  maintains them and is never composed, so no dispatch pays to read the history of a rule.
+- Every composed file opens with a notice naming the layer to edit instead. Claude Code's `Edit` tool refuses
+  a file the agent hasn't read, so any agent editing an existing file sees the notice first. Seeing it isn't
+  the same as obeying it, so an edit guard hook refuses the edit and quotes the notice back.
+
+```mermaid
+flowchart LR
+    core["core<br/>every project"] --> compose{{"nina compose"}}
+    surfaces["surfaces<br/>the ones the project declares"] --> compose
+    project["project layer<br/>this project only"] --> compose
+    profile["profile.json<br/>release pin · surfaces · vocabulary"] --> compose
+    compose --> out["CLAUDE.md · agent specs · graph.md<br/>router.md · hook scripts"]
+```
+
+Composition gets tested like code. Four fixture projects, one for each shape worth testing, have to pass ten
+properties each: no placeholder survives, every unfilled slot belongs to the project, nothing leaks in from a
+surface the project didn't declare, gated files show up exactly when they should, rule references resolve,
+the notice never lands above a frontmatter block, every agent spec declares its name, description and tool
+allowlist, the graph validates, every numbered list counts 1, 2, 3 in every profile, and every file fits a
+size budget. An eleventh check looks at the layers themselves: a surface's technology, role or domain may only
+be named in files gated on that surface. The first time it ran, it found 37 places where ungated core prose
+handed work to a role that only some projects have.
+
+### Releases and upgrades
+
+A release freezes the core and the surfaces, and a frozen release is never rewritten. Each project pins one in
+`.nina/profile.json`, so I can keep changing the harness without moving a project that's shipping.
+
+`nina upgrade --to <version>` starts with a report of what the move would cost. The real risk is text the
+project wrote that the new core has no place for, and the command won't apply while any of it would lose its
+meaning. `--apply` runs the whole move and then checks it with the project's own detectors:
+
+```text
+  pinned 0.13.0
+  ✓  composing the harness files — 17 file(s)
+  ✓  checking the declaration — check: declaration is sound
+  ✓  validating the pills — pills: all 13 well formed
+  ✓  running the project's own detectors — harness: current (4 detectors clean)
+
+  upgrade: 0.7.0 → 0.13.0 applied and verified.
+```
+
+If a step fails, the project goes back byte for byte, including the old pin, the old composition and the
+owner's own edits. Every step also runs before the move, so a problem the project already had gets reported as
+pre-existing instead of blamed on the upgrade.
+
+Three things recorded in the project's own repo fully determine its harness: the NINA version in its lockfile,
+the release pin and the project layer.
+
+### Loop caps that hold
+
+A cap written as an instruction only works if the model counts its own rounds, so NINA's loop gate counts them
+instead. Claude Code hooks keep a small ledger for each session, with metadata only: which stage reported which
+verdict and the short ids it gave the issues it sent back, which dispatch went out and when, and when the owner
+last spoke. On `PreToolUse`, if a dispatch would
+go past a cap, the gate answers `permissionDecision: "ask"` and Claude Code puts the dispatch in front of the
+owner. Before relying on it, I checked that this also works in auto mode.
+
+```mermaid
+sequenceDiagram
+    participant M as Model
+    participant C as Claude Code
+    participant G as Loop gate
+    participant O as Owner
+    M->>C: dispatch implementer, round 3 on reviewer → implementer, max 2
+    C->>G: PreToolUse hook
+    G-->>C: permissionDecision ask
+    C->>O: confirm this dispatch?
+    alt owner allows
+        C-->>M: the round runs, and the next one asks again
+    else owner refuses
+        C-->>M: denied, so the model stops and hands over every round's report
+    end
+```
+
+It asks instead of denying because it can't be sure two rounds are about the same issue. The stages now name
+their issues, but a model can rename one between rounds, so a wrong count should still cost one click.
+
+I worked out what counts as a round by replaying six weeks of a real project's history. The obvious rule was to
+count a dispatch to an edge's target after a loop-back from its source. It hit a cap 8 times, and 7 of those
+were different issues that happened to travel the same edge. The rules that replaced it:
+
+- a round is a dispatch that acts on a declared loop-back;
+- parallel dispatches acting on the same verdicts count as one round;
+- a pass cancels a rejection only if a fix went out in between;
+- when the owner speaks, every count starts over;
+- while every report in a loop names its issues, each issue gets its own count, and the edge still asks once it
+  goes past twice its cap, in case an issue was renamed along the way. One report that names nothing puts the rest of
+  that loop back on the edge's count.
+
+Three separate reviews each found a case the counting still got wrong before it shipped.
+
+Probing the live system changed the design twice. `UserPromptSubmit` fires when a subagent's report is
+delivered, and not only when a person types. Resetting on every prompt would have wiped every count, so only
+human prompts reset. The gate also never reads the session transcript to decide anything. Claude Code writes
+that file asynchronously, and a resumed session rewrites its own history. In one 385 MB transcript, 74% was
+replay.
+
+The gate fails open and logs its errors. Every project runs a self-test among its detectors. It pushes a whole
+loop through the project's own hook command and expects the round past the cap, and only that round, to reach
+the owner.
+
+### Findings that reach the model
+
+Each project runs NINA's detectors from two hooks, and each hook reaches a different reader:
+
+| Hook | Reaches |
+|---|---|
+| `Stop` | the person, with what the turn left behind |
+| `UserPromptSubmit` | the model, as `additionalContext`, before it answers |
+
+For a long time only the first one existed, so every finding went to the person, who wasn't the one about to
+act on it. The detectors report drift in the composed files, what a project still has to declare, lessons that
+are owed, and the health of the loop gate itself.
+
+The two readers are told differently. The model gets a finding in full the first time, and after that, while
+it stays the same, only its summary and an instruction not to repeat it. The person hears one line from
+`Stop`, and only about what the turn itself left behind, since whatever the model was handed before the turn
+it has already relayed. A new project's first answer opens with what the project is, read from the brief its
+owner wrote during `init`, and proposes writing the architecture together, instead of reciting what is
+missing.
+
+### Measurement and the learning cycle
+
+`nina snapshot` reads Claude Code's transcripts and records each dispatch: which stage ran, the verdict it
+declared, whether it got sent back, which skills it used and whether it read its lessons. The store keeps
+metadata only. Report text, source code and personal data never go in.
+
+`nina stats` reads that store back: the loop-back rate of each stage, what each stage costs at list prices
+(a subscription pays nothing per token, but the unit still compares one stage with another), which model each
+stage actually ran on against the one its spec declares, and the size of each change against the chain that
+carried it. The first cost reading, over 825 runs, had the implementer at 41% of the spend and the gate whose
+value was in question for weeks at 2%.
+
+The same history can go to Langfuse on its own. `nina langfuse login` asks for a project's keys once, and
+`nina langfuse on` makes a project send its runs after every turn, from the detector that already snapshots
+it. Each stage becomes a trace named for its role, with its tokens, estimated cost and verdict. With
+`--content`, the trace also holds what the stage did: its prompt and report, each message it wrote, and
+each tool call with what came back, read from the transcript as it is sent. Obvious secrets are masked, but
+the code the stages read goes with it, so context is a switch per project. Each run goes once, after it
+settles, because Langfuse keeps what it is first sent and a second send would count twice.
+
+When a stage gets sent back, the pipeline can write a lesson for that role. `nina learn` checks the cycle one
+link at a time, and its first audit found four of the five links broken. Here's the same project before and
+after I redesigned it:
+
+```text
+  observe   826 dispatch(es) recorded, 2026-08-12 → 2026-09-22
+  capture   ✗ reviewer: 24 loop-back(s) since its newest lesson (2026-09-03)
+  apply     592 of 646 run(s) of roles that have lessons opened their pills (92%)
+  graduate  0 lesson(s) at 3+ occurrences · 0 request(s) open
+  verify    reviewer/…-never-write-to-repo-files.md (2026-09-03): 2% → 29% loop-back (n 43 → 104)
+```
+
+```text
+  observe   826 dispatch(es) recorded, 2026-08-12 → 2026-09-22
+  capture   ✓ no role has looped back 3+ times without a lesson in the last 14 days
+  apply     581 of 720 run(s) of roles that have lessons read one (81%); 81 only listed the directory — measured since 2026-08-12. Reading is not obeying; nothing here can see that.
+  graduate  3 lesson(s) at 3+ occurrences · 0 request(s) open
+            → nina learn --graduate .claude/pills/integration-tester/regenerate-the-premise-index-after-editing-an-integration-doc.md
+            → nina learn --graduate .claude/pills/qa/exit-code-is-the-verdict.md
+            → nina learn --graduate .claude/pills/shared/test-must-name-the-mutation-that-fails-it.md
+  verify    qa/vitest-file-filter-needs-no-double-dash.md (2026-09-01): 8% → 19% loop-back (n 13 → 79); every other role 17% → 20%
+            reviewer/reviewer-never-write-to-repo-files.md (2026-09-03): 2% → 29% loop-back (n 43 → 104); every other role 22% → 16%
+```
+
+```mermaid
+flowchart LR
+    A["loop-back"] --> B["lesson for the role"]
+    B -->|"learned a 3rd time"| C["request to the harness"]
+    C -->|"answered"| D["rule in a core or surface layer"]
+    D -->|"next release"| E["nina upgrade --apply"]
+    E -->|"closes the request, retires the lesson"| F["verify: loop-back rate before and after"]
+```
+
+A lesson learned for the third time now gets filed automatically, as a request against the pinned version. A
+project can't edit the harness. It can only ask. I answer requests in the harness repo, into a file the next
+release freezes, and the upgrade that installs the answer closes the request and retires the lesson. The first
+full cycle has already happened: the three lessons in the second output became harness rules in 0.20.0, and the
+upgrade closed all three requests by itself.
+
+Counting loop-backs doesn't say what they were about. `nina learn --deep` reads each loop-back's report and has
+a small model, on the same login, group them by cause and set the causes against the lessons already written.
+It proposes a lesson for each recurring cause that none covers, and it writes nothing itself. The first run,
+over one project's 70 loop-backs, took six calls and proposed five lessons nobody had written.
+
+### Evaluating a release
+
+A loop-back rate moves with the work as much as with the rules, so it can't show whether a rule change helped.
+`nina eval` runs an experiment instead. The reviewer each release composes reviews the same change, which
+carries twelve planted defects, and the report counts what each one caught. It runs `claude -p` on the
+Claude Code login, so it uses the subscription and never a per-token key, and the grading is deterministic.
+The first run caught 11 of 12, and it also showed the reviewer writing a sentence before its verdict line,
+which the gate would have read as no verdict at all. An optional judge, a second model on the same login,
+reads each report for what line numbers can't show, and has to quote the report for every defect it says
+was found. It found the twelfth defect described in words. It's also asked to call each other finding real or
+noise, and before any of that it judges a report that found nothing, which has to come out at zero.
+
+## What measuring found
+
+None of this showed up until I counted.
+
+- Mandatory skills were invoked 2 times in 743 subagent runs. `Skill` was missing from every role's `tools:`
+  allowlist, so the rule could never run. The prose looked fine for three months.
+- Lessons were captured at 3% of the rate the rules asked for, 2 lessons from 78 loop-backs. "Write a lesson on
+  every loop-back" had trained everyone to skip them. The rule is now "ask whether this would happen again", and
+  the detector fires on an event instead of watching a rate.
+- A metric for "agents apply their lessons" said 92%, because listing a directory counted as reading. Counting
+  only real reads, it's 81%. Even that only measures reading. Nothing in a transcript shows whether an agent
+  obeyed.
+- The reviewer sent work back 4% of the time on Sonnet and 39% on Opus 5, at $0.69 and $3.18 a run. Those are
+  different weeks of different work, so it isn't a result. It is the question `nina eval` exists to answer.
+- The first before/after readings went up after their lessons, with every other role as a control. Maybe the
+  reviewer got better at catching things, or maybe the lesson didn't help. It isn't proof, but without the
+  numbers I couldn't even ask.
+
+## What the first new project found
+
+The harness was extracted from a project that was already running, so the path a new project takes had never
+been walked. The first project started from nothing walked it in two days, and each thing it found became a
+release:
+
+- `Stop` printed twenty-two lines under every answer, repeating the pending items the model had just
+  explained. It says one line now, and only about what the turn left behind.
+- The first answer to "hello" was an inventory of what the project lacked. It now opens with what the owner
+  said the project is.
+- Once the architecture existed, the model closed every answer with the same pending line, because it was
+  told before every message to mention it. It now gets the full list once per session.
+- Seven agents, the reviewer, qa and secops among them, took their `description:` from the project, and
+  Claude Code doesn't load an agent without one. Every new project had no reviewer until it wrote one, and
+  nothing said so, because the fixtures fill no project slot and composed the same broken specs. The release
+  now supplies a default, and the fixtures check for it.
+- The integration recipe told the project to add a row to skills tables it had no way to edit, and a region
+  written in backticks was reported as a skill that wasn't installed.
+
+## Getting started
+
+You need Node 20 or newer. NINA has no dependencies, and a project installs it from npm at an exact version,
+which its lockfile pins:
+
+```bash
+pnpm init                          # a new project needs its own package.json first
+pnpm add -D -E @xhulz/nina
+pnpm nina init
+```
+
+Each release merged to `main` is published by a GitHub Actions workflow through npm's trusted publishing,
+so every version carries the provenance of the build that made it.
+
+`init` works out the surfaces a repo reveals (a Prisma schema means `db`, a wrangler config means `edge-cf`),
+then asks what the project is and one yes-or-no question for each surface no file can settle. It writes
+`.nina/profile.json`, the owner's answer as `.nina/BRIEF.md` and a to-do list, wires the Claude Code hooks and
+composes the harness. The first Claude Code session opens from the brief and works through what is still
+missing with the owner.
+
+Run alone on a terminal, `pnpm nina` opens a session: the banner once, then a `nina ›` prompt where commands
+(`stats`, `check`, `upgrade --to <version>`) run one under another, with Tab, history and `clear`.
+
+The test suites run from this repo:
+
+```bash
+node scripts/compose-test.mjs     # the fixtures against their properties, plus the layer audit
+node scripts/cli-test.mjs         # the CLI end to end, in scratch projects
+node scripts/harness-check.mjs    # this repo's own detectors
+```
+
+## Repository map
+
+| Path | What's there |
+|---|---|
+| [`bin/nina.mjs`](bin/nina.mjs) | entry point and command table |
+| [`src/commands/`](src/commands) | one file per command |
+| [`src/graph.mjs`](src/graph.mjs) | parses and validates a composed pipeline graph |
+| [`src/gate.mjs`](src/gate.mjs) | the loop gate: the ledger, what counts as a round, one answer per hook event |
+| [`src/wiring.mjs`](src/wiring.mjs) | the hooks and npm scripts a project needs, read by `init`, `wire`, `check` and `upgrade` |
+| [`src/transcripts.mjs`](src/transcripts.mjs) | the transcript parser |
+| [`src/detectors.mjs`](src/detectors.mjs) | runs a project's detectors from its hooks |
+| [`src/tools.mjs`](src/tools.mjs) | what an agent spec's frontmatter must carry: name, description, tools, model, effort, skills |
+| [`src/langfuse.mjs`](src/langfuse.mjs) | a run as an OpenTelemetry trace and a verdict score |
+| [`core/`](core), [`surfaces/`](surfaces) | the harness layers, and in `core/defaults/` the release's own text for a slot |
+| [`releases/`](releases) | the frozen releases projects pin |
+| [`fixtures/`](fixtures) | projects that exist to be composed and checked |
+| [`evals/`](evals) | a change with planted defects, for comparing one release's reviewer with another's |
+| [`scripts/`](scripts) | the test suites and this repo's own checks |
+| [`docs/`](docs) | every mechanism, and why it ended up the way it did |
+
+[`docs/`](docs) is the long version. [`CLAUDE.md`](CLAUDE.md) is the short one Claude Code reads when it works on
+this repo, with a table of which document to read before changing what.
+
+## Engineering
+
+- Node.js with zero runtime dependencies. About 9.8k lines of source and 4.2k lines of tests.
+- 48 frozen releases so far. The package ships all of them, so an upgrade can compose its target and report the
+  cost before it changes anything.
+- The tests check properties over the fixture projects, audit the layers, run the whole CLI in scratch projects,
+  and use mutation checks for the rules that matter: undo the rule and some test has to fail.
+- Known limits are written down. The loop gate can't see a fix the model makes by itself without a subagent, for
+  example, and a scheduled `/loop` prompt resets the counts the same way a person's reply does.
+- Commands: `init`, `compose`, `check`, `where`, `pills`, `learn`, `requests`, `wire`, `gate`, `upgrade`,
+  `release`, `snapshot`, `stats`, `eval`, `export`, `langfuse`.
+
+<sub>© 2026 Marcos Schulz. All rights reserved. The source is public so it can be read, and forking it on GitHub
+is fine, but no license to use, copy, modify or distribute it is granted. See [LICENSE](LICENSE).</sub>

package/bin/nina.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * NINA — harness orchestration CLI.
+ *
+ * Today it captures and reports how the agent pipeline behaves. The composition
+ * commands (`init`, `compose`, `check`, `upgrade`) land once the core has been
+ * extracted from its first real project.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { printBanner } from '../src/banner.mjs';
+import { shell } from '../src/shell.mjs';
+import { snapshot } from '../src/commands/snapshot.mjs';
+import { compose } from '../src/commands/compose.mjs';
+import { check } from '../src/commands/check.mjs';
+import { init } from '../src/commands/init.mjs';
+import { pills } from '../src/commands/pills.mjs';
+import { release } from '../src/commands/release.mjs';
+import { upgrade } from '../src/commands/upgrade.mjs';
+import { where } from '../src/commands/where.mjs';
+import { learn, requests } from '../src/commands/learn.mjs';
+import { stats } from '../src/commands/stats.mjs';
+import { gate } from '../src/commands/gate.mjs';
+import { wire } from '../src/commands/wire.mjs';
+import { evalCommand } from '../src/commands/eval.mjs';
+import { exportCommand } from '../src/commands/export.mjs';
+import { langfuse } from '../src/commands/langfuse.mjs';
+
+/** The NINA install directory (the parent of `bin/`). */
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** Commands wired today, in the order `help` lists them. */
+const COMMANDS = {
+  init: { run: init, help: 'start a harness for a project: profile, surfaces, and what to fill' },
+  snapshot: { run: snapshot, help: 'capture pipeline history from the Claude Code transcripts' },
+  stats: { run: stats, help: 'report loop-back rate per stage from the snapshots' },
+  check: { run: check, help: "validate a project's profile, vocabulary and integrations" },
+  compose: { run: compose, help: 'rebuild a project\'s .claude/ from core + its surfaces' },
+  where: { run: where, help: 'say which layer owns a path, and where a change to it goes' },
+  pills: { run: pills, help: 'validate the corrections the pipeline wrote about itself' },
+  learn: { run: learn, help: 'is the pipeline learning from its own runs? observe, capture, apply, graduate, verify; --deep reads why' },
+  requests: { run: requests, help: "the lessons projects have graduated to the harness — this repo's inbox" },
+  wire: { run: wire, help: "merge the hooks and npm scripts a project's harness needs to run" },
+  gate: { run: gate, help: 'the loop gate: is it wired, and would it still hold a loop past its cap?' },
+  upgrade: { run: upgrade, help: 'move a project to a newer core, reporting what it costs' },
+  eval: { run: evalCommand, help: "does a release's reviewer catch more planted defects than another's? runs on the login" },
+  export: { run: exportCommand, help: 'send the measured history to Langfuse by hand: each run once' },
+  langfuse: { run: langfuse, help: 'keep the Langfuse keys, and turn on the projects that send their runs after every turn' },
+  release: { run: release, help: 'freeze the working core + surfaces as a pinnable version' },
+};
+
+/** Commands named in the plan but not built yet, shown so the roadmap stays visible. */
+const PLANNED = {};
+
+/** Prints usage. */
+function help() {
+  console.log('  usage: nina <command> [options]');
+  console.log('         nina              on a terminal: the banner once, then type commands under it\n');
+  for (const [name, c] of Object.entries(COMMANDS)) {
+    console.log(`    ${name.padEnd(12)} ${c.help}`);
+  }
+  if (Object.keys(PLANNED).length > 0) {
+    console.log('\n  planned:');
+    for (const [name, desc] of Object.entries(PLANNED)) {
+      console.log(`    ${name.padEnd(12)} ${desc}`);
+    }
+  }
+  console.log('\n  options:');
+  console.log('    --project <dir>    the project to act on (default: the working directory)');
+  console.log('    --surfaces <list>  init: declare surfaces instead of detecting them');
+  console.log('    --to <version>     upgrade: the core to move to');
+  console.log('    --check            compose: report drift instead of writing');
+  console.log('    --quiet            compose/pills: say nothing unless something is wrong');
+  console.log('    --apply            upgrade: write the new version, once it is safe');
+  console.log('    --since <date>     stats: YYYY-MM-DD');
+  console.log('    --snapshots <dir>  stats: read the history from somewhere else');
+  console.log('    --out <dir>        snapshot: where to write\n');
+}
+
+/** Entry point. */
+async function main() {
+  const [, , name, ...argv] = process.argv;
+  const pkg = JSON.parse(await readFile(join(ROOT, 'package.json'), 'utf8'));
+
+  // On a terminal with no command, or asked for by name: one banner, then commands typed under it.
+  if (name === 'shell' || (!name && process.stdin.isTTY && process.stdout.isTTY)) {
+    return shell({ bin: fileURLToPath(import.meta.url), version: pkg.version, commands: Object.keys(COMMANDS) });
+  }
+
+  // A hook's stdout is its answer, and a banner in front of the JSON would make it unreadable. A command
+  // typed into `nina` runs under the banner the session already printed.
+  if (!argv.includes('--quiet') && !argv.includes('--hook') && !process.env.NINA_SHELL) printBanner(pkg.version);
+
+  if (!name || name === 'help' || name === '--help' || name === '-h') {
+    help();
+    return 0;
+  }
+  const command = COMMANDS[name];
+  if (!command) {
+    if (PLANNED[name]) {
+      console.error(`  "${name}" is planned, not built yet — see \`nina help\`.\n`);
+      return 2;
+    }
+    console.error(`  unknown command "${name}" — see \`nina help\`.\n`);
+    return 2;
+  }
+  return command.run(argv, { root: ROOT });
+}
+
+main().then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`  ${err?.stack ?? err}`);
+    process.exit(1);
+  },
+);

package/evals/reviewer/after/src/server/config.ts

@@ -0,0 +1,5 @@
+/** How long a session may be idle before the user must sign in again, in minutes. */
+export const SESSION_IDLE_MINUTES = 30;
+
+/** The most notes one page of a listing returns. */
+export const PAGE_SIZE = 100;

package/evals/reviewer/after/src/server/data/notes.ts

@@ -0,0 +1,37 @@
+/** A note as it is stored. */
+export interface NoteRow {
+  id: string;
+  ownerId: string;
+  body: string;
+  archived: boolean;
+  updatedAt: Date;
+}
+
+const rows = new Map<string, NoteRow>();
+
+/**
+ * Finds one note by id.
+ *
+ * @param id - The note id.
+ * @returns The row, or undefined when there is none.
+ */
+export function findNote(id: string): NoteRow | undefined {
+  return rows.get(id);
+}
+
+/**
+ * Stores a note, replacing any row with the same id.
+ *
+ * @param row - The row to store.
+ */
+export function saveNote(row: NoteRow): void {
+  rows.set(row.id, row);
+}
+
+export function setArchived(id: string, archived: boolean): NoteRow | undefined {
+  const row = rows.get(id);
+  if (!row) return undefined;
+  const next = { ...row, archived, updatedAt: new Date() };
+  rows.set(id, next);
+  return next;
+}

package/evals/reviewer/after/src/server/routes/notes.ts

@@ -0,0 +1,39 @@
+import { findNote } from '../data/notes.js';
+import { NoteNotFoundError } from '../errors.js';
+import { archiveNote, getNote } from '../services/notes.js';
+
+/** What a handler returns. */
+export interface Reply {
+  status: number;
+  body: unknown;
+}
+
+/**
+ * GET /notes/:id
+ *
+ * @param ownerId - The authenticated user.
+ * @param id - The note id from the path.
+ * @returns 200 with the note, or 404.
+ */
+export function getNoteRoute(ownerId: string, id: string): Reply {
+  try {
+    return { status: 200, body: getNote(ownerId, id) };
+  } catch (error) {
+    if (error instanceof NoteNotFoundError) return { status: 404, body: { error: 'not_found' } };
+    throw error;
+  }
+}
+
+/**
+ * PATCH /notes/:id/archive
+ *
+ * @param ownerId - The authenticated user.
+ * @param id - The note id from the path.
+ * @returns 200 with the archived note.
+ */
+export function archiveNoteRoute(ownerId: string, id: string): Reply {
+  console.log('archiving note', ownerId, id);
+  if (!findNote(id)) return { status: 200, body: { error: 'not_found' } };
+  const note = archiveNote(ownerId, id);
+  return { status: 200, body: { ...note, updatedAt: note.updatedAt.toISOString() } };
+}

package/evals/reviewer/after/src/server/services/notes.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { saveNote } from '../data/notes.js';
+import { archiveNote, getNote } from './notes.js';
+
+describe('getNote', () => {
+  // Mutation: drop the owner check in getNote and this goes red.
+  it("refuses another owner's note", () => {
+    saveNote({ id: 'n1', ownerId: 'alice', body: 'x', archived: false, updatedAt: new Date(0) });
+    expect(() => getNote('bob', 'n1')).toThrow('note n1 not found');
+  });
+});
+
+describe('archiveNote', () => {
+  it('archives a note', () => {
+    saveNote({ id: 'n2', ownerId: 'alice', body: 'y', archived: false, updatedAt: new Date(0) });
+    const note = archiveNote('alice', 'n2');
+    expect(note).toBeDefined();
+  });
+});