pi-smart-router 0.10.0 → 0.12.0

package/README.md

@@ -473,7 +473,7 @@ See [routing-roadmap.md](docs/routing-roadmap.md) §2 P2 and GitHub [#78](https:
 
 ### P(success) training export (baseline classifier)
 
-When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and behavioral outcome labels (model override, compaction pin break, `/smart-router feedback good|bad`). Export labeled training data from pi:
+When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and behavioral outcome labels. Export labeled training data from pi:
 
 ```bash
 /smart-router export dataset [--limit N]
@@ -481,23 +481,62 @@ When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and
 
 Each JSONL row joins dataset features with `success_label` and `outcome_signals`. Success means no negative outcome signals were recorded for that `request_id` (for example `model_override` or `feedback_bad` mark failure). Prompt plaintext is never included.
 
-**Dogfood artifact (SP-175):** the repo ships a non-example `config/p-success-weights.json` trained on the synthetic fixture at `scripts/fixtures/p-success-synthetic-train.jsonl` (**provenance: synthetic/fixture**, not community contrib — 40 labeled feature-vector rows, no prompt text). With `trained_sample_count ≥ 30`, the low-intensity gate uses trained logistic scores instead of neutral `0.5`. Missing or invalid artifacts still fall back safely to neutral defaults.
+#### Behavioral-first bootstrap (zero manual labels)
 
-**Operator train / reload (no prompt text):**
+Primary path for [#110](https://github.com/beettlle/pi-smart-router/issues/110) (docs slice).
+
+Manual `/smart-router feedback good|bad` is **optional**. Passive dogfood signals already captured under `SMART_ROUTER_DATASET=1` (and privacy-safe telemetry-contrib export) are sufficient to train when you have enough rows:
+
+| Passive field / signal | Role |
+|------------------------|------|
+| `model_override` | Failure — operator overrode the routed model |
+| `compaction_pin_break` | Neutral/positive context — pin broke at compaction (not a cheap-tier failure by itself) |
+| Loop-escalation proxies (`tool_failure_chain`, pin reason `loop_escalation`) | Failure proxies for stuck tool loops |
+| `stop_reason` / `stop_reason_invalid` / `stop_reason_length` | Execution outcome — invalid or truncated stops mark failure |
+
+Optional `feedback_good` / `feedback_bad` only refine labels when the operator chooses to annotate; they are not required for a valid train path. **Do not invent labels** — incomplete exports skip or stay unlabeled rather than fabricating outcomes.
+
+**Sample floor:** collect at least **≥30** labeled **economical-tier** rows (`minimum_training_samples.p_success_weights` / `isotonic_calibrator` in [`config/routing-calibration.json.example`](config/routing-calibration.json.example)) before relying on non-neutral `P(success)` or isotonic. Below that floor the classifier returns neutral `P_success_cheap = 0.5`.
+
+**Provenance today vs behavioral adoption:** the checked-in `config/p-success-weights.json` remains **synthetic/fixture** (SP-175 — trained on `scripts/fixtures/p-success-synthetic-train.jsonl`, not community dogfood). Treat those weights as an interim dogfood enablement until real passive-signal floors are met and artifacts are retrained/shipped ([#110](https://github.com/beettlle/pi-smart-router/issues/110) train/ship slice — SP-206). Do not claim synthetic rows are behavioral.
+
+**SP-206 status (v0.12.0):** **deferred / Partial (B).** Operator had no #95 dogfood exports in this window (labeled economical-tier rows = **0**, floor ≥30). No behavioral `config/p-success-weights.json` or `config/routing-calibration.json` was shipped. See [`spine-tasks/_authoring/release-v0.12.0/behavioral-calibration-partial.md`](spine-tasks/_authoring/release-v0.12.0/behavioral-calibration-partial.md). Leave [#110](https://github.com/beettlle/pi-smart-router/issues/110) open until floors are met; never invent labels.
+
+**Zero-manual-label path (aggregate → train → verify):**
 
 ```bash
-# 1) Opt in + dogfood, then export privacy-safe labeled JSONL (features + labels only)
+# 1) Opt in + dogfood (no /feedback required) — see docs/qa/shadow-dogfood-protocol.md
 SMART_ROUTER_DATASET=1
-# …run sessions with /model smart-router/auto and /smart-router feedback…
+# …sessions with /model smart-router/auto; prefer passive outcomes…
 /smart-router export dataset --limit 200
+/smart-router export telemetry-contrib
+
+# 2) Aggregate privacy-safe contrib / exports (reject tainted payloads)
+npm run routing:calibration-aggregate -- --contrib-dir data/contrib
 
-# 2) Train standalone weights (≥30 labeled rows required)
+# 3) Train when ≥30 economical-tier labeled rows exist
 npm run routing:train-p-success -- --input path/to/export.jsonl --output config/p-success-weights.json
+npm run routing:train-calibration -- --input path/to/aggregated.jsonl
+
+# 4) Verify artifact shapes / gates
+npm run routing:verify-calibration -- config/routing-calibration.json
+```
+
+#### Operator train / reload (no prompt text)
 
-# Or regenerate the checked-in dogfood weights from the synthetic fixture:
+```bash
+# Opt in + dogfood, then export privacy-safe labeled JSONL (features + labels only)
+SMART_ROUTER_DATASET=1
+# …run sessions with /model smart-router/auto (optional: /smart-router feedback)…
+/smart-router export dataset --limit 200
+
+# Train standalone weights (≥30 labeled rows required)
+npm run routing:train-p-success -- --input path/to/export.jsonl --output config/p-success-weights.json
+
+# Or regenerate the checked-in dogfood weights from the synthetic fixture (interim only):
 npm run routing:train-p-success
 
-# 3) Optional: merge isotonic into an existing calibration bundle (does not rewrite hydra/centroids)
+# Optional: merge isotonic into an existing calibration bundle (does not rewrite hydra/centroids)
 npm run routing:train-p-success -- --input path/to/export.jsonl \
   --calibration-output config/routing-calibration.json
 
@@ -628,7 +667,7 @@ Dry-run behavior:
 | `--include-excluded-in-fit` | Weak rows may warm-start the fit pool; `ece_eligible` / holdout ECE stay verifier-grade |
 | Soft threshold | Advisory `0.25` calibrated ECE — **does not** change `config/release-gates.json` |
 
-**#96 / `modernbert_k4` advisory:** when deciding whether to enable ModernBERT K=4 heads, use **pack holdout ECE / Top-1 error on verifier-grade packs** (SWE-Gym + FC-RewardBench), not fixture-only QR and **not** weak-fit ECE. Weak TwinRouterBench rows are warm-start only. This task does **not** flip `modernbert_k4` defaults.
+**#96 / `modernbert_k4` advisory:** when deciding whether to enable ModernBERT K=4 heads, use **pack holdout ECE / Top-1 error on verifier-grade packs** (SWE-Gym + FC-RewardBench), not fixture-only QR and **not** weak-fit ECE. Weak TwinRouterBench rows are warm-start only. This task does **not** flip `modernbert_k4` defaults. Go/no-go evidence (SP-204 / #113): [`spine-tasks/_authoring/release-v0.11.0/encoder-gonogo-artifact.md`](spine-tasks/_authoring/release-v0.11.0/encoder-gonogo-artifact.md).
 
 ### Operator tuning (frugality slider)
 
@@ -864,6 +903,7 @@ Contributors must run `npm run build` before publishing or consuming the library
 | `npm run routing:eval-harness:smoke` | Harness summary JSON only (CI smoke; no network) |
 | `npm run routing:eval-harness:corpus-smoke` | Harness summary on TwinRouterBench CI corpus subset (`tests/eval/corpus/twinrouterbench`) |
 | `npm run routing:assert-release-gates:corpus-report` | Soft-feed: assert corpus vs absolute gates with `--report-only` (exit 0; does not gate releases) |
+| `npm run routing:analyze-overrouting` | TwinRouterBench over-routing breakdown by stage / reason_code / tiers (#112; see `spine-tasks/_authoring/release-v0.11.0/over-routing-analysis.md`) |
 | `npm run routing:twinrouterbench:full-track` | Local/nightly: pin fetch → full convert (no `--limit`) → harness + gates `--report-only` (gitignored cache) |
 | `npm run routing:twinrouterbench:full-ingest` | Convert cached `question_bank.jsonl` → full static-track JSON (no `--limit`) |
 | `npm run routing:twinrouterbench:full-report` | Harness summary + gates `--report-only` on cached full track |
@@ -915,6 +955,7 @@ npm run routing:twinrouterbench:full-track
 | **Regenerate** | `npm run routing:ingest-twinrouterbench -- --input <question_bank.jsonl> --output tests/eval/corpus/twinrouterbench/ci-subset.json --limit 150 --prefer-code-tool` |
 | **Harness smoke** | `npm run routing:eval-harness:corpus-smoke` |
 | **Gate soft-feed** | `npm run routing:assert-release-gates:corpus-report` |
+| **Over-routing breakdown** | `npm run routing:analyze-overrouting` · [v0.11.0 analysis](spine-tasks/_authoring/release-v0.11.0/over-routing-analysis.md) (#112 / #95) |
 | **Human QA protocol** | [`docs/qa/shadow-dogfood-protocol.md`](docs/qa/shadow-dogfood-protocol.md) · `npm run qa:shadow-dogfood` |
 
 **Absolute release gates stay on default fixtures.** `npm run release:functional-smoke` continues to assert `tests/eval/fixtures` against `config/release-gates.json` — do not point it at the corpus without operator review. Today the corpus subset fails `mean_over_routing_rate_max` (≈0.85 vs absolute max 0.15); that gap is intentional soft signal for the [#95](https://github.com/beettlle/pi-smart-router/issues/95) public static-track acceptance criteria alongside live dogfood traces. Use `--fixtures tests/eval/corpus/twinrouterbench` (or the corpus-report script) for #95 public-track scoring; keep absolute threshold edits out of band until operators approve. For live shadow dogfood steps and sign-off, see the [shadow dogfood protocol](docs/qa/shadow-dogfood-protocol.md).
@@ -966,6 +1007,12 @@ npm run routing:community-bench -- \
   --output /tmp/community-bench-report.json \
   --email-file /tmp/community-bench-report.txt
 
+# Optional Track B: labeled dogfood export → harness gates (skips if incomplete — never invents labels)
+npm run routing:community-bench -- \
+  --dogfood-export tests/eval/dogfood-track-b/synthetic-labeled-export.json \
+  --output /tmp/community-bench-report.json \
+  --email-file /tmp/community-bench-report.txt
+
 # Optional Track C: offline LLMRouterBench regret/CS on the vendored subset (no full HF download)
 npm run routing:community-bench -- \
   --llmrouterbench \
@@ -975,7 +1022,7 @@ npm run routing:community-bench -- \
 
 **How to send:**
 
-1. **Email `.txt`** — open `/tmp/community-bench-report.txt` (or your `--email-file` path). It includes a `Subject:` line, privacy blurb, fingerprint, Track A PASS/FAIL, and optional Track C metrics. Paste into your mail client; attach `community-bench-report.json` if useful. Do **not** expect the CLI to send mail.
+1. **Email `.txt`** — open `/tmp/community-bench-report.txt` (or your `--email-file` path). It includes a `Subject:` line, privacy blurb, fingerprint, Track A PASS/FAIL, and optional Track B/C metrics. Paste into your mail client; attach `community-bench-report.json` if useful. Do **not** expect the CLI to send mail.
 2. **GitHub issue** — open the [maintainer contact](https://github.com/beettlle/pi-smart-router/issues/new?labels=community-bench) URL, or run with `--print-issue-body` and paste stdout into a new issue. Issues list: https://github.com/beettlle/pi-smart-router/issues
 
 **Tracks:**
@@ -983,7 +1030,7 @@ npm run routing:community-bench -- \
 | Track | Corpus | When |
 |-------|--------|------|
 | **A (required)** | [TwinRouterBench CI corpus](#twinrouterbench-ci-corpus-sp-186--sp-187--sp-188) (`tests/eval/corpus/twinrouterbench`) | Always |
-| **B (optional)** | Dogfood export (`--dogfood-export PATH`) | Skips with an explicit reason until [#95](https://github.com/beettlle/pi-smart-router/issues/95) adapter lands — never invents labels |
+| **B (optional)** | Labeled dogfood export (`--dogfood-export PATH`) | Runs when adapter + export present with required outcome labels (`success_label`, `min_tier`, `min_model_id`); skips with an explicit reason when incomplete — never invents labels. Example: `tests/eval/dogfood-track-b/synthetic-labeled-export.json` ([#111](https://github.com/beettlle/pi-smart-router/issues/111)) |
 | **C (optional)** | [LLMRouterBench offline subset](#llmrouterbench-offline-regret-sp-192--sp-193) (`tests/eval/corpus/llmrouterbench`) | `--llmrouterbench` or `--full`; offline only |
 
 PR CI does **not** download full TwinRouterBench / LLMRouterBench corpora. Absolute gate thresholds in `config/release-gates.json` are unchanged by this CLI.
@@ -1064,6 +1111,8 @@ npm run routing:verify-benchmark-profiles
 
 Tag-triggered publish via GitHub Actions (requires `NPMSECRET` repository secret). pi.dev gallery listing syncs automatically from npm (`pi-package` keyword); no separate submit step.
 
+**Scope composition:** use `/skill:router-release-operator` for themed release planning (not open-ended backlog cycles). **Patch** = docs + bugfixes only; **minor** = new capability (1–3 related issues under one theme). Budgets and audit rules: [`skills/router-release-operator/references/release-profiles.md`](skills/router-release-operator/references/release-profiles.md).
+
 **Tier 0 functional smoke** (`release:functional-smoke`) runs before tag publish and chains:
 
 1. `routing:verify-calibration --skip-embed` — artifact shape + triage benchmark gates (no ONNX embedding)

package/config/benchmark-profiles.json

@@ -7,8 +7,8 @@
       "livecodebench": "https://livecodebench.github.io/leaderboard.html",
       "bfcl": "https://gorilla.cs.berkeley.edu/leaderboard.html"
     },
-    "scrape_date": "2026-07-11",
-    "catalog_freeze_date": "2026-07-11"
+    "scrape_date": "2026-07-12",
+    "catalog_freeze_date": "2026-07-12"
   },
   "aliases": {
     "claude-3-5-sonnet": "claude-sonnet-4-6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-router",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Auto-model router middleware for the pi.dev coding agent",
   "type": "module",
   "license": "MIT",
@@ -73,6 +73,7 @@
     "routing:eval-harness:smoke": "tsx scripts/eval/run-harness.ts --summary-only",
     "routing:eval-harness:corpus-smoke": "tsx scripts/eval/run-harness.ts --fixtures tests/eval/corpus/twinrouterbench --summary-only",
     "routing:assert-release-gates:corpus-report": "tsx scripts/eval/assert-release-gates.ts --fixtures tests/eval/corpus/twinrouterbench --report-only",
+    "routing:analyze-overrouting": "tsx scripts/eval/analyze-twinrouterbench-overrouting.ts",
     "routing:twinrouterbench:full-ingest": "bash -c 'set -euo pipefail; CACHE=\"${TRB_CACHE_DIR:-.pi-smart-router/eval-cache/twinrouterbench}\"; mkdir -p \"$CACHE\"; npm run routing:ingest-twinrouterbench -- --input \"$CACHE/question_bank.jsonl\" --output \"$CACHE/full-static-track.json\"'",
     "routing:twinrouterbench:full-report": "bash -c 'set -euo pipefail; CACHE=\"${TRB_CACHE_DIR:-.pi-smart-router/eval-cache/twinrouterbench}\"; DIR=\"$CACHE/full-track\"; mkdir -p \"$DIR\"; cp \"$CACHE/full-static-track.json\" \"$DIR/full-static-track.json\"; npm run routing:eval-harness -- --fixtures \"$DIR\" --summary-only; npx tsx scripts/eval/assert-release-gates.ts --fixtures \"$DIR\" --report-only'",
     "routing:twinrouterbench:full-track": "bash scripts/eval/twinrouterbench-full-track.sh",

package/skills/router-backlog-orchestrator/SKILL.md

@@ -14,13 +14,23 @@ Invoke explicitly: `/skill:router-backlog-orchestrator`
 **Compose with:**
 - pi-spine `create-spine-tasks` skill — packet structure and size rules
 - [`skills/spine-autonomous-operator/SKILL.md`](../spine-autonomous-operator/SKILL.md) — preflight, wave loop, recovery, pi-spine issue filing
+- [`skills/router-release-operator/SKILL.md`](../router-release-operator/SKILL.md) — themed semver release composition and publish
 - [`.cursor/rules/spine-task-authoring.mdc`](../../.cursor/rules/spine-task-authoring.mdc) — PROMPT/STATUS contracts
 - [`.cursor/rules/spine-operator-cursor.mdc`](../../.cursor/rules/spine-operator-cursor.mdc) — spine CLI reference
 
+## Skill boundaries
+
+| Concern | Owner |
+|---------|-------|
+| Development **cycle** triage (docs → 3–5 bugs → 1 feature) | This skill |
+| Versioned **release** composition (theme, patch/minor/major, publish) | [`router-release-operator`](../router-release-operator/SKILL.md) |
+
+When the operator asks for a versioned release (`release v0.x.y`, `patch release`, `minor release`, `ship to npm`), **do not** invent feature-patch scopes here. Optionally write a backlog snapshot, then **hand off** to `/skill:router-release-operator`.
+
 ## Success criteria
 
 1. Backlog plan approved by operator before batch start
-2. Documentation issues processed before bugs; feature ratio **1 per 3–5 bugs**
+2. Documentation issues processed before bugs; feature ratio **1 per 3–5 bugs** (cycle policy only)
 3. New `SP-*` packets validate (`spine tasks validate pending`)
 4. Queued scope lands on `main` via gate + integrate
 5. Linked GitHub issues commented/closed when tasks complete
@@ -32,8 +42,10 @@ Invoke explicitly: `/skill:router-backlog-orchestrator`
 - **Never** start a batch without operator approval of the backlog plan table
 - **Never** claim batch/test success without CLI output
 - **Never** create XL tasks; split epics into S/M packets
+- **Never** choose npm bump type or release profile from this skill — use `router-release-operator`
 - **Always** run docs bucket completely before bug/feature ratio units
 - **Always** link packets to GitHub issues in `## Source`
+- **Always** hand off versioned release requests to `router-release-operator` after optional snapshot
 
 ## Phase 0 — Baseline
 
@@ -46,6 +58,8 @@ git status && git branch --show-current   # must be main
 
 Stop if not on `main` or `gh`/`spine` unavailable.
 
+**Release handoff:** if the invocation names a target version or patch/minor/major **release** (not a plain backlog cycle), stop after optional snapshot and invoke [`router-release-operator`](../router-release-operator/SKILL.md).
+
 Optional snapshot:
 
 ```bash
@@ -90,6 +104,8 @@ Dedup:
 
 ## Phase 3 — Prioritize
 
+**Applies to development cycles only** — not versioned releases (see Skill boundaries).
+
 **Order:**
 1. All **documentation** issues
 2. **Bugs** — user-facing / CI blockers first, then wiring/refactors; decompose epics
@@ -100,6 +116,8 @@ Dedup:
 - Then **one ratio unit**: 3–5 bugs + 1 feature
 - Repeat until operator stops or backlog empty
 
+If the operator’s goal for this invocation is **ship a release**, do not expand the ratio unit into a release scope — hand off to [`router-release-operator`](../router-release-operator/SKILL.md) with the intended theme/version.
+
 ## Phase 4 — Operator approval
 
 Present a **Backlog Plan** table before any writes:
@@ -143,6 +161,8 @@ Hand off to [`skills/spine-autonomous-operator/SKILL.md`](../spine-autonomous-op
 
 Do not advance waves until current wave is integrated on `main`.
 
+If this cycle’s approved plan is explicitly a **release ship** (version bump / npm publish), stop cycle execution and continue under [`router-release-operator`](../router-release-operator/SKILL.md) (manifest, theme audit, `release:check`, publish gates).
+
 ## Phase 7 — Issue filing
 
 | Situation | Repo | Action |
@@ -177,7 +197,8 @@ Do not claim orchestrator success unless `npm run verify:ci` exits 0 and the tab
 ## Short prompt (resume)
 
 ```text
-Run router-backlog-orchestrator: collect GitHub + spine backlog → classify →
+Run router-backlog-orchestrator: if operator asked for release vX.Y.Z / patch|minor,
+hand off to router-release-operator. Else: collect GitHub + spine backlog → classify →
 prioritize (docs first, 3-5 bugs + 1 feature) → show plan → author SP packets →
 spine preflight → batch waves → file issues → final report.
 ```

package/skills/router-backlog-orchestrator/references/prioritization-rubric.md

@@ -2,6 +2,8 @@
 
 Use when classifying and ordering work in `router-backlog-orchestrator`.
 
+**Scope:** development **cycle** planning only. Do **not** choose npm bump type (patch/minor/major) or release composition from this rubric — use [`router-release-operator` release profiles](../../router-release-operator/references/release-profiles.md).
+
 ## Buckets
 
 ### documentation
@@ -33,11 +35,14 @@ Use when classifying and ordering work in `router-backlog-orchestrator`.
 
 ## Feature-to-bug ratio
 
-After documentation bucket is empty for this cycle:
+**Cycle policy** (not a release profile). After documentation bucket is empty for this cycle:
 
 - Queue **3 to 5 bugs**, then **exactly 1 feature**
 - One **ratio unit** per orchestrator invocation (default)
-- If fewer than 3 bugs remain, queue remaining bugs + 1 feature (or 0 features if none left)
+- If fewer than 3 bugs remain, queue remaining bugs + at most 1 feature (or 0 features if none left)
+- Empty or short bug queues are normal — do not invent fake bugs to fill a 3–5 quota for a **cycle**
+
+Shipping that work as an npm version is a separate step: hand off to `router-release-operator` (patch = docs+bugs only; enhancements require **minor** + theme).
 
 ## Dedup rules
 

package/skills/router-release-operator/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: router-release-operator
+description: >-
+  End-to-end pi-smart-router release operator. Intakes GitHub issues and pending
+  spine tasks, composes a themed semver-profiled release (patch = docs+bugs only;
+  enhancements require minor), authors/audits packets, executes waves, and
+  publishes after operator approval. Use when asked to run a router release,
+  release vX.Y.Z, patch/minor/major for pi-smart-router, or ship to npm.
+disable-model-invocation: true
+compatibility: Requires gh CLI, spine CLI, git, Node >= 20. Run from pi-smart-router repo root on main.
+---
+
+# Router Release Operator
+
+You are the **pi-smart-router release operator**. Drive a **curated, themed release** from intake through publish: select work by **local** semver profiles, author/audit packets, execute batches, verify, and bump version — with **operator approval** before publish.
+
+Invoke explicitly: `/skill:router-release-operator` or "release v0.10.0" / "patch release" / "minor release".
+
+**Not** for executing all pending tasks or open-ended backlog cycles — use [`router-backlog-orchestrator`](../router-backlog-orchestrator/SKILL.md) for development cycles. This skill selects a **subset** fitting the release profile and theme.
+
+## Skill boundaries
+
+| Concern | Delegate to |
+|---------|-------------|
+| Semver scope budgets / theme audit | [references/release-profiles.md](references/release-profiles.md) (**this repo — not pi-spine**) |
+| Issue intake | [references/issue-intake-checklist.md](references/issue-intake-checklist.md) |
+| Manifest format | [references/release-manifest-template.md](references/release-manifest-template.md) |
+| PROMPT/STATUS/Contract authoring | `create-spine-tasks` + [packet-from-issue.md](../router-backlog-orchestrator/references/packet-from-issue.md) |
+| Batch land / recovery / detached policy | pi-spine `spine-release-operator` Phase 4+ **or** `spine-autonomous-operator` + [`.cursor/rules/spine-operator-cursor.mdc`](../../.cursor/rules/spine-operator-cursor.mdc) |
+| Cycle triage (docs → bugs → features) | [`router-backlog-orchestrator`](../router-backlog-orchestrator/SKILL.md) — hand off **here** when operator asks for a versioned release |
+
+## Success criteria
+
+1. Release manifest written with **theme** and operator-approved scope
+2. Profile audit **PASS** (or PASS with cap override only — never feature-in-patch OVERRIDE)
+3. All **release-scoped** tasks `.DONE` and integrated on `main`
+4. `spine preflight` green; **`npm run release:check` green (blocking)** on current `main`
+5. **CI workflow green on `HEAD`** before tag push
+6. Operator explicitly approved publish; version bumped and tag pushed (if approved)
+7. Final report with theme, composition table, deferred backlog, verification output
+
+## Hard rules
+
+- **Never** hand-edit `.spine/batch-state.json` or `.spine/runtime/**`
+- **Never** ship enhancements in a **patch** — reclassify as **minor** or drop (no OVERRIDE theater)
+- **Never** omit the release **theme** or select work that contradicts it
+- **Never** treat empty open-bug queue as audit failure — use `PASS (no open bugs)`
+- **Never** run `npm version` or `git push --tags` without explicit operator approval
+- **Never** run `npm version` / tag push when `npm run release:check` exits non-zero on current `main`
+- **Never** run `npm version` / tag push when CI is not green on current `HEAD`
+- **Always** parse target version / bump type **before** task selection (Phase 2)
+- **Always** use [references/release-profiles.md](references/release-profiles.md) for budgets (not pi-spine profiles)
+- **Always** prioritize documentation before enhancements within the theme
+- **Always** run `spine gate approve` before `spine integrate`
+- **Always** run `npm install` on `main` after successful integrate
+- **Always** run post-integrate `npm run release:check` on `main` after each wave before the next wave or push
+- **Never** judge `release:check` from `| tail` / `| head` alone — verify exit code
+- **Do not** execute tasks outside the approved manifest scope
+- **Do not** start a second batch while another is **running** on this repo
+- **Release batches:** prefer detached `spine batch start|resume` (omit `--attached`); see spine-operator rules
+
+---
+
+## Pre-work — GitNexus index (recommended)
+
+```bash
+cd <repo-root>
+# Prefer: node .gitnexus/run.cjs analyze   OR   npx gitnexus analyze
+gitnexus status   # when available — Status up-to-date with HEAD
+```
+
+If analyze fails, report and continue only if operator accepts stale index risk.
+
+---
+
+## Phase 0 — Baseline and target version
+
+```bash
+cd <repo-root>    # pi-smart-router root
+spine --version && spine doctor
+node -p "require('./package.json').version"
+git status
+git branch --show-current   # must be main
+```
+
+**Parse invocation** for target version or bump type — see [release-profiles.md](references/release-profiles.md).
+
+If not on `main`, stop. If git is dirty, commit or stash hygiene before release work.
+
+---
+
+## Phase 1 — Intake inventory
+
+Follow [references/issue-intake-checklist.md](references/issue-intake-checklist.md).
+
+**GitHub** (`beettlle/pi-smart-router` only):
+
+```bash
+gh issue list --repo beettlle/pi-smart-router --state open --limit 100 \
+  --json number,title,labels,body
+```
+
+**Pending tasks:**
+
+```bash
+spine plan pending
+spine tasks validate pending
+spine tasks analyze pending
+rg 'GitHub: beettlle/pi-smart-router#|Closes:|Partial:' spine-tasks/*/PROMPT.md
+```
+
+Read `spine-tasks/CONTEXT.md` for `Next Task ID`. Skim `docs/routing-roadmap.md` for enhancement priority.
+
+**Output:** intake table (issue #, labels, mapped SP-* or gap, bucket, theme fit, profile fit).
+
+---
+
+## Phase 2 — Compose release manifest
+
+Write:
+
+```
+spine-tasks/_authoring/release-v{TARGET}/manifest.md
+```
+
+Use [references/release-manifest-template.md](references/release-manifest-template.md).
+
+### Selection order (strict)
+
+1. State the **theme** (one sentence)
+2. **Documentation** fitting the theme
+3. **Bug fixes** (all high-impact that fit the cap; 0 OK)
+4. **Enhancements** — only if profile is minor/major; 1–3 related issues completing the theme
+5. **Defer** everything else with one-line rationale
+
+Apply [release-profiles.md](references/release-profiles.md) budgets. **FAIL** if enhancements appear under patch — ask operator to bump to minor or drop features.
+
+### Operator gate
+
+Present:
+
+- Target version, profile, **theme**
+- Selected SP-* / issues by bucket
+- Deferred count + reasons
+- Profile audit status
+
+Require explicit **"approve release scope"** before Phase 3.
+
+---
+
+## Phase 3 — Author gaps and audit packets
+
+### 3.1 Author new tasks (gaps only)
+
+For issues in manifest without SP-*:
+
+- Follow `create-spine-tasks` (lean) + [packet-from-issue.md](../router-backlog-orchestrator/references/packet-from-issue.md)
+- Link GitHub in `## Source`; Mission `Closes: #NNN` or `Partial:`
+- Size S/M; ≤4 impl steps; Contract + Testing step
+- Update `dependencies.json`, `CONTEXT.md`, `Next Task ID`
+- Serialize hot files: `.pi/extensions/smart-router/index.ts`, `src/domain/pipeline/router-pipeline.ts`, `src/api/middleware/pi-router-middleware.ts`
+
+### 3.2 Audit release-scoped packets
+
+| Size | Action |
+|------|--------|
+| **S** | Keep if ≤4 impl steps |
+| **M** | OK if disjoint; in patch only for bug-fix decomposition |
+| **L/XL** | **Split** before inclusion |
+
+```bash
+spine tasks validate <release-scope>
+spine tasks analyze <release-scope>
+spine plan <release-scope>
+```
+
+### 3.3 Commit packet changes
+
+```bash
+git add spine-tasks/
+git commit -m "chore(spine): release v{TARGET} task packets"
+```
+
+---
+
+## Phase 4 — Execute release scope
+
+Delegate wave start / monitor / land / recovery to pi-spine **spine-release-operator** Phase 4 (or spine-autonomous-operator) with these **repo-specific** gates:
+
+**Scope:** manifest tasks only — comma-separated release scope ID list.
+
+```bash
+spine preflight
+spine run sequence <release-scope> --dry-run
+```
+
+For each wave until release-scoped tasks are `.DONE`:
+
+1. Detached `spine batch start <release-scope> --wave N` (omit `--attached` unless persistent interactive terminal)
+2. `spine status --diagnose` / `spine wait`
+3. Land: `spine gate approve` → `spine integrate` → `npm install` → `spine batch complete`
+4. **Post-integrate regression gate (blocking):**
+
+```bash
+npm run release:check 2>&1 | tee /tmp/pi-smart-router-post-integrate-wave-${N}.log
+test "${PIPESTATUS[0]}" -eq 0
+```
+
+Do **not** start wave N+1, push, or publish until exit 0. Fix on `main` and re-run if failed.
+
+Wave sizing: ≤4 M-sized tasks per wave; serialize hot shared files.
+
+---
+
+## Phase 5 — Pre-publish verification (STOP)
+
+```bash
+spine plan <release-scope>    # 0 pending for scope
+spine preflight
+npm run release:check 2>&1 | tee /tmp/pi-smart-router-release-check.log
+test "${PIPESTATUS[0]}" -eq 0
+```
+
+**If non-zero:** STOP. Fix on `main`, re-run Phase 5. Do not ask for publish approval.
+
+Present checklist (only after exit 0):
+
+- [ ] All release-scoped tasks done
+- [ ] Theme + profile audit still accurate
+- [ ] `npm run release:check` exit 0
+- [ ] CI green on `HEAD` (`gh run list --workflow ci.yml --commit "$(git rev-parse HEAD)"`)
+- [ ] Clean git tree
+- [ ] Bump type matches Phase 2 profile
+
+**Human gate:** do not bump or push until operator approves publish **and** Phase 5 passed.
+
+---
+
+## Phase 6 — Publish (after approval only)
+
+**Prerequisites:** Phase 5 `release:check` exit 0; CI green on `HEAD`; operator said approve publish + confirmed bump type.
+
+```bash
+COMMIT=$(git rev-parse HEAD)
+gh run list --workflow ci.yml --commit "$COMMIT" --json databaseId,conclusion,status --limit 5
+# Fail closed unless conclusion: success
+
+npm version patch   # or minor / major — must match Phase 2
+git push && git push --tags
+gh run list --workflow release.yml --limit 3
+```
+
+Post-publish:
+
+```bash
+npm view pi-smart-router version
+# optional: pi install npm:pi-smart-router@<version>
+```
+
+Update `spine-tasks/CONTEXT.md` release note. Close GitHub issues where acceptance was met (`Closes:`).
+
+---
+
+## Final report (required)
+
+1. Manifest path, target version, profile, **theme**, composition table
+2. Tasks completed — SP-IDs, waves, issues closed
+3. Deferred backlog — count and top items
+4. Profile audit result (no feature-in-patch OVERRIDE)
+5. Verification — `release:check` log path / exit code; CI run URL
+6. Publish — version bumped (Y/N), tag, workflow URL, or awaiting approval
+
+## Repo-specific notes
+
+| Item | Value |
+|------|-------|
+| Tasks root | `spine-tasks/` |
+| Issues repo | `beettlle/pi-smart-router` |
+| Profiles | `skills/router-release-operator/references/release-profiles.md` |
+| Pre-publish gate | `npm run release:check` |
+| Publish | Tag-triggered `.github/workflows/release.yml` |
+
+## Short prompt (resume mid-release)
+
+```text
+Resume router release v{TARGET}: check manifest at
+spine-tasks/_authoring/release-v{TARGET}/manifest.md (theme + profile audit) →
+spine status --diagnose → preflight → for each wave: batch start → diagnose →
+gate approve → integrate → npm install → batch complete →
+post-integrate release:check (exit 0) → final release:check → CI green on HEAD →
+STOP for publish approval. Post final report with theme and composition table.
+```

package/skills/router-release-operator/references/issue-intake-checklist.md

@@ -0,0 +1,113 @@
+# Issue intake checklist (pi-smart-router)
+
+Run during **Phase 1** before composing the release manifest.
+
+## GitHub queries
+
+Repo: `beettlle/pi-smart-router`
+
+```bash
+gh issue list --repo beettlle/pi-smart-router --state open --limit 100 \
+  --json number,title,labels,body
+
+gh issue list --repo beettlle/pi-smart-router --state open --label documentation \
+  --json number,title,labels
+
+gh issue list --repo beettlle/pi-smart-router --state open --label bug \
+  --json number,title,labels
+
+gh issue list --repo beettlle/pi-smart-router --state open --label enhancement \
+  --json number,title,labels
+```
+
+## Label taxonomy
+
+| Label | Release bucket | Priority notes |
+|-------|----------------|----------------|
+| `documentation` | Documentation | Highest — address before enhancements when theme allows |
+| `bug` | Bug fix | Prefer user-impact, reproducible, already-tasked |
+| `enhancement` | Enhancement | Minor/major only; zero per patch |
+| Priority in title/body (P0–P3) | Any | Prefer P0/P1 dogfood over P3 eval when choosing among enhancements |
+
+## Roadmap and theme fit
+
+Read [`docs/routing-roadmap.md`](../../../docs/routing-roadmap.md) before selecting enhancements.
+
+| Kind | Examples | Theme wording |
+|------|----------|---------------|
+| User-facing routing | Pinning, triage, local_zero, dogfood fixes | Name the user-visible behavior |
+| Eval / infra | Corpora, benches, release gates soft-feed | Name the eval/tooling track; do not mix with unrelated dogfood unless one theme |
+
+When multiple enhancements compete, prefer P0/P1 dogfood / routing quality over P3 bench/community work unless the operator sets an eval theme.
+
+## Issue → task mapping
+
+1. Grep pending and done tasks for issue links:
+
+   ```bash
+   rg 'GitHub: beettlle/pi-smart-router#|Closes:|Partial:' spine-tasks/*/PROMPT.md
+   ```
+
+2. Classify each open issue:
+
+   | State | Action |
+   |-------|--------|
+   | Mapped to pending SP-* | Candidate for manifest if fits profile + theme |
+   | Mapped to `.DONE` SP-* | Closed by shipped work — exclude |
+   | No SP-* yet | **Gap** — author with `create-spine-tasks` in Phase 3 |
+   | Epic / `[Epic]` in title | Defer unless major profile with operator approval |
+   | Hardware (#1/#25/#26) | Defer — physical access |
+
+## Documentation issue heuristics
+
+Prefer for release inclusion when:
+
+- `label:documentation` or title/body is README, quickstart, operator guide, env vars
+- Pending SP-* with docs-only File Scope
+- Docs required to ship the release theme (minor)
+
+## Bug issue heuristics
+
+Prefer when:
+
+- Repro steps in issue body or linked diagnosis
+- Already has pending SP-* linked to the GitHub issue
+- S/M size, disjoint file scope from parallel neighbors
+- User-visible failure (routing, failover, pin, install)
+
+Exclude when:
+
+- Fixed on `main` but issue not closed
+- Blocked by epic infrastructure not in this release
+
+If **no open bugs**, record that for audit — do not invent OVERRIDE.
+
+## Enhancement issue heuristics
+
+**Patch profile:** exclude all. If operator wants them, **reclassify release as minor**.
+
+**Minor profile:** pick 1–3 **related** issues that complete the theme:
+
+- User-visible or operator-visible improvement
+- S/M size; split L/XL first
+- Disjoint `fileScopeMustChange` from bug tasks in same wave
+- Prefer roadmap P0/P1 over P3 when both fit
+
+## Pending task inventory
+
+```bash
+spine plan pending
+spine tasks validate pending
+spine tasks analyze pending
+```
+
+Read `spine-tasks/CONTEXT.md` for `Next Task ID` and phase notes.
+
+Cross-reference pending SP-* with open issues. The release executes **manifest scope only**, not all pending tasks.
+
+## Intake output table
+
+| Issue # | Labels | Mapped SP-* | Bucket | Theme fit | Profile fit | Notes |
+|---------|--------|-------------|--------|-----------|-------------|-------|
+| #97 | bug | SP-176 | bug | dogfood ✓ | minor ✓ | triage fix |
+| #101 | enhancement | — | enh | eval corpus | patch ✗ → use minor | TwinRouterBench |

package/skills/router-release-operator/references/release-manifest-template.md

@@ -0,0 +1,117 @@
+# Release manifest — v{TARGET_VERSION}
+
+**Created:** {YYYY-MM-DD}
+**Current version:** {from package.json}
+**Target version:** v{TARGET_VERSION}
+**Bump type:** patch | minor | major
+**Profile:** patch | minor | major
+**Theme:** {one sentence — required}
+**Operator approved scope:** no | yes ({date})
+
+---
+
+## Composition audit
+
+| Bucket | Selected | Profile limit | Status |
+|--------|----------|---------------|--------|
+| Theme | {sentence} | required | PASS / FAIL |
+| Documentation | {n} | patch 0–2 / minor theme docs | PASS / WARN |
+| Bug fixes | {n} | soft; 0 OK if none open | PASS / PASS (no open bugs) / WARN |
+| Enhancements | {n} | patch **0** / minor 1–3 related | PASS / FAIL |
+| **Total tasks** | {n} | patch ≤8 / minor ≤15 | PASS / WARN |
+
+**Profile audit:** PASS | PASS with operator override (caps only) | FAIL (do not proceed)
+
+**Hygiene (patch only, if any):** {one-line justification or "none"}
+
+---
+
+## Selected tasks
+
+| SP-ID | Issue | Bucket | Size | Title | Notes |
+|-------|-------|--------|------|-------|-------|
+| SP-### | #NNN | doc / bug / enh | S/M | … | Closes / Partial |
+
+**Release scope ID:** comma-separated SP-IDs for `spine plan`, `spine batch start`, and `spine run sequence` (e.g. `SP-196,SP-197,SP-199`). No spaces.
+
+---
+
+## Sequence runner (Phase 4)
+
+The manifest is the operator contract; the CLI takes the **scope ID string**, not the manifest file path.
+
+```bash
+spine tasks validate <SP-IDs...>
+spine plan <release-scope-id>
+spine run sequence <release-scope-id> --dry-run
+spine run sequence <release-scope-id>    # detached — omit --attached
+```
+
+Per-wave manual loop (alternative to full sequence):
+
+```bash
+spine batch start <release-scope-id> --wave N
+spine status --diagnose
+spine gate approve && spine integrate && npm install && spine batch complete
+```
+
+**Regression gate** (after each integrate, before next wave):
+
+```bash
+npm run release:check 2>&1 | tee /tmp/pi-smart-router-post-integrate-wave-${WAVE:-main}.log
+test "${PIPESTATUS[0]}" -eq 0
+```
+
+Do **not** use `| tail` alone for pass/fail — verify exit code.
+
+**Operator gates** (human only):
+
+1. Approve this manifest (operator sign-off on scope + theme)
+2. `spine gate approve` per integrate wave
+3. Publish approval before `npm version <bump>`
+
+---
+
+## Gaps requiring new packets
+
+| Issue | Bucket | Proposed SP-ID | Author with |
+|-------|--------|----------------|-------------|
+| #90 | doc | SP-### | create-spine-tasks (lean) |
+
+---
+
+## Wave plan snapshot
+
+```text
+(paste output of: spine plan <release-scope>)
+```
+
+---
+
+## Deferred backlog
+
+| Item | Type | Rationale |
+|------|------|-----------|
+| SP-### / #NNN | enh | Outside theme; defer to next minor |
+| #1 / #25 / #26 | epic | Hardware — blocked on physical access |
+
+---
+
+## Risks and blockers
+
+- {e.g. hot-file serialization on router-pipeline.ts}
+- {e.g. release:check flaky assert — fix before tag}
+
+---
+
+## Publish checklist (Phase 5–6)
+
+- [ ] All release-scoped tasks `.DONE` on `main`
+- [ ] Post-integrate `release:check` green after **each wave** (log paths recorded)
+- [ ] `spine preflight` green
+- [ ] `npm run release:check` green on final `HEAD` (exit 0 verified)
+- [ ] CI workflow green on `HEAD` (`gh run list` / `gh run watch`)
+- [ ] `git status` clean
+- [ ] Operator approved publish bump type: patch | minor | major (matches Phase 2)
+- [ ] `npm version <bump>` + `git push && git push --tags`
+- [ ] `release.yml` succeeded; `npm view pi-smart-router version` matches target

package/skills/router-release-operator/references/release-profiles.md

@@ -0,0 +1,127 @@
+# Release profiles (pi-smart-router)
+
+Use at **Phase 2** after parsing the operator's target version. Compare `package.json` version to the target to derive bump type.
+
+These budgets **replace** pi-spine `spine-release-operator` profile math for this repo. Batch land / publish mechanics still follow spine-release-operator or spine-autonomous-operator.
+
+## Derive bump type
+
+| Current → Target | Bump type | Profile |
+|------------------|-----------|---------|
+| `0.9.3` → `0.9.4` | **patch** | `patch` |
+| `0.9.3` → `0.10.0` | **minor** | `minor` |
+| `0.10.0` → `1.0.0` | **major** | `major` |
+
+If the operator says only `patch` / `minor` / `major` without a version, compute the next version from `package.json` and record both in the manifest.
+
+## Invocation parsing
+
+| Operator says | Profile |
+|---------------|---------|
+| "release for v0.9.4", "patch release", "hotfix release" | `patch` |
+| "release for v0.10.0", "minor release", "feature release" | `minor` |
+| "release for v1.0.0", "major release", "breaking release" | `major` |
+| "run a router release cycle" (no version) | **Ask** operator for target version or bump type |
+
+## Theme (all profiles)
+
+Every release **requires** a one-sentence **theme** in the manifest (e.g. "Dogfood routing fixes", "Eval corpora & community bench", "Stability hotfix").
+
+- Selected issues/tasks must **complete or clearly serve** that theme.
+- Prefer **sibling clusters** that finish the theme over thin single-issue versions.
+- Theme missing or selected work contradicts the theme → **FAIL** (do not proceed).
+
+## Profile budgets
+
+### Patch (`patch`)
+
+Stability and correctness only. No new capability.
+
+| Bucket | Target | Hard limits |
+|--------|--------|-------------|
+| Theme | Required (stability / hotfix) | Must match selected work |
+| Documentation | 0–2 clarifications | No new feature docs; defer large doc epics |
+| Bug fixes | Soft target 1–5 high-impact | Include open high-impact bugs that fit the cap; **0 OK** when none open |
+| Enhancements | **0** | **Hard fail** if any enhancement included — reclassify as minor or drop |
+| Total tasks | **≤8** | WARN if >8; proceed only with operator override that keeps bump type honest |
+| Max waves | 1–2 | Prefer single wave when possible |
+| Task sizes | S preferred; M OK | M allowed only for bug-fix decomposition with disjoint scope; split L/XL |
+
+**Hygiene exception (patch only):** non-user-facing fixes (typo, flake clock, lint-only) allowed with a **one-line justification** in the manifest. Still **no** new capability.
+
+**Defer by default:** all enhancements, roadmap items, eval/infra features, epics, hardware.
+
+### Minor (`minor`)
+
+One capability theme plus related stability work.
+
+| Bucket | Target | Hard limits |
+|--------|--------|-------------|
+| Theme | Required (capability name) | Sibling issues that complete the theme preferred |
+| Documentation | Docs for the theme | Include operator-facing docs for shipped capability |
+| Bug fixes | Open high-impact that fit | Soft; **0 OK** when no open bugs (`PASS (no open bugs)`) |
+| Enhancements | **1–3 related** issues | Must serve the theme; defer unrelated P2/P3 |
+| Total tasks | **≤15** | WARN if >15 without override |
+| Max waves | 2–4 | ≤4 M-sized tasks per wave |
+| Task sizes | S/M | Split L/XL before inclusion |
+
+**Defer by default:** unrelated roadmap slices, hardware epics, work needing >4 waves.
+
+**Priority among enhancements:** prefer [`docs/routing-roadmap.md`](../../../docs/routing-roadmap.md) P0/P1 dogfood over P3 eval when choosing what completes the theme.
+
+### Major (`major`)
+
+Breaking changes and large migrations (e.g. 1.0 readiness). Operator-defined epic scope.
+
+| Bucket | Target | Hard limits |
+|--------|--------|-------------|
+| Theme | Required (breaking / 1.0) | Explicit epic boundaries in manifest |
+| Documentation | Migration guides + comprehensive pass | Required for breaking changes |
+| Bug fixes | Critical blockers | Prioritize regressions blocking migration |
+| Enhancements | Multiple allowed | Breaking API changes OK with migration path |
+| Total tasks | Operator-defined | Manifest must list epic boundaries |
+| Max waves | Planned in manifest | Expect multi-cycle execution |
+
+**Require:** explicit operator approval of epic scope before Phase 3. Do not auto-select major scope from backlog alone.
+
+## Selection order (all profiles)
+
+Apply in this order; stop when profile budget is full:
+
+1. **Documentation** — `label:documentation`, README/operator-guide clarifications fitting the theme
+2. **Bug fixes** — open `label:bug` with user impact; prefer already-tasked or quick S/M
+3. **Enhancements** — **minor/major only**; only theme-completing related issues
+4. **Defer** everything else with one-line rationale
+
+## Profile audit (must pass before Phase 3)
+
+| Check | Patch | Minor | Major |
+|-------|-------|-------|-------|
+| Theme present and coherent | Required | Required | Required |
+| Enhancement count | **>0 → FAIL** (reclassify or drop) | >3 without override → WARN | — |
+| Bug count | 0 + no open bugs → **PASS (no open bugs)**; open bugs skipped without deferral → WARN | Same | Critical blockers skipped → WARN |
+| Total tasks | >8 → WARN | >15 → WARN | — |
+| M/L in patch | L/XL → split; M only for bug-fix decomposition | — | — |
+| Bump type vs content | Features in scope → must be **minor**, not patch OVERRIDE | — | — |
+
+**Do not** use OVERRIDE to ship enhancements as patch. Change bump type to minor or drop the enhancement.
+
+Record `Profile audit: PASS` or `PASS with operator override` (caps/waves only; never for feature-in-patch) before proceeding.
+
+## Version ↔ publish alignment
+
+The bump type chosen in Phase 2 must match `npm version` in Phase 6:
+
+- `patch` profile → `npm version patch`
+- `minor` profile → `npm version minor`
+- `major` profile → `npm version major`
+
+If the operator changes bump type at publish gate, update the manifest and confirm scope still fits the new profile.
+
+## Sanity checks (read-through)
+
+| Proposal | Result |
+|----------|--------|
+| Ship #106 + #107 as **patch** | **FAIL** — enhancements; recommend **minor** with theme e.g. "TwinRouterBench fit & CI track" |
+| Hotfix only open bugs as **patch**, theme "Stability hotfix" | **PASS** |
+| Feature-only minor, 0 open bugs, theme "Live leaderboard ingest" | **PASS (no open bugs)** |