@xhulz/nina 0.57.0 → 0.58.1

package/releases/0.58.1/core/tree/.claude/graph.md

@@ -0,0 +1,79 @@
+# Pipeline graph
+
+The one place this project's stages, and the edges between them, are stated. Every other document that
+routes work — `CLAUDE.md`, `router.md`, `pipeline.md`, each role's loop-back rules — describes this
+graph; where one of them disagrees with it, this file is right and the other is a defect to report
+(Hard Rule #17). It is composed for this project, so a stage this project does not have is not in it,
+and no edge points at one.
+
+`nina check` validates it: every stage has a spec, every spec is a stage, every edge leaves on a verdict
+its stage can actually emit, every verdict a stage can emit goes somewhere, and every loop-back edge has
+a cap.
+
+## Stages
+
+- `planner` — decomposes ambiguous or multi-step work into ordered steps
+- `architect` — designs the approach and writes the spec, with cited premises
+- `design-reviewer` — reads the spec before any code, when the design is the question
+- `implementer` — writes code and tests to the spec; never runs the tests
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot blockchain.1 -->
+- `reviewer` — audits the diff against the spec, and names every gate the diff triggers
+- `qa` — runs the tests, once, at the end
+- `devops` — deploys to preview and smokes it; production only on the owner's explicit go
+- `secops` — the security gate, once per milestone
+
+The two terminals are `done` and `human`. `human` is the owner: a decision nobody in the pipeline can
+make, or a loop that has run out of rounds.
+
+## Edges
+
+One per line: the stage, where its work goes, on which verdict, and when. A loop-back edge ends with
+its **cap** — how many times the SAME issue may travel it, the issue being what the stage names on the
+`ISSUES` line under its verdict. When the next round would exceed the cap,
+the orchestrator stops and hands the owner the reports from every round, instead of dispatching again:
+a third attempt at a fix that failed twice is rarely different from the second, and each round costs
+minutes to hours. A different issue on the same edge starts its own count. Where the project wires the loop
+gate, the dispatch past a cap waits for the owner to confirm it; `router.md` says how rounds are counted.
+
+- `planner` → `architect` on `PLAN-READY`
+- `planner` → `human` on `BLOCKED` — the work cannot be decomposed without an answer
+- `architect` → `implementer` on `SPEC-READY`
+- `architect` → `design-reviewer` on `SPEC-READY` — the design is the question: it builds a check, scanner, parser or filter, or picks a mechanism nothing here has run
+- `architect` → `human` on `BLOCKED` — an unverifiable premise or a missing decision
+- `architect` → `planner` on `BLOCKED` — the plan itself is wrong, not the design · max 1
+- `design-reviewer` → `implementer` on `APPROVED`
+- `design-reviewer` → `architect` on `REJECTED` — a design flaw, found before any code · max 2
+- `implementer` → `reviewer` on `DIFF-READY`
+- `implementer` → `architect` on `BLOCKED` — the spec is wrong, needs a file it does not list, or asks one run for more files or lines than a step may write · max 2
+- `implementer` → `planner` on `BLOCKED` — the spec is too large for one step · max 1
+<!-- nina:slot db.2 -->
+<!-- nina:slot integrations.2 -->
+<!-- nina:slot blockchain.2 -->
+<!-- nina:slot money.1 -->
+- `reviewer` → `qa` on `APPROVED`
+- `reviewer` → `done` on `APPROVED` — a spike, or a chain with no architect whose change no test covers
+- `reviewer` → `implementer` on `REJECTED` — an implementation bug · max 2
+- `reviewer` → `architect` on `REJECTED` — a design flaw, or no preview-deploy plan · max 2
+- `qa` → `devops` on `PASS` — the change touches a deployed surface
+- `qa` → `secops` on `PASS` — the last step of a milestone
+- `qa` → `done` on `PASS` — nothing to deploy, or nowhere yet
+- `qa` → `implementer` on `FAIL` — a test fails, the run exits non-zero, or a "pre-existing" failure does not reproduce · max 2
+- `qa` → `architect` on `FAIL` — the test is right and the spec was wrong · max 2
+- `devops` → `done` on `DEPLOYED` — preview is green; production waits for the owner
+- `devops` → `implementer` on `BLOCKED` — the deploy failed because the code is wrong · max 2
+- `devops` → `architect` on `BLOCKED` — the spec has no workable deploy plan · max 2
+- `secops` → `done` on `SECURE`
+- `secops` → `implementer` on `BLOCKED` — a CRITICAL or HIGH that is a bug · max 2
+- `secops` → `architect` on `BLOCKED` — a CRITICAL or HIGH that is a design flaw · max 2
+
+## Concurrency
+
+Stages that only read may run together: after the implementer, the `reviewer` and every gate the diff
+triggers go out in one message, and `qa` goes out once each of them has approved; at a milestone's end,
+`secops` runs beside `devops`, after the last `qa` passed.
+`qa` always runs alone. These may run as several agents at once, each on its own share of the work:
+- `architect` × many — the sibling specs of one milestone, each its own spec
+- `implementer` × many — work that shares no file and builds on nothing the other writes: side by side in different packages, each in its own worktree within one
+- `reviewer` × many — one per axis of risk the diff carries, for a diff over ~200 lines

package/releases/0.58.1/core/tree/.claude/patterns.md

@@ -0,0 +1,251 @@
+# Patterns & Conventions
+
+Read this before writing code. Architects cite it in specs; implementers follow it; reviewers enforce it.
+
+---
+
+## Language & tooling
+
+- **TypeScript strict mode** everywhere. No `any` without a justifying comment.
+- **pnpm workspaces + Turborepo**. Never `npm` or `yarn`. Use `turbo run <task>` for orchestrated work.
+- **Biome** for format + lint. No ESLint / Prettier.
+- **Vitest** for unit tests.
+<!-- nina:slot edge-cf.3 -->
+- **Zod** for runtime validation at all trust boundaries (API ingress, env loading, queue payload, an RPC between services, webhook body, integration responses).
+
+### Relative imports carry a `.js` extension — this is intentional, do NOT "fix" it
+
+Relative imports in `.ts`/`.tsx` source MUST use the `.js` extension (e.g. `import { x } from './client.js'`, never `'./client'` or `'./client.ts'`). This looks wrong but is correct ESM-TypeScript and is load-bearing:
+
+- The repo is ESM (`"type": "module"`, `module: ESNext`, `moduleResolution: Bundler`, `verbatimModuleSyntax: true` in `packages/tsconfig/base.json`). **TypeScript never rewrites import specifiers** — what you write is what lands in the emitted `.js`.
+- Emitting packages ({{EMITTING_PKGS}}) compile with `tsc` to real `.js` in `dist/` and are consumed via their `exports` map (`./dist/*.js`). At runtime the file IS `client.js`; a source `'./client.ts'` would emit a dead `'./client.ts'` reference → broken import. The `.js` form is the only one that works for these.
+- Bundled apps (`{{API_DIR}}` and `{{APP_DIR}}`, each via its bundler) resolve `'./x.js'` back to `./x.ts` source transparently, so the same convention works everywhere.
+- Switching to `.ts` extensions would require `allowImportingTsExtensions`, which only works with `noEmit` — it would break every emitting package. Do not propose it.
+
+This is the official TypeScript guidance for ESM. A reviewer/AI that "corrects" `.js` → `.ts` (or strips the extension) is introducing a bug, not a cleanup.
+
+---
+
+## Folder structure within a TS package
+
+```
+package/
+├── src/
+│   ├── index.ts          # public exports only — this is the package API
+│   ├── internal/         # not re-exported; no deep imports allowed from outside
+│   └── types.ts          # shared types
+├── test/                 # *.test.ts mirroring src/ structure
+└── package.json
+```
+
+- External code imports from `{{PKG_SCOPE}}/<name>` (barrel `index.ts`), never `{{PKG_SCOPE}}/<name>/src/internal/...`.
+
+---
+
+## `export` only what crosses a module boundary
+
+**`export` is a claim that something outside this file needs the symbol.** If nothing does, drop the
+keyword — the declaration stays, it just stops pretending to be API.
+
+This is not cosmetic. An unused export is invisible to every tool we have: TypeScript's
+`noUnusedLocals` and Biome's `noUnusedVariables` both stop at the file boundary, so an exported dead
+symbol is the one kind of dead code nothing flags. It also makes the symbol look load-bearing to the
+next reader, which is how a second implementation gets written next to the first.
+
+- A React component's `Props` type used only by that component is **not** exported. Export it only
+  when another module actually imports it.
+- The same goes for a service's internal result/input shapes, an error code union that never leaves
+  its module, and a constant only its own file reads.
+<!-- nina:slot project.1 library-packages -->
+- The standing report is `.claude/code-map.generated.md` § *Rot signals*. The
+  reviewer checks it for symbols the current diff introduced: **a new export nothing consumes is
+  dead on arrival.**
+
+---
+
+## Naming
+
+- **Files:** `kebab-case.ts` for modules, `PascalCase.tsx` for React components.
+- **Types / interfaces:** `PascalCase`. No `I` prefix.
+- **Functions / vars:** `camelCase`.
+- **Constants:** `SCREAMING_SNAKE_CASE` only for true compile-time constants.
+- **Env vars:** `SCREAMING_SNAKE_CASE`, loaded through a typed `env.ts` with Zod validation.
+<!-- nina:slot prisma.1 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot money.3 -->
+
+---
+
+## Readable code — *Clean Code* as a reference
+
+Robert C. Martin's *Clean Code* is the reference for writing code the next reader understands without
+running it. It is a reference, not a rulebook: when two ways of writing the same thing both meet the
+spec, choose the one the book would choose. Where the book and this document disagree, this document
+wins: the book treats comments as a failure, and here every declaration still carries TSDoc
+(§ *TSDoc*). The reviewer does not reject a diff on this section alone.
+
+- **A name says what the thing is or does.** A function is a verb (`loadProfile`), a boolean reads as a
+  question (`isExpired`, `canRetry`), a collection is plural. No abbreviation a newcomer has to decode,
+  no bare `data`, `info`, `tmp` or `manager`, and one word per concept: not `fetch` in one module and
+  `get` in the next for the same operation.
+- **A function does one thing, at one level of abstraction.** A function that calls three steps does
+  not also parse a string inline. When a block needs a comment to say what it does, it is a function
+  with that comment as its name.
+- **Guard clauses over nesting.** Leave early on the case you cannot handle — with a named failure, not
+  a silent default — so the main path reads at one indentation level.
+- **Few parameters, no flag parameters.** Past three, pass one object with named fields. A boolean that
+  switches what a function does (`render(true)`) is two functions.
+- **No magic values.** A number or string whose meaning is not obvious where it is used gets a named
+  constant.
+- **A side effect shows in the name.** `getX` does not write. A function either answers a question or
+  changes something, not both, where splitting costs nothing.
+- **Extract what is the same rule, not what has the same shape.** Two blocks that look alike but would
+  change for different reasons stay apart.
+
+**Where it stops.** Readability works inside the scope you were given. Extracting a private function or
+naming a constant in a file you are already writing is in scope; a new shared helper, module, class
+hierarchy or interface the spec did not name is a new abstraction, and goes back to the architect. Code
+you read but are not changing is not rewritten to read better. And indirection is not the goal: a
+function, an interface with one implementation or a pattern earns its place by making the caller
+clearer, not by making the function smaller.
+
+---
+
+## API conventions
+
+### Layering: Route → Service → Data Objects
+
+Every request (and queue/webhook invocation) traverses three layers in order. **No layer may skip the next.** Full diagram in `.claude/architecture.md`.
+
+- **Route** (`{{API_DIR}}/src/routes/<resource>.ts`): Zod validation, auth + role extraction, envelope shaping, privacy-safe log, deps construction. Nothing else.
+<!-- nina:slot integrations.1 -->
+- **Service** (`{{API_DIR}}/src/services/<resource>.ts`): business orchestration, owner scoping (every read and write filtered by who owns the data), Date→ISO mapping, named-error taxonomy. HTTP-agnostic.
+- **Data Objects:** the database client, the platform bindings, and each integration's boundary module.
+
+**Hard rules (reviewer enforces):**
+
+<!-- nina:slot db.2 -->
+- Routes must NOT call `.toISOString()` on service results — services do that.
+- Services must NOT import the HTTP framework's request context, shape a response, or reference status codes.
+<!-- nina:slot prisma.2 -->
+<!-- nina:slot db.4 -->
+<!-- nina:slot money.4 -->
+<!-- nina:slot money.5 -->
+<!-- nina:slot integrations.2 -->
+
+### Other API rules
+
+- **Zod validation at the request boundary.** No ad-hoc `if (!body.foo) return 400`.
+- Response shape is always `{ok: true, data: T} | {ok: false, error: {code, message}}`. No bare throws leaking to clients.
+- Custom errors: `class AppError extends Error { code: string; status: number }`. Each route maps known classes to HTTP codes.
+<!-- nina:slot money.6 -->
+<!-- nina:slot db.5 -->
+<!-- nina:slot db.7 -->
+<!-- nina:slot prisma.3 -->
+<!-- nina:slot drizzle.1 -->
+<!-- nina:slot d1.1 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot project.2 integration-error-types -->
+
+---
+
+## SDK / shared package conventions
+
+- **Tree-shakeable:** barrel `index.ts` only re-exports. No side effects at module top level.
+- Works in: modern browsers, Node 20+, and every runtime the project deploys to.
+- No `console.log` in production paths. Use a `debug(msg)` helper that's a no-op in prod, and never log PII.
+<!-- nina:slot frontend.1 -->
+
+---
+
+## Tests
+
+### Unit tests
+- Test **pure functions** directly. No mocks of our own code.
+<!-- nina:slot money.7 -->
+- Don't test implementation details. Test behavior at the module boundary.
+
+### Integration tests
+<!-- nina:slot edge-cf.4 -->
+<!-- nina:slot db.6 -->
+<!-- nina:slot integrations.4 -->
+
+### Fixtures
+<!-- nina:slot project.3 test-fixtures -->
+
+### Test files MUST be inside the typecheck program
+
+A package whose `tsconfig.json` has `include: ["src"]` **does not typecheck its own tests.** That is
+a false green, and an expensive one: the test still imports the symbol you deleted and still passes
+a fixture whose shape drifted, and you find out at vitest time — or never, if nobody runs that
+suite. It is the mechanism behind the pill *test-files-not-typechecked-on-symbol-removal*.
+<!-- nina:slot project.4 typecheck-current-state -->
+
+A package that emits (`build: tsc`, with `rootDir: "src"`) cannot simply add `test` to its build
+config. Give it a second config instead and point the script at it:
+
+```jsonc
+// tsconfig.typecheck.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": ".", "noEmit": true },
+  "include": ["src", "test"]
+}
+```
+```jsonc
+// package.json — build keeps using tsconfig.json, typecheck does not
+"typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+```
+<!-- nina:slot project.5 typecheck-coverage -->
+
+---
+
+## Correcting a document
+
+When you correct a document, **delete what you are correcting.** A document that contradicts itself
+is worse than one that is merely wrong: every reader picks the half that suits what they are already
+writing, so two readers reach opposite conclusions from the same file and both believe they followed
+it. The correction and the text it replaces cannot coexist "for history" — that is what the commit
+log is for.
+
+---
+
+## TSDoc — required on all TS declarations
+
+Every named declaration gets a TSDoc block (`/** ... */`) — exported or not: functions, classes + members, interfaces + members, type aliases, enums + members, and top-level constants whose name doesn't convey intent.
+
+### Structure
+- **First line:** a concise one-sentence summary.
+- **`@param`** when the purpose isn't fully encoded in name and type.
+- **`@returns`** when the return carries information the type alone doesn't convey.
+- **`@throws`** whenever the function can throw — name the error type and condition.
+- **`@example`** for non-trivially composed APIs.
+- **`@remarks`** for invariants, perf trade-offs, caveats.
+
+### What TSDoc is NOT
+- Not a restatement of the signature. Not a changelog. Not a crutch for bad naming.
+
+### Enforcement
+Reviewer verifies coverage. **Missing TSDoc on any new declaration = `REJECTED`.**
+
+---
+
+## Inline comments — default: none
+
+Separate from TSDoc. Regular `//` comments stay rare:
+- **Only** for non-obvious **WHY**: an invariant, a subtle perf trade-off, a workaround.
+- **Never** for WHAT — if code doesn't read clearly, fix the code.
+- **Never** reference callers, tickets, or PR history.
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot project.7 required-secrets -->
+<!-- nina:slot edge-cf.2 -->
+
+---
+
+## Commit / PR conventions
+
+- One logical change per PR. Multi-concern PRs get split by reviewer.
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
+- PR description answers **why**, not **what**.
+- Reviewer verifies: typecheck clean, Biome clean, every gate the diff triggered approved (`.claude/graph.md`), no secret leaked, no PII in logs or tests.

package/releases/0.58.1/core/tree/.claude/pills/README.md

@@ -0,0 +1,150 @@
+# Pills of Knowledge
+
+Hard-won, per-agent **behavioral corrections** — lessons learned the expensive way (a loop-back,
+a rejected diff, a blocked milestone, a user correction). Each agent reads its own pills **before
+acting** so it does not repeat a past mistake.
+
+This is a knowledge surface, not a convention doc. Keep the niche clean:
+
+| Surface | Holds | Example |
+|---|---|---|
+| `CLAUDE.md` / `.claude/patterns.md` | **Codebase law / conventions** | "relative imports carry a `.js` extension" |
+| `.claude/integrations/<slug>.md` | **External premises**, with evidence | "the client's `signOut()` never rejects" |
+| **`.claude/pills/<role>/` (here)** | **Agent behavioral corrections** | "implementer: `waitFor()` hangs under fake timers" |
+
+If a lesson is really a code convention or an external premise, it belongs in those files — not here.
+
+## Layout
+
+```
+.claude/pills/
+├── README.md     # this file
+├── shared/       # pills that apply to MORE THAN ONE role
+└── <role>/       # one directory per role, named exactly as its spec in .claude/agents/
+```
+
+A role directory is created on demand, when its first pill is written. One **lesson per file**,
+`kebab-case.md`. An agent reads `pills/<its-role>/*.md` **and** the `pills/shared/*.md` whose
+`applies_to` includes it.
+
+Placement is not decoration — it is delivery. A pill sitting in `architect/` that declares
+`applies_to: [architect, implementer]` is never read by the implementer, because the implementer
+only globs its own directory and `shared/`. So the rule is mechanical, and `nina pills` enforces it:
+
+- **one role in `applies_to`** → the pill lives in that role's directory
+- **more than one** → the pill lives in `shared/`
+
+A pill loose at the top level of `pills/` is read by nobody.
+
+## Pill format
+
+Frontmatter is mandatory. A pill without it still reads like prose to a human, but it is invisible
+to every filter the agents and the tooling run — `status`, `trigger` and `applies_to` all stop
+working, so the pill is either ignored or applied where it does not belong.
+
+```markdown
+---
+id: <role-dir>-<file-slug>         # derived from the path, so it cannot drift
+applies_to: [implementer]          # one or more roles; drives who reads it, and where it lives
+severity: low | medium | high
+status: active | retired           # retired = graduated into a rule, kept for history
+date: YYYY-MM-DD                   # when learned; this is what lets staleness be spotted
+occurrences: 1                     # bump when the SAME lesson is learned again — see Graduation
+last_seen: YYYY-MM-DD              # set with every bump; how the harness knows the lesson is current
+trigger: <when this pill is relevant — the agent applies it only if the task matches>
+citations: [path/to/file.ts:42]    # the code this pill is a claim about, when there is any
+---
+**What went wrong:** <the concrete mistake, with where it happened>
+**Rule:** <the imperative — what to do / not do next time>
+**Why:** <the mechanism, so the rule is understood and not merely obeyed>
+**How to apply:** <the concrete check or step the agent runs>
+source: <the run / commit / conversation that produced the lesson>
+```
+
+The `id` is the pill's directory and filename joined. When the filename already opens with the
+role — `reviewer/reviewer-never-write-to-repo-files.md` — the role is not repeated.
+
+**Every pill carries evidence: `citations`, or `source`, or both.** A pill is a claim about how
+this system behaves, and a claim with nothing behind it is the thing this harness exists to remove.
+The two are not interchangeable, and that is why they sit in different places:
+
+- `citations` point at code in this repository, so a machine can later ask whether the cited line
+  still exists. Use them whenever the lesson is about code. They are a **frontmatter field**
+  because tooling reads them back.
+- `source` points at the episode — a run, a commit, a conversation. Use it when the lesson is about
+  a tool or a process and there is no line to cite. Only a person ever reads it, so it closes the
+  body rather than crowding the header.
+
+## The four guardrails (so this stays an asset, not noise)
+
+1. **Bounded growth + graduation.** "Read all my pills" only works while the set is small. See
+   *Graduation* below.
+2. **Staleness.** A pill that cites code rots like any note. `date` flags age and `citations` make
+   the rot findable; **verify before trusting**, and prune or update when you next touch the topic.
+3. **Defined authoring trigger.** Every loop-back (qa → implementer, a reviewer rejection, a mandatory
+   gate blocking) **and every user correction** is looked at for a lesson, and a pill is written when the
+   mistake would happen again — `.claude/router.md` § *Look at every loop-back for a lesson*. The lesson
+   belongs to the stage whose work was sent back. If it already has a pill, do not write a second one:
+   increment that pill's `occurrences` and set `last_seen`.
+4. **Trigger-targeted, not blanket.** The agent reads its pills but **applies only those whose
+   `trigger` matches the current task**. This is what lets the corpus grow without drowning the agent.
+
+## Graduation
+
+`occurrences` is the counter that decides when a correction has stopped being an anecdote. A pill
+learned once is a note. The same pill learned a third time is evidence that the surrounding rules do
+not cover the case, and the fix belongs where nobody has to remember it:
+
+- a convention of this codebase → this project's `.claude/patterns.md`, `CLAUDE.md` or the agent's own
+  spec, each written through its copy under `.nina/project/tree/` (`nina where <file>` lists the slots),
+  then `nina compose`
+- a premise about a dependency → `.claude/integrations/<slug>.md`
+- a correction that would apply to **any** project of this shape → back into the harness itself, as
+  a rule in the core or in the surface that implies it
+
+Which of these it is, is this project's call, and only the last leaves it. When a pill reaches three
+occurrences, `harness:check` asks for the call every turn until it is made:
+
+- **A rule here:** write it, then `nina learn --graduate <pill> --here <file>`. That retires the pill —
+  `status: retired`, moved to `.claude/pills/retired/<the directory it was in>/` — and keeps a record under
+  `.nina/requests/`, so the lesson is still watched: if it comes back three more times, the rule did not
+  hold, and `harness:check` sends it to the harness. A retired pill is history, not instruction, and there
+  no agent opens it to find out. Deleting it would lose the reason the rule exists.
+- **A rule for every project:** the core and the surfaces live in another repository, and this project
+  composes a frozen version of them, so this graduation is a request. `nina learn --graduate <pill>` writes
+  one under `.nina/requests/`, carrying the pinned version, the layer the rule belongs in and the lesson in
+  this project's words. **Commit it with the pill.** The harness maintainer answers it in a release — with
+  the rule, or with the reason it stays here — and the `nina upgrade` that installs that release closes the
+  request: a rule retires the pill; a decline leaves it active, and `harness:check` asks for it as a rule
+  here. Until then the pill stays active; retiring it earlier drops the lesson in the gap.
+
+Either can be done before three. `nina pills` names every active pill that has reached three
+occurrences and, for the harness, proposes where it should go: the core when its roles are composed by
+every project, or the surface that its roles exist for. That is a proposal, not a verdict — a reviewer
+lesson can still be about one surface, and only a person can tell. It is reported as a note, never a
+failure: a recurring lesson is work to do, not a defect.
+
+## Reading contract (referenced from each agent spec)
+
+> Before acting, read `.claude/pills/<your-role>/*.md` and the `pills/shared/*.md` whose
+> `applies_to` includes your role. Treat `status: active` pills as binding for any task matching
+> their `trigger`. Skip `retired` pills. If a pill cites code that no longer exists, prefer the
+> current code and flag the pill as stale.
+
+## Checking
+
+```bash
+nina pills --project .
+```
+
+Reports malformed frontmatter, pills filed where their audience will not read them, roles this
+project does not compose, and pills carrying no evidence.
+
+It also resolves every `citations` entry against the repository. A path that no longer exists, or a
+line past the end of the file it names, is a failure: the pill is telling an agent to look at
+something that is not there. A citation that still resolves in a file which **changed after the
+pill's `date`** is only a note — the line survived, but the code on it may have moved on, and no
+machine can settle that. Verify it before trusting it, then update the pill or retire it.
+
+This is what `citations` buys, and it is the reason the format asks for them. A pill with only a
+`source` cannot be checked this way at all.

package/releases/0.58.1/core/tree/.claude/pipeline.md

@@ -0,0 +1,101 @@
+# Pipeline
+
+<!-- nina:slot project.1 track-summary -->
+
+<!-- nina:slot project.2 pipeline-diagram -->
+
+The `reviewer` and every gate the diff triggers are read-only, so **dispatch them together in one
+message** after the implementer rather than in sequence. The reviewer names the gates the diff
+triggers; `qa` goes out once the reviewer and each of them approved, and runs vitest once, on its own. On a diff over ~200 lines, fan the reviewer out by dimension. Full rules:
+`.claude/router.md` § *Parallelization*.
+
+---
+
+## Stage contracts
+
+Each stage has: **Input** → what arrives, **Output** → the artifact handed on, **Tools** → what it may use, **Exit criteria** → what must be true before handing off.
+
+---
+
+### Planner
+
+- **Input:** user request, often ambiguous or multi-step.
+- **Output:** ordered list of subtasks, each tagged with a 1-line goal + scope (S/M/L) + retrieval list + parallelization tag (`SEQUENTIAL` / `PARALLEL-SAFE`).
+- **Tools:** what its spec's `tools:` grants. **No edits except planning artifacts.**
+- **Exit criteria:** each subtask is small enough for an architect to design in a single pass.
+- **Skip if:** task is already small, single-concern, and concrete.
+
+### Architect
+
+- **Input:** one subtask from planner, or a well-scoped direct request.
+- **Output:** technical spec — files to touch, function signatures, data flow, edge cases, tests to add, patterns to follow. Marks which gates in `.claude/graph.md` the change will trigger — the database gate if the schema or a query will be touched, the integration gate if an integration boundary will be — AND, for the latter, includes an **Integration premises** section: every behavior the implementation depends on, each carrying the evidence its kind requires — a `<package dir>/node_modules/<lib>/<file>:<line>` citation with its version, a contract-test case, an observed response, or a `P<n>` reference into `.claude/integrations/<slug>.md`. No premise without a citation.
+- **Tools:** what its spec's `tools:` grants. **No edits except spec files + `.claude/integrations/**`.**
+- **Exit criteria:** implementer can code without re-planning AND the integration gate, where `.claude/graph.md` has one, can verify each premise / contract case without re-deriving it.
+
+### Implementer
+
+- **Input:** architect's spec.
+- **Output:** working TS code + tests. `{{TYPECHECK_CMD}}`, `{{LINT_CMD}}`, and (when frontend) `{{BUILD_CMD}}` clean for the affected packages. Diff scoped to the spec. **Does NOT run vitest.**
+- **Tools:** what its spec's `tools:` grants.
+- **Exit criteria:** typecheck/lint/build pass; no scope creep; if the database was touched, says so on first line; if an external service surface touched, says so.
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+
+### Reviewer (gate before qa)
+
+- **Input:** implementer's diff + all upstream artifacts.
+- **Output:** `APPROVED`, or `REJECTED` with `path:line` references.
+- **Tools:** what its spec's `tools:` grants. **No edits. No vitest.**
+- **Exit criteria:**
+  - `{{TYPECHECK_CMD}}`, `{{LINT_CMD}}` pass; `{{BUILD_CMD}}` when frontend touched.
+  - Diff matches spec (reject scope creep).
+  - `.claude/patterns.md` conventions followed (TSDoc, layering, naming, owner scoping).
+<!-- nina:slot db.2 -->
+<!-- nina:slot integrations.2 -->
+  - No security / privacy regression (no PII in logs, no leaked secret, no query missing its owner scope).
+<!-- nina:slot money.1 -->
+  - **Preview-first deploy invariant:** a spec that culminates in prod deploy names a preview URL where smoke runs FIRST.
+
+### QA (test execution)
+
+- **Input:** `APPROVED` from the reviewer and every gate the diff triggered + the implementer's touched-package list.
+- **Output:** PASS (ready for deploy) or FAIL (loops back to implementer/architect).
+- **Tools:** what its spec's `tools:` grants.
+- Runs vitest **once**, per affected package, **sequentially** (configs enforce single-fork). Kills stray test processes at start and end. See `.claude/agents/qa.md`.
+
+### Devops (deploy)
+
+- **Trigger:** qa PASS on a step that changes a deployed surface. Not for test-only, docs-only or harness-only steps, nor while the project has no preview target yet.
+- **Input:** qa PASS + the touched-package list + the architect spec's preview-deploy plan.
+- **Output:** `DEPLOYED` (targets, migrations, the smoke it actually ran, the rollback) or `BLOCKED` (what stopped it, which stage owns the fix).
+- **Tools:** what its spec's `tools:` grants. **No edits to code, tests or config.**
+- **Checks:** clean rebuild of emitting packages; both targets when the API surface changed; every variable the bundle reads present at build time; migrations applied in order against the intended database; secret parity; smoke against preview exercising the changed path; a named rollback.
+- **Production:** never on its own initiative — an explicit go from {{OWNER}}, for that change.
+
+---
+
+## Handoff discipline
+
+Each stage produces a **written artifact** — spec, diff, review comments. The next stage consumes the artifact, **not** the original user message. If the implementer finds itself re-reading the original user message, something is wrong with the spec.
+
+---
+
+## Examples
+<!-- nina:slot project.3 worked-example-a -->
+<!-- nina:slot project.4 worked-example-b -->
+
+### Example C — Trivial fix
+
+User: "Fix the typo in the dashboard page title."
+
+No stage: a trivial edit goes through no chain (`CLAUDE.md`, the task table). Edit it directly, run the typecheck, and commit.
+
+---
+
+## When the pipeline breaks
+
+Where each failing verdict sends the work, and how many rounds it gets, is in `.claude/graph.md` —
+the one place it is stated, composed for this project.<!-- nina:why --> This section used to restate it, and had
+already drifted from it: it sent an architect back to the planner along an edge the graph did not
+have.<!-- /nina:why --> One thing the graph cannot express, so it stays here: a stage that hits something no spec
+anticipated stops and says so. It does not guess.