rote-cli 0.14.0__tar.gz → 0.15.0__tar.gz

{rote_cli-0.14.0 → rote_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rote-cli
-Version: 0.14.0
+Version: 0.15.0
 Summary: Compile AI agent skills into cheap, fast, deterministic pipelines that run without an LLM in the loop
 Project-URL: Homepage, https://roteskills.com
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -25,30 +25,31 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: pydantic>=2.7
+Requires-Dist: pytest<10,>=9.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: api
-Requires-Dist: anthropic>=0.89; extra == 'api'
+Requires-Dist: anthropic>=1.15; extra == 'api'
 Provides-Extra: dbos
-Requires-Dist: dbos<3,>=2.26; extra == 'dbos'
+Requires-Dist: dbos<4,>=3.3; extra == 'dbos'
 Provides-Extra: dev
-Requires-Dist: anthropic>=0.89; extra == 'dev'
-Requires-Dist: dbos<3,>=2.26; extra == 'dev'
-Requires-Dist: fastmcp<4,>=3.4.2; extra == 'dev'
+Requires-Dist: anthropic>=1.15; extra == 'dev'
+Requires-Dist: dbos<4,>=3.3; extra == 'dev'
+Requires-Dist: fastmcp<5,>=4.1.1; 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: trustme>=1.2.1; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: fastmcp<4,>=3.4.2; extra == 'mcp'
+Requires-Dist: fastmcp<5,>=4.1.1; 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<4,>=3.4.2; extra == 'serve'
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'serve'
 Requires-Dist: httpx>=0.28; extra == 'serve'
 Provides-Extra: temporal
 Requires-Dist: temporalio>=1.7; extra == 'temporal'
@@ -75,6 +76,91 @@ genuinely need judgment. A 10 to 20 minute agent loop becomes a
 background workflow that costs a fraction of the tokens and can be
 regression tested.
 
+### Try it free in 60 seconds
+
+No API key, no subscription, no tokens, no clone. The
+[`expense-audit`](examples/expense-audit/) example is a month-end expense
+audit skill whose compiled pipeline ships with working code, and it comes
+inside the package, so you can emit it and run it before you compile
+anything of your own:
+
+```sh
+uv tool install 'rote-cli[dbos]'   # or: python3 -m venv .venv && . .venv/bin/activate && pip install 'rote-cli[dbos]'
+rote example expense-audit         # copies the skill, IR, code and sample input to ./expense-audit
+                                   # (zero-install: uvx --from rote-cli rote example expense-audit)
+
+# IR -> a plain Python script, then run it on the sample batch
+rote emit expense-audit/expected/pipeline-draft.yaml --runtime python --out expense-audit/app-python
+rote run expense-audit/app-python --input expense-audit/input.json
+```
+
+`rote example` prints these commands (and the dbos and eval ones) for
+the copy it made. `rote example` alone lists what is bundled. Prefer the
+repo? `git clone https://github.com/trevhud/rote.git && cd rote`, then
+use `examples/expense-audit/` in place of `expense-audit/`.
+
+```
+rote run (python): succeeded
+  0.1s
+{
+  "file_report": {
+    "report_path": "/home/you/expense-audit/app-python/reports/2026-09-expense-audit.md",
+    "status": "draft",
+    "reviewer": null,
+    "reimbursable_usd": 2395.59,
+    "pending_usd": 844.39,
+    "returned_usd": 64.17,
+    "batch_total_usd": 3304.15,
+    "auto_approved": ["Dev Patel", "Emi Tanaka"],
+    "review_items": 4,
+    "blocked_items": 2
+  }
+}
+```
+
+Sixteen expense lines in five currencies went through a parallel wave of
+three mandatory checks, a per-employee audit fanned out five ways, and a
+report written to disk, with no model anywhere in the loop. The full
+skill also parks for the controller's approval, which needs a durable
+runtime:
+
+```sh
+rote emit expense-audit/expected/pipeline.yaml --runtime dbos --out expense-audit/app-dbos
+rote run expense-audit/app-dbos --input expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+# ... "status": "final", "reimbursable_usd": 2990.98, "returned_usd": 313.17
+```
+
+What compiling it bought, measured: we ran the same batch twice each way
+with `rote eval --run` (the skill as an agent via `claude -p` on Sonnet,
+against the dbos app above):
+
+| | Skill run as an agent | Compiled pipeline |
+| --- | --- | --- |
+| Wall clock per run | 42.9 s | 9.8 s, mostly DBOS startup |
+| Cost per run | $0.22 | $0 |
+| Identical output across runs | 1 of 2 | 2 of 2 |
+
+So it's roughly 4x faster in practice, it drops from $0.22 a run to
+nothing, and it gives the same answer every time. The agent's two runs
+disagreed on where they filed the report. Full results are in
+[`examples/expense-audit/scorecard.md`](examples/expense-audit/scorecard.md).
+
+To get a scorecard for any pipeline without running anything, use
+`rote eval`. It fetches the live price list once and runs no inference.
+Its numbers are an estimate from turn counts, not a measurement:
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+`pip` installs don't include `examples/`, hence the clone. The other
+examples' extracted modules are `NotImplementedError` stubs waiting for
+real vendor API clients, so `expense-audit` is the one that runs end to
+end. Details in [its README](examples/expense-audit/README.md).
+
+### Compile your own skill
+
 ```sh
 pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
@@ -159,6 +245,19 @@ representation (`pipeline.yaml`), extracted Python modules for the
 deterministic parts, typed signature stubs for the LLM-judge parts, and
 runnable code for the durable execution engine of your choice.
 
+The agent implements the deterministic `pure_function` steps the skill
+spells out and writes tests for them. Before the compile reports
+success, rote checks what the agent wrote and runs those tests, and any
+failure goes back to the agent to fix. The tests are code an LLM wrote
+from a skill you may not have written, so rote runs them in an OS
+sandbox (`sandbox-exec` on macOS, bubblewrap on Linux): no network, no
+reads outside the compile's work dir and the Python install, no programs
+other than Python, no API keys in the environment, an empty `HOME`. If
+no sandbox works on your machine, the tests are skipped and the compile
+says the deliverable is unverified. `--trust-skill` runs them without a
+sandbox, and `--no-verify-tests` never runs them; either way, review
+`<out>/compiled/tests/` before running them yourself.
+
 `rote` is a three-layer system; each layer has one job and contracts on
 a small interface.
 
@@ -180,7 +279,7 @@ a small interface.
 ```
 
 1. **The compiler agent** (`skills/rote-compile/`): a regular
-   Anthropic Skill (`SKILL.md` + four reference files). This is the
+   Anthropic Skill (`SKILL.md` + six reference files). This is the
    *brain*; it runs inside any Skills-compatible surface, and you don't
    need `rote` to use it.
 2. **The IR** (`src/rote/ir.py`): Pydantic models for the five node
@@ -210,7 +309,9 @@ touching Python tooling:
 Then say "compile this skill" (or run `/rote:compile`). It confirms the
 source directory, asks which runtime you want, runs the CLI via
 [uv](https://docs.astral.sh/uv/) in the background, and reports the
-emitted pipeline. A second skill, `/rote:serve`, wires compiled
+emitted pipeline. `/rote:implement` then fills in the emitted stub
+modules against each node's IR contract and verifies the result with
+`rote run`. A third skill, `/rote:serve`, wires compiled
 pipelines up as MCP tools so Claude can trigger the deployed workflows
 (see [docs/mcp-trigger.md](docs/mcp-trigger.md)).
 
@@ -230,9 +331,10 @@ this README still works logged out.
 
 > **Naming note:** the `rote` package on PyPI is an unrelated
 > memoization library that also installs `import rote`, so the two can't
-> share an environment. This project's distribution is `rote-cli` while
-> the CLI command and import name stay `rote`, hence
-> `uvx --from rote-cli rote ...`. See [docs/releasing.md](docs/releasing.md).
+> share an environment. This project's distribution is `rote-cli` and the
+> import name stays `rote`. The package installs the same CLI under two
+> commands, `rote` and `rote-cli`, so both `uvx rote-cli ...` and
+> `uvx --from rote-cli rote ...` work. See [docs/releasing.md](docs/releasing.md).
 
 ### Run on the bundled example
 
@@ -246,7 +348,7 @@ rote compile examples/bdr-outreach/skill --out /tmp/bdr-compiled
 
 On that skill the compiler produces a 22-node IR that's **78.9%
 codifiable** (15 of 19 non-gate nodes), extracts 5 Python modules and 2
-typed judge signatures, and flags 4 mandatory nodes and 3 HITL gates,
+typed judge signatures, and flags 3 mandatory nodes and 3 HITL gates,
 all in ~13 minutes for ~$0.70 (Sonnet via Claude Code). Along the way it
 independently lifts the three MANDATORY exclusion checks out of prose,
 pulls four batch-size constants out of prompt text, and models a
@@ -425,6 +527,8 @@ subscription path.
 
 ## How it differs from other tools
 
+For a side-by-side with calcifier, skill-to-workflow, Claude Code dynamic workflows, and hand-written workflows, see [docs/comparison.md](docs/comparison.md).
+
 - **vs. raw durable engines (Temporal / Cloudflare / Inngest / Restate):**
   they give you the workflow *runtime*; they don't help you decide *what
   should be a workflow*. `rote` is the missing step that turns a working
@@ -443,16 +547,17 @@ subscription path.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example. The
-fast suite (`pytest tests/`) makes no real API calls and is what CI runs
-on every push, alongside a Python e2e (DBOS over SQLite + the MCP server
-over real stdio). Each adapter also has a `slow`-marked e2e that runs its
-emitted code against the real runtime (Temporal's time-skipping server,
-the TypeScript targets via `tsc --noEmit` and live dev servers, the
-plain-Python subprocess); those need a Node toolchain / Docker, so they
-run locally with `pytest tests/ -m slow`, not in CI.
-
-Known gaps: the extracted modules are `NotImplementedError` stubs
-you fill in with real API-client code, and a Restate adapter is planned.
+fast suite (`pytest tests/`) makes no real API calls, spends no tokens,
+and runs on every push. CI also runs every `slow`-marked e2e suite on
+every push: DBOS over SQLite, the MCP server over real stdio, the
+TypeScript targets via `tsc --noEmit` and live dev servers (Cloudflare
+`wrangler dev`, the Inngest dev server), and DBOS TypeScript against a
+Docker Postgres. Locally, `pytest tests/ -m slow` runs them; they need a
+Node toolchain and Docker.
+
+Known gaps: extracted modules that need a vendor API client (HubSpot,
+ZoomInfo, and so on) come out as `NotImplementedError` stubs you fill in,
+and a Restate adapter is planned.
 Published on
 PyPI as [`rote-cli`](https://pypi.org/project/rote-cli/) via tag-driven
 Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
@@ -472,7 +577,7 @@ measure your own workflow instead of reading someone else's, use
 ```
 rote/
 ├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
-├── skills/rote-compile/  the compiler agent (SKILL.md + 4 reference files)
+├── skills/rote-compile/  the compiler agent (SKILL.md + 6 reference files)
 ├── src/rote/
 │   ├── cli.py             rote compile / emit / eval / serve
 │   ├── ir.py              Pydantic IR models + load_pipeline
@@ -480,6 +585,7 @@ rote/
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
 ├── examples/
+│   ├── expense-audit/     free first run: working extracted code · fan-out · HITL gate
 │   ├── bdr-outreach/      canonical: all 5 node kinds · IR baseline · run snapshots
 │   ├── ops-report/        100% roteness: zero LLM nodes + a HITL gate
 │   ├── deal-monitor/      data-heavy: parallel waves · fan-out judges · template render
@@ -501,12 +607,16 @@ rote/
   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`: compiled pipelines as MCP tools (FastMCP 3.x)
+  `rote serve`: compiled pipelines as MCP tools (FastMCP 4.x)
 - [`docs/releasing.md`](docs/releasing.md): tag-driven PyPI Trusted
   Publishing
 - [`skills/rote-compile/`](skills/rote-compile/): the compiler's
-  `SKILL.md` and its four rubric files (node kinds, crystallization
-  heuristics, IR schema, LLM-judge extraction)
+  `SKILL.md` and its six rubric files (node kinds, crystallization
+  heuristics, IR schema, LLM-judge extraction, implementation, eval
+  estimates)
+- [`examples/expense-audit/`](examples/expense-audit/): the free first
+  run: a hand-compiled pipeline with working extracted code that
+  `rote run` completes on python, dbos, and temporal with no credentials
 - [`examples/bdr-outreach/`](examples/bdr-outreach/): the canonical
   skill, its ground-truth IR, and snapshotted real compiler runs
 - [`examples/ops-report/`](examples/ops-report/): the 100%-roteness

{rote_cli-0.14.0 → rote_cli-0.15.0}/README.md

@@ -19,6 +19,91 @@ genuinely need judgment. A 10 to 20 minute agent loop becomes a
 background workflow that costs a fraction of the tokens and can be
 regression tested.
 
+### Try it free in 60 seconds
+
+No API key, no subscription, no tokens, no clone. The
+[`expense-audit`](examples/expense-audit/) example is a month-end expense
+audit skill whose compiled pipeline ships with working code, and it comes
+inside the package, so you can emit it and run it before you compile
+anything of your own:
+
+```sh
+uv tool install 'rote-cli[dbos]'   # or: python3 -m venv .venv && . .venv/bin/activate && pip install 'rote-cli[dbos]'
+rote example expense-audit         # copies the skill, IR, code and sample input to ./expense-audit
+                                   # (zero-install: uvx --from rote-cli rote example expense-audit)
+
+# IR -> a plain Python script, then run it on the sample batch
+rote emit expense-audit/expected/pipeline-draft.yaml --runtime python --out expense-audit/app-python
+rote run expense-audit/app-python --input expense-audit/input.json
+```
+
+`rote example` prints these commands (and the dbos and eval ones) for
+the copy it made. `rote example` alone lists what is bundled. Prefer the
+repo? `git clone https://github.com/trevhud/rote.git && cd rote`, then
+use `examples/expense-audit/` in place of `expense-audit/`.
+
+```
+rote run (python): succeeded
+  0.1s
+{
+  "file_report": {
+    "report_path": "/home/you/expense-audit/app-python/reports/2026-09-expense-audit.md",
+    "status": "draft",
+    "reviewer": null,
+    "reimbursable_usd": 2395.59,
+    "pending_usd": 844.39,
+    "returned_usd": 64.17,
+    "batch_total_usd": 3304.15,
+    "auto_approved": ["Dev Patel", "Emi Tanaka"],
+    "review_items": 4,
+    "blocked_items": 2
+  }
+}
+```
+
+Sixteen expense lines in five currencies went through a parallel wave of
+three mandatory checks, a per-employee audit fanned out five ways, and a
+report written to disk, with no model anywhere in the loop. The full
+skill also parks for the controller's approval, which needs a durable
+runtime:
+
+```sh
+rote emit expense-audit/expected/pipeline.yaml --runtime dbos --out expense-audit/app-dbos
+rote run expense-audit/app-dbos --input expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+# ... "status": "final", "reimbursable_usd": 2990.98, "returned_usd": 313.17
+```
+
+What compiling it bought, measured: we ran the same batch twice each way
+with `rote eval --run` (the skill as an agent via `claude -p` on Sonnet,
+against the dbos app above):
+
+| | Skill run as an agent | Compiled pipeline |
+| --- | --- | --- |
+| Wall clock per run | 42.9 s | 9.8 s, mostly DBOS startup |
+| Cost per run | $0.22 | $0 |
+| Identical output across runs | 1 of 2 | 2 of 2 |
+
+So it's roughly 4x faster in practice, it drops from $0.22 a run to
+nothing, and it gives the same answer every time. The agent's two runs
+disagreed on where they filed the report. Full results are in
+[`examples/expense-audit/scorecard.md`](examples/expense-audit/scorecard.md).
+
+To get a scorecard for any pipeline without running anything, use
+`rote eval`. It fetches the live price list once and runs no inference.
+Its numbers are an estimate from turn counts, not a measurement:
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+`pip` installs don't include `examples/`, hence the clone. The other
+examples' extracted modules are `NotImplementedError` stubs waiting for
+real vendor API clients, so `expense-audit` is the one that runs end to
+end. Details in [its README](examples/expense-audit/README.md).
+
+### Compile your own skill
+
 ```sh
 pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
@@ -103,6 +188,19 @@ representation (`pipeline.yaml`), extracted Python modules for the
 deterministic parts, typed signature stubs for the LLM-judge parts, and
 runnable code for the durable execution engine of your choice.
 
+The agent implements the deterministic `pure_function` steps the skill
+spells out and writes tests for them. Before the compile reports
+success, rote checks what the agent wrote and runs those tests, and any
+failure goes back to the agent to fix. The tests are code an LLM wrote
+from a skill you may not have written, so rote runs them in an OS
+sandbox (`sandbox-exec` on macOS, bubblewrap on Linux): no network, no
+reads outside the compile's work dir and the Python install, no programs
+other than Python, no API keys in the environment, an empty `HOME`. If
+no sandbox works on your machine, the tests are skipped and the compile
+says the deliverable is unverified. `--trust-skill` runs them without a
+sandbox, and `--no-verify-tests` never runs them; either way, review
+`<out>/compiled/tests/` before running them yourself.
+
 `rote` is a three-layer system; each layer has one job and contracts on
 a small interface.
 
@@ -124,7 +222,7 @@ a small interface.
 ```
 
 1. **The compiler agent** (`skills/rote-compile/`): a regular
-   Anthropic Skill (`SKILL.md` + four reference files). This is the
+   Anthropic Skill (`SKILL.md` + six reference files). This is the
    *brain*; it runs inside any Skills-compatible surface, and you don't
    need `rote` to use it.
 2. **The IR** (`src/rote/ir.py`): Pydantic models for the five node
@@ -154,7 +252,9 @@ touching Python tooling:
 Then say "compile this skill" (or run `/rote:compile`). It confirms the
 source directory, asks which runtime you want, runs the CLI via
 [uv](https://docs.astral.sh/uv/) in the background, and reports the
-emitted pipeline. A second skill, `/rote:serve`, wires compiled
+emitted pipeline. `/rote:implement` then fills in the emitted stub
+modules against each node's IR contract and verifies the result with
+`rote run`. A third skill, `/rote:serve`, wires compiled
 pipelines up as MCP tools so Claude can trigger the deployed workflows
 (see [docs/mcp-trigger.md](docs/mcp-trigger.md)).
 
@@ -174,9 +274,10 @@ this README still works logged out.
 
 > **Naming note:** the `rote` package on PyPI is an unrelated
 > memoization library that also installs `import rote`, so the two can't
-> share an environment. This project's distribution is `rote-cli` while
-> the CLI command and import name stay `rote`, hence
-> `uvx --from rote-cli rote ...`. See [docs/releasing.md](docs/releasing.md).
+> share an environment. This project's distribution is `rote-cli` and the
+> import name stays `rote`. The package installs the same CLI under two
+> commands, `rote` and `rote-cli`, so both `uvx rote-cli ...` and
+> `uvx --from rote-cli rote ...` work. See [docs/releasing.md](docs/releasing.md).
 
 ### Run on the bundled example
 
@@ -190,7 +291,7 @@ rote compile examples/bdr-outreach/skill --out /tmp/bdr-compiled
 
 On that skill the compiler produces a 22-node IR that's **78.9%
 codifiable** (15 of 19 non-gate nodes), extracts 5 Python modules and 2
-typed judge signatures, and flags 4 mandatory nodes and 3 HITL gates,
+typed judge signatures, and flags 3 mandatory nodes and 3 HITL gates,
 all in ~13 minutes for ~$0.70 (Sonnet via Claude Code). Along the way it
 independently lifts the three MANDATORY exclusion checks out of prose,
 pulls four batch-size constants out of prompt text, and models a
@@ -369,6 +470,8 @@ subscription path.
 
 ## How it differs from other tools
 
+For a side-by-side with calcifier, skill-to-workflow, Claude Code dynamic workflows, and hand-written workflows, see [docs/comparison.md](docs/comparison.md).
+
 - **vs. raw durable engines (Temporal / Cloudflare / Inngest / Restate):**
   they give you the workflow *runtime*; they don't help you decide *what
   should be a workflow*. `rote` is the missing step that turns a working
@@ -387,16 +490,17 @@ subscription path.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example. The
-fast suite (`pytest tests/`) makes no real API calls and is what CI runs
-on every push, alongside a Python e2e (DBOS over SQLite + the MCP server
-over real stdio). Each adapter also has a `slow`-marked e2e that runs its
-emitted code against the real runtime (Temporal's time-skipping server,
-the TypeScript targets via `tsc --noEmit` and live dev servers, the
-plain-Python subprocess); those need a Node toolchain / Docker, so they
-run locally with `pytest tests/ -m slow`, not in CI.
-
-Known gaps: the extracted modules are `NotImplementedError` stubs
-you fill in with real API-client code, and a Restate adapter is planned.
+fast suite (`pytest tests/`) makes no real API calls, spends no tokens,
+and runs on every push. CI also runs every `slow`-marked e2e suite on
+every push: DBOS over SQLite, the MCP server over real stdio, the
+TypeScript targets via `tsc --noEmit` and live dev servers (Cloudflare
+`wrangler dev`, the Inngest dev server), and DBOS TypeScript against a
+Docker Postgres. Locally, `pytest tests/ -m slow` runs them; they need a
+Node toolchain and Docker.
+
+Known gaps: extracted modules that need a vendor API client (HubSpot,
+ZoomInfo, and so on) come out as `NotImplementedError` stubs you fill in,
+and a Restate adapter is planned.
 Published on
 PyPI as [`rote-cli`](https://pypi.org/project/rote-cli/) via tag-driven
 Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
@@ -416,7 +520,7 @@ measure your own workflow instead of reading someone else's, use
 ```
 rote/
 ├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
-├── skills/rote-compile/  the compiler agent (SKILL.md + 4 reference files)
+├── skills/rote-compile/  the compiler agent (SKILL.md + 6 reference files)
 ├── src/rote/
 │   ├── cli.py             rote compile / emit / eval / serve
 │   ├── ir.py              Pydantic IR models + load_pipeline
@@ -424,6 +528,7 @@ rote/
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
 ├── examples/
+│   ├── expense-audit/     free first run: working extracted code · fan-out · HITL gate
 │   ├── bdr-outreach/      canonical: all 5 node kinds · IR baseline · run snapshots
 │   ├── ops-report/        100% roteness: zero LLM nodes + a HITL gate
 │   ├── deal-monitor/      data-heavy: parallel waves · fan-out judges · template render
@@ -445,12 +550,16 @@ rote/
   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`: compiled pipelines as MCP tools (FastMCP 3.x)
+  `rote serve`: compiled pipelines as MCP tools (FastMCP 4.x)
 - [`docs/releasing.md`](docs/releasing.md): tag-driven PyPI Trusted
   Publishing
 - [`skills/rote-compile/`](skills/rote-compile/): the compiler's
-  `SKILL.md` and its four rubric files (node kinds, crystallization
-  heuristics, IR schema, LLM-judge extraction)
+  `SKILL.md` and its six rubric files (node kinds, crystallization
+  heuristics, IR schema, LLM-judge extraction, implementation, eval
+  estimates)
+- [`examples/expense-audit/`](examples/expense-audit/): the free first
+  run: a hand-compiled pipeline with working extracted code that
+  `rote run` completes on python, dbos, and temporal with no credentials
 - [`examples/bdr-outreach/`](examples/bdr-outreach/): the canonical
   skill, its ground-truth IR, and snapshotted real compiler runs
 - [`examples/ops-report/`](examples/ops-report/): the 100%-roteness

rote_cli-0.15.0/examples/expense-audit/README.md

@@ -0,0 +1,156 @@
+# Example: Expense Audit
+
+The **free first run**. A month-end expense audit skill whose compiled
+pipeline ships with *working* extracted code, so `rote emit` + `rote run`
+complete end to end with no API key, no subscription, and no tokens. The
+other examples show what compilation produces against real vendor APIs.
+Their extracted modules are `NotImplementedError` stubs until someone
+writes the HubSpot or Gmail client. This one shows the result actually
+running.
+
+The work is all arithmetic and rules: convert sixteen expense lines from
+five currencies at the finance month-end rates, find duplicates and late
+submissions, check every line against the policy's caps and receipt
+rules, auto-approve clean reports, and file the audit for payroll. Run
+as an agent, every month re-reads the policy and re-derives the same
+rules from prose. Compiled, it is a few milliseconds of Python and one
+human decision.
+
+## What it demonstrates
+
+- **A parallel entry wave.** `convert_to_usd`, `find_duplicates`, and
+  `find_late_submissions` all read the raw export and nothing else, so
+  they run concurrently (a thread pool on python, `asyncio.gather` on
+  temporal, steps enqueued on a DBOS queue on dbos).
+- **`fan_out`.** `audit_report` runs once per employee report, five
+  times on the sample batch, and the results come back as a list in
+  input order.
+- **`mandatory: true`.** The duplicate and late checks, which SKILL.md
+  marks MANDATORY, are unconditional code. They can't be skipped on a
+  month that "looks small enough to eyeball".
+- **Rules lifted out of prose.** Category caps, the $25.00 receipt
+  threshold, the $2,500.00 report limit, the 60-day window, and the FX
+  table live as constants in `expected/extracted/`, not prompt text.
+- **`hitl_gate`.** `controller_review` parks the durable workflow until
+  the controller approves or rejects each review item, then the report
+  is filed as final.
+- **No `llm_judge`.** Nothing in the skill needs judgment once the
+  policy is written down, so the compiled pipeline makes zero model
+  calls. Roteness 1.0.
+
+## Two IRs, one pipeline
+
+| File | Gate | Runs on |
+| --- | --- | --- |
+| `expected/pipeline.yaml` | `controller_review` | `dbos`, `temporal` (and the TS runtimes for emission) |
+| `expected/pipeline-draft.yaml` | none | `python` too |
+
+The `python` runtime refuses pipelines with a `hitl_gate`: a plain script
+can't durably park for days waiting on a human. `pipeline-draft.yaml` is
+the same pipeline with the gate removed, so `file_report` files a
+**draft** with every review item pending. A test
+(`tests/test_expense_audit_example.py`) pins that the two IRs differ by
+exactly the gate and its edges.
+
+## Run it
+
+From the repo root, after `uv tool install 'rote-cli[dbos]'` (or `pip install` into a venv):
+
+```sh
+# Plain Python, no gate: a draft report.
+rote emit examples/expense-audit/expected/pipeline-draft.yaml --runtime python --out /tmp/expense-audit
+rote run /tmp/expense-audit --input examples/expense-audit/input.json
+
+# DBOS, with the controller's decision delivered to the parked gate.
+rote emit examples/expense-audit/expected/pipeline.yaml --out /tmp/expense-audit-dbos
+rote run /tmp/expense-audit-dbos --input examples/expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+
+# Temporal: needs the temporal extra and a release newer than 0.14.0. The first run downloads the dev server.
+rote emit examples/expense-audit/expected/pipeline.yaml --runtime temporal --out /tmp/expense-audit-temporal
+rote run /tmp/expense-audit-temporal --input examples/expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+
+# The before/after scorecard (fetches live model prices, no inference).
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+The run prints the totals as JSON and writes the markdown report to
+`reports/2026-09-expense-audit.md` under the app dir on every runtime.
+Set `EXPENSE_AUDIT_REPORT_DIR` to put it somewhere else.
+
+Expected results on `input.json`:
+
+| | Draft (python) | Final (dbos, temporal) |
+| --- | --- | --- |
+| Reimbursable | $2,395.59 | $2,990.98 |
+| Pending review | $844.39 | $0.00 |
+| Returned to employee | $64.17 | $313.17 |
+| Batch total | $3,304.15 | $3,304.15 |
+
+The review queue holds four review items (a meal over the cap, software
+over the cap, a late line, entertainment without pre-approval) and two
+blocks (a $25.97 ride with no receipt, a duplicate Lyft charge filed as
+"lyft"). Blocks go back to the employee whatever the controller says. A
+decision that names a block item fails the step with the ids to fix.
+
+## Layout
+
+```
+examples/expense-audit/
+├── README.md
+├── input.json                    # the sample month export (2026-09)
+├── eval-input.json               # input.json plus the gate payload, for `rote eval --run`
+├── scorecard.md                  # measured before/after (rote eval --run)
+├── skill/
+│   ├── SKILL.md                  # the source skill, as an agent would run it
+│   └── references/
+│       ├── expense-policy.md     # caps, receipts, severities
+│       ├── fx-rates.md           # finance month-end rates
+│       └── report-format.md      # the layout payroll reads
+└── expected/
+    ├── pipeline.yaml             # hand-compiled IR, with the controller gate
+    ├── pipeline-draft.yaml       # the same IR without the gate
+    ├── eval.yaml                 # per-step agent-turn estimates for `rote eval`
+    └── extracted/                # working implementations, no stubs
+        ├── fx.py
+        ├── checks.py
+        ├── audit.py
+        └── report.py
+└── runs/
+    └── 2026-10-18-first-agent-run/   # a real `rote compile` of skill/, for comparison
+```
+
+`expected/` is hand-authored, like the other examples' baselines.
+
+## Measured, not estimated
+
+`scorecard.md` is `rote eval --run --trials 2` on this example, with
+`eval-input.json` (the batch plus the controller's decision). The agent
+runs took 42.9 s and $0.22 each, and they disagreed on `report_path`.
+The pipeline runs took 9.8 s, most of it DBOS startup, cost $0, and
+produced identical output. The static estimate at the top of that file
+(3.2 to 6.5 minutes before) is only a model of agent turns. Trust the
+Measured section over it. To reproduce, emit the dbos app as above and
+run this (it spends subscription tokens on the agent side):
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml --run --trials 2 \
+  --input examples/expense-audit/eval-input.json --runtime-dir /tmp/expense-audit-dbos
+```
+
+## What the real compiler produced
+
+`runs/2026-10-18-first-agent-run/` is a real `rote compile` of this
+skill (claude driver, Sonnet, 46 turns, 12 minutes, $2.56). It agrees on
+node kinds and on the three-way parallel entry wave, and it puts the
+controller gate in the same place. It differs in three ways:
+
+- It folded grouping and auditing into one `apply_policy_rules` node
+  instead of fanning `audit_report` out per employee.
+- It marked 7 nodes mandatory where the hand-written IR marks 5.
+- It left every extracted function as a `NotImplementedError` stub, even
+  though this skill's logic is plain Python.
+
+The hand-written IR is the intended shape. The compiler gaps are being
+fixed in a separate PR.