@xhulz/nina 0.59.0 → 0.60.0

package/releases/0.60.0/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.60.0/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.

package/releases/0.60.0/core/tree/.claude/retrieval.md

@@ -0,0 +1,103 @@
+# Retrieval Map (RAG for workflow)
+
+Which documents to pull into context for a given task type. Goal: **avoid loading all docs on every task** — that wastes tokens and crowds out the actual work.
+
+This is the closest thing the harness has to RAG for development. Treat it as authoritative.
+
+---
+
+## Always loaded (by Claude Code itself)
+- `CLAUDE.md` — loads automatically. Don't re-read.
+
+## Pills (per-agent behavioral corrections — loaded by the agent itself)
+
+`.claude/pills/<role>/*.md` + `.claude/pills/shared/*.md` hold hard-won corrections from past mistakes (a loop-back, a rejected diff, a blocked milestone, a user correction). **Each subagent reads its own pills before acting** (the instruction is in every `.claude/agents/<role>.md`). Distinct from the surfaces above: pills capture *agent behavior* ("the implementer did X wrong"), not codebase conventions (→ `patterns.md`) or library premises (→ `integrations/`). The orchestrator looks at every loop-back and user correction for a lesson, and writes a pill when it would happen again. Graduation: a lesson learned three times goes to the harness as a request, and the upgrade to the release that answers it retires the pill. Format + guardrails: `.claude/pills/README.md`.
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot project.1 integration-doc-list -->
+<!-- nina:slot integrations.2 -->
+
+## Code map (load first for file-location tasks)
+
+**Rule:** Before grepping the repo to find which files participate in a domain, load `.claude/code-map.md`. Two layers:
+
+- **`.claude/code-map.md`** — hand-curated. Purpose, invariants, the critical paths, what to reuse. **Read this one.**
+- **`.claude/code-map.generated.md`** — the exhaustive mechanical inventory (every module, its exports, its test) plus the dead-export and untested-module reports, built by a script of the project's own: the harness ships none. Go here when you need the full list. A project with no such script yet defers this file in its profile, and `.claude/code-map.md` is then the whole map — every instruction that points here falls back to it.
+
+Where the project checks the curated map against the tree, its `harness:check` runs that check every turn. **A "does this helper already exist?" question is answered here, not by writing a second one.**
+
+## Load on demand
+
+### Task types
+
+| Task type | Load these docs | Dispatch |
+|---|---|---|
+| New API endpoint | `.claude/architecture.md` § *API*, § *Layering*, `.claude/patterns.md` § *API conventions* | architect → implementer → reviewer → qa |
+<!-- nina:slot db.1 -->
+<!-- nina:slot db.2 -->
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot edge-cf.2 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot frontend.1 -->
+<!-- nina:slot edge-cf.3 -->
+| Performance investigation | `.claude/architecture.md` § *Performance targets*, relevant source | architect → implementer |
+
+### Meta tasks
+
+**Before changing anything under `.claude/` or `CLAUDE.md`, settle where it goes.** Most of those
+files are composed and cannot be changed from this project; the rest are yours outright, and the
+first question is mechanical rather than a judgement call: **does the file carry `nina:generated`?**
+`nina where <path>` answers that and the rest for any path — including a path that does not exist
+yet, which is the case no file's own header can answer — and it prints the same sentence that file's
+header carries rather than a second wording of it. Inside a generated file the second question is
+the judgement one, and it is only about that case: is the wrong text **this project's fact**, which
+belongs in a `project.N` slot, or **a rule for every project**, which cannot be changed from here?
+
+| Task type | Load these docs | Dispatch |
+|---|---|---|
+| A rule an agent follows is wrong | `nina where <the composed file>` — it is a **request against the pinned core**, quoting file and line. It cannot be edited here | report it; it arrives back through `nina upgrade` |
+| A number, path, command or provider in a composed file is wrong | `nina where <the composed file>` — it is **this project's fact**, so it belongs in the slot it names under `.nina/project/tree/` | whoever found it, now |
+| A spec the harness should compose is not on disk | `nina where <the path>` — a file gated on a surface this project does not declare is **not missing**, it is switched off. Declaring the surface is a decision about the project, not a fix | whoever is asking why it is absent |
+| A mistake just happened and should not happen twice | `.claude/pills/README.md` — a **pill** under `.claude/pills/<role>/`, written directly. Never an edit to the agent's spec | the orchestrator, on the loop-back |
+| What a library actually does, proven at runtime | `.claude/integrations/<slug>.md` — yours to write, and the slug belongs in `.nina/profile.json` or nothing knows the doc exists | the integration gate, or whoever proved it |
+| A plan for work in progress | `.claude/plans/**` — yours, and nothing composes it, ever | whoever is planning |
+| Anything that is not one of the above | `nina where <the path>` — it will say "not harness", which is an answer: the file is ordinary project code and the harness has no opinion about it | whoever is editing it |
+| New subagent role | `.claude/pipeline.md`, `.claude/router.md`, existing `.claude/agents/*.md` | human decision |
+| Package / route / service / RPC method added or removed | `.claude/code-map.md` — update the curated map, and its check where the project has one | whoever shipped the change, at the close of the step |
+| Update this map | the project's slot in it — `nina where .claude/retrieval.md` names it; a row every project needs is a request against the pinned core | architect (light) → reviewer |
+
+---
+
+## How to scope loads
+
+- **Load a section, not a full doc, when possible.** Architecture and patterns docs have headings; jump to the relevant one.
+- **Don't preload.** Only read a doc when the task actually requires it.
+- **Re-read existing code before editing it**, even if read this session — it may have changed.
+
+---
+
+## Anti-patterns
+
+- ❌ Loading `.claude/architecture.md` in full for a 3-line bug fix.
+- ❌ Loading `.claude/patterns.md` when the task is a pure design discussion (no code yet).
+- ❌ Loading every subagent spec manually — they load automatically when dispatched via Agent.
+- ❌ Re-reading `CLAUDE.md` after Claude Code has loaded it.
+- ❌ Skipping the retrieval map and loading "everything just in case."
+
+---
+
+## When unsure
+
+1. Read the **first 50 lines** of `.claude/architecture.md` (table of contents).
+2. Identify the relevant section.
+3. Read that section only.
+4. If still unclear, escalate to the user — don't guess with more tokens.
+
+---
+
+## Updating this map
+
+When a new kind of task appears that isn't in the table:
+1. Add a row here first.
+2. Commit the update alongside the change it describes.
+3. Don't let the map rot — a stale retrieval map is worse than no map.

package/releases/0.60.0/core/tree/.claude/router.md

@@ -0,0 +1,205 @@
+# Agent Router
+
+Decides which subagent (or chain) to dispatch for a given task. Subagent definitions live in `.claude/agents/`.
+
+<!-- nina:slot project.1 track-summary -->
+
+---
+
+## Decision tree
+
+The stages and edges are in `.claude/graph.md`. What follows is this project's own way of sizing a
+task into a chain over them.
+
+<!-- nina:slot project.2 decision-tree -->
+
+---
+
+## Track flow
+
+<!-- nina:slot project.3 track-flow-diagram -->
+
+The stages, and the edges between them, are in `.claude/graph.md` — the one place they are stated. Every gate the diff triggers runs beside the reviewer, and `qa` goes out once all of them approved. The reviewer's `Gates` line names the gates the diff triggers: send any you did not. When the architect's report says `Design review: needed`, says nothing of it, or the change builds a check, scanner, parser or filter, send the spec to the `design-reviewer` before the implementer, once per spec, before its first step: a design flaw found in the spec costs one correction, found in the diff a whole round.
+
+**Every loop has a cap.** Before dispatching a loop-back, count the rounds the SAME issue has already made on that edge. At the cap `.claude/graph.md` gives it, do not dispatch again: stop and hand {{OWNER}} the report from every round. A third attempt at a fix that failed twice is rarely different from the second, each round costs minutes to hours<!-- nina:why -->, and until this rule existed nothing in the pipeline could stop a loop at all<!-- /nina:why -->. A different issue on the same edge starts its own count. A stage that sends work back names each issue on the `ISSUES` line under its verdict; when you dispatch a round — the fix, and the check of the fix — copy that line into both dispatches, so the stage that checks can keep the id of an issue that is still open. That id is what your count is of.
+
+Where the project wires the **loop gate** (`scripts/loop-gate.mjs`, run by hooks — `nina wire` puts them
+in place), the cap is held for you. It counts a round when a dispatch acts on a loop-back a stage
+declared on its `VERDICT` line — per issue while every round's reports named theirs on the `ISSUES` line,
+per loop from the first that did not until it closes — whichever stage the fix went to; several dispatches
+acting on the same verdicts are one round; and each message from {{OWNER}} gives every open loop one round
+more — your own `AskUserQuestion` does not. A loop closes when a review launched after the latest fix passes
+with no rejection beside it — a resumed one too, and a pass needs no `ISSUES` line — or when the next stage,
+sent out after the last review, passes. Work run side by side shares one count per stage and verdict: a rejection still open in
+one task keeps another's pass from closing it. The dispatch past the cap goes to {{OWNER}} to confirm. If they refuse it, do
+what the graph says — hand them each round's report and ask how to proceed — and do not route around the
+refusal by resuming the fixer or making the fix yourself.
+
+The gate trusts the ids it is given: an issue renamed between rounds starts its count over, so an edge
+still goes to {{OWNER}} once it has gone round more than twice its cap with no approval between. It does
+not see a fix you make without a subagent — so keep your own count as well, gate or no gate. When you
+dispatch a second round on an edge, say "round 2 of max 2 on <edge>" in the dispatch itself, so the
+count is in the transcript for whoever reads it next. After a compaction the gate hands you its open loops
+and the documents to read again; `nina gate --status` lists them, and what closes each, at any time.
+
+### Milestone gate
+
+**secops** is a milestone gate, not a per-sub-step stage: when the LAST sub-step of a numbered set (`6.*`)
+or phase passes qa, dispatch it beside devops to audit the whole assembled surface. The set is not done
+until it returns `SECURE`; a `BLOCKED` goes back to the architect or implementer, then to a re-audit.
+
+---
+
+## Rules
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot blockchain.1 -->
+
+### Planner only for ambiguous, multi-step, or multi-package work
+If the task fits in one head and lives in a single package, skip to architect (or implementer for trivial things).
+One package is not one step, though: the architect still splits a long file list into steps (see *A spec's steps are passes of their own*).
+
+### Architect output is a spec, not code
+Architect produces a TS spec; implementer consumes the spec; they do not re-read the original user message.
+
+### A chain with no architect: the dispatch is the spec
+When a chain starts at the implementer, your dispatch is its spec: the goal, the files it may touch and
+what must hold when it is done. The reviewer reviews against it and asks none of what only an architect's
+spec carries — an Obsolescence list, a preview-deploy plan, a skill citation, integration premises. A
+change that needs one of those needs an architect.
+
+### A spec is corrected in place
+A spec sent back is corrected where it is wrong; new work comes as a new step file or spec. Never ask for
+a `Revision N` section, and correct a spec yourself only in place, searching it and its steps for what you contradict. Point a dispatch at the sections and steps
+that changed, by number: a history at a spec's head is read first by every stage and applies to
+nothing.<!-- nina:why --> The architect was told to correct in place, and the
+orchestrator went on asking for revisions. The first new project's second spike spec opened with four
+revision sections, one of them written by the orchestrator, and every dispatch told the stage to read them
+first. Its first spec reached an eighth revision, which had become the way new work was asked for.<!-- /nina:why -->
+
+### A spike answers one question
+A spike is an experiment: it answers a question about a service, a library or the data before anything is
+designed on it, and its code is evidence, kept in a directory of its own outside the product's packages.
+The architect writes a spike plan, one page, not a spec: the question, what to run and observe, the
+answer that settles it, and when to stop. The reviewer checks that it measures what it says it measures.
+No qa, devops or secops. A plan in steps runs them as a spec's (§ *A spec's steps are passes of their own*), without qa:
+a step that builds on another goes out once every review of that one approved, whatever the plan says. Its plan is
+corrected at most twice, counting a correction you make in place; past that, or when its answer raises a new
+question, stop and ask {{OWNER}}: a new question is a new spike, and a spike revised past its question is
+the product being designed without a spec.
+
+### Reviewer audits; QA runs tests
+Reviewer runs `{{TYPECHECK_CMD}}` / `{{LINT_CMD}}` (and `{{BUILD_CMD}}` for frontend) and verifies clean, confirms guardrails ran, but **does not run vitest**. QA runs vitest once after approval.
+
+### A stage that returns no verdict
+A report with no `VERDICT` line, a run that stopped, or one out of context is not a pass. Resume it once
+with `SendMessage` for its report; failing that, dispatch the stage again, saying what the first run left
+in the tree. Nothing builds on its work until a verdict does.
+
+### A round of work goes to a fresh run
+A resumed run is billed its whole history again on every turn. Resume one only for something short: its missing report, or a re-check of a few files. A fix, a revised spec or a re-run of flows goes to a new run of the stage, dispatched with what it needs: the spec's path, the findings with their `ISSUES` line, and the files and probes they name.<!-- nina:why --> In the project this was learned in, a resumed fix began at a 526k-token context and re-read 60M tokens, twice a first round, and resumed rounds held three quarters of everything the pipeline read.<!-- /nina:why -->
+
+### Notes ride with the work
+A report's **Notes** send nothing back (Hard Rule #20). Carry them into the next dispatch of the same work — the fix round when there is one, else the next step's spec — and list those still open when you report the step to {{OWNER}}. A rejection whose every issue is a note goes back to the stage that gave it, to give its verdict again under that rule, not to a fix.
+
+### A report that sends work two ways
+When one report names issues for the architect and for the implementer, the architect goes first, and the
+implementer fixes against the corrected spec.
+
+### Pipeline is not sacred
+If reviewer finds a design flaw, loop back to the architect. Don't paper over with implementation hacks.
+
+### Plugin skills are part of the pipeline
+The mandatory triggers are the table in `CLAUDE.md` and each spec's own § *Skills you MUST consult*; every
+stage invokes them through the `Skill` tool. The architect cites which skill informed the spec, and the
+reviewer rejects a spec touching a surface with a mandatory skill that cites none and says nothing of why.
+
+### Devops owns the deploy
+Invoke **devops** after **qa PASS** on any step that changes a deployed surface (API, frontend, schema, deploy config, secrets, platform bindings). It is the stage that executes Hard Rule #14 — the reviewer only checks that the spec *has* a preview-deploy plan. Skip it for steps that touch only tests, docs, or the harness, and while the project has no preview target yet. **Preview and staging it deploys on its own; production needs an explicit go from {{OWNER}} for that specific change, quoted in the dispatch.**
+<!-- nina:slot frontend.2 -->
+
+### Look at every loop-back for a lesson
+
+When a stage loops back (qa → implementer on a test failure, reviewer rejects a diff, a gate blocks) **or** the user corrects something, the orchestrator asks one question: **would this happen again?** If it would, the lesson goes into a pill under `.claude/pills/<role>/` (or `shared/` if it spans roles) so the responsible agent does not repeat it. If it would not — a typo, a flake, a one-off — say so in one line and move on. The question is not optional; the pill is its answer when the answer is yes. <!-- nina:why -->The rule used to be "a pill on every loop-back", and it was followed 3% of the time. <!-- /nina:why -->A rule that demands a lesson from a typo trains everyone to skip the ones that were lessons. `harness:check` watches the outcome<!-- nina:why --> instead of the ritual<!-- /nina:why --> — a role sent back three times since its newest lesson is reported every turn until one is written (`nina learn`). Skip it only if the lesson is really a code convention (→ `patterns.md`/`CLAUDE.md`, through `.nina/project/tree/`) or a library premise (→ `integrations/<lib>.md`): write it there. If the lesson already has a pill, do **not** write a second one — increment its `occurrences` and set `last_seen` to today. At three, `harness:check` asks every turn where it graduates: a convention of this codebase becomes a rule here, and `nina learn --graduate <pill> --here <file>` retires the pill; a rule any project of this shape needs goes to the harness with `nina learn --graduate <pill>` — commit the request with the pill. Each subagent reads its own pills before acting, and `nina pills` checks they are well formed and filed where their audience reads them (see `.claude/pills/README.md`).
+
+---
+
+## Parallelization
+
+**The rule that decides everything here: a stage that only reads can always run beside another
+stage that only reads. A stage that writes files owns those files alone.** Most of this pipeline is
+read-only, so most of it can overlap — the default of running every stage nose-to-tail is a
+habit, not a constraint.
+
+Dispatch concurrent agents **in a single message with multiple Agent tool calls**. Separate messages
+run them one after another and buy nothing.
+
+### Run these in parallel
+
+| Together | Why it is safe | What it buys |
+|---|---|---|
+| **`reviewer` ∥ every gate the diff triggered** after the implementer | all read-only + Bash | the gates stop being a serial prefix to the review |
+| **`reviewer` fanned out by dimension** — one per axis of risk the diff carries, such as tenant isolation, patterns and spec-scope | read-only; they never touch the same output | **the biggest single win.** One reviewer carrying ~15 checklists over a 500-line diff misses things; three narrow ones do not. Faster *and* better |
+| **`architect` across the sibling specs of one milestone** (`<feature>-spec1..N`) | each writes its own file under `.claude/plans/specs/` | the specs share context, so designing them together is more coherent than one-at-a-time, and the whole milestone is specced in one pass |
+| **`devops` ∥ `secops`** at the end of a milestone | devops only reads code; what it writes is a deploy target, not the tree | the audit and the preview deploy stop being sequential |
+| **`Explore` fan-out** for "where does X live" | read-only | one search instead of every stage re-grepping the tree |
+
+### Implementers side by side
+
+Two implementers write at once only on work that shares no file and builds on nothing the other writes:
+the planner's `PARALLEL-SAFE`, a step's `Builds on` and the binding file lists say which. Where decides how:
+
+- **In different packages, each checked on its own** (typecheck, lint and build scoped to it, and none of
+  them building the other package first): side by side in this checkout.
+- **In one package, or where a check spans packages:** each with **`isolation: "worktree"`**. A worktree
+  holds only what is committed — every closed pass is (§ *Commits*) — and lacks what git does not track,
+  such as dependencies or a virtual environment, until its implementer sets it up.
+- You merge a worktree's work, in step order. Never let two agents merge.<!-- nina:why --> The rule
+  used to be one implementer per package, always in a worktree. The first new project had no commit for a
+  worktree to hold, so it ran two implementers side by side in one checkout, one per spike directory, and
+  neither disturbed the other. It also ran two steps of one spec one after the other that built on the
+  same two steps and nothing else, only because they shared a package and both edited its README.<!-- /nina:why -->
+
+### A spec's steps are passes of their own
+
+When the architect splits a spec into steps, each step is its own pass from the implementer on: an
+implementer for that step alone, then the reviewer and every gate its diff triggers, then qa. A step's
+implementer goes out only once every step it builds on has closed its pass, so no step is built on one
+that was sent back. Steps whose turn comes together and share no file go out together, as § *Implementers side by side*
+says; their reviews go out together too, and their qa runs one after the other. Parallel steps save
+time, not tokens: each run builds its own context, and a step that builds on another is never one of
+them. Never hand one implementer several steps, or a spec that lists more than {{STEP_FILES}} files or forecasts more
+than {{STEP_LINES}} lines with no steps: that spec goes back to the architect to be split. The planner's `ONE-SPEC` and `ONE-REVIEW` group
+its own sibling steps into one spec and one review; they never put two of an architect's steps in one
+implementer run.
+
+### Commits
+
+When a pass closes — `qa` returns `PASS`, or the reviewer approves a chain that ends there — commit what
+it changed, with a message naming the step and its spec. Commit on a working branch: never on the
+project's default branch, so before a piece of work's first commit there, create a branch named for its
+spec. Never push, amend, rebase or force; {{OWNER}} merges. A pass sent back is not committed. You are
+the only one who commits (Hard Rule #18): a commit is what a worktree holds, what `secops` audits a
+milestone by, and what `qa` checks a "pre-existing" failure against.
+
+### Keep these serial
+
+- **`qa`.** Vitest is ~2–3 GB per worker; concurrent invocations take the machine down. One run, at
+  the end of each pass. This is not negotiable and is not a speed problem — the suites are seconds, except those
+  `CLAUDE.md` names as slow.
+- **The merge**, always.
+- **A loop-back.** When a stage rejects, fix and re-run that stage; do not fan out around a failure.
+
+---
+
+## Examples
+
+| User request | Pipeline |
+|---|---|
+<!-- nina:slot project.5 dispatch-examples -->
+
+---
+
+## Quick triage
+
+When the doubt is whether a critical path is touched, take the heavier chain; when it is only how much ceremony, the lighter one (`CLAUDE.md` § *If you are uncertain which chain applies*).

package/releases/0.60.0/core/tree/.claude/templates/integration.md

@@ -0,0 +1,48 @@
+<!-- nina:requires integrations -->
+# <Name> — premises
+
+> One integration, one doc. The **integration-tester** creates it on first contact with the
+> dependency and appends to it whenever it observes behavior this file does not yet carry.
+> Everything below is evidence. A claim you cannot cite belongs in *Open questions*, not in a
+> premise — a premise that turns out to be a guess is how an integration regression ships.
+
+- **Kind:** `installed-library` · `live-api` · `platform-binding` — each that applies (a client library over a platform binding is both); a premise's kind decides what counts as its evidence.
+- **Boundary:** the one module that speaks to this dependency. Nothing else may.
+- **Skill:** the installed skill covering it, or *none* — do not invent one.
+
+## Premise index
+
+Read this table and the sections your task actually cites. Not the whole file.
+
+| Premise | Evidence | Claim |
+|---|---|---|
+| P1 | `<citation>` | one sentence |
+
+---
+
+## P1 — <the claim, as a sentence>
+
+**Claim.** What the dependency does, in one sentence, stated specifically enough to be wrong.
+
+**Evidence.** The form depends on the kind:
+
+- `installed-library` — `<package dir>/node_modules/<lib>/<file>:<line>`, with the lines that prove it
+  quoted and the version beside it. From the version actually installed here, not the latest release,
+  and through the package's own link: the store directory behind it is renamed by a peer change. A library
+  no package links, a dependency of a dependency, has no link of its own: cite it through the one that depends
+  on it, `<package dir>/node_modules/<parent> → <lib>@<version>/<file>:<line>`, which `nina check` resolves from where that link leads.
+- `live-api` — the request sent and the response received, verbatim, or the contract-test case that
+  pins it. The vendor's documentation is not evidence: it describes what they intend, and you are
+  depending on what they do.
+- `platform-binding` — what the local emulator did when driven, plus the platform's installed types.
+
+**Why it matters here.** Which code depends on this being true, and what breaks if it is not.
+
+**Checked.** `<date>` against `<version / environment>`.
+
+---
+
+## Open questions
+
+Behavior this doc does not settle yet, and what would settle it. A question here is honest work;
+the same uncertainty written as a premise is a defect waiting for a deploy.