pi-smart-router 0.1.0

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "pi-smart-router",
+  "version": "0.1.0",
+  "description": "Auto-model router middleware for the pi.dev coding agent",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "smart-router",
+    "routing",
+    "ai",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beettlle/pi-smart-router.git"
+  },
+  "homepage": "https://github.com/beettlle/pi-smart-router#readme",
+  "bugs": {
+    "url": "https://github.com/beettlle/pi-smart-router/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "pi-smart-router": "./bin/pi-smart-router.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    ".pi/extensions/smart-router",
+    "!.pi/extensions/smart-router/node_modules",
+    "!.pi/extensions/smart-router/node_modules/**",
+    "!.pi/extensions/smart-router/package-lock.json",
+    "config",
+    "skills",
+    "specs/001-build-smart-router/contracts/telemetry-contrib.schema.json",
+    "data/contrib/example.json"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run release:check",
+    "release:check": "npm run verify:ci",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage:check": "vitest run --coverage",
+    "lint": "eslint . --ext .ts && node --input-type=module -e \"import { readFileSync } from 'node:fs'; import { parse } from 'yaml'; const doc = parse(readFileSync('config/models.yaml.example', 'utf8')); if (!Array.isArray(doc.models) || doc.models.length < 3) throw new Error('models.yaml.example must list at least one model per tier'); const tiers = new Set(doc.models.map((m) => m.tier)); for (const tier of ['zero-tier', 'economical-cloud', 'frontier-cloud']) { if (!tiers.has(tier)) throw new Error('missing tier: ' + tier); } console.log('models.yaml.example: valid');\"",
+    "routing:bootstrap-centroids": "node --experimental-strip-types scripts/bootstrap-routing-centroids.ts",
+    "routing:calibration-aggregate": "node --experimental-strip-types scripts/calibration-aggregate.ts",
+    "routing:train-calibration": "node --experimental-strip-types scripts/train-routing-calibration.ts",
+    "routing:verify-calibration": "npm run build && node --experimental-strip-types scripts/verify-routing-calibration.ts",
+    "routing:test-projection": "npm run build && node --experimental-strip-types scripts/test-hydra-projection.ts",
+    "verify:ci": "npm run build && npm run typecheck && npm run lint && npm test && npm run coverage:check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.21",
+    "@typescript-eslint/eslint-plugin": "^8.62.1",
+    "@typescript-eslint/parser": "^8.62.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^8.57.1",
+    "typescript": "^5.8.3",
+    "@vitest/coverage-v8": "^3.2.3",
+    "vitest": "^3.2.3",
+    "yaml": "^2.9.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@huggingface/transformers": "^4.2.0",
+    "better-sqlite3": "^12.11.1",
+    "zod": "^4.4.3"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true
+  },
+  "pi": {
+    "extensions": [
+      ".pi/extensions/smart-router/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "minPiVersion": "0.80.0"
+  }
+}

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

@@ -0,0 +1,183 @@
+---
+name: router-backlog-orchestrator
+description: Plans and executes the next pi-smart-router development cycle from GitHub issues and spine backlog. Prioritizes documentation first, then bugs, then features at one feature per 3-5 bugs. Creates SP-* task packets, runs spine batch with monitoring, and files issues on beettlle/pi-spine or beettlle/pi-smart-router as appropriate.
+disable-model-invocation: true
+compatibility: Requires gh CLI, spine CLI, git, Node >= 20. Run from repo root on main.
+---
+
+# Router Backlog Orchestrator
+
+Orchestrates **backlog triage → spine packet authoring → batch execution → issue filing** for [pi-smart-router](https://github.com/beettlle/pi-smart-router).
+
+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
+- [`.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
+
+## Success criteria
+
+1. Backlog plan approved by operator before batch start
+2. Documentation issues processed before bugs; feature ratio **1 per 3–5 bugs**
+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
+6. Engine faults filed at [pi-spine issues](https://github.com/beettlle/pi-spine/issues); product defects at [pi-smart-router issues](https://github.com/beettlle/pi-smart-router/issues)
+
+## Hard rules
+
+- **Never** hand-edit `.spine/batch-state.json` or `.spine/runtime/**`
+- **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
+- **Always** run docs bucket completely before bug/feature ratio units
+- **Always** link packets to GitHub issues in `## Source`
+
+## Phase 0 — Baseline
+
+```bash
+cd <repo-root>
+gh auth status
+spine --version && spine doctor
+git status && git branch --show-current   # must be main
+```
+
+Stop if not on `main` or `gh`/`spine` unavailable.
+
+Optional snapshot:
+
+```bash
+skills/router-backlog-orchestrator/scripts/collect-backlog.sh
+```
+
+## Phase 1 — Collect backlog
+
+**GitHub:**
+
+```bash
+gh issue list --repo beettlle/pi-smart-router --state open --limit 100 \
+  --json number,title,labels,body,url,createdAt
+```
+
+**Local spine:**
+
+```bash
+spine plan pending
+spine plan all
+```
+
+Scan for orphan packets (PROMPT without `.DONE`). Read [`spine-tasks/CONTEXT.md`](../../spine-tasks/CONTEXT.md) for `Next Task ID`.
+
+Write optional authoring snapshot: `spine-tasks/_authoring/backlog-snapshot-YYYYMMDD.md`.
+
+## Phase 2 — Classify and dedupe
+
+Use [references/prioritization-rubric.md](references/prioritization-rubric.md).
+
+| Bucket | Signals |
+|--------|---------|
+| documentation | label `documentation`, or README/docs/quickstart/operator guide |
+| bug | label `bug`, fix/wiring/regression/P0 audit |
+| feature | label `enhancement`, new capability |
+| epic | title `[Epic]` or multiple deliverables → **split** before authoring |
+
+Dedup:
+- Search `spine-tasks/**/PROMPT.md` for `GitHub: beettlle/pi-smart-router#NNN`
+- Skip issues already linked to `.DONE` tasks unless amendment needed
+- Prefer GitHub issue over duplicate orphan PROMPT
+
+## Phase 3 — Prioritize
+
+**Order:**
+1. All **documentation** issues
+2. **Bugs** — user-facing / CI blockers first, then wiring/refactors; decompose epics
+3. **Features** — one per ratio unit after every **3–5 bugs**
+
+**Default batch scope per invocation:**
+- All open doc tasks first
+- Then **one ratio unit**: 3–5 bugs + 1 feature
+- Repeat until operator stops or backlog empty
+
+## Phase 4 — Operator approval
+
+Present a **Backlog Plan** table before any writes:
+
+| Order | Issue | Bucket | Proposed SP-ID | Size | Notes |
+|-------|-------|--------|----------------|------|-------|
+
+Include ratio summary (e.g. "4 bugs + 1 feature this cycle"). **Stop** until operator approves.
+
+## Phase 5 — Author spine packets
+
+Follow [references/packet-from-issue.md](references/packet-from-issue.md) and `create-spine-tasks`:
+
+1. Allocate IDs from `Next Task ID` in `spine-tasks/CONTEXT.md`
+2. Create `spine-tasks/SP-0xx-slug/PROMPT.md` + `STATUS.md`
+3. Add `## Source` with GitHub link and bucket
+4. Update `spine-tasks/dependencies.json` (serialize hot files: `.pi/extensions/smart-router/index.ts`, `src/domain/pipeline/router-pipeline.ts`)
+5. Validate:
+
+```bash
+spine tasks validate pending
+spine tasks analyze pending
+spine plan pending
+```
+
+6. Commit on `main`:
+
+```bash
+git add spine-tasks/
+git commit -m "chore(spine): queue SP-0xx+ from backlog orchestrator"
+```
+
+## Phase 6 — Execute spine batch
+
+Hand off to [`skills/spine-autonomous-operator/SKILL.md`](../spine-autonomous-operator/SKILL.md) **Phase 2 onward**:
+
+- `spine preflight` (green required)
+- Wave loop: `spine batch start pending --wave N --attached`
+- Monitor: `spine status --diagnose`, `spine wait`
+- Land: `spine gate approve` → `spine integrate` → `npm install` → `npm run verify:ci` → `spine batch complete`
+
+Do not advance waves until current wave is integrated on `main`.
+
+## Phase 7 — Issue filing
+
+| Situation | Repo | Action |
+|-----------|------|--------|
+| Repeatable spine fault after `suggestedCommand` | beettlle/pi-spine | `spine issue draft --create` or template in spine-autonomous-operator |
+| Product bug / regression found during work | beettlle/pi-smart-router | [references/github-router-issue-template.md](references/github-router-issue-template.md) |
+| Task lands (.DONE + integrate) | beettlle/pi-smart-router | Comment summary + **close** linked issue if acceptance met |
+
+Search existing issues before creating duplicates.
+
+## Phase 8 — Final report
+
+1. Backlog plan executed (issue → SP mapping)
+2. Ratio achieved (bugs vs features)
+3. GitHub issues opened/closed/commented (URLs)
+4. Spine recovery actions
+5. Verification: `spine plan pending`, `spine preflight`, `npm run verify:ci` — **block success on any failure**
+6. Remaining backlog preview for next invocation
+
+**Final report verification template** — list each CI step pass/fail:
+
+| Step | Command | Result |
+|------|---------|--------|
+| Build | `npm run build` | pass / fail |
+| Typecheck | `npm run typecheck` | pass / fail |
+| Lint | `npm run lint` | pass / fail |
+| Test | `npm test` | pass / fail |
+| Coverage | `npm run coverage:check` | pass / fail |
+
+Do not claim orchestrator success unless `npm run verify:ci` exits 0 and the table is included in the report.
+
+## Short prompt (resume)
+
+```text
+Run router-backlog-orchestrator: 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/github-router-issue-template.md

@@ -0,0 +1,78 @@
+# pi-smart-router GitHub issue template
+
+File product bugs and gaps at https://github.com/beettlle/pi-smart-router/issues
+
+Search existing issues before creating.
+
+## Title format
+
+```text
+[bug] Short description
+[docs] Short description
+[enhancement] Short description
+```
+
+## Body template
+
+```markdown
+## Summary
+
+One paragraph describing the problem or gap.
+
+## Environment
+
+- pi-smart-router: `<git rev-parse --short HEAD>`
+- pi: `pi --version`
+- Node: `node --version`
+- Provider/model (if routing): e.g. smart-router/auto → gemini-flash
+
+## Steps to reproduce
+
+1. ...
+2. ...
+
+## Expected
+
+...
+
+## Actual
+
+...
+
+## Spine task (if any)
+
+- SP-0xx-slug (link or path)
+- Batch ID: `.spine/runtime/...` (if applicable)
+
+## Verification
+
+Commands that demonstrate fix or repro:
+
+```bash
+npm run typecheck && npm test
+```
+
+## Labels
+
+- `bug` | `documentation` | `enhancement`
+```
+
+## Create via gh
+
+```bash
+gh issue create --repo beettlle/pi-smart-router \
+  --title "[bug] ..." \
+  --label bug \
+  --body-file /tmp/issue-body.md
+```
+
+## Close linked issue after SP task lands
+
+```bash
+gh issue comment 13 --repo beettlle/pi-smart-router \
+  --body "Fixed in SP-047, integrated on main. Verification: npm run typecheck && npm test."
+
+gh issue close 13 --repo beettlle/pi-smart-router --reason completed
+```
+
+Only close when acceptance criteria from the issue are met and verification output is attached or referenced.

package/skills/router-backlog-orchestrator/references/packet-from-issue.md

@@ -0,0 +1,99 @@
+# Spine packet from GitHub issue
+
+Map GitHub issue fields → `spine-tasks/SP-0xx-slug/PROMPT.md`.
+
+## PROMPT skeleton
+
+```markdown
+# Task: SP-0xx — Short Slug
+
+**Created:** YYYY-MM-DD
+**Size:** S|M
+
+## Review Level: 1
+
+**Assessment:** One-line scope from issue title.
+**Score:** N/8
+
+## Source
+
+- GitHub: beettlle/pi-smart-router#NNN
+- Bucket: documentation|bug|feature
+
+## Mission
+
+(Paste or distill issue body — acceptance criteria as prose.)
+
+## Dependencies
+
+- SP-0yy   # prior task if hot-file or logical order
+
+## Context to Read First
+
+- (paths from issue + codebase search)
+
+## File Scope
+
+| Scope | Paths |
+|-------|-------|
+| Must change | `path/to/file.ts` |
+| Must NOT change | `src/domain/**` |
+
+## Contract
+
+| Field | Value |
+|-------|-------|
+| testCommand | `npm run verify:ci` |
+| fileScopeMustChange | `path/to/primary/file.ts` |
+| fileScopeMustNotChange | `src/domain/**` |
+| completionCriteria | (from issue acceptance criteria) |
+
+## Steps
+
+### Step 1: ...
+
+- [ ] ...
+
+### Step 2: Testing and verification
+
+- [ ] Run `npm run verify:ci`
+- [ ] (issue-specific checks)
+
+## Completion Criteria
+
+- [ ] (bullet list mirroring issue)
+```
+
+## Field mapping
+
+| GitHub | PROMPT section |
+|--------|----------------|
+| `title` | `# Task: SP-0xx —` suffix; Review Level assessment |
+| `body` | Mission, Steps, Completion Criteria |
+| `labels` | Source bucket; hints for File Scope |
+| `number` | `## Source` link |
+
+## STATUS.md
+
+Use template from `.cursor/rules/taskplane/status-template.md`. Initialize all checkboxes unchecked.
+
+## dependencies.json
+
+Add edge `"SP-0xx": ["SP-0yy"]` matching PROMPT `## Dependencies`.
+
+## CONTEXT.md
+
+After creating packets:
+- Bump `Next Task ID`
+- Add phase table row(s) for new tasks
+- Update `Last Updated` date
+
+## Validation
+
+```bash
+spine tasks validate pending
+spine tasks analyze pending
+spine plan pending
+```
+
+Fix contract paths: no trailing `/`, no parenthetical path comments.

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

@@ -0,0 +1,65 @@
+# Backlog prioritization rubric
+
+Use when classifying and ordering work in `router-backlog-orchestrator`.
+
+## Buckets
+
+### documentation
+
+- GitHub label: `documentation`
+- Title/body mentions: README, quickstart, operator guide, env vars, install, dogfooding
+- **Always first** in every orchestrator run — process all open doc issues before bugs
+
+### bug
+
+- GitHub label: `bug`
+- Keywords: fix, wiring, regression, P0, audit gap, fails, error, crash, missing
+- Secondary sort (after docs):
+  1. User-facing / session-breaking (routing failures, failover, auth)
+  2. CI / verification blockers (lint, typecheck, missing build script)
+  3. Correctness / spec drift (pipeline order, ghost layers, swallowed errors)
+  4. Internal refactors that unblock other bugs
+
+### feature
+
+- GitHub label: `enhancement` (without `documentation` primary intent)
+- New commands, dataset recording, platform support, build tooling enhancements
+
+### epic
+
+- Title contains `[Epic]` or body lists multiple independent deliverables
+- **Never** one SP packet — split into S/M tasks with explicit dependencies
+- Example: privacy dataset epic → schema → store → opt-in → export (serial chain)
+
+## Feature-to-bug ratio
+
+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)
+
+## Dedup rules
+
+1. If `PROMPT.md` contains `GitHub: beettlle/pi-smart-router#N` and task has `.DONE`, skip unless issue reopened
+2. If open issue matches pending SP without `.DONE`, do not duplicate — finish existing packet
+3. If orphan PROMPT conflicts with GitHub issue, prefer GitHub as source; amend or retire orphan
+
+## Hot-file serialization
+
+These paths must not appear in parallel same-wave `fileScopeMustChange`:
+
+- `.pi/extensions/smart-router/index.ts`
+- `src/domain/pipeline/router-pipeline.ts`
+- `src/api/middleware/pi-router-middleware.ts`
+
+Chain dependencies in `dependencies.json` when multiple tasks touch the same file.
+
+## Size limits
+
+| Size | Target | Action |
+|------|--------|--------|
+| S | <2h, ≤4 impl steps | Preferred |
+| M | 2–4h | OK if scope disjoint |
+| L | 4–8h | Split |
+| XL | >8h | Must split |

package/skills/router-backlog-orchestrator/scripts/collect-backlog.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Collect open GitHub issues and local spine backlog snapshot.
+# Usage: from repo root: skills/router-backlog-orchestrator/scripts/collect-backlog.sh
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "$REPO_ROOT"
+
+echo "=== pi-smart-router backlog snapshot ==="
+echo "Date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "Repo: $REPO_ROOT"
+echo "Branch: $(git branch --show-current 2>/dev/null || echo unknown)"
+echo ""
+
+echo "=== GitHub open issues (beettlle/pi-smart-router) ==="
+if command -v gh >/dev/null 2>&1; then
+  gh issue list --repo beettlle/pi-smart-router --state open --limit 100 \
+    --json number,title,labels,url,createdAt \
+    2>/dev/null || echo "(gh failed — check auth)"
+else
+  echo "(gh not installed)"
+fi
+echo ""
+
+echo "=== Spine plan pending ==="
+if command -v spine >/dev/null 2>&1; then
+  spine plan pending 2>/dev/null || true
+else
+  echo "(spine not installed)"
+fi
+echo ""
+
+echo "=== Orphan PROMPT packets (no .DONE) ==="
+find spine-tasks -name PROMPT.md 2>/dev/null | while read -r prompt; do
+  dir="$(dirname "$prompt")"
+  if [[ ! -f "$dir/.DONE" ]]; then
+    echo "$dir"
+  fi
+done
+
+echo ""
+echo "=== Next Task ID (from CONTEXT.md) ==="
+grep -E '^\*\*Next Task ID:\*\*' spine-tasks/CONTEXT.md 2>/dev/null || echo "(CONTEXT.md not found)"