rote-cli 0.8.0__tar.gz → 0.10.0__tar.gz

{rote_cli-0.8.0 → rote_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rote-cli
-Version: 0.8.0
+Version: 0.10.0
 Summary: Graduate fuzzy AI skills into deterministic, reliable workflows
 Project-URL: Homepage, https://github.com/trevhud/rote
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -32,11 +32,17 @@ Requires-Dist: dbos>=2.26; extra == 'dev'
 Requires-Dist: fastmcp>=3.4.2; extra == 'dev'
 Requires-Dist: httpx>=0.28; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: openai>=2.45; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: temporalio>=1.7; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
+Requires-Dist: httpx>=0.28; extra == 'mcp'
+Provides-Extra: openai-api
+Requires-Dist: openai>=2.45; extra == 'openai-api'
 Provides-Extra: serve
 Requires-Dist: fastmcp>=3.4.2; extra == 'serve'
 Requires-Dist: httpx>=0.28; extra == 'serve'
@@ -221,8 +227,8 @@ emitted code + a README on how to run, signal gates, and deploy).
 
 ### Other commands
 
-- **`rote emit <pipeline.yaml>`** — run just the adapter step on an
-  existing IR (no LLM, no cost). The cheap inner loop while iterating on
+- **`rote emit <pipeline.yaml> --out <dir>`** — run just the adapter step
+  on an existing IR (no LLM, no cost). The cheap inner loop while iterating on
   adapters or IR shapes. Re-emitting is safe: a `.rote-manifest.json`
   tracks what `rote` wrote, and files you've edited are left untouched
   (the fresh version lands as `<name>.new`).
@@ -231,6 +237,61 @@ emitted code + a README on how to run, signal gates, and deploy).
   `provenance.json` and re-derives only the nodes whose source sections
   changed; unchanged nodes keep their ids (so in-flight durable workflows
   aren't orphaned) and implemented stubs are kept. No change → no agent run.
+- **`rote run <path>`** — one-off local execution of either side. A
+  skill directory runs as an agent via `claude -p` (your registered MCP
+  servers injected, read-only tool gate unless `--allow-writes`); an
+  emitted runtime directory — or a `graduate --out` directory — runs
+  the pipeline itself — all six runtimes (`python`/`dbos`/`temporal`
+  in-process or on a managed local dev server, `cloudflare` under
+  `wrangler dev`, `inngest` against a managed `inngest-cli dev`,
+  `dbos-ts` against your Postgres or a throwaway Docker one). HITL
+  gate payloads via `--signal name='{...}'` or an interactive prompt.
+  Runtimes that bundle a dev UI surface it: temporal runs print a live
+  Temporal Web UI URL and inngest runs print the dev-server dashboard,
+  both live for the duration of the run. Output JSON on stdout, status
+  on stderr, so it pipes.
+- **`rote deploy <path>`** — push an emitted pipeline where it runs:
+  `cloudflare` wraps `npx wrangler deploy` (with `--dry-run`), `dbos` /
+  `dbos-ts` wrap `npx dbos-cloud app deploy` — the vendor CLI owns auth
+  and output; rote adds detection and preflights (including surfacing
+  *which* account your wrangler session belongs to before uploading).
+  Runtimes with no push model (temporal, inngest, python) print honest
+  hosting guidance with doc links instead of a fake action.
+  `--target rote-cloud` bundles a cloudflare-emitted app (esbuild via
+  npx) and uploads it to a hosted rote-cloud instance — with a stored
+  `rote login`, no flags or env vars needed (`--url`/`--token` and
+  `$ROTE_CLOUD_URL`/`$ROTE_CLOUD_TOKEN` still override).
+- **`rote login`** — connect the CLI to a rote-cloud account via the
+  OAuth device flow: your browser opens with a one-time code pre-filled
+  (over SSH, `--device` prints the code + URL instead), you click
+  Approve, and the CLI stores a tenant API key at
+  `~/.local/share/rote/cloud.json` (mode 0600). Once logged in,
+  `rote graduate` runs **on rote cloud by default**: the skill bundle
+  syncs up (sha-diffed, so unchanged files don't re-upload), the
+  platform runs the graduation server-side, live progress streams back
+  through the same renderer as a local run, the result auto-deploys,
+  and the artifacts download into your `--out` directory in the exact
+  local layout. `--local` keeps the graduation on your machine (then
+  the cloudflare-emit + auto-deploy flow applies), `--no-deploy` or a
+  config opt-out (`runtime:` pinned to a local target, or
+  `deploy: none`) keeps everything local; `--cloud` forces the server
+  even where config says otherwise. Logged out, everything works
+  locally exactly as before. `rote whoami` shows the account (verified
+  live); `rote logout` revokes the key server-side and clears the store.
+- **`rote init`** — one-time interactive onboarding: pick where
+  graduated pipelines run (rote cloud — with login offered inline — or
+  a local runtime, with a one-line pitch for each), which graduator
+  driver does the work (availability probed live), and optionally a
+  model. Answers are saved to `~/.config/rote/config.yaml`
+  (`--project` writes a `./rote.yaml` that overrides it per-repo) and
+  every later command reads them. It's the only interactive command
+  besides login — CI never hits a prompt.
+- **`rote config`** — print every configurable default with its
+  effective value *and the layer that set it*. Resolution everywhere is
+  `flag > ROTE_* env (ROTE_RUNTIME, ROTE_DEPLOY, ROTE_AGENT,
+  ROTE_MODEL) > project rote.yaml > user config > built-in`. Config
+  files are strict: a typo'd key or value is a loud error, never a
+  silent fallback. `--json` for automation.
 - **`rote eval <graduated>`** — render the before/after scorecard (wall
   clock, cost across the current model lineup at live prices, and how
   much of the run is still LLM-decided). `rote graduate` writes this to
@@ -266,9 +327,12 @@ way, prefer the more deterministic kind.
 
 ## Runtimes
 
-Pick with `--runtime`; the same IR drives all of them. None of the
-emitted code references MCP — the crystallization step replaces tool
-calls with direct vendor API calls.
+Pick with `--runtime`; the same IR drives all of them. Under
+`--backend api`, none of the emitted code references MCP — the
+crystallization step replaces tool calls with direct vendor API calls.
+Under the default `--backend mcp`, tool-using nodes emit a working MCP
+client call (with durable park-on-auth on every MCP-capable runtime);
+see [`docs/mcp-client.md`](docs/mcp-client.md).
 
 | Runtime | `--runtime` | Language | Shape | Notes |
 | --- | --- | --- | --- | --- |
@@ -348,7 +412,7 @@ Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
 
 ```
 rote/
-├── docs/                  agent-runtime · mcp-trigger · releasing
+├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
 ├── skills/rote-graduate/  the graduator agent (SKILL.md + 4 reference files)
 ├── src/rote/
 │   ├── cli.py             rote graduate / emit / eval / serve
@@ -367,9 +431,15 @@ rote/
 
 ## Documentation
 
+- [`AGENTS.md`](AGENTS.md) — operating manual for a coding agent *driving*
+  `rote` as an installed tool (invocation contract, the slow/costs-money
+  `graduate` flow, auth, failure recovery, the stub-filling job, `--json`)
 - [`docs/agent-runtime.md`](docs/agent-runtime.md) — design record for the
   driver abstraction (the `claude -p` env gotcha; the non-use of
   `claude-agent-sdk`)
+- [`docs/mcp-client.md`](docs/mcp-client.md) — the OAuth MCP client
+  emitted code uses under `--backend mcp`: endpoint/credential
+  resolution and durable park-on-auth across every MCP-capable runtime
 - [`docs/mcp-trigger.md`](docs/mcp-trigger.md) — `rote register` +
   `rote serve`: graduated pipelines as MCP tools (FastMCP 3.x)
 - [`docs/releasing.md`](docs/releasing.md) — tag-driven PyPI Trusted

{rote_cli-0.8.0 → rote_cli-0.10.0}/README.md

@@ -175,8 +175,8 @@ emitted code + a README on how to run, signal gates, and deploy).
 
 ### Other commands
 
-- **`rote emit <pipeline.yaml>`** — run just the adapter step on an
-  existing IR (no LLM, no cost). The cheap inner loop while iterating on
+- **`rote emit <pipeline.yaml> --out <dir>`** — run just the adapter step
+  on an existing IR (no LLM, no cost). The cheap inner loop while iterating on
   adapters or IR shapes. Re-emitting is safe: a `.rote-manifest.json`
   tracks what `rote` wrote, and files you've edited are left untouched
   (the fresh version lands as `<name>.new`).
@@ -185,6 +185,61 @@ emitted code + a README on how to run, signal gates, and deploy).
   `provenance.json` and re-derives only the nodes whose source sections
   changed; unchanged nodes keep their ids (so in-flight durable workflows
   aren't orphaned) and implemented stubs are kept. No change → no agent run.
+- **`rote run <path>`** — one-off local execution of either side. A
+  skill directory runs as an agent via `claude -p` (your registered MCP
+  servers injected, read-only tool gate unless `--allow-writes`); an
+  emitted runtime directory — or a `graduate --out` directory — runs
+  the pipeline itself — all six runtimes (`python`/`dbos`/`temporal`
+  in-process or on a managed local dev server, `cloudflare` under
+  `wrangler dev`, `inngest` against a managed `inngest-cli dev`,
+  `dbos-ts` against your Postgres or a throwaway Docker one). HITL
+  gate payloads via `--signal name='{...}'` or an interactive prompt.
+  Runtimes that bundle a dev UI surface it: temporal runs print a live
+  Temporal Web UI URL and inngest runs print the dev-server dashboard,
+  both live for the duration of the run. Output JSON on stdout, status
+  on stderr, so it pipes.
+- **`rote deploy <path>`** — push an emitted pipeline where it runs:
+  `cloudflare` wraps `npx wrangler deploy` (with `--dry-run`), `dbos` /
+  `dbos-ts` wrap `npx dbos-cloud app deploy` — the vendor CLI owns auth
+  and output; rote adds detection and preflights (including surfacing
+  *which* account your wrangler session belongs to before uploading).
+  Runtimes with no push model (temporal, inngest, python) print honest
+  hosting guidance with doc links instead of a fake action.
+  `--target rote-cloud` bundles a cloudflare-emitted app (esbuild via
+  npx) and uploads it to a hosted rote-cloud instance — with a stored
+  `rote login`, no flags or env vars needed (`--url`/`--token` and
+  `$ROTE_CLOUD_URL`/`$ROTE_CLOUD_TOKEN` still override).
+- **`rote login`** — connect the CLI to a rote-cloud account via the
+  OAuth device flow: your browser opens with a one-time code pre-filled
+  (over SSH, `--device` prints the code + URL instead), you click
+  Approve, and the CLI stores a tenant API key at
+  `~/.local/share/rote/cloud.json` (mode 0600). Once logged in,
+  `rote graduate` runs **on rote cloud by default**: the skill bundle
+  syncs up (sha-diffed, so unchanged files don't re-upload), the
+  platform runs the graduation server-side, live progress streams back
+  through the same renderer as a local run, the result auto-deploys,
+  and the artifacts download into your `--out` directory in the exact
+  local layout. `--local` keeps the graduation on your machine (then
+  the cloudflare-emit + auto-deploy flow applies), `--no-deploy` or a
+  config opt-out (`runtime:` pinned to a local target, or
+  `deploy: none`) keeps everything local; `--cloud` forces the server
+  even where config says otherwise. Logged out, everything works
+  locally exactly as before. `rote whoami` shows the account (verified
+  live); `rote logout` revokes the key server-side and clears the store.
+- **`rote init`** — one-time interactive onboarding: pick where
+  graduated pipelines run (rote cloud — with login offered inline — or
+  a local runtime, with a one-line pitch for each), which graduator
+  driver does the work (availability probed live), and optionally a
+  model. Answers are saved to `~/.config/rote/config.yaml`
+  (`--project` writes a `./rote.yaml` that overrides it per-repo) and
+  every later command reads them. It's the only interactive command
+  besides login — CI never hits a prompt.
+- **`rote config`** — print every configurable default with its
+  effective value *and the layer that set it*. Resolution everywhere is
+  `flag > ROTE_* env (ROTE_RUNTIME, ROTE_DEPLOY, ROTE_AGENT,
+  ROTE_MODEL) > project rote.yaml > user config > built-in`. Config
+  files are strict: a typo'd key or value is a loud error, never a
+  silent fallback. `--json` for automation.
 - **`rote eval <graduated>`** — render the before/after scorecard (wall
   clock, cost across the current model lineup at live prices, and how
   much of the run is still LLM-decided). `rote graduate` writes this to
@@ -220,9 +275,12 @@ way, prefer the more deterministic kind.
 
 ## Runtimes
 
-Pick with `--runtime`; the same IR drives all of them. None of the
-emitted code references MCP — the crystallization step replaces tool
-calls with direct vendor API calls.
+Pick with `--runtime`; the same IR drives all of them. Under
+`--backend api`, none of the emitted code references MCP — the
+crystallization step replaces tool calls with direct vendor API calls.
+Under the default `--backend mcp`, tool-using nodes emit a working MCP
+client call (with durable park-on-auth on every MCP-capable runtime);
+see [`docs/mcp-client.md`](docs/mcp-client.md).
 
 | Runtime | `--runtime` | Language | Shape | Notes |
 | --- | --- | --- | --- | --- |
@@ -302,7 +360,7 @@ Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
 
 ```
 rote/
-├── docs/                  agent-runtime · mcp-trigger · releasing
+├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
 ├── skills/rote-graduate/  the graduator agent (SKILL.md + 4 reference files)
 ├── src/rote/
 │   ├── cli.py             rote graduate / emit / eval / serve
@@ -321,9 +379,15 @@ rote/
 
 ## Documentation
 
+- [`AGENTS.md`](AGENTS.md) — operating manual for a coding agent *driving*
+  `rote` as an installed tool (invocation contract, the slow/costs-money
+  `graduate` flow, auth, failure recovery, the stub-filling job, `--json`)
 - [`docs/agent-runtime.md`](docs/agent-runtime.md) — design record for the
   driver abstraction (the `claude -p` env gotcha; the non-use of
   `claude-agent-sdk`)
+- [`docs/mcp-client.md`](docs/mcp-client.md) — the OAuth MCP client
+  emitted code uses under `--backend mcp`: endpoint/credential
+  resolution and durable park-on-auth across every MCP-capable runtime
 - [`docs/mcp-trigger.md`](docs/mcp-trigger.md) — `rote register` +
   `rote serve`: graduated pipelines as MCP tools (FastMCP 3.x)
 - [`docs/releasing.md`](docs/releasing.md) — tag-driven PyPI Trusted

{rote_cli-0.8.0 → rote_cli-0.10.0}/pyproject.toml

@@ -50,6 +50,9 @@ temporal = [
 api = [
     "anthropic>=0.89",
 ]
+openai-api = [
+    "openai>=2.45",
+]
 dbos = [
     "dbos>=2.26",
 ]
@@ -57,6 +60,10 @@ serve = [
     "fastmcp>=3.4.2",
     "httpx>=0.28",
 ]
+mcp = [
+    "fastmcp>=3.4.2",
+    "httpx>=0.28",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
@@ -65,6 +72,7 @@ dev = [
     "types-pyyaml",
     "temporalio>=1.7",
     "anthropic>=0.89",
+    "openai>=2.45",
     "dbos>=2.26",
     "fastmcp>=3.4.2",
     "httpx>=0.28",

{rote_cli-0.8.0 → rote_cli-0.10.0}/skills/rote-graduate/SKILL.md

@@ -46,6 +46,19 @@ re-deriving a known-fixed procedure at runtime is waste.
 
 ## Pipeline
 
+**Progress markers.** At the START of each Phase N, rewrite
+`progress.ndjson` in the work directory so it holds one JSON line per
+phase entered so far, in order:
+
+```
+{"phase": 1, "name": "Intake"}
+{"phase": 2, "name": "Node Classification"}
+```
+
+Rewrite the whole file each time (append the new phase's line to the
+ones already there). This file is machine-read for live progress
+display; it is not a deliverable and never affects the IR.
+
 ### Phase 1: Intake
 
 Read the target directory exhaustively:
@@ -86,7 +99,13 @@ justification per row.
 
 ### Phase 3: Codification Scan
 
-Read `references/crystallization-heuristics.md` before starting this phase.
+Read `references/crystallization-heuristics.md` and
+`references/implementation.md` before starting this phase. The second
+file governs how far to take each extracted module: contract-documented
+stubs by default, **working implementations plus golden-fixture tests**
+when ground truth is available (a `probe-context/` directory of observed
+MCP traffic in your work dir, and/or web research tools to verify
+current vendor API shapes).
 
 For each node classified as `pure_function` or `external_call`, surface every
 codification opportunity:
@@ -174,6 +193,12 @@ Checklist before declaring Phase 5 done:
 
 - Every `pure_function` / `external_call` node has an `impl:` pointing
   at a real file you created in Phase 3.
+- Every step that calls an MCP tool in the source skill carries the
+  matching `mcp:` binding (see ir-schema.md — and cross-check against
+  `probe-context/observed-tools.json` when it exists: observed traffic
+  with no binding is a graduation bug).
+- If you wrote working implementations, `tests/test_extracted.py`
+  exists, is deterministic and offline, and you believe it passes.
 - Every `llm_judge` node has a `signature:` pointing at a real file
   you created in Phase 4.
 - Every `agent_loop` node has `tools:` listed.

{rote_cli-0.8.0 → rote_cli-0.10.0}/skills/rote-graduate/references/crystallization-heuristics.md

@@ -110,6 +110,17 @@ code makes skipping impossible.
 "always", "must", "never skip", "do not skip", "be sure to". Audit
 every hit.
 
+**Calibration — err toward marking.** On real production skills MOST
+deterministic nodes end up `mandatory: true`, not a handful: every
+fixed threshold, every filter/exclusion rule, every data pull the
+output cannot be correct without, every fixed template render. (The
+first agent run on the ops-report example marked 1 of 13 nodes when
+9 of 10 was right — a daily report is *made of* rules that must all
+fire.) Ask per node: "if the agent version silently skipped this
+step, would the output be wrong or dangerous?" If yes, mark it.
+Reserve unmarked for genuinely optional enrichment — a nice-to-have
+field, a best-effort lookup with a fallback.
+
 ---
 
 ### Pattern 4 — Fixed string templates for reports and outputs
@@ -200,6 +211,29 @@ but they're actually hard thresholds.
 **How to detect:** look for numeric comparisons in rubrics ("below X",
 "above Y", "at least Z"). Every one is a potential pre-filter.
 
+### Pattern 8 — Independent data pulls hiding in sequential prose
+
+**What it looks like:** the skill lists data-gathering steps in
+sequence ("First pull the Slack channel. Then run the Gmail
+searches.") but no step consumes another's output — the ordering
+exists only because an agent executes one tool call at a time.
+
+**What to do:** give the independent pulls no connecting edges so
+they land in the same execution wave, and list every independent
+entry point in `entry_nodes` (plural!). Adapters run same-wave nodes
+concurrently — the graduated pipeline should be *faster* than the
+agent, and parallel data pulls are usually the single biggest
+wall-clock win available.
+
+**How to detect:** for each pair of adjacent data-pull steps, ask
+"does step B's input mention anything step A produced?" If not, they
+are parallel regardless of the prose order. The deal-monitor example
+is the canonical case: the Slack intake pull and the fixed Gmail
+searches share nothing and must be two entry nodes — the first agent
+run serialized them into one entry and left the speedup on the table.
+
+---
+
 ## When NOT to crystallize
 
 The hunt for crystallization should be aggressive, but not blind. Leave

rote_cli-0.10.0/skills/rote-graduate/references/implementation.md

@@ -0,0 +1,109 @@
+# Writing Extracted Implementations
+
+Phase 3 produces `extracted/*.py` modules. This file governs **how much
+of each module you implement** and how to prove what you wrote is
+right. The bar depends on what evidence you have.
+
+## The two regimes
+
+### Regime 1 — No ground truth (default)
+
+No `probe-context/` directory exists in your work dir, and you have no
+web research tools. Emit **contract-documented stubs**: the function
+signature, a docstring stating the input/output contract as precisely
+as the skill text allows, and a `raise NotImplementedError(...)` body.
+Do NOT write vendor API calls from memory — SDK and endpoint shapes
+drift faster than any model's training data, and a plausible-but-wrong
+implementation is worse than an honest stub because it fails at
+runtime instead of at review.
+
+### Regime 2 — Ground truth available (implement for real)
+
+`probe-context/` exists (observed MCP traffic + inferred schemas from
+an instrumented run of this exact skill), and/or you have WebSearch /
+WebFetch. Now you are expected to write **working implementations**:
+
+1. **Contract from observation.** The observed input payload keys are
+   your function parameters; the observed result shape is your return
+   contract. If the skill prose disagrees with the observed traffic,
+   trust the traffic and note the discrepancy in the graduation report.
+2. **Endpoint from current docs, never memory.** Before writing a
+   vendor call, use WebSearch/WebFetch to confirm the current endpoint,
+   auth scheme, request/response shape, and official SDK name. Cite the
+   doc URL in the module docstring. If you cannot verify a shape, fall
+   back to Regime 1 for that function and say why in the report.
+3. **Credentials via environment variables only.** One variable per
+   vendor, named `<VENDOR>_API_KEY` (or the vendor's own documented
+   convention, e.g. `GOOGLE_APPLICATION_CREDENTIALS`). Read it at call
+   time, and raise a clear `RuntimeError` naming the variable when it
+   is missing. NEVER hardcode a credential, NEVER invent a
+   plausible-looking value, NEVER default to a dummy that would send a
+   request with fake auth.
+4. **Minimal dependencies.** Prefer the vendor's official Python SDK
+   when one exists and is current; otherwise plain `httpx`. Every
+   third-party dependency you introduce must be listed in the module
+   docstring so the adapter's requirements emission can pick it up.
+5. **Honest error surfaces.** No silent fallbacks, no bare excepts, no
+   returning empty results on failure. A 4xx/5xx should raise with the
+   response body attached — errors are how the durable runtime knows
+   to retry or park.
+
+## Tests are part of the deliverable
+
+When you implement for real (Regime 2), also write
+`tests/test_extracted.py` in your work dir:
+
+- **Golden-fixture tests from observed payloads.** Every parse /
+  transform / filter function gets called with a real observed payload
+  (copy it from `probe-context/observed-tools.json` into the test as a
+  fixture literal) and asserted against the real result. These are the
+  highest-value tests you can write: they prove the implementation
+  handles what production actually sends.
+- **Network functions get a transport-stubbed test.** Monkeypatch the
+  HTTP layer (or inject a fake client) and assert the function builds
+  the documented request and parses the documented response — using
+  the observed payloads as the canned response body. **No test may
+  touch the network**, require credentials, or be nondeterministic:
+  they must pass with plain `pytest` in an offline environment.
+- **Constants get pinned.** Every constant lifted in Phase 3 (batch
+  sizes, thresholds, day windows) gets one assertion, so a silent edit
+  fails a test instead of shipping.
+
+Structure the file so `pytest tests/` passes from the work dir root —
+imports as `from extracted.<module> import <fn>` with a conftest or
+sys.path line if needed. If a test would need something you can't
+provide deterministically, don't write a flaky approximation; note the
+gap in the graduation report instead.
+
+## What NOT to do, in any regime
+
+- Do not write to `signatures/` from this file's rules — judge modules
+  are governed by `llm-judge-extraction.md`.
+- Do not call MCP at runtime from extracted code. The `mcp:` binding on
+  the node (see `ir-schema.md`) is how the MCP backend wires itself;
+  your `extracted/` implementation is the *direct-API* backend the
+  user selects with `--backend api`. Keep both true to the same
+  contract.
+- Do not invent data the observation doesn't show. An inferred schema
+  from one sample marks fields it saw; absence of a field is not
+  license to add speculative ones.
+- Do not soften a failing contract to make a test pass. The observed
+  payload is the spec; if your implementation can't reproduce it,
+  the implementation is wrong.
+
+## BDR worked example
+
+`enrich_contact_batch` under Regime 2, with an observed
+`zoominfo_enrich_contacts` call in probe-context:
+
+- Function takes `contacts: list[dict]` (the observed input key),
+  chunks by the lifted `BATCH_SIZE = 10`, calls the documented
+  ZoomInfo enrich endpoint with `ZOOMINFO_API_KEY` from the env, and
+  returns the observed response shape (`{"contacts": [...]}`)
+  normalized per the inferred schema.
+- `tests/test_extracted.py` asserts: chunking math at the boundary
+  (10, 11, 20 contacts), request shape against a stubbed transport
+  using the observed input, response parsing against the observed
+  result payload verbatim, and `BATCH_SIZE == 10`.
+- Module docstring cites the ZoomInfo enrich doc URL fetched during
+  implementation and lists `httpx` as the dependency.

{rote_cli-0.8.0 → rote_cli-0.10.0}/skills/rote-graduate/references/ir-schema.md

@@ -99,8 +99,51 @@ kind. The validator enforces kind-specific requirements.
     strategy: persistent
     ttl: 30d
   fan_out: false                 # optional, if true node invoked per input element
+  mcp:                           # external_call only — see "MCP bindings" below
+    server: hubspot              # logical MCP server name (identifier)
+    tool: hubspot_batch_upsert   # exact MCP tool name the skill calls
 ```
 
+### MCP bindings (`mcp:`) — REQUIRED when the source step is an MCP tool call
+
+If the skill step you are graduating calls an MCP tool — and in
+production skills, almost every data pull and vendor write does — the
+`external_call` node **must** carry an `mcp:` binding recording the
+logical server name and the exact tool name:
+
+```yaml
+- id: fetch_intake_messages
+  kind: external_call
+  impl: extracted/slack.py:fetch_intake_messages
+  mcp:
+    server: slack                # the MCP server the skill's tool lives on
+    tool: slack_read_channel     # the tool name, exactly as the skill calls it
+```
+
+This is not documentation — the binding is load-bearing:
+
+- With `--backend mcp` (the default), adapters emit a **working call to
+  that tool** instead of a NotImplementedError stub; without the binding
+  the user has to hand-write the integration you could have wired.
+- The pipeline's required-MCP-servers manifest, preflight auth
+  recommendations, and durable park-on-auth all derive from bindings —
+  an unbound node is invisible to all three.
+- `rote graduate` cross-checks bindings against traffic observed in a
+  baseline run; a tool the skill demonstrably calls with no binding is
+  reported as a missed requirement (i.e., a graduation bug).
+
+Rules:
+
+- One binding per node — the server + tool pair the step actually uses.
+  If a step uses two tools, it's two nodes (or an `agent_loop`).
+- `server` is the *logical* name (identifier: letters/digits/underscore);
+  it resolves to an endpoint at runtime via the rote registry — do not
+  put URLs in the binding unless the skill pins an explicit endpoint.
+- Keep `impl:` too: the binding and the extracted stub are the two
+  backends (`mcp` vs `api`) of the same node.
+- Steps that are *not* MCP tool calls (plain HTTP the skill documents,
+  browser automation, file I/O) take no binding — never invent one.
+
 ### Data-flow bindings (`inputs:`)
 
 `input:` documents *types*; `inputs:` binds *where the values come

{rote_cli-0.8.0 → rote_cli-0.10.0}/skills/rote-graduate/references/node-kinds.md

@@ -66,10 +66,18 @@ deterministic. If the agent decides which tool to call and what to pass
 each iteration, it's an `agent_loop`.
 
 **MCP → deterministic API:** this is the kind that most often originates
-as an MCP tool call in the source skill. The graduation step is to record
-the underlying vendor API the tool wraps (e.g.,
-`POST /crm/v3/objects/contacts/batch/upsert`) in the `impl`'s docstring so
-the trace from skill → MCP tool → REST endpoint is visible in the code.
+as an MCP tool call in the source skill. Graduating it has TWO required
+outputs, not one:
+
+1. An **`mcp:` binding on the node** — `server` + `tool`, exactly as the
+   skill calls it (see "MCP bindings" in ir-schema.md). This is
+   load-bearing: the default backend emits a working call to that tool
+   from the binding, and requirements/auth features derive from it.
+   Omitting it on a step that calls an MCP tool is a graduation bug.
+2. The underlying vendor API the tool wraps (e.g.,
+   `POST /crm/v3/objects/contacts/batch/upsert`) recorded in the
+   `impl`'s docstring, so the trace from skill → MCP tool → REST
+   endpoint is visible in the code.
 
 ---
 

{rote_cli-0.8.0 → rote_cli-0.10.0}/src/rote/__init__.py

@@ -1,3 +1,3 @@
 """rote — graduate fuzzy AI skills into deterministic workflows."""
 
-__version__ = "0.8.0"
+__version__ = "0.10.0"

rote_cli-0.10.0/src/rote/__main__.py

@@ -0,0 +1,12 @@
+"""``python -m rote`` — the same CLI as the ``rote`` console script.
+
+Exists so generated configs can invoke rote through a known
+interpreter (``sys.executable -m rote``) instead of guessing at PATH —
+the eval harness's ``headersHelper`` wiring depends on this.
+"""
+
+import sys
+
+from rote.cli import main
+
+sys.exit(main())

rote_cli-0.10.0/src/rote/_dbos.py

@@ -0,0 +1,65 @@
+"""Shared introspection helpers for emitted DBOS apps.
+
+Used anywhere rote needs to talk to an emitted app's system database
+from outside the app process: the eval harness (gate signaling) and the
+MCP auth-release path (``rote mcp login`` waking parked workflows).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+import yaml
+
+
+def _load_dbos_config(app_dir: Path) -> dict[str, object]:
+    config = yaml.safe_load((app_dir / "dbos-config.yaml").read_text(encoding="utf-8"))
+    return config if isinstance(config, dict) else {}
+
+
+def dbos_system_database_url(app_dir: Path) -> str:
+    """The system database URL an emitted DBOS *Python* app will use.
+
+    Must mirror the emitted main.py's resolution order exactly —
+    ``DBOS_SYSTEM_DATABASE_URL`` env override first, then the default
+    SQLite file in the app dir — or messages get delivered to a
+    database the app isn't watching.
+    """
+    override = os.environ.get("DBOS_SYSTEM_DATABASE_URL")
+    if override:
+        return override
+    config = _load_dbos_config(app_dir)
+    name = str(config.get("name", "pipeline"))
+    return f"sqlite:///{(app_dir / f'{name}.dbos.sqlite').resolve()}"
+
+
+def dbos_ts_system_database_url(app_dir: Path) -> str:
+    """The system database URL an emitted DBOS *TypeScript* app will use.
+
+    Mirrors the TS SDK's resolution (verified against dbos-transact-ts
+    ``src/config.ts``, SDK 4.23.x): the emitted main.ts passes
+    ``process.env.DBOS_SYSTEM_DATABASE_URL`` to ``DBOS.setConfig``; a
+    ``system_database_url`` key in dbos-config.yaml (with ``${VAR}``
+    substitution — unset vars become empty, exactly like the SDK) wins
+    next; otherwise the SDK default: Postgres at ``PGHOST``/``PGPORT``
+    with ``PGUSER``/``PGPASSWORD`` (falling back to
+    ``postgres:dbos@localhost:5432``) and database ``<name>_dbos_sys``.
+    The TS SDK is Postgres-only — there is no SQLite branch.
+    """
+    override = os.environ.get("DBOS_SYSTEM_DATABASE_URL")
+    if override:
+        return override
+    config = _load_dbos_config(app_dir)
+    configured = config.get("system_database_url")
+    if isinstance(configured, str) and configured:
+        expanded = re.sub(r"\$\{(\w+)\}", lambda m: os.environ.get(m.group(1), ""), configured)
+        if expanded:
+            return expanded
+    name = re.sub(r"[^a-zA-Z0-9_]", "_", str(config.get("name", "pipeline")))
+    host = os.environ.get("PGHOST", "localhost")
+    port = os.environ.get("PGPORT", "5432")
+    user = os.environ.get("PGUSER", "postgres")
+    password = os.environ.get("PGPASSWORD", "dbos")
+    return f"postgresql://{user}:{password}@{host}:{port}/{name}_dbos_sys"