Merge pull request #84 from speakeasy-api/feat/pi-openrouter-runtime

Run the drafting pipeline on pi and OpenRouter

Author: walker-tx

.claude/skills/tune-pipeline/SKILL.md

@@ -17,7 +17,7 @@ adding; no-change is a valid outcome.
    `doctrine/CHANGELOG.md` (what already changed, what was rejected —
    do not re-propose either without new evidence), then the current
    doctrine: every file in `doctrine/`, `doctrine/personas/`, and the
-   Cursor SDK workflow under `pipeline/`.
+   draft-guide workflow under `pipeline/`.
 2. **Read the signal**: everything in `retro/runs/` and `retro/notes/`
    not already cited by a changelog entry. If the corpus is large (more
    than ~10 run records), fan out reader subagents — one per review

.github/workflows/guide-draft.yml

@@ -85,7 +85,7 @@ jobs:
         if: steps.preflight.outputs.refused != 'true'
         working-directory: pipeline
         env:
-          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
         run: npm run factory -- distill
 
       - name: Comment resolved intent
@@ -116,7 +116,7 @@ jobs:
         if: steps.preflight.outputs.refused != 'true' && success()
         working-directory: pipeline
         env:
-          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           PULSE_REGISTRY_KEY: ${{ secrets.PULSE_REGISTRY_KEY }}
           PULSE_REGISTRY_TENANT: ${{ secrets.PULSE_REGISTRY_TENANT }}
           SLUG: ${{ steps.distill.outputs.slug }}

.gitignore

@@ -7,6 +7,3 @@ tools/pulse-catalog/pulse-catalog.json
 
 # Local scratch / probe dirs
 .tmp-*/
-.tmp-gram/
-.tmp-probe/
-.tmp-probe2/

FACTORY.md

@@ -1,6 +1,6 @@
 # Guide draft factory
 
-Turn a GitHub issue into a draft MCP Setup Guide PR. Same Cursor SDK pipeline
+Turn a GitHub issue into a draft MCP Setup Guide PR. Same drafting pipeline
 as `mise run draft-guide` / `npm run draft-guide`, driven by a label instead of
 a local CLI.
 
@@ -15,7 +15,7 @@ Repo → **Settings → Secrets and variables → Actions**:
 
 | Secret | Required? | What it is |
 | --- | --- | --- |
-| `CURSOR_API_KEY` | **Yes** | Cursor API key (Dashboard → Integrations / API Keys) |
+| `OPENROUTER_API_KEY` | **Yes** | OpenRouter API key (openrouter.ai → Keys) |
 | `AGENT_PAT` | Recommended | PAT with contents + issues + pull requests write on this repo. Falls back to `GITHUB_TOKEN` (PRs still work; label chaining is less reliable). |
 | `PULSE_REGISTRY_KEY` | Recommended | PulseMCP Sub-Registry API key — resolves Speakeasy MCP Catalog presence before research. Without it, `speakeasy_add_server: auto` guides keep both catalog/custom paths unless remotes are tenanted or the guide forces `custom-remote` / `catalog`. |
 | `PULSE_REGISTRY_TENANT` | Recommended with key | PulseMCP tenant slug (e.g. `gram-recommended`). Required together with the key for catalog lookup. |
@@ -40,7 +40,7 @@ The workflow creates these if missing. You can also create them by hand:
 2. Add the label **`guide:draft`**.
 3. Watch the issue comments and the **Actions** tab (`Guide draft` workflow).
 
-Runs can take a long time (often 20–40+ minutes). Usage burns Cursor plan tokens.
+Runs can take a long time (often 20–40+ minutes). Usage burns OpenRouter credits.
 
 ### What you get
 
@@ -103,7 +103,7 @@ A non-factory open PR that already `Closes #<issue>` (collaborator-authored) blo
 ## Local equivalent
 
 ```bash
-export CURSOR_API_KEY=cursor_...
+export OPENROUTER_API_KEY=sk-or-...
 mise run draft-guide -- asana --overwrite --notes "drop secret-reset recovery branch"
 # Match factory: pause before draft when material OQs lack Decision N replies
 mise run draft-guide -- x --overwrite --pause-on-scope
@@ -169,7 +169,7 @@ be unavailable).
    branch. Refuse only for non-factory collaborator PRs that target the
    same issue.
 2. **Labels** — remove `guide:draft` + `guide:blocked`, add `guide:in-progress`.
-3. **Distill** — light Cursor agent reads title + body + issue comments (+
+3. **Distill** — light distill agent reads title + body + issue comments (+
    existing `guides/*` slugs) → structured JSON or `needs_clarification`.
 4. **Comment** — “Resolved as `slug` …” (or resume notice) summary.
 5. **Draft** — `npm run draft-guide -- <slug> --overwrite --pause-on-scope
@@ -210,6 +210,31 @@ Hard failures (exit `1`, missing artifacts) take the blocked path with no PR.
 - Distill `needs_clarification` and the post-research scope gate are the
   intentional stops before / mid heavy pipeline.
 
+## Runtime facts that are easy to get wrong
+
+The pipeline spawns the `pi` CLI against OpenRouter. Seven things are not
+obvious from reading the code, and each one has cost a run:
+
+- **`pi` exits 0 on API errors.** Success is decided by `classifyPiRun`
+  (`pi-stream.ts`), never by the exit code. Checking the code reports a guide
+  that never generated as one that generated empty.
+- **Never edit the repo while a run is in flight.** The I7 tripwire captures its
+  baseline *once*, before any agent runs, so a file you touch mid-run is
+  indistinguishable from an agent breach and fails the phase.
+- **There is no container.** The env allowlist in `pi-guard.ts` and the
+  `git status` tripwire in `runtime-pi.ts` are the entire boundary keeping
+  secrets out of the agent and the agent inside `guides/<slug>/`.
+- **The research phase keeps `bash` deliberately.** `pi` ships no web-fetch
+  tool, so `bash` + `curl` is research's only route to provider docs. Removing
+  it does not tighten research, it disables it.
+- **Session continuity is one flag.** The same `--session <path>` creates the
+  session on turn 1 and resumes it on turn 2, which is what lets remediation say
+  "use the research you already gathered". `--no-session` breaks that.
+- **`model` feeds `input_digest`.** Changing the model slug goes cold on every
+  committed lock, so the next run of each guide re-runs every phase.
+- **Secrets come from `mise`** via a gitignored `mise.local.toml`. If
+  `OPENROUTER_API_KEY` reads empty the shell snapshot is stale — use `mise exec --`.
+
 ## Related
 
 - [`README.md`](README.md) — short how-to (issue flow + local CLI)

README.md

@@ -24,10 +24,10 @@ How it works (labels, scope checks, Decisions, resume): **[`FACTORY.md`](FACTORY
 
 ## Run locally
 
-Requires Node ≥ 22.13 and a Cursor API key.
+Requires Node ≥ 22.13 and an OpenRouter API key.
 
 ```bash
-export CURSOR_API_KEY=cursor_...   # Dashboard → Integrations / API Keys
+export OPENROUTER_API_KEY=sk-or-...   # openrouter.ai → Keys
 # Optional — resolve Speakeasy catalog presence (same as mise run pull-catalog):
 # export PULSE_REGISTRY_KEY=...
 # export PULSE_REGISTRY_TENANT=gram-recommended

doctrine/CHANGELOG.md

@@ -6,6 +6,43 @@ evidence (Run Records / Retro Notes) behind it. Required by constitution
 invariant I8; written by `/tune-pipeline` when a human approves a
 proposal, or by hand for direct human edits.
 
+## 2026-07-31 — pipeline-lock examples follow the pi runtime
+
+Files: `doctrine/pipeline-lock.md`.
+
+- **Runtime naming (`:8`, `:114`, `:203`):** the contract described itself
+  as honored by "the Cursor SDK workflow" and used `cursor-sdk` as the
+  `runtime` example and in the illustrative lock. `7e635e1` replaced the
+  `@cursor/sdk` runtime with a direct spawn of the `pi` CLI over
+  OpenRouter, deleted `pipeline/src/runtime.ts`, and set the lock literal
+  to `runtime: 'pi'` (`pipeline/src/workflow.ts`). Prose is now
+  runtime-neutral ("the drafting pipeline"); the two examples say `pi`.
+- **Model slot alias (`:109`, `:111-112`):** the `review.<dim>` row read
+  "default vs light/`sonnet` slot" and the example forbade "a slot alias
+  like `sonnet`". No slot mechanism survives: `7e635e1` removed
+  `Dimension.model`, `AgentOptions.model` and the `dim.model` spread along
+  with `resolveModel`, which held the `'sonnet'` → light-model branch. The
+  **rule is kept** — a resolved id, never an alias — because it still binds
+  any future runtime that reintroduces slots; only its illustration moved.
+- **Model examples (`:209`, `:250`, `:297`):** `claude-fable-5` → the
+  OpenRouter slug `openrouter/openai/gpt-5.6-sol`, which is what
+  `modelId()` now returns and therefore what `input_digest` covers.
+
+No normative rule changed. Digest exclusions, the `runtime`-is-observational
+constraint, and the resolved-id requirement all stand as written; this entry
+only corrects examples and one runtime name that `7e635e1` falsified.
+
+Evidence: commits `7e635e1` (runtime cutover) and `e4fa3d7` (removal of the
+code left unused by it), PR #84; run records
+`retro/runs/2026-07-31T15:07:07Z-google-calendar.json` (converged fresh
+draft on pi, `runtime: "pi"`) and `…T14:58:27Z-…` (the failed first run).
+
+Known divergence, deliberate: the illustrative lock at `:203` is labelled
+`guides/box/pipeline.lock.json`, and the real file still records
+`"runtime": "cursor-sdk"` — correct, as a historical record of a run that
+did use it. The sample follows current doctrine, not that file, until box
+next runs.
+
 ## 2026-07-30 — first-class "no setup required" fact for consumers
 
 Files: `schema/guide.v1.schema.json`, `guides/*/meta.yaml` (all 18),

doctrine/pipeline-lock.md

@@ -5,7 +5,7 @@ Normative semantics for `guides/<slug>/pipeline.lock.json`. The JSON Schema is
 
 This contract records, per guide, the **input fingerprints** that produced the
 current artifacts so a later drafting run can **skip** steps whose inputs did
-not change. The Cursor SDK workflow (`pipeline/`) honors these rules;
+not change. The drafting pipeline (`pipeline/`) honors these rules;
 `--force` bypasses skips. `--overwrite` / `-y` only skips the guide-exists
 prompt and still honors the lock.
 
@@ -106,12 +106,12 @@ in the workflow is an implementation detail.
 | --- | --- | --- | --- | --- |
 | `research` | resolved default model | `doctrine/glossary.md`, `doctrine/shared.md`, `doctrine/roles/technical-research.md`, `doctrine/speakeasy-setup.md` | `[]` (sources are external) | `provider`, `notes` |
 | `draft` | resolved default model | `doctrine/glossary.md`, `doctrine/shared.md`, `doctrine/roles/writer.md`, `doctrine/personas/<id>.md` | stable digests of `research.md`, `meta.yaml` | `provider`, `notes`, `persona` |
-| `review.<dim>` | resolved model for that dimension (default vs light/`sonnet` slot) | `doctrine/glossary.md`, `doctrine/shared.md`, role doc (`fidelity.md` or `review.md`), plus persona file when the dimension uses a persona | stable digests of `research.md`, `meta.yaml`, `external.md`, `speakeasy.md` | `provider`, `notes`, `persona`, `dimension` |
+| `review.<dim>` | resolved model for that dimension | `doctrine/glossary.md`, `doctrine/shared.md`, role doc (`fidelity.md` or `review.md`), plus persona file when the dimension uses a persona | stable digests of `research.md`, `meta.yaml`, `external.md`, `speakeasy.md` | `provider`, `notes`, `persona`, `dimension` |
 
-`model` is always the **resolved** model id (e.g. `claude-fable-5`), never a
-slot alias like `sonnet`.
+`model` is always the **resolved** model id (e.g.
+`openrouter/openai/gpt-5.6-sol`), never a slot alias.
 
-Top-level `runtime` (e.g. `cursor-sdk`) is observational and **must not**
+Top-level `runtime` (e.g. `pi`) is observational and **must not**
 appear inside `inputs` or affect `input_digest`.
 
 ## Research unchanged
@@ -200,13 +200,13 @@ Illustrative `guides/box/pipeline.lock.json` (digests are placeholders):
   "schema_version": 1,
   "slug": "box",
   "persona": "it-admin",
-  "runtime": "cursor-sdk",
+  "runtime": "pi",
   "updated_at": "2026-07-23T16:00:00Z",
   "steps": {
     "research": {
       "input_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
       "inputs": {
-        "model": "claude-fable-5",
+        "model": "openrouter/openai/gpt-5.6-sol",
         "prompt_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
         "reading_list": [
           {
@@ -247,7 +247,7 @@ Illustrative `guides/box/pipeline.lock.json` (digests are placeholders):
     "draft": {
       "input_digest": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
       "inputs": {
-        "model": "claude-fable-5",
+        "model": "openrouter/openai/gpt-5.6-sol",
         "prompt_digest": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
         "reading_list": [
           {
@@ -294,7 +294,7 @@ Illustrative `guides/box/pipeline.lock.json` (digests are placeholders):
     "review.fidelity": {
       "input_digest": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
       "inputs": {
-        "model": "claude-fable-5",
+        "model": "openrouter/openai/gpt-5.6-sol",
         "prompt_digest": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
         "reading_list": [
           {

mise.toml

@@ -15,12 +15,12 @@ hide = true
 run = "npm install"
 
 [tasks.draft-guide]
-description = "Draft a Guide via the Cursor SDK pipeline (pipeline/)"
+description = "Draft a Guide via the drafting pipeline (pipeline/)"
 dir = "pipeline"
 depends = ["_pipeline-install"]
 # Usage (from repo root): mise run draft-guide -- box [--overwrite] [--force] [--pause-on-scope] [...]
 # Exit: 0 converged, 2 unconverged/blocked/failed, 3 awaiting_scope (--pause-on-scope)
-# Requires CURSOR_API_KEY in the environment (user or team service-account key).
+# Requires OPENROUTER_API_KEY in the environment.
 run = "npm run draft-guide --"
 
 [tasks.lint-guide]