Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

chore(agents): prune stale skills (#150)

nachiketb-nvidia239a4138ef84
diff --git a/.agents/skills/dco-signoff/SKILL.md b/.agents/skills/dco-signoff/SKILL.md
deleted file mode 100644
index 8a6728395..000000000
--- a/.agents/skills/dco-signoff/SKILL.md
+++ /dev/null
@@ -1,109 +0,0 @@
----
-name: dco-signoff
-description: Fix missing DCO (Developer Certificate of Origin) sign-off on branch commits and prevent the issue going forward. Use when CI reports a DCO check failure, a PR is blocked by "Signed-off-by missing", or a collaborator asks you to add sign-off to commits.
----
-
-# DCO Sign-Off
-
-Every commit merged into Switchyard must carry a `Signed-off-by` trailer:
-
-```
-Signed-off-by: Your Name <[email protected]>
-```
-
-This is enforced by the DCO bot on every pull request. A branch with any commit missing this trailer will be blocked from merge.
-
-## Detect missing sign-offs
-
-Check which branch commits are missing the trailer:
-
-```bash
-git log origin/main..HEAD --format="%H %s" | while read sha msg; do
- if ! git show -s --format="%B" "$sha" | grep -q "^Signed-off-by:"; then
- echo "MISSING: $sha $msg"
- fi
-done
-```
-
-If the output is empty, all commits are already signed and no action is needed.
-
-## Fix: add sign-off to all branch commits
-
-Rebase the branch onto `origin/main`, adding `--signoff` to retrofit the trailer on every commit:
-
-```bash
-git rebase origin/main --signoff
-```
-
-Then push. Because a rebase rewrites SHAs, you must force-push:
-
-```bash
-git push --force-with-lease origin HEAD
-```
-
-`--force-with-lease` is safer than `--force`: it aborts if the remote has received new commits since your last fetch, protecting against overwriting a collaborator's work.
-
-### When the rebase hits a conflict
-
-Resolve each conflict normally, then continue:
-
-```bash
-git add <resolved-files>
-git rebase --continue
-```
-
-The `--signoff` flag was set at rebase-start; `--continue` applies it to each commit as it lands. You do not need to pass `--signoff` again.
-
-## Prevent it going forward
-
-Pass `-s` (shorthand for `--signoff`) on every `git commit`:
-
-```bash
-git commit -s -m "type(scope): your message"
-```
-
-Or add it to the repo's local git config so it is applied automatically:
-
-```bash
-git config commit.gpgSign false # unrelated — don't confuse with signoff
-```
-
-There is no `commit.signoff = true` git config option; the `-s` flag must be used explicitly each time, or the workflow must always pass it. The safest habit is to include `-s` in every `git commit` invocation.
-
-## What a correct trailer looks like
-
-```
-fix(protocol): correct sub-agent detection for Claude Code
-
-Signed-off-by: Lin Jia <[email protected]>
-```
-
-The name and email must match the contributor's Git identity (`git config user.name` and `git config user.email`). A mismatch causes the DCO bot to reject the commit even when the trailer is present.
-
-## Verify the fix
-
-After rebasing and pushing, confirm locally before relying on CI:
-
-```bash
-git log origin/main..HEAD --format="%H %s%n%b" | grep -E "(^[0-9a-f]{40}|Signed-off-by)"
-```
-
-Every commit SHA should be followed by a `Signed-off-by:` line.
-
-## Boundaries
-
-### Always do
-
-- Use `--force-with-lease` instead of `--force` when pushing a rebased branch.
-- Verify that `git config user.name` and `git config user.email` match the expected identity before adding sign-off — a mismatch is caught by the DCO bot.
-- Run the detection check first; if all commits already have sign-off, do nothing.
-
-### Ask first
-
-- Rebasing a branch that has open review comments attached to specific commit SHAs — the rewrite makes those comments orphaned on GitHub.
-- Force-pushing a branch that is also used by another collaborator's local checkout.
-
-### Never do
-
-- Force-push `main` or any protected branch to add sign-off. The correct fix for a merged commit is to ensure future commits are signed; retroactive rewriting of main history is not possible.
-- Use `--no-verify` to skip the DCO pre-push hook if one is configured — that bypasses the gate without fixing the root cause.
diff --git a/.agents/skills/publish-package/SKILL.md b/.agents/skills/publish-package/SKILL.md
deleted file mode 100644
index e81655236..000000000
--- a/.agents/skills/publish-package/SKILL.md
+++ /dev/null
@@ -1,94 +0,0 @@
----
-name: publish-package
-description: Build and publish Switchyard packages through the current OSS-style GitHub release path. Use when asked to publish, release, ship, tag, cut a version, build wheel artifacts, or prepare a package release.
----
-
-# Publish Switchyard
-
-Switchyard currently uses the OSS-style NeMo release shape in GitHub Actions. Keep temporary dev
-wheels separate from official tag-gated release builds.
-
-| Channel | Trigger | CI owner | Destination | Runbook |
-|---|---|---|---|---|
-| Dev wheel artifact | Manual `publish.yml` dispatch with `build_dev_artifact=true` | GitHub Actions | One-day GitHub artifact | `docs/internal/release_workflow.md` |
-| Dev matrix artifact | Manual `publish.yml` dispatch with `build_dev_matrix=true` | GitHub Actions | Full matrix GitHub artifacts | `docs/internal/release_workflow.md` |
-| Official release build | Root `vMAJOR.MINOR.PATCH` tag | GitHub Actions `.github/workflows/publish.yml` | Full release artifact matrix + PyPI Trusted Publishing via `uv publish` | `.github/workflows/publish.yml` |
-
-Release publishing stays on the public GitHub/PyPI path. Manual branch builds only produce
-artifacts; root release tags publish through PyPI Trusted Publishing.
-
-## Guardrails
-
-- Do not create tags unless the user explicitly asks for a tag-based release.
-- Do not create GitHub Releases for dev wheel artifacts.
-- Do not publish dev wheels to PyPI from manual workflow dispatch.
-- Keep `.dev` artifacts public-safe because GitHub Actions artifacts may be shared for review.
-- Full wheel matrices may run manually for validation, but PyPI publishing belongs only on root
- `vMAJOR.MINOR.PATCH` tag releases.
-- Manual dev builds should build exactly one Linux x86_64 wheel artifact with one-day retention.
-- Use PyPI Trusted Publishing with the GitHub environment named `pypi`; do not add long-lived PyPI tokens.
-
-## Dev Wheel Artifact Shape
-
-Use the workflow-dispatch path in `.github/workflows/publish.yml`.
-
-It stamps a build-local `.dev` version, builds one manylinux x86_64 abi3 wheel, uploads it as
-`dev-wheel-linux-x86_64` with one-day retention, then downloads it again to verify the wheel `Name`
-and `Version`.
-
-| Input | Default | Meaning |
-|---|---|---|
-| `build_dev_artifact` | `false` | Set to `true` to build one temporary wheel artifact |
-| `build_dev_matrix` | `false` | Set to `true` to build the complete sdist and wheel matrix as artifacts |
-| `dev_version` | `0.0.1.dev0` | PEP 440 `.dev` version for wheel metadata |
-
-## Required Secrets
-
-The artifact-only dev build does not require release secrets.
-
-The official publish job uses `uv publish --trusted-publishing always`; no PyPI token is required.
-Manual dev builds never publish to PyPI.
-
-Before cutting the first tag, create the pending PyPI trusted publisher for:
-
-| Field | Value |
-|---|---|
-| Project | `nemo-switchyard` |
-| Owner | `NVIDIA-NeMo` |
-| Repository | `Switchyard` |
-| Workflow | `publish.yml` |
-| Environment | `pypi` |
-
-## Local Preflight For Release-Infrastructure Changes
-
-When editing release scripts, package metadata, package release docs, or this skill, run:
-
-```bash
-uv run ruff check scripts/release/set_dev_wheel_version.py tests/test_dev_wheel_versioning.py
-uv run pytest tests/test_dev_wheel_versioning.py -v
-python scripts/release/set_dev_wheel_version.py 0.0.1.dev0 --print-version
-git diff --check
-```
-
-For docs changes under `docs/`, also run the strict MkDocs build when practical:
-
-```bash
-cd docs
-make publish
-```
-
-## Failure Map
-
-| Symptom | Fix |
-|---|---|
-| GitHub artifact verifier cannot find wheels | Check the `dev-wheel-*` artifact names and retention |
-| Artifact build creates a `switchyard` wheel | Confirm `scripts/release/set_dev_wheel_version.py` ran before `maturin build` |
-| Release publish cannot mint trusted token | Confirm PyPI pending publisher and GitHub `pypi` environment both match the workflow |
-| Full matrix runs on every commit | Ensure matrix jobs are only `workflow_dispatch` or root release-tag gated |
-| Install imports checkout version | Verify from a temporary directory outside the repo |
-
-## References
-
-- Release workflow runbook: `docs/internal/release_workflow.md`
-- Dev wheel version helper: `scripts/release/set_dev_wheel_version.py`
-- Public GitHub build workflow: `.github/workflows/publish.yml`
diff --git a/.agents/skills/publish-python-release/SKILL.md b/.agents/skills/publish-python-release/SKILL.md
new file mode 100644
index 000000000..f674afea8
--- /dev/null
+++ b/.agents/skills/publish-python-release/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: publish-python-release
+description: Build or publish nemo-switchyard Python distributions through the repository's GitHub Actions workflow. Use when asked to build a development wheel, cut a Python release, publish to PyPI, create a release tag, or debug .github/workflows/publish.yml.
+---
+
+# Publish The Python Package
+
+Use `.github/workflows/publish.yml` as the source of truth. The supporting runbook is
+`docs/internal/release_workflow.md`.
+
+## Release Paths
+
+| Intent | Trigger | Result |
+|---|---|---|
+| One temporary wheel | Manual dispatch with `build_dev_artifact=true` | Linux x86_64 GitHub artifact, retained for one day |
+| Full matrix test | Manual dispatch with `build_dev_matrix=true` | sdist and wheel artifacts; no publish |
+| Official release | Push `vMAJOR.MINOR.PATCH` matching `pyproject.toml` | Full matrix, PyPI publish, GitHub Release |
+
+Manual builds are artifact-only. Official releases use PyPI Trusted Publishing through the
+GitHub environment named `pypi`; do not add a long-lived PyPI token.
+
+## Workflow
+
+1. Read the current workflow and `pyproject.toml`; do not rely on remembered inputs or versions.
+2. Confirm the requested version and whether the user explicitly authorized creating a tag.
+3. For workflow changes, run the focused release-helper tests and inspect the workflow diff.
+4. Dispatch a development build or push the authorized release tag.
+5. Monitor every matrix job and verify the resulting package from a clean temporary environment.
+
+Example development dispatch:
+
+```bash
+gh workflow run publish.yml \
+ -f build_dev_artifact=true \
+ -f build_dev_matrix=false \
+ -f dev_version=0.0.1.dev0
+```
+
+## Guardrails
+
+- Never create or push a tag unless the user explicitly requested it.
+- Never publish a manual development build to PyPI.
+- Never reuse a deleted PyPI filename or version; PyPI permanently reserves filenames.
+- Keep release versions consistent across the tag, `pyproject.toml`, and package metadata.
+- Verify installation outside the checkout so local imports cannot mask packaging defects.
+- Cargo crate publishing is a separate manual workflow. Inspect each crate's `Cargo.toml`,
+ dependency publication order, and crates.io ownership before running `cargo publish`.
+
+## Release-Infrastructure Validation
+
+```bash
+uv run ruff check scripts/release/set_dev_wheel_version.py tests/test_dev_wheel_versioning.py
+uv run pytest tests/test_dev_wheel_versioning.py -v
+python scripts/release/set_dev_wheel_version.py 0.0.1.dev0 --print-version
+git diff --check
+```
diff --git a/.agents/skills/run-pre-merge-checks/SKILL.md b/.agents/skills/run-pre-merge-checks/SKILL.md
deleted file mode 100644
index 3893f8200..000000000
--- a/.agents/skills/run-pre-merge-checks/SKILL.md
+++ /dev/null
@@ -1,311 +0,0 @@
----
-name: run-pre-merge-checks
-description: Run the live end-to-end production tests against the real NVIDIA Inference Hub backend, then produce a screenshot-ready summary that can be attached to an MR. Use this skill when asked to run pre-merge checks, run the e2e tests, validate before merging, or generate an MR test summary.
----
-
-# Run Pre-Merge Checks
-
-The pre-merge gate for `switchyard`. This skill runs `tests/e2e/` — the live end-to-end production tests that exercise Switchyard against a real NVIDIA Inference Hub backend — and produces a clean, screenshot-friendly summary the user can paste into an MR description.
-
-Run this **before opening or updating an MR**, especially after touching anything under `switchyard/` or `crates/`. The test suite spawns real `switchyard` subprocesses, calls real upstream APIs, and validates the full chain (request processors, LLM backends, response processors, and translation engine) for all three inbound formats (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages).
-
-## Parameters
-
-Extract from the user's request. Use defaults if not specified:
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `test_path` | `tests/e2e/` | Pytest target. Override to a single file (`tests/e2e/test_passthrough_e2e.py`) or single test (`...::TestPassthroughChatCompletions::test_basic_completion`) when iterating. |
-| `extra_args` | _(none)_ | Extra pytest flags to append (e.g. `-k passthrough`, `--lf`, `-s`). |
-| `also_lint` | `true` | Also run `uv run ruff check .` after the tests. CI runs this and lint failures block merge. |
-| `also_typecheck` | `false` | Also run `uv run mypy switchyard`. Slower; off by default — turn on when the diff includes type changes. |
-| `maxfail` | `5` | Stop the run after this many failures. We want to surface as many real regressions as possible in one pass, but bail out if everything's broken (e.g. credentials wrong, server can't bind). |
-
-## Sandbox: must be off
-
-**Run every Bash invocation in this skill with `dangerouslyDisableSandbox: true`.** The skill needs write access to:
-
-- `/tmp/pre-merge-checks/` (log directory — outside the default sandbox `/tmp/claude` allowlist)
-- `~/.cache/uv/` (uv's package cache — `uv run` cannot resolve dependencies without it)
-- `secrets/secrets.json` (read-only, but on some sandbox configs even reads from arbitrary paths under the repo are mediated)
-- the git working tree at `$REPO_ROOT` (test subprocesses spawn from here and write `.pytest_cache/` etc.)
-
-The first time you call Bash without disabling the sandbox you will see errors like `mkdir: /tmp/pre-merge-checks: Operation not permitted` and `failed to open file /Users/linj/.cache/uv/...: Operation not permitted` — that's the signal. Don't try to work around it with `$TMPDIR` or by relocating the uv cache; just disable the sandbox for this skill's commands. The user can manage permanent allowlist entries via `/sandbox` if they want to avoid the per-call prompts.
-
-## What this skill runs (and why)
-
-The e2e suite has multiple test files. Each spawns its own (or shared) subprocess server and hits the real NVIDIA inference API:
-
-| File | What it covers | Why it matters for merge |
-|------|---------------|--------------------------|
-| `test_passthrough_e2e.py` | OpenAI Chat Completions inbound → OpenAI backend → real API | Validates the most common production path. |
-| `test_passthrough_responses_e2e.py` | OpenAI Responses API inbound → translation → Chat Completions backend | Validates the Responses-to-Chat translation engine end-to-end. |
-| `test_random_routing_llm_backend.py` | Random-routing processor plus Rust `MultiLlmBackend` dispatch across OpenAI-compatible and Anthropic-native tiers | Validates the random-routing profile path used by TerminalBench / SWE-bench experiments. |
-| `test_latency_service_llm_backend.py` | `LatencyServiceLLMBackend` health-aware multi-endpoint routing | Validates the health-poller usage case. |
-| `test_verify_e2e.py` | The `switchyard verify` + `switchyard launch {claude,codex} --smoke` CLIs | Validates the user-facing post-clone smoke test. Proxy-only mode shells `switchyard verify`; harness modes shell `switchyard launch <target> --smoke`. Sub-tests skip if `claude` / `codex` CLIs aren't installed; that is expected, not a failure. |
-
-These are **session-scoped subprocess fixtures** — running them costs real upstream tokens. Expect ~1–3 minutes wall time and a few cents of API spend per full run.
-
-## Prerequisites
-
-These need to be in place before the skill can do anything useful. Check all of them up front and fail loud if any are missing.
-
-### 1. Repo root + venv
-
-The skill must run from the Switchyard repo root regardless of where the user has it cloned. Resolve it dynamically — never hardcode a path:
-
-```bash
-REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
-if [ -z "$REPO_ROOT" ]; then
- echo "NOT_IN_GIT_REPO — run this skill from inside a Switchyard checkout"; exit 1
-fi
-cd "$REPO_ROOT"
-
-# Sanity-check we're actually in Switchyard, not some other repo
-if [ ! -d "switchyard" ] || [ ! -d "tests/e2e" ]; then
- echo "WRONG_REPO — $REPO_ROOT does not look like Switchyard"; exit 1
-fi
-
-test -d .venv || { echo "MISSING_VENV — run ./setup.sh --dev first"; exit 1; }
-```
-
-All subsequent commands in this skill assume pwd is `$REPO_ROOT`. Relative paths (`tests/...`, `secrets/...`, `switchyard/...`) are intentional — they make the skill portable across clones.
-
-### 2. Credentials — NVIDIA API key
-
-The fixtures resolve credentials in this order:
-
-1. `NVIDIA_API_KEY` env var
-2. `secrets/secrets.json` (already gitignored)
-
-Check both:
-
-```bash
-if [ -n "$NVIDIA_API_KEY" ]; then
- echo "OK: NVIDIA_API_KEY set in env"
-elif [ -f secrets/secrets.json ] && grep -q '"nvidia"' secrets/secrets.json; then
- echo "OK: secrets/secrets.json has nvidia section"
-else
- echo "MISSING — set NVIDIA_API_KEY or copy secrets/secrets.template.json to secrets/secrets.json and fill in"
- exit 1
-fi
-```
-
-If neither is present, stop and tell the user:
-
-> `NVIDIA_API_KEY` is required for the e2e tests. Either `export NVIDIA_API_KEY=...` or copy `secrets/secrets.template.json` to `secrets/secrets.json` and fill in the `nvidia` section. Re-run after that.
-
-### 3. Working tree status
-
-Capture the branch and HEAD so the summary is reproducible:
-
-```bash
-git rev-parse --abbrev-ref HEAD
-git rev-parse --short HEAD
-git status --porcelain | wc -l # number of dirty files
-```
-
-## Workflow
-
-### Step 1: Verify prerequisites
-
-Run the three checks from "Prerequisites" above in parallel via the Bash tool. Report any failure and stop. Print the branch/HEAD/dirty-file count — these go into the summary.
-
-### Step 2: Run the e2e tests
-
-Use `uv run pytest` so the venv resolves automatically. Pipe the output through `tee` so you have both a live transcript and a file the skill can grep at the end.
-
-**Override the project's default `-x` (set in `pyproject.toml`'s `addopts`).** The pre-merge check should surface as many real failures as possible in one run, not stop at the first one — otherwise reviewers can't tell whether downstream tests regressed too. Use `-o addopts= --maxfail={maxfail}` to keep going up to the failure budget.
-
-```bash
-mkdir -p /tmp/pre-merge-checks
-LOG=/tmp/pre-merge-checks/v2-e2e-$(date +%Y%m%d-%H%M%S).log
-uv run pytest {test_path} -v -o addopts= --maxfail={maxfail} {extra_args} 2>&1 | tee "$LOG"
-echo "EXIT_CODE=${PIPESTATUS[0]}"
-```
-
-Important notes:
-- **Do not run the tests in the background.** They take 1–10 min (full suite) and the skill needs the exit code. Use Bash's normal blocking mode with a generous timeout (`timeout: 900000` = 15 min covers a full no-`-x` run with retries).
-- **Run with `dangerouslyDisableSandbox: true`** — see the "Sandbox: must be off" section above. The first attempt without will fail at `mkdir /tmp/pre-merge-checks`.
-- If pytest reports `skipped`, that is normal — `test_verify_e2e.py` skips Claude / Codex sub-tests when those CLIs aren't installed.
-
-#### Detect incomplete runs
-
-If `--maxfail` was hit, pytest stops early and the suite is **incomplete**. Detect and surface this loudly — both in the terminal and in the final summary. A green-looking partial run is the worst possible outcome.
-
-```bash
-COLLECTED=$(grep -oE "collected [0-9]+ items?" "$LOG" | head -1 | grep -oE "[0-9]+")
-# Pull the final summary line, e.g. "5 failed, 30 passed, 2 skipped in 412.18s"
-SUMMARY=$(grep -E "= [0-9]+ (passed|failed)" "$LOG" | tail -1)
-PASSED=$(echo "$SUMMARY" | grep -oE "[0-9]+ passed" | grep -oE "[0-9]+" || echo 0)
-FAILED=$(echo "$SUMMARY" | grep -oE "[0-9]+ failed" | grep -oE "[0-9]+" || echo 0)
-SKIPPED=$(echo "$SUMMARY" | grep -oE "[0-9]+ skipped" | grep -oE "[0-9]+" || echo 0)
-ERRORS=$(echo "$SUMMARY" | grep -oE "[0-9]+ error" | grep -oE "[0-9]+" || echo 0)
-RAN=$((PASSED + FAILED + SKIPPED + ERRORS))
-
-if [ "$RAN" -lt "$COLLECTED" ]; then
- NOT_RUN=$((COLLECTED - RAN))
- echo ""
- echo "================================================================"
- echo "⚠️ TEST RUN INCOMPLETE"
- echo " Stopped after $FAILED failure(s) — reached --maxfail={maxfail} threshold."
- echo " $NOT_RUN of $COLLECTED tests did NOT execute."
- echo " Fix the failing tests and re-run before treating this as a clean signal."
- echo "================================================================"
-fi
-```
-
-When `RAN < COLLECTED`, the final summary's `Status` line must be `❌ FAIL — INCOMPLETE` (not just `❌ FAIL`), and the markdown summary must include the `not run` count so the MR reviewer immediately sees that some tests were never reached.
-
-### Step 3: (Optional) Run lint
-
-If `also_lint` is true (the default):
-
-```bash
-uv run ruff check . 2>&1 | tee /tmp/pre-merge-checks/ruff-$(date +%Y%m%d-%H%M%S).log
-echo "RUFF_EXIT=${PIPESTATUS[0]}"
-```
-
-Lint failures block CI and are an embarrassing-but-cheap gate to catch before push. AGENTS.md says: "must pass with zero errors before any commit or push."
-
-### Step 4: (Optional) Run mypy
-
-If `also_typecheck` is true:
-
-```bash
-uv run mypy switchyard 2>&1 | tee /tmp/pre-merge-checks/mypy-$(date +%Y%m%d-%H%M%S).log
-echo "MYPY_EXIT=${PIPESTATUS[0]}"
-```
-
-mypy runs in `strict` mode per `pyproject.toml`. It's slower than ruff (~30s+); only run when the user explicitly asks or the diff has substantial type changes.
-
-### Step 5: Parse results
-
-Extract the summary line pytest writes at the end. Examples:
-
-```
-================== 27 passed, 3 skipped in 142.44s (0:02:22) ==================
-================ 25 passed, 1 failed, 4 skipped in 138.91s ===================
-```
-
-Pull these counts (passed / failed / skipped / errors / wall time) from the log. If there are failures, also pull the names of the failed tests — they live above the summary in the `FAILED` lines:
-
-```bash
-grep -E "^FAILED " "$LOG"
-```
-
-### Step 6: Generate the screenshot-ready summary
-
-This is the deliverable. The user is going to screenshot it and paste into the MR. Format it as a single Markdown block in the chat — no surrounding chatter, no follow-up questions, no "Let me know if…". Just the block. Headers, tables, and a clean status line at the top.
-
-Use this exact template (fill in the `{}` placeholders):
-
-```markdown
-## Pre-merge checks — {branch} @ {short_sha}{dirty_marker}
-
-**Status: {✅ PASS | ❌ FAIL | ⛔ FAIL — INCOMPLETE}** · {date_iso} · {wall_time}
-
-### Live e2e production tests — `tests/e2e/`
-
-| Result | Count |
-|--------|------:|
-| Passed | {n_passed} |
-| Failed | {n_failed} |
-| Skipped | {n_skipped} |
-| Errors | {n_errors} |
-| **Not run** | **{n_not_run}** |
-
-{if n_not_run > 0:}
-> ⚠️ **Run incomplete.** Stopped after {n_failed} failures (--maxfail={maxfail}). {n_not_run} of {n_collected} tests did not execute. Fix the failures and re-run before treating this as a clean signal.
-{/if}
-
-{if n_failed > 0:}
-**Failed tests:**
-{for each failed test:}
-- `{test_node_id}`
-{/for}
-{/if}
-
-### Lint — `uv run ruff check .`
-
-{✅ clean | ❌ {N} errors — see log}
-
-### Type check — `uv run mypy switchyard`
-
-{✅ clean | ❌ {N} errors — see log | ⏭ skipped}
-
----
-
-<sub>Generated by `run-pre-merge-checks` skill · log: `{log_path}`</sub>
-```
-
-Notes for filling in:
-- `{dirty_marker}` is `+dirty` if `git status --porcelain` had any output, otherwise empty.
-- `{date_iso}` is `date -u +"%Y-%m-%dT%H:%MZ"`.
-- `{wall_time}` is the `in 142.44s` portion of the pytest summary, formatted as `2m 22s` or `38s`.
-- `{n_collected}` comes from the pytest `collected N items` line; `{n_not_run} = n_collected − (passed + failed + skipped + errors)`.
-- The top-level `Status` is:
- - `⛔ FAIL — INCOMPLETE` if `n_not_run > 0` (--maxfail was hit). This is the worst signal — surface it loudly.
- - `❌ FAIL` if pytest, ruff, or mypy returned non-zero but every collected test ran.
- - `✅ PASS` only when every gate is green AND every collected test ran.
-- The "Not run" table row and the warning callout are omitted entirely when `n_not_run == 0` (don't render empty rows).
-- The "Failed tests" section is omitted entirely when `n_failed == 0`.
-- The mypy row is omitted entirely when `also_typecheck=false` (don't render `⏭ skipped` unless the user explicitly asked for typecheck and we couldn't run it).
-
-### Step 7: After the summary
-
-Below the Markdown block, in plain text (one short paragraph), tell the user:
-1. Where the full log is (`/tmp/pre-merge-checks/...`).
-2. If anything failed, the most likely failure mode based on the failed test names — see "Failure triage" below.
-3. Nothing else. No "let me know" / "should I retry" / "anything else" — the user knows what to do next.
-
-## Failure triage
-
-When a test fails, surface the right next step instead of dumping the full traceback into chat. Common patterns:
-
-| Failure pattern | Likely cause | What to tell the user |
-|-----------------|--------------|------------------------|
-| `pytest.skip("NVIDIA API key not found...")` on every test | Credentials not picked up despite Step 1 passing | Confirm `secrets/secrets.json` has a `nvidia` section with `api_key` *and* `base_url` *and* `model`. Env var alone is not enough — fixtures also need the model name. |
-| `passthrough server failed to start within 60s` | Subprocess crashed before binding the port | Tail the captured stderr from the test output; usually a `ModuleNotFoundError` (stale install) or a port conflict. Suggest `uv sync --dev` then retry. |
-| `httpx.HTTPStatusError: 401` from any test | API key valid but rejected by NVIDIA hub | Either the key was revoked, or the `base_url` in `secrets/secrets.json` doesn't match the key's tenant. |
-| `assert response.choices[0].message.content` is empty | Upstream model returned empty body — flaky inference, not a code bug | Suggest re-running just that test (`pytest <node_id> -v`); if it reproduces twice, dig in. |
-| `test_verify_e2e.py::TestVerifyClaudeE2E` skipped | `claude` CLI not installed in this env | Expected. Not a failure. Mention this in the plain-text addendum so the user knows skips ≠ regressions. |
-| Anthropic translation tests fail with `KeyError: 'role'` or similar | Bug in `foundation/translation/anthropic_openai.py` from the user's diff | Surface the failed test names; this is a real bug to fix. |
-| `RuntimeError: Event loop is closed` | Pytest-asyncio teardown race with subprocess fixture | Re-run; if it persists, file an issue. Not a real failure of the user's code. |
-
-## Iteration helpers
-
-If the user says "run again, just the failed ones":
-```bash
-uv run pytest --lf -v
-```
-
-If the user says "run with print output":
-```bash
-uv run pytest tests/e2e/ -v -s
-```
-
-If the user asks why a particular test failed (after a failed run):
-```bash
-grep -A 60 "FAILED {test_node_id}" "$LOG"
-```
-
-## Boundaries
-
-### Always do
-
-- Treat `tests/e2e/` as the canonical live pre-merge gate. If the user wants something narrower, accept a `test_path` override but still default to the full suite.
-- Block the run on missing credentials. Don't proceed to pytest if `NVIDIA_API_KEY` and `secrets/secrets.json` are both absent — pytest will skip *every* test, producing a misleading green summary.
-- Run `ruff check .` alongside the tests by default. CI runs it and the user will catch lint failures here before push.
-- Output the summary as a single self-contained Markdown block so the user can screenshot it without editing.
-
-### Ask first
-
-- Running anything more expensive than this skill, such as the full benchmark suite or ad hoc live provider suites outside `tests/e2e/`.
-- Modifying `secrets/secrets.json`, even to fill in obvious defaults — it's gitignored for a reason.
-
-### Never do
-
-- Run broader live or benchmark suites by default — those may need different credentials and take much longer.
-- Suppress test failures or downgrade the summary to "PASS" because the failures look "minor." If pytest's exit code is non-zero, the summary says FAIL.
-- Commit, push, or open a PR from inside this skill. The user explicitly invokes this *to inform their MR*; the MR ceremony is theirs.
diff --git a/.agents/skills/rust-code-reviewer/SKILL.md b/.agents/skills/rust-code-reviewer/SKILL.md
deleted file mode 100644
index 694972449..000000000
--- a/.agents/skills/rust-code-reviewer/SKILL.md
+++ /dev/null
@@ -1,128 +0,0 @@
----
-name: "rust-code-reviewer"
-description: "Use this agent for a strict Rust code review. Embodies systems-level review patterns and the design-craft principles from the actionbook/rust-skills curriculum. Particularly useful for reviewing Rust code, systems-level changes, and code touching the switchyard core, translation, components, or Python/Rust FFI crates."
----
-
-You are a senior systems engineer reviewing Rust code. Apply everything below strictly. You are an exacting reviewer who expects the very highest standards of code quality.
-
-For switchyard, this skill is most appropriate for these areas. Be strict if the code touches these. Outside these areas, lean toward suggestions rather than blocking issues:
-- `crates/switchyard-core/`
-- `crates/switchyard-translation/`
-- `crates/switchyard-components/`
-- `crates/switchyard-server/`
-- `crates/switchyard-py/` — Python/Rust FFI surface
-
-## Core Review Philosophy
-
-- **Simplicity over cleverness**: Flag over-engineered abstractions. Prefer straightforward, readable code.
-- **Concise, optimized code**: Minimal ceremony, minimal docstrings. Question verbose documentation.
-- **Systems-level thinking**: Consider memory allocation, async runtime behavior, lock contention, and latency.
-- **Design before fix**: When you spot a smell, ask the design question behind it ("who should own this?", "is this failure expected?") before reaching for the mechanical patch. The deeper references in this skill follow this pattern.
-- **Rust idioms**: Favor `Result`-based error handling with `anyhow`/`thiserror` as used in the project. Watch for unnecessary `clone()`, `unwrap()` in non-test code, and needless `Arc`/`Mutex`.
-- **Correctness in concurrent code**: Scrutinize `tokio`, channels, cancellation, and shared state carefully.
-- **Clear, direct naming**: Flag vague names; prefer short, precise identifiers.
-- **Minimal diff surface**: Call out unrelated changes mixed into a PR.
-- **Logging and observability**: Ensure `tracing` spans/events are meaningful, not noisy.
-
-Use this tone: direct, concise, technically grounded, occasionally pointed but never hostile. Avoid filler praise. Most review comments should be one or two lines long.
-
-## How to review
-
-Unless explicitly told otherwise, review **only the recently written/modified code** — not the entire codebase. Use `git diff`, `git log`, or ask for the specific files/PR if unclear.
-
-1. **Identify the review target** with `git status`, `git diff --stat`, and `git diff`.
-
-2. **Dispatch by diff signal** (see [`references/dispatch.md`](references/dispatch.md)). The diff tells you which deeper review lens applies — open the matching `references/*.md` file and read it before the relevant pass. For theoretical depth, the matching `m01`–`m15` skill from the actionbook curriculum is available as a Skill tool invocation.
-
-3. **Loop**: Use the philosophy, rules, and rubrics in this file and the loaded references to find issues. Repeat — multiple passes over the code, keep finding issues and style comments until you cannot find any more.
-
-4. **Write the review**:
- - Prefer concrete `file:line` findings over general advice.
- - Group issues by severity (Blocking / Important / Style). Include all findings including style comments.
-
-## Universal review rules
-
-Apply these on every pass over the changed code. These are the project-wide non-negotiables; deeper craft sits in [`references/`](references/).
-
-1. **No `unwrap()` / `expect()` in production code.** If unavoidable, explain why it cannot fail. Per switchyard AGENTS.md, `.expect()` is banned even in Rust tests — propagate errors with `?`, return typed errors, or match explicitly.
-2. **`tracing` crate, never `log`.** The interface is subtly different. Delete `use tracing as log;` because that is confusing.
-3. **Structured tracing fields, not formatted strings.** Example: `tracing::error!(error = %e, backend, "failed to translate response")` beats `error!("failed to translate response from {}: {}", backend, e)`. Use `%` for `to_string()`, `?` for `Debug`.
-4. **Right log level.** `info!` is for logs we think end-users will want to see. Routine internal events should be `debug!`. Hot paths are `trace!` or remove. Logging is relatively expensive — it takes a lock on the output channel.
-5. **Don't add `Arc<Mutex<…>>` reflexively.** As long as we are not doing concurrent work on multiple threads, we shouldn't need to synchronize. We rarely need both `Arc` and `Box` because they are both pointers; if both are used there should be a comment justifying it. Owners decide their own synchronization — don't pre-wrap shared state in a constructor. See [`references/smart-pointers.md`](references/smart-pointers.md) and [`references/async-and-concurrency.md`](references/async-and-concurrency.md).
-6. **Don't wrap `Clone` types in another `Arc`.** Cheaply-cloneable handle types are designed to be cloned directly.
-7. **Drop unnecessary `.clone()`.** This reduces memory copies. Can we pass a reference, move it, or make it `Copy` instead? `Copy` types don't need `.clone()`. See [`references/ownership-and-borrowing.md`](references/ownership-and-borrowing.md).
-8. **Prefer `parking_lot::RwLock` over `tokio::sync::RwLock`** for short critical sections when no `.await` is held across the lock. It is faster and fairer.
-9. **`Drop` for cleanup, not manual unlock paths.** RAII over ad-hoc cleanup. See [`references/resource-lifecycle.md`](references/resource-lifecycle.md).
-10. **Prefer stdlib/tokio primitives over new dependencies.** Avoid new dependencies if possible.
-11. **Don't change error messages or interfaces just for taste** — but rename when the name actively misleads (`serve` implies a long-running server, `Manager`/`Handler` are too generic to convey responsibility, etc.).
-12. **Call out scope creep.** A PR should do one thing well. Example: "We should focus this PR, it's a bit of a mixture of things." Example 2: "This part seems unrelated to the rest of the PR."
-13. **Async Rust focus**: For async Rust, pay extra attention to locks held across `.await`, blocking work on executor threads, spawned task shutdown/error handling, cancellation behavior, and channel backpressure. See [`references/async-and-concurrency.md`](references/async-and-concurrency.md).
-14. **Stack vs heap allocation**: Avoid unnecessary heap allocation on all paths. See [`references/performance.md`](references/performance.md).
-
-## Comment hygiene
-
-See [`references/naming-and-comments.md`](references/naming-and-comments.md) for the full catalog. Highlights:
-
-- If a comment repeats the code or the function name, it should be deleted.
-- Don't put history in comments — that's what `git` is for.
-- AI-generated comments are a smell. AI loves overly obvious comments. Encourage the author to review their PR comments, delete the verbose/obvious ones, and rephrase others to be more helpful.
-- AI-generated tests are a smell. AI often adds too many specific tests. Encourage the author to reduce to the three most important ones. Tests should cover *behavior*, not exhaustively enumerate inputs.
-- Triple-slash `///` is documentation; double-slash `//` is internal. Don't mix in the same file unintentionally.
-- Copyright header at the top: we only need the two SPDX lines. Anything beyond is noise and should be trimmed.
-
-## Concurrency / async patterns
-
-See [`references/async-and-concurrency.md`](references/async-and-concurrency.md) for the full lens. Quick rules:
-
-- When using `sleep`, write the tokio version as fully qualified `tokio::time::sleep`, and write the stdlib version as plain `sleep` with `use std::thread::sleep`. This helps differentiate them.
-- Question `Unbounded*` channels — they can OOM the server. Tolerate them with a justification. Bounded channels are **defense-in-depth**, not sized for the happy path.
-- Question `tokio::spawn` — sometimes the work belongs inline. Don't spawn for the sake of it.
-
-## Naming
-
-See [`references/naming-and-comments.md`](references/naming-and-comments.md). Quick rules:
-
-- Names should not imply more than they do. Example 1: "`serve` makes me think of a server, like an HTTP server for example, so I expect a long-running thread." Example 2: "This doesn't do DNS resolution, but the name implies it does."
-- Boolean variables and functions should be prefixed with `is_`/`needs_`/`has_` to make truthy meaning obvious. Example: `fn is_streaming(req: &ChatRequest) -> bool` not `fn streaming(req: &ChatRequest) -> bool`.
-- `mod.rs` is an older convention. Prefer using a file with the same name as the module at the parent level. Example: for a `name/` module use `name.rs` at the parent level instead of `mod.rs`.
-- Don't preserve underscore prefixes on variables that *are* used. `_text` → `text`.
-
-## Switchyard-specific concerns
-
-- **PyO3 FFI boundary (`crates/switchyard-py/`)**: never let a Rust panic cross into Python — convert errors to `PyErr` (e.g. `PyValueError`) at the boundary. Watch for `unwrap`/`expect`/`panic!` inside `#[pyfunction]`/`#[pymethods]`. Mind GIL hold time around `.await` and avoid blocking the executor with `Python<'_>` held.
-- **Streaming translation (`crates/switchyard-translation/`)**: SSE event ordering, stream termination (`[DONE]` / `message_stop`), and partial-chunk handling matter. Flag any codec change that drops fields, reorders events, or loses error frames.
-- **Format parity**: Rust backends/translators must stay byte-for-byte compatible with the Python implementation they shadow. If a translator is added or modified, expect parity coverage under `crates/*/tests/` and call it out when missing.
-- **Roles and chain shape**: in Rust, `LlmBackend` is the shared backend trait; request-side and response-side processors are concrete components with inherent async methods. Translation is a separate crate. Reject changes that quietly broaden a backend's responsibility, skip a stage, or smuggle translation logic into a backend/processor.
-
-## Tests
-
-- **Behavior coverage > line coverage.** Ask whether the new logic is exercised, not whether the diff is touched.
-- Be skeptical of long lists of similar test cases (especially AI-added) — push for the 3 most important ones.
-- Rust tests must not use `.expect()` — match explicitly or use `?` so failures stay intentional and visible.
-- For translator/codec changes, expect adversarial or parity tests under `crates/*/tests/` rather than only happy-path coverage.
-
-## References (deep-dive lenses)
-
-These are not summaries to read top-to-bottom every review. They are lenses — open the file when the matching diff signal appears.
-
-| Reference | Open when the diff touches… | Companion skill |
-|-----------|------------------------------|-----------------|
-| [`dispatch.md`](references/dispatch.md) | Anything — this is the routing table | — |
-| [`ownership-and-borrowing.md`](references/ownership-and-borrowing.md) | `.clone()`, lifetimes, moves, `&mut` patterns | `/m01-ownership` |
-| [`smart-pointers.md`](references/smart-pointers.md) | `Box`, `Rc`, `Arc`, `Weak`, `RefCell`, `Cell` | `/m02-resource` |
-| [`mutability.md`](references/mutability.md) | `RefCell`, `Cell`, `Mutex`, interior mutability, `&mut self` | `/m03-mutability` |
-| [`generics-and-dispatch.md`](references/generics-and-dispatch.md) | `impl Trait`, `dyn Trait`, `Box<dyn …>`, generics, trait bounds | `/m04-zero-cost` |
-| [`type-driven-design.md`](references/type-driven-design.md) | `PhantomData`, marker traits, newtypes, builder patterns, type-state | `/m05-type-driven` |
-| [`error-handling.md`](references/error-handling.md) | `Result`, `Option`, `?`, `unwrap`, `expect`, `anyhow`, `thiserror`, custom errors | `/m06-error-handling` |
-| [`async-and-concurrency.md`](references/async-and-concurrency.md) | `async`/`await`, `tokio::spawn`, channels, `Mutex`, `Send`/`Sync` | `/m07-concurrency` |
-| [`performance.md`](references/performance.md) | Hot paths, allocation, `Vec`/`HashMap` sizing, benchmarks, profiling | `/m10-performance` |
-| [`resource-lifecycle.md`](references/resource-lifecycle.md) | `Drop`, `OnceCell`/`OnceLock`/`Lazy`, connection pools, scope guards | `/m12-lifecycle` |
-| [`domain-error-resilience.md`](references/domain-error-resilience.md) | Retry, backoff, circuit breaker, fallback, recovery strategy | `/m13-domain-error` |
-| [`anti-patterns.md`](references/anti-patterns.md) | Whenever something feels off — quick catalog of smells → refactors | `/m15-anti-pattern` |
-| [`naming-and-comments.md`](references/naming-and-comments.md) | Comments, doc strings, identifier names, module layout | `/coding-guidelines` |
-
-## Second pass checklist
-
-VERY IMPORTANT: Before finalizing findings, make one more focused pass over each changed hunk for all the universal rules above, and for each reference whose signal fired during the diff. Don't skip the loop — second-pass findings are often where the design issues live.
-
-ALWAYS REPORT ALL FINDINGS.
diff --git a/.agents/skills/rust-code-reviewer/references/anti-patterns.md b/.agents/skills/rust-code-reviewer/references/anti-patterns.md
deleted file mode 100644
index bbeec52b7..000000000
--- a/.agents/skills/rust-code-reviewer/references/anti-patterns.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Anti-pattern catalog
-
-**Open when**: you sense something is off and want a quick smell-to-refactor lookup.
-
-**Companion skill**: `/m15-anti-pattern`.
-
-This is the dictionary view. Each row is a smell → likely cause → suggested fix → deeper reference.
-
-## The top offenders
-
-### 1. `.clone()` everywhere
-- **Cause**: fighting the borrow checker, ownership model never decided.
-- **Fix**: pass references, redesign the function signature, use `Arc` for shared ownership, use `Cow` for sometimes-borrow-sometimes-own.
-- **See**: [`ownership-and-borrowing.md`](ownership-and-borrowing.md).
-
-### 2. `.unwrap()` / `.expect()` in production
-- **Cause**: author punted on the failure case.
-- **Fix**: propagate with `?`, return a typed error, or prove non-failure in the type system (`if let`, exhaustive match).
-- **See**: [`error-handling.md`](error-handling.md).
-
-### 3. `Arc<Mutex<…>>` reflex
-- **Cause**: "we might share this" defensive wrapping at construction time.
-- **Fix**: let callers wrap when they actually share. Or redesign to message passing.
-- **See**: [`smart-pointers.md`](smart-pointers.md), [`async-and-concurrency.md`](async-and-concurrency.md).
-
-### 4. Lock held across `.await`
-- **Cause**: forgot the executor is single-threaded per task.
-- **Fix**: drop the guard in a scope before the await.
-- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
-
-### 5. Stringly-typed everything
-- **Cause**: `String` is easy, types are work.
-- **Fix**: newtype with a `parse` boundary so the rest of the code can't pass garbage.
-- **See**: [`type-driven-design.md`](type-driven-design.md).
-
-### 6. Booleans where an enum belongs
-- **Cause**: started with two states, never refactored when a third appeared.
-- **Fix**: enum.
-- **See**: [`type-driven-design.md`](type-driven-design.md).
-
-### 7. Unbounded channel
-- **Cause**: easier than picking a number.
-- **Fix**: pick a number. The number is wrong, you'll learn the right one. Unbounded is OOM-shaped.
-- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
-
-### 8. Reflexive `tokio::spawn`
-- **Cause**: "async means spawn."
-- **Fix**: `.await` inline unless you need concurrency. Track join handles if you do spawn.
-- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
-
-### 9. Returning `Box<dyn Trait>` for a single implementor
-- **Cause**: future-proofing for an unrealized abstraction.
-- **Fix**: return the concrete type or `impl Trait` until a second implementor appears.
-- **See**: [`generics-and-dispatch.md`](generics-and-dispatch.md).
-
-### 10. Hand-rolled cleanup
-- **Cause**: didn't know `Drop` existed or didn't want to bother.
-- **Fix**: `impl Drop`. RAII saves the error paths you forgot about.
-- **See**: [`resource-lifecycle.md`](resource-lifecycle.md).
-
-### 11. Retry on every error
-- **Cause**: didn't distinguish transient from permanent.
-- **Fix**: split the error type so retry can match on category.
-- **See**: [`domain-error-resilience.md`](domain-error-resilience.md).
-
-### 12. `lazy_static!` in new code
-- **Cause**: copy-pasted from old code.
-- **Fix**: `OnceLock` (std) or `Lazy::new` (once_cell).
-- **See**: [`resource-lifecycle.md`](resource-lifecycle.md).
-
-### 13. `LinkedList`
-- **Cause**: muscle memory from another language.
-- **Fix**: `Vec` or `VecDeque`.
-- **See**: [`performance.md`](performance.md).
-
-### 14. `&mut self` that only reads
-- **Cause**: copy-pasted method signature.
-- **Fix**: `&self`. Stops forcing exclusive borrows on callers.
-- **See**: [`mutability.md`](mutability.md).
-
-### 15. Re-implementing standard combinators
-- **Cause**: didn't know the method existed.
-- **Fix**: `map`, `and_then`, `unwrap_or_else`, `ok_or_else`, `if let Some`, `let-else`. Read `Option`/`Result` docs.
-
-### 16. Long lists of similar tests (especially AI-added)
-- **Cause**: AI loves enumeration.
-- **Fix**: keep the 3 that cover distinct behaviors. Delete the rest. Coverage is about behaviors, not inputs.
-
-### 17. Comments restating the function name
-- **Cause**: AI tax or formality-by-default.
-- **Fix**: delete. If the name doesn't say it, fix the name, don't paper over with a comment.
-- **See**: [`naming-and-comments.md`](naming-and-comments.md).
-
-### 18. "Just use `String` for now"
-- **Cause**: deferred modeling.
-- **Fix**: model now or write down explicitly that the type is intentionally loose and why.
-
-### 19. `match e.to_string().contains("…")`
-- **Cause**: error type is opaque, downstream needs to decide.
-- **Fix**: expose the variant. String-matching errors is fragile.
-- **See**: [`error-handling.md`](error-handling.md), [`domain-error-resilience.md`](domain-error-resilience.md).
-
-### 20. Big god struct with `Arc<Mutex<…>>` on every field
-- **Cause**: no decomposition.
-- **Fix**: split into smaller types with clear ownership. The locks usually disappear with the split.
-- **See**: [`smart-pointers.md`](smart-pointers.md), [`mutability.md`](mutability.md).
-
-## How to use this list
-
-Treat it as a fast scan during your second pass. When you spot a row, jump to the referenced file for the full review checklist. Don't quote this catalog at the author — translate to a `file:line` comment with the specific fix.
diff --git a/.agents/skills/rust-code-reviewer/references/async-and-concurrency.md b/.agents/skills/rust-code-reviewer/references/async-and-concurrency.md
deleted file mode 100644
index e170ee2ba..000000000
--- a/.agents/skills/rust-code-reviewer/references/async-and-concurrency.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Async & concurrency review
-
-**Open when the diff has**: `async fn`, `.await`, `tokio::`, `spawn`, channels (`mpsc`, `oneshot`, `broadcast`, `watch`), `Mutex`/`RwLock`, `Send`/`Sync` bounds, or shared state across tasks.
-
-**Companion skill**: `/m07-concurrency`.
-
-## The design question
-
-**CPU-bound or I/O-bound, and what's the sharing model?** Async (`tokio`) is for I/O concurrency. Threads (`std::thread`, `rayon`) are for CPU parallelism. Mixing them up — running `rayon` work on a `tokio` runtime, calling blocking I/O from an async fn — is the source of most "the server hangs" bugs.
-
-## Red flags
-
-### 1. Lock held across `.await`
-```rust
-// Smell
-let guard = state.lock().await;
-let resp = http.get(url).send().await?; // guard held — blocks all other tasks
-guard.update(resp);
-```
-The whole point of async is concurrent I/O. A lock across `.await` serializes everyone. Fix by dropping the guard before awaiting:
-```rust
-let snapshot = {
- let guard = state.lock().await;
- guard.snapshot()
-};
-let resp = http.get(url).send().await?;
-state.lock().await.update(resp);
-```
-For `std::sync::Mutex` / `parking_lot::Mutex`, the guard is `!Send` and the code won't even compile in most cases — but `tokio::sync::Mutex` lets it compile and bite you at runtime.
-
-### 2. Blocking work on the executor thread
-- `std::thread::sleep` inside an `async fn` — should be `tokio::time::sleep`.
-- `std::fs::read_to_string` in async code — use `tokio::fs` or `tokio::task::spawn_blocking`.
-- CPU-heavy work without `spawn_blocking` — starves the runtime.
-
-Convention from the main SKILL.md: write `tokio::time::sleep` fully qualified, and stdlib `sleep` with `use std::thread::sleep;` to make the distinction obvious at a glance.
-
-### 3. `tokio::spawn` for the sake of it
-Not every task belongs in a separate task. Spawning has overhead (scheduling, allocation, potential for orphaned work) and complicates error propagation. Reflexive spawning is a smell. Ask:
-- Does this work need to run concurrently with the caller? If not, just `.await` it.
-- Is the spawned task awaited or `join_handle.abort()`-on-drop'd? Orphaned spawns leak.
-- Does it propagate errors back? If the spawn returns `Result` and nothing reads the `JoinHandle`, errors are silently dropped.
-
-### 4. Unbounded channels
-```rust
-// Smell
-let (tx, rx) = mpsc::unbounded_channel();
-```
-Unbounded channels can OOM the process. Producers don't block, so the queue grows until the box dies. **Bounded channels are defense-in-depth** — `mpsc::channel(N)` with a reasonable `N` for your domain. If the bound is hit, you learn something is wrong. Unbounded only with a justification (explicit comment) that the producer side is provably finite.
-
-### 5. `Arc<Mutex<…>>` as a substitute for message passing
-The "share state with a mutex" pattern often loses to "give one task the state and send it messages." When the lock-contended state is on the hot path, an actor-style design (`mpsc::Sender<Command>`) is faster and easier to reason about.
-
-### 6. `tokio::select!` arms that aren't cancel-safe
-`select!` cancels the losing futures. If one arm has side effects (e.g. partially read from a stream), it may corrupt state on cancellation. Use cancellation-safe APIs (`tokio::io::AsyncReadExt::read_buf` is, `read_exact` is not — read the tokio docs for each). Comment when non-trivial.
-
-### 7. `Send` + `Sync` bound proliferation
-If every function signature has `T: Send + Sync + 'static`, you've effectively made the whole codebase global. Sometimes the right answer is to keep the data on one task and avoid the share entirely.
-
-### 8. Spawned tasks with no shutdown story
-Long-running tasks (poll loops, watchdogs) spawned via `tokio::spawn` need a cancellation token, a shutdown channel, or to be tied to a `JoinSet` that the owner drops. Otherwise they outlive the system that created them.
-
-### 9. `block_on` inside an async context
-Calling `Runtime::block_on` from inside a `tokio::spawn`'d task or any async fn deadlocks or panics. Always a bug.
-
-### 10. `parking_lot::RwLock` vs `tokio::sync::RwLock`
-Default to `parking_lot::RwLock` for short critical sections (no `.await` inside) — it's faster and fairer. Reach for `tokio::sync::RwLock` only when you genuinely need to hold the lock across `.await`.
-
-## Acceptable cases
-
-- A `tokio::sync::Mutex` held across `.await` on a strict serialization boundary (e.g. one HTTP client per upstream) where serializing is the point.
-- `Arc<Mutex<HashMap<…>>>` for a small read/write cache where the contention is bounded and measured.
-- `tokio::spawn` for long-running independent work *with* a documented shutdown path.
-
-## Comment templates
-
-- "`MutexGuard` held across `.await` on line N. Drop it in a scope first."
-- "`std::thread::sleep` inside an async fn — `tokio::time::sleep`."
-- "Unbounded channel — what bounds the producer? If nothing, this is an OOM waiting to happen."
-- "Spawning here but nothing awaits the `JoinHandle` — errors will be lost."
-- "`tokio::sync::RwLock` for a short read with no await — `parking_lot::RwLock` is faster and fairer."
-- "`select!` arm is not cancel-safe — `read_exact` will lose bytes on cancellation."
-
-## Trace up
-
-If the concurrency model is unclear ("who owns this state? who runs this code?"), the fix isn't a different lock — it's a clearer task structure. Pair this review with `/m09-domain` for the modeling angle and `/m12-lifecycle` for the cleanup angle.
diff --git a/.agents/skills/rust-code-reviewer/references/dispatch.md b/.agents/skills/rust-code-reviewer/references/dispatch.md
deleted file mode 100644
index b63fbe704..000000000
--- a/.agents/skills/rust-code-reviewer/references/dispatch.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Dispatch: diff signal → which lens
-
-Use this table on the first pass. `grep` the diff (`git diff`) for the listed signals, then read the matching reference. If the signal fires for code you don't fully grasp at the design level, also invoke the companion `/m*-*` skill — it gives the cognitive framing for the same area.
-
-The references are review checklists (concrete smells, before/after). The `m*-*` skills are design-craft pedagogy. Read the reference first; invoke the skill when you need the "why" to write a useful comment.
-
-## Quick-scan greps
-
-Run these against the diff first. Each hit suggests one or more lenses.
-
-| `git diff` pattern | Likely lens(es) |
-|---|---|
-| `\.clone()` | `ownership-and-borrowing` → `performance` |
-| `\.unwrap()`, `\.expect(` | `error-handling` |
-| `panic!`, `todo!`, `unimplemented!` | `error-handling` |
-| `Arc<`, `Rc<`, `Box<`, `Weak<` | `smart-pointers` → `async-and-concurrency` if `Arc<Mutex<…>>` |
-| `RefCell`, `Cell`, `\.borrow_mut\(` | `mutability` |
-| `Mutex`, `RwLock` | `async-and-concurrency` → `mutability` |
-| `async fn`, `\.await`, `tokio::`, `#\[tokio::` | `async-and-concurrency` |
-| `tokio::spawn`, `task::spawn` | `async-and-concurrency` |
-| `unbounded_channel`, `mpsc::unbounded`, `crossbeam_channel::unbounded` | `async-and-concurrency` |
-| `dyn `, `impl Trait`, `Box<dyn ` | `generics-and-dispatch` |
-| `PhantomData`, `marker::` | `type-driven-design` |
-| `lazy_static!`, `OnceCell`, `OnceLock`, `Lazy::new` | `resource-lifecycle` |
-| `impl Drop for`, `drop(` | `resource-lifecycle` |
-| `retry`, `backoff`, `circuit`, `with_retry`, `tokio::time::sleep` in a loop | `domain-error-resilience` |
-| `Vec::new()` near `\.push(` in a loop, `String::new()` near `+= ` | `performance` |
-| `for .* in 0\.\.` over a collection (vs `.iter()`) | `performance` |
-| `pub fn (get_|set_)` | `naming-and-comments` |
-| Triple-slash docs on private items, doc paragraphs that restate the fn name | `naming-and-comments` |
-| `mod.rs` added | `naming-and-comments` |
-| `unsafe`, `transmute`, `*mut`, `*const`, `extern "C"` | invoke `/unsafe-checker` skill |
-| `#[pyfunction]`, `#[pymethods]`, `Python<'_>`, `PyResult` | switchyard PyO3 section in main `SKILL.md` |
-| Files under `crates/switchyard-translation/` | switchyard translation section in main `SKILL.md` |
-
-## Decision flow
-
-1. **Run the greps above** against `git diff`. Each hit adds a lens to your pass list.
-2. **Read each lens's reference** before doing its pass — they're short and signal-specific.
-3. **For design-level concerns**, invoke the matching `/m*-*` skill. Use these especially when:
- - You can't articulate *why* a pattern is bad, just that it feels off.
- - The author may push back — the m-skill gives you the design argument, not just the rule.
- - The smell points up a layer: a `Arc<Mutex<…>>` everywhere isn't a synchronization bug, it's a domain-modeling bug (`/m09-domain`); `.clone()` everywhere isn't a perf bug, it's an ownership-design bug (`/m01-ownership`).
-
-## Anti-patterns in dispatch itself
-
-- **Don't apply every lens to every diff.** A 5-line bug fix doesn't need an ownership review.
-- **Don't skip dispatch on "small" diffs.** A 5-line diff that adds `Arc<Mutex<HashMap<…>>>` is exactly when ownership/concurrency review matters most.
-- **Don't quote the m-skill at the author.** Translate it to a `file:line` comment in their PR. The skills are for you, the reviewer.
diff --git a/.agents/skills/rust-code-reviewer/references/domain-error-resilience.md b/.agents/skills/rust-code-reviewer/references/domain-error-resilience.md
deleted file mode 100644
index 655241e5c..000000000
--- a/.agents/skills/rust-code-reviewer/references/domain-error-resilience.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Domain error & resilience review
-
-**Open when the diff has**: retry loops, backoff, circuit breakers, fallbacks, "graceful degradation," or domain-error hierarchies.
-
-**Companion skill**: `/m13-domain-error`.
-
-## The design question
-
-**Is this error transient (retry helps), permanent (retry doesn't), or a contract violation (caller's bug)?** Different categories need different responses. Treating all errors the same — retry-everything, or fail-on-anything — is the most common architectural mistake in network code.
-
-| Category | Example | Response |
-|---|---|---|
-| Transient | timeout, 503, connection reset | retry with backoff |
-| Permanent | 400, parse error, auth | surface to caller |
-| Contract | invariant violated | panic / fail loud |
-| Degraded | one upstream of N is down | fall back, log, continue |
-
-## Red flags
-
-### 1. Retry on every error
-```rust
-// Smell
-loop {
- match call().await {
- Ok(v) => return Ok(v),
- Err(_) => sleep(Duration::from_secs(1)).await,
- }
-}
-```
-This retries `BadRequest` forever. Match on the error variant and only retry the transient ones (timeouts, 5xx, connection drops).
-
-### 2. Fixed-interval retry
-Sleeping `1s` between retries hammers an upstream that's already struggling. Use exponential backoff with jitter (`tokio::time::sleep` over `2^n + rand`). The `backon` or `tokio-retry` crates do this; rolling your own is fine if simple.
-
-### 3. Retry with no max attempts / no max duration
-Infinite retry hides bugs. Cap at N attempts *and* a total deadline. The deadline matters more — N attempts at exponential backoff can sleep for hours.
-
-### 4. No circuit breaker on a high-volume dependency
-If you're calling a flaky upstream at 1k/s, retry amplifies its problem (retry storm). A circuit breaker (`tower::limit`, `failsafe`, hand-rolled) opens after a failure threshold and short-circuits subsequent calls — protects both you and the upstream.
-
-### 5. Fallback that silently degrades
-```rust
-let result = primary().await.unwrap_or_else(|_| secondary());
-```
-No log, no metric, no signal. Operators have no idea the primary is failing. Always log/meter the fallback path with `tracing::warn!` and a counter.
-
-### 6. Retry inside a request handler with no deadline
-Web handler that retries 5× × 1s each = 5s p99. Set a request-wide timeout (`tokio::time::timeout`) above the retry loop, so the user gets a 504 instead of a connection that hangs.
-
-### 7. Error type that doesn't distinguish categories
-```rust
-// Smell — caller can't decide whether to retry
-enum BackendError { Failed(String) }
-
-// Better
-enum BackendError {
- Transient { source: anyhow::Error }, // worth retrying
- Permanent { status: u16, body: String }, // do not retry
- InvalidRequest(String), // caller bug
-}
-```
-The error type is the API contract for failure. If it can't drive the retry decision, the retry decision will be wrong somewhere.
-
-### 8. `match` on string error messages
-`if e.to_string().contains("timeout") { … }` is fragile and breaks the moment the upstream changes wording. Match on the typed variant or status code.
-
-### 9. Catching too broadly
-`Result<T, Box<dyn Error>>` in a retry decision means you can't see what failed. The retry layer should see a typed error.
-
-## Acceptable cases
-
-- A single retry on a known-transient operation with a small fixed delay — readable inline code beats pulling in a retry crate.
-- Best-effort writes (analytics, telemetry) where loss is acceptable — but log and meter the drop.
-- Panic on a contract violation discovered at runtime (programmer bug). That's `panic!`'s job.
-
-## Comment templates
-
-- "Retrying every error variant — this retries `BadRequest` forever. Match on the kind first."
-- "Fixed `sleep(1s)` between retries — add exponential backoff + jitter."
-- "No max attempts → infinite retry on a permanent failure. Cap it and add a deadline."
-- "Fallback path is silent — log and meter, otherwise we won't notice degradation."
-- "`BackendError::Failed(String)` can't drive a retry decision. Split into `Transient`/`Permanent`/`InvalidRequest`."
-
-## Trace up
-
-Resilience patterns belong in the domain, not in a generic util. Where you put the retry/fallback/circuit decides what gets protected and what doesn't. That's an architectural question (`/m09-domain`). Don't accept a "wrap everything in a retry helper" PR without asking what the failure boundaries actually are.
diff --git a/.agents/skills/rust-code-reviewer/references/error-handling.md b/.agents/skills/rust-code-reviewer/references/error-handling.md
deleted file mode 100644
index 999a2c73e..000000000
--- a/.agents/skills/rust-code-reviewer/references/error-handling.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Error handling review
-
-**Open when the diff has**: `Result`, `Option`, `?`, `unwrap`, `expect`, `panic!`, `anyhow`, `thiserror`, custom error enums, or error conversions.
-
-**Companion skill**: `/m06-error-handling`.
-
-## The design question
-
-**Is this failure expected, absent, a bug, or unrecoverable?** Each maps to a different tool. Mixing them is how you end up with `.unwrap()` on user input and `Result<…, String>` deep in a library.
-
-| Failure kind | Tool |
-|---|---|
-| Expected (I/O, parse, network) | `Result<T, E>` with typed `E` |
-| Absence (lookup, optional) | `Option<T>` |
-| Programmer bug (broken invariant) | `panic!` / `assert!` |
-| Unrecoverable (OOM, corrupted state) | `panic!` or process exit |
-
-Library vs application:
-- **Library code**: typed errors with `thiserror`, so callers can match.
-- **Application/binary code**: `anyhow::Error` with `.context()` for the call chain.
-
-## Red flags
-
-### 1. `.unwrap()` / `.expect()` in production code
-Switchyard project rule: forbidden, including in Rust tests. Propagate with `?`, return typed errors, or `match` explicitly. If you see `.unwrap()` and the author argues "it can't fail," ask them to encode that in the type system (`if let`, exhaustive `match`, type-state) so the compiler proves it.
-
-Common exceptions worth challenging:
-- `.unwrap()` after a `is_some()` check — use `if let Some(x)` or `match` instead.
-- `.unwrap()` on regex compilation of a literal at startup — replace with `OnceLock` + return-`Result` constructor, or use `regex_static`.
-
-### 2. `panic!` for recoverable failures
-Network timeout, bad JSON, missing config — none of these are programmer bugs. They're expected runtime conditions and belong in `Result`. `panic!` is for "this should never happen and if it did the program is in a state we can't reason about."
-
-### 3. `Result<T, String>` or `Result<T, Box<dyn Error>>` in a library
-Strings are unmatchable; `Box<dyn Error>` discards type information. For a library, define a `thiserror` enum so downstream code can match on variants.
-
-### 4. Swallowed errors
-```rust
-// Smell
-let _ = some_fallible_op();
-some_op().ok();
-match res { Ok(v) => v, Err(_) => default } // why default? what error?
-```
-Ignoring errors silently is rarely correct. At minimum log them with `tracing::warn!` or `tracing::error!` with structured fields. Better: handle them, or propagate.
-
-### 5. `?` followed by `.unwrap()` immediately
-Inconsistent: you decided one was recoverable, then the next isn't. Re-examine.
-
-### 6. Lossy error conversion
-`.map_err(|_| MyError::Generic)?` discards the original. Use `#[from]` (thiserror) or wrap with context: `.map_err(|e| MyError::Backend { source: e })?` or `.with_context(|| "backend call")?`.
-
-### 7. `anyhow::Error` in a public library API
-`anyhow` is the application-side ergonomic helper. Exposing it from a library forces all downstream code to depend on `anyhow` and unable to programmatically match. Use `thiserror` for the lib's error type; let the binary wrap in `anyhow` if it wants.
-
-### 8. `.context()` overload
-Every `?` having `.context("…")` adds noise. Add context at *boundaries* (function entry/exit, foreign-system calls), not on every internal line.
-
-## Acceptable cases
-
-- `unreachable!()` with a comment explaining the invariant.
-- `assert!`/`debug_assert!` for programmer-bug guards at function entry.
-- `panic!` in a `From` impl that's only used to convert a `Result` into a known-Ok path — but flag and ask if `expect_err`/`unwrap_or_else` is cleaner.
-
-## Comment templates
-
-- "`.unwrap()` here — what's the invariant that says this can't fail? Encode it in the types or propagate the error."
-- "`Result<T, String>` from a public function — callers can't match. Use a `thiserror` enum."
-- "Swallowed error on line N. Either handle it or `tracing::warn!(error = %e, …)`."
-- "`anyhow::Error` in a public lib API — switch to `thiserror`."
-
-## Trace up
-
-Repeated `.unwrap()`/`.expect()`/`panic!` in a module is rarely "a few bad lines." It's a sign the author didn't decide what failure means in this layer. That's a domain-error question — see [`domain-error-resilience.md`](domain-error-resilience.md) and `/m13-domain-error`.
diff --git a/.agents/skills/rust-code-reviewer/references/generics-and-dispatch.md b/.agents/skills/rust-code-reviewer/references/generics-and-dispatch.md
deleted file mode 100644
index b68833929..000000000
--- a/.agents/skills/rust-code-reviewer/references/generics-and-dispatch.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Generics & dispatch review
-
-**Open when the diff has**: `impl Trait`, `dyn Trait`, `Box<dyn …>`, generic functions, `where` clauses, trait bounds, or trait object collections.
-
-**Companion skill**: `/m04-zero-cost`.
-
-## The design question
-
-**Compile-time or runtime polymorphism?** Generics → monomorphization → one instantiation per concrete type → fast at runtime, slow to compile, bigger binary. Trait objects → vtable lookup → small binary, slower hot path, supports heterogeneous collections. Pick on need, not on reflex.
-
-| Need | Use |
-|---|---|
-| One concrete type at each call site, hot path | Generics (`fn foo<T: Trait>`) |
-| Heterogeneous collection (`Vec<Box<dyn Trait>>`) | Trait object |
-| Public API that wants to hide the type | `impl Trait` return |
-| Trait that must be object-safe | Avoid `Self`-receiver methods, generic methods |
-
-## Red flags
-
-### 1. `Box<dyn Trait>` for a single concrete type
-```rust
-// Smell — only one implementor in the whole project
-fn build() -> Box<dyn Backend> { Box::new(OpenAiBackend::new()) }
-```
-If there's only one implementor and no testing/mocking reason, return the concrete type or `impl Backend`.
-
-### 2. Generics with complex `where` clauses where `dyn` would suffice
-```rust
-// Smell — every call site monomorphizes 4 KB of code for no perf win
-fn log_each<T: Display + Send + Sync + 'static>(items: Vec<T>) {
- for x in items { tracing::info!(%x); }
-}
-```
-If the function isn't hot and isn't pinned by type, `&[&dyn Display]` is fine.
-
-### 3. Object-unsafe traits forced into `dyn`
-A trait with a generic method or `Self` by value isn't object-safe and `dyn Trait` won't compile. If the author started adding `where Self: Sized` workarounds, it's a signal the trait design is wrong — split the trait or stop using `dyn`.
-
-### 4. Trait bound proliferation
-```rust
-fn f<T: Clone + Send + Sync + 'static + Debug + Default + Eq>(t: T) -> T { … }
-```
-Each bound is a constraint on callers. Drop the ones the body doesn't actually need.
-
-### 5. `impl Trait` in a position that hides too much
-Returning `impl Iterator<Item = u64>` is fine for a private helper. Returning `impl Trait` from a public API where callers might want to *name* the type (store it in a struct, return it from another fn) makes them unable to. Be deliberate.
-
-### 6. `Vec<Box<dyn Trait>>` where an enum would do
-If you have a fixed, known-at-compile-time set of variants, an enum is simpler, faster, and easier to exhaustively match. `Vec<Box<dyn Trait>>` is for the open set case.
-
-## Acceptable cases
-
-- `Box<dyn Error + Send + Sync>` — standard error trait object.
-- `Arc<dyn Backend>` for runtime-chosen backends — that's exactly what `dyn` is for.
-- Generic functions with one or two bounds where the body genuinely uses each.
-- `impl Trait` in argument position (`fn f(items: impl IntoIterator<Item = u64>)`) — usually a readability win.
-
-## Comment templates
-
-- "Only one implementor — `Box<dyn Backend>` is buying us nothing. Return `OpenAiBackend` or `impl Backend`."
-- "These bounds are a wishlist. The body doesn't use `Default` or `Eq` — drop them."
-- "Returning `impl Iterator` here means downstream can't store it. Was that intentional?"
-- "Closed set of variants — this should be an enum, not `Vec<Box<dyn …>>`."
-
-## Trace up
-
-Generics-vs-trait-objects is a Layer-1 decision in service of a Layer-2 question: "what is the abstraction here, and at what boundary does it close?" If the trait keeps gaining methods or callers keep adding bounds, the abstraction is leaky — that's a design problem (`/m09-domain`), not a dispatch problem.
diff --git a/.agents/skills/rust-code-reviewer/references/mutability.md b/.agents/skills/rust-code-reviewer/references/mutability.md
deleted file mode 100644
index 98965335a..000000000
--- a/.agents/skills/rust-code-reviewer/references/mutability.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Mutability review
-
-**Open when the diff has**: `RefCell`, `Cell`, `Mutex`, `RwLock`, `&mut self`, or interior-mutability patterns.
-
-**Companion skill**: `/m03-mutability`.
-
-## The design question
-
-**Does this really need to mutate, or did the author reach for `mut` because the data model is wrong?** Interior mutability bypasses the borrow checker's compile-time guarantees and replaces them with runtime checks (`RefCell` panics) or runtime cost (`Mutex` contention). Use it when needed, never reflexively.
-
-## Red flags
-
-### 1. `RefCell` because the author "got a borrow error"
-The borrow checker complained, and the fastest fix was `RefCell`. Now you have a runtime panic landmine. Read the original code — usually the right fix was restructuring (split the struct, return a value instead of mutating, use `&mut` on a smaller scope).
-
-### 2. `Mutex` to mutate a field that's set once
-```rust
-// Smell
-struct Server { config: Mutex<Config> }
-```
-If `config` is set at construction and read forever after, it doesn't need a `Mutex`. Pass it as `Arc<Config>` (immutable share) or use `OnceCell<Config>`.
-
-### 3. `&mut self` that doesn't actually mutate
-If a method takes `&mut self` but only reads fields, change it to `&self`. The `&mut` forces exclusive access on callers for no reason.
-
-### 4. Lock held across `.await`
-This is the headline async-mutability bug. `std::sync::Mutex` held across `.await` is a soundness issue (`MutexGuard: !Send`); `parking_lot::Mutex` is the same; `tokio::sync::Mutex` is the only correct choice for that pattern. Even then, **prefer dropping the guard before awaiting**:
-```rust
-// Smell
-let mut state = mutex.lock().await;
-state.update();
-some_async_call().await; // lock held the whole time
-
-// Better
-{
- let mut state = mutex.lock().await;
- state.update();
-} // guard dropped
-some_async_call().await;
-```
-See [`async-and-concurrency.md`](async-and-concurrency.md) for the full pattern.
-
-### 5. `RwLock` where reads dominate but writes are unrelated
-If readers and writers touch different fields, you're forcing them to serialize for no reason. Split the struct so each lock guards a coherent unit.
-
-### 6. `Cell<T>` for non-`Copy` types
-`Cell` is for `Copy` types (`Cell<u64>`). For non-`Copy`, you need `RefCell`. If you see `Cell<String>` it doesn't compile — but if you see contortions to make `Cell` work, the design is fighting the tool.
-
-## Acceptable cases
-
-- `RefCell` inside a `pub`-API type where the interior mutation is genuinely an implementation detail (e.g. lazy caching).
-- `Mutex` on a field that's read and written from multiple tasks for legitimate shared state.
-- `Atomic*` for counters / flags — these are zero-overhead and `Send + Sync` for free.
-
-## Comment templates
-
-- "`&mut self` here but I only see reads — `&self` works."
-- "`RefCell` looks reactive to a borrow error. What was the original code trying to do? There's probably a structural fix."
-- "Lock held across `.await` on line N — drop the guard in a scope first."
-- "`Mutex<Config>` but it's set once. `Arc<Config>` or `OnceCell` instead."
-
-## Trace up
-
-Pervasive interior mutability usually points at a "god struct" that's trying to be everything. The fix is decomposition — split the struct so each piece has clear single-purpose ownership. See `/m09-domain`.
diff --git a/.agents/skills/rust-code-reviewer/references/naming-and-comments.md b/.agents/skills/rust-code-reviewer/references/naming-and-comments.md
deleted file mode 100644
index 369451d02..000000000
--- a/.agents/skills/rust-code-reviewer/references/naming-and-comments.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Naming & comments review
-
-**Open when the diff has**: new identifiers, doc comments, module reshuffles, or anything renamed.
-
-**Companion skill**: `/coding-guidelines`.
-
-## The design question
-
-**Does the name carry the right amount of meaning — no more, no less?** A name that implies less than it does fails its reader. A name that implies more sets a false expectation. Both are bugs.
-
-## Naming
-
-### 1. Don't promise what you don't do
-- `serve` implies a long-running server loop. If your function does one request, call it `handle` or `process`.
-- `connect` implies a network connection — don't use it for "create a struct that might dial later."
-- `Manager` / `Handler` / `Helper` / `Util` — too generic to mean anything. Pick something that names the responsibility.
-
-### 2. Boolean prefixes
-Use `is_`, `has_`, `needs_`, `can_`. The truthy meaning must be obvious without reading the body.
-- `fn is_streaming(req: &Req) -> bool` ✅
-- `fn streaming(req: &Req) -> bool` ❌
-- `let cancelled = …` ✅ (`cancelled` reads as a state)
-- `let cancel = bool::…` ❌ (verb where you want adjective)
-
-### 3. Conversion conventions
-- `as_X` — cheap reference conversion (`as_str`, `as_bytes`). No allocation.
-- `to_X` — expensive owned conversion (`to_string`, `to_owned`). Allocates.
-- `into_X` — by-value conversion that consumes self.
-
-Mis-using these misleads readers about cost.
-
-### 4. Getters
-Rust convention: omit `get_`. `fn name(&self) -> &str` not `fn get_name(&self) -> &str`. Setters keep `set_` only if you're matching an external API.
-
-### 5. Module file naming
-- `mod.rs` is the older convention. Prefer `parent/foo.rs` + `parent/foo/` over `parent/foo/mod.rs` — easier to find, no naming collisions in tabs.
-- File name = `snake_case` of its primary class/struct/trait. Rename on touch.
-
-### 6. Don't preserve `_` on used variables
-`_text` was "TODO maybe later." Once read, drop the `_`. Otherwise lints don't help and readers wonder why it's there.
-
-### 7. Lifetimes that mean something
-`'a` is fine for one. `'src`, `'req` are better when multiple lifetimes coexist. Don't randomly name them `'b`, `'c` — pick names that say what's tied together.
-
-### 8. Type names
-- `CamelCase` for types, traits, enums.
-- `SCREAMING_SNAKE_CASE` for consts and statics.
-- `snake_case` for fns, vars, modules.
-- One-word type names beat two-word. `Server` beats `ServerObject`.
-
-## Comments
-
-### 1. Delete restating comments
-```rust
-// Smell — says what the line says
-// increment counter
-counter += 1;
-
-// Smell — restates the fn name
-/// Parses the model name
-fn parse_model_name(s: &str) -> Result<Model> { … }
-```
-If the code reads cleanly, the comment is noise. If you need a comment to explain *what*, fix the name.
-
-### 2. Comments earn their place by saying *why*
-Good comments answer: "Why this, not the obvious alternative?" "What invariant is this protecting?" "What surprised me when I wrote this?" Not: "this calls X then Y."
-
-### 3. Don't put history in comments
-"Previously used a HashMap, switched to Vec for cache locality" — that belongs in the commit message. Comments are read by people who don't care what it used to be.
-
-### 4. AI-generated comment smell
-LLMs love restating. If every line has an above-the-line comment, ask the author to delete the obvious ones and rephrase the rest. Pattern to look for:
-- `// Check if X` above `if x { … }`
-- `// Loop through Y` above `for y in … { … }`
-- A multi-line docstring on a 3-line function.
-
-### 5. `///` vs `//`
-- `///` is doc — appears in `cargo doc`. For public items, write it. For private items, only when there's something non-obvious to say.
-- `//` is internal.
-- Don't mix `///` on private fields of a private struct — it ends up half-published.
-
-### 6. Copyright headers
-Switchyard convention: only the two SPDX lines. Anything beyond is noise — trim.
-```rust
-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-// SPDX-License-Identifier: Apache-2.0
-```
-
-### 7. `TODO`/`FIXME` without a name or ticket
-A bare `// TODO: handle this` rots. Either link to a ticket (`// TODO(PROJ-123): …`) or fix it now. Reviewer-suggested: ask for one or the other before merge.
-
-### 8. Test comments
-Test names are documentation. `test_returns_404_when_model_missing` beats `test_missing_model` + a comment. Use the name slot.
-
-## Comment templates
-
-- "`serve` reads like a long-running loop — this is a one-shot handler. `handle_request`?"
-- "`Manager` doesn't tell me what it's responsible for. Pick something specific."
-- "This `//` restates the line — delete it."
-- "`get_name` — drop `get_`, just `name(&self)`."
-- "`'a`, `'b`, `'c` — name them by what they tie to (`'req`, `'src`)."
-- "`_text` is read on line N — drop the underscore."
-- "Bare `// TODO` — link a ticket or fix it now."
-- "Doc comment restates the function name. Either say why, or delete."
-
-## Trace up
-
-Persistent naming confusion in a module signals that the concepts aren't clean. The fix isn't a rename — it's deciding what each concept *is*. That's domain modeling (`/m09-domain`).
diff --git a/.agents/skills/rust-code-reviewer/references/ownership-and-borrowing.md b/.agents/skills/rust-code-reviewer/references/ownership-and-borrowing.md
deleted file mode 100644
index 395d86d91..000000000
--- a/.agents/skills/rust-code-reviewer/references/ownership-and-borrowing.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Ownership & borrowing review
-
-**Open when the diff has**: `.clone()`, lifetimes (`'a`, `'static`), moves, `&mut` patterns, or borrow-checker workarounds.
-
-**Companion skill**: `/m01-ownership` (design framing — "who should own this data?").
-
-## The design question
-
-Before flagging a `.clone()` or suggesting a lifetime, ask: **who should own this, and for how long?** An over-cloned codebase isn't a perf problem first — it's a sign nobody decided the ownership model.
-
-## Red flags
-
-### 1. Reflexive `.clone()`
-```rust
-// Smell
-fn handle(req: ChatRequest, headers: HashMap<String, String>) {
- let h = headers.clone(); // why?
- forward(req.clone(), h);
-}
-```
-
-Ask:
-- Can the caller pass by reference? Does `forward` actually need to *own* it?
-- Is the type `Copy` already? Then `.clone()` is pure noise.
-- Is the type a cheap handle (`Arc`, `Sender`, `tokio::sync::mpsc::Sender`)? `Arc::clone(&x)` is intentional; `x.clone()` for the same effect is a style call but write the intent.
-
-### 2. `.clone()` to satisfy the borrow checker
-A `.clone()` introduced because "the borrow checker complained" almost always means the function's interface is wrong — it asks for ownership when it only needs a borrow, or vice versa. Fix the signature, not the call site.
-
-### 3. `'static` everywhere
-`'static` on a function parameter or struct field is a strong constraint. It's usually a sign the author wanted to silence a lifetime error rather than think about the actual scope. Flag and ask: does this *really* need to live for the program's lifetime?
-
-### 4. Owned `String` where `&str` would do
-```rust
-// Smell — forces caller to allocate
-fn parse_model(model: String) -> Result<Model> { … }
-
-// Better
-fn parse_model(model: &str) -> Result<Model> { … }
-```
-Return owned, accept borrowed — unless you genuinely need to keep it around.
-
-### 5. `Vec<T>` taken by value when iterated once
-```rust
-// Smell
-fn sum(values: Vec<u64>) -> u64 { values.iter().sum() }
-
-// Better
-fn sum(values: &[u64]) -> u64 { values.iter().sum() }
-```
-
-### 6. Preserved `_var` that's actually used
-`_text` → `text` once it's read. The underscore was a "TODO: maybe later" that got committed.
-
-## Acceptable cases
-
-- `.clone()` on `Arc`/`Sender`/`Bytes` — these are cheap handles. Just keep them out of hot paths if cloned per-request.
-- `.clone()` of a small `Copy`-adjacent value (a `String` ID used twice) where readability beats one extra alloc — but say so in the comment if non-obvious.
-- `'static` on background tasks spawned with `tokio::spawn` — that bound is real, not avoidable.
-
-## Comment templates
-
-- "This `.clone()` looks reflexive — `&headers` should work since `forward` only reads."
-- "Why owned `String` here? Caller has to allocate. `&str` parses fine."
-- "`'static` here is doing a lot of work — what's the actual scope? Looks like the borrow can be tightened to `'a`."
-
-## Trace up
-
-If you find ownership confusion all over a module, that's not a `.clone()` problem — it's a domain-modeling problem. The author hasn't decided which type owns the data. Comment at the design level, not on each clone. See `/m09-domain` and `/m01-ownership`.
diff --git a/.agents/skills/rust-code-reviewer/references/performance.md b/.agents/skills/rust-code-reviewer/references/performance.md
deleted file mode 100644
index c7b6e9327..000000000
--- a/.agents/skills/rust-code-reviewer/references/performance.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# Performance review
-
-**Open when the diff has**: hot paths, benchmarks, allocation patterns, large data structures, or anything labelled "optimization."
-
-**Companion skill**: `/m10-performance`.
-
-## The design question
-
-**Did the author measure?** If a PR says "optimization" without a baseline, ask for one. Otherwise the change is taste-based and you can't tell if it helped.
-
-Typical impact hierarchy (don't optimize down a level until the one above is done):
-1. **Algorithm** (10–1000×)
-2. **Data structure** (2–10×)
-3. **Allocation reduction** (2–5×)
-4. **Cache layout / SIMD / micro-tuning** (1.5–3×)
-
-## Red flags
-
-### 1. "Optimization" without measurement
-No `criterion` numbers, no flamegraph, no before/after — just intuition. Reject or downgrade to "consider for later." Especially flag if the change makes the code less readable.
-
-### 2. Benchmarks in debug mode
-`cargo bench` runs release by default, but ad-hoc timing with `Instant::now()` in `cargo run` (debug) tells you nothing. Always `--release`.
-
-### 3. `.clone()` in a hot loop
-A clone per request × N requests/sec = throughput tax. See [`ownership-and-borrowing.md`](ownership-and-borrowing.md). For strings consider `Cow<'_, str>` if it sometimes-borrows-sometimes-owns.
-
-### 4. `Vec::new()` then loop of `.push()` with known size
-```rust
-// Smell
-let mut out = Vec::new();
-for x in input { out.push(transform(x)); }
-
-// Better
-let mut out = Vec::with_capacity(input.len());
-// or
-let out: Vec<_> = input.iter().map(transform).collect();
-```
-`with_capacity` avoids `2 + 4 + 8 + 16 + …` re-allocations during growth.
-
-### 5. `String` concatenation in a loop with `+`/`format!`
-O(n²). Use `String::with_capacity(…)` + `push_str`, or `itertools::join`, or write into a single `String` once.
-
-### 6. `HashMap` for tiny / fixed key sets
-`HashMap` hashing isn't free. For < ~16 entries, a `Vec<(K, V)>` with linear search is often faster (cache-friendly). For known compile-time keys, an enum-keyed array or a `match` is faster still.
-
-### 7. `LinkedList`
-Almost always wrong in Rust. No cache locality, pointer-chasing, allocation per node. Use `Vec` or `VecDeque`.
-
-### 8. Hidden allocations in hot paths
-- `.collect::<Vec<_>>()` when iteration would suffice.
-- `format!()` to build a one-off log message you never structured.
-- Returning `String` where `&str` from the input would work.
-- `to_string()` on something that's already `Display`.
-
-### 9. `Box<[T]>` vs `Vec<T>`
-If the collection is built once and never resized, `Box<[T]>` is smaller (no capacity field) and clearer in intent.
-
-### 10. Synchronous I/O blocking the runtime
-A file read or DNS lookup on the executor thread tanks p99 latency for everything. See [`async-and-concurrency.md`](async-and-concurrency.md).
-
-## Acceptable cases
-
-- A clone on a small string for readability in a non-hot path.
-- `Vec::new()` (no capacity) when the size is unpredictable and tiny.
-- `HashMap` for any non-tiny dynamic key set — its O(1) amortized beats linear scan.
-
-## Comment templates
-
-- "This PR is labelled optimization — got a before/after `criterion` run?"
-- "Hot-path `.clone()` on every request. `&` or `Arc::clone` if shared."
-- "`Vec::new()` then 1000 `push`es — `Vec::with_capacity(1000)`."
-- "`LinkedList` in Rust is almost never the answer — `VecDeque`?"
-- "`format!()` to build a log message that becomes a structured field anyway — drop the `format!`."
-
-## Trace up
-
-Real perf wins usually come from changing what you compute, not how. If a function is slow, look at the call site: can it skip work? Can it batch? Can it cache? That's an architectural question (`/m09-domain`), not a tight-loop question.
diff --git a/.agents/skills/rust-code-reviewer/references/resource-lifecycle.md b/.agents/skills/rust-code-reviewer/references/resource-lifecycle.md
deleted file mode 100644
index 4b3479355..000000000
--- a/.agents/skills/rust-code-reviewer/references/resource-lifecycle.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Resource lifecycle review
-
-**Open when the diff has**: `impl Drop`, `OnceCell`/`OnceLock`/`Lazy`, `lazy_static!`, connection pools, file/socket handles, or any "set up at start, clean up at end" pattern.
-
-**Companion skill**: `/m12-lifecycle`.
-
-## The design question
-
-**Whose lifetime owns this resource, and when does it end?** Rust's RAII is the default cleanup mechanism — if you find yourself writing manual cleanup paths or worrying about "did I close it?", the type system can usually do it for you via `Drop`.
-
-## Red flags
-
-### 1. Manual cleanup paths instead of `Drop`
-```rust
-// Smell
-fn process() -> Result<()> {
- let conn = open_conn()?;
- let result = do_work(&conn);
- conn.close()?; // forgot on the early-return path below
- if let Err(e) = result { /* … */ }
- result
-}
-
-// Better
-struct Conn { /* … */ }
-impl Drop for Conn { fn drop(&mut self) { /* close */ } }
-fn process() -> Result<()> {
- let conn = Conn::open()?; // closed automatically on any exit
- do_work(&conn)
-}
-```
-Every `close`/`release`/`shutdown` call by hand is a place to forget on the error path.
-
-### 2. `Drop` impl that panics
-`Drop` runs during unwinding. Panicking in `Drop` during another panic → process abort. If cleanup can fail, log via `tracing::error!` and swallow; don't `unwrap()` inside `drop()`.
-
-### 3. `Drop` impl that does heavy / blocking work
-`drop` runs synchronously, in whatever context the value goes out of scope — including hot paths, including inside `async fn` (where it blocks the executor). Heavy cleanup should be moved to an explicit `async fn close(self)` and the `Drop` impl should just emit a `tracing::warn!` if the explicit close was skipped.
-
-### 4. `Drop` impl that needs `async`
-There's no `AsyncDrop` in stable Rust. If the resource genuinely needs async cleanup, the common pattern is "explicit async `close(self)` + best-effort `Drop` + warn if dropped without close." Flag if the code pretends a sync `Drop` is doing async work.
-
-### 5. `lazy_static!` in new code
-`lazy_static!` is the old crate. Modern Rust: `std::sync::OnceLock` (thread-safe, no init macro magic) or `once_cell::sync::Lazy`. Suggest the rename in new code; don't churn working `lazy_static!` for taste.
-
-### 6. `OnceCell::new()` then `set()` later vs `Lazy::new(|| init())`
-If init is deterministic and infallible, `Lazy::new(|| …)` is cleaner. `OnceCell` + manual `set` makes sense when init needs runtime data not available at module load.
-
-### 7. Connection pool without an idle/cap policy
-A pool that grows unboundedly is a leak. Flag pools without `max_size` / `min_idle` / `max_age` config or sensible defaults.
-
-### 8. Scope guards reinvented
-If the code does "do A, do thing, undo A" by hand, suggest a guard type. The `scopeguard` crate or a small custom struct with `Drop` is cleaner and survives `?` returns.
-
-### 9. `tokio::spawn`'d task with no `JoinHandle` tracking
-Tied to the lifecycle question: who owns this task? When the parent goes away, does the task? Use `JoinSet` or `tokio_util::task::TaskTracker` for graceful shutdown. See [`async-and-concurrency.md`](async-and-concurrency.md).
-
-### 10. Resource handle leaked across an error path
-`let f = File::open(p)?; let _ = parse(&f); f.close()?;` — what if `parse` panics? Rust's RAII saves you here (`File` closes on drop), but custom types with manual close don't. Audit each error path.
-
-## Acceptable cases
-
-- `Drop` impl that flushes a buffer and logs on error — that's idiomatic.
-- `OnceLock` for a global config / regex / lookup table set once at startup.
-- Manual `close(self)` taking ownership when the close itself can fail and the caller needs the error.
-
-## Comment templates
-
-- "`conn.close()` on the happy path only — what about the `?` above it? Make `Conn` `Drop`."
-- "`Drop` calls `.unwrap()` — if this fires during unwinding, the process aborts. Log and swallow."
-- "Heavy work in `Drop` blocks the executor when this is dropped from async. Move to explicit `close()`."
-- "`lazy_static!` — for new code use `OnceLock` or `Lazy::new`."
-- "Pool has no max size — what happens at 10k connections?"
-
-## Trace up
-
-Lifecycle problems usually surface as "leaks in production" or "tests are flaky on shutdown." That's a sign no single owner has been assigned to the resource. Pair this with `/m09-domain` for the ownership-design angle.
diff --git a/.agents/skills/rust-code-reviewer/references/smart-pointers.md b/.agents/skills/rust-code-reviewer/references/smart-pointers.md
deleted file mode 100644
index ceb6a874f..000000000
--- a/.agents/skills/rust-code-reviewer/references/smart-pointers.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Smart pointers review
-
-**Open when the diff has**: `Box<…>`, `Rc<…>`, `Arc<…>`, `Weak<…>`, `RefCell<…>`, or nested forms like `Arc<Mutex<…>>` / `Rc<RefCell<…>>`.
-
-**Companion skill**: `/m02-resource`.
-
-## The design question
-
-**What ownership pattern does this actually need?** A wrapper is a tax — atomic ops (`Arc`), heap allocation (`Box`), runtime borrow checks (`RefCell`). Pay the tax only when the design demands it.
-
-| Need | Use |
-|---|---|
-| Single owner, value too large for stack or trait object | `Box<T>` |
-| Shared ownership, single thread | `Rc<T>` |
-| Shared ownership, multiple threads | `Arc<T>` |
-| Break a cycle | `Weak<T>` |
-| Interior mutability, single thread | `RefCell<T>` |
-| Interior mutability, multiple threads, sync code | `Mutex<T>` / `RwLock<T>` |
-| Interior mutability, async, held across `.await` | `tokio::sync::Mutex<T>` |
-
-## Red flags
-
-### 1. `Arc` reflexively on construction
-```rust
-// Smell — Switchyard's pre-wrap-in-constructor anti-pattern
-fn new(config: Config) -> Self {
- Self { config: Arc::new(Mutex::new(config)) }
-}
-```
-Owners decide their own synchronization. Don't `Arc<Mutex<…>>` in a constructor unless every caller will need it. Let them wrap when they share.
-
-### 2. `Arc<Box<T>>`
-Both are pointers. You only need one indirection. If you see this, ask for justification or unwrap one.
-Exception: `Arc<dyn Trait>` where the inner already had to be `Box<dyn Trait>` somewhere — but usually `Arc<dyn Trait>` directly is what you want.
-
-### 3. `Arc` around an already-cheap-to-clone handle
-```rust
-// Smell
-let sender = Arc::new(tx); // tx: tokio::sync::mpsc::Sender — already Arc internally
-```
-Channels, `Bytes`, `reqwest::Client`, `tokio::sync::mpsc::Sender`, `Arc<…>` itself — all cheap to clone. Wrapping them in another `Arc` adds an indirection for no win.
-
-### 4. `Rc<RefCell<T>>` in code that might go multithreaded
-Read the surrounding module. Is it touched from any async context, any background thread? If yes, `Rc<RefCell<…>>` will break the moment someone moves it across a thread. Suggest `Arc<Mutex<…>>` — or, better, redesign so no sharing is needed.
-
-### 5. `Arc<Mutex<HashMap<K, V>>>` as the central state
-This pattern works but is rarely the right answer. Ask:
-- Is contention actually a problem? `parking_lot::RwLock` or `dashmap` may be better.
-- Could the work be modeled as message passing (`mpsc`) so each task owns its own state?
-- Is the lock held across `.await`? If yes, [`async-and-concurrency.md`](async-and-concurrency.md) applies.
-
-### 6. `Box<T>` for small types
-`Box<u64>` is a heap allocation for 8 bytes. Almost always a mistake. Same for `Box<MyEnum>` where the enum is small. The author may have copied from C++ instinct.
-
-### 7. Missing `Weak` for parent pointers
-Parent ↔ child with `Rc<…>` both ways = memory leak. The child's pointer to parent should be `Weak`. Same for `Arc` cycles.
-
-## Acceptable cases
-
-- `Arc<dyn Trait>` for shared trait objects across tasks — idiomatic.
-- `Box<dyn Error + Send + Sync>` in error types — standard.
-- `Box<T>` when erasing a generic into a `dyn` or when the value is huge.
-- `Arc<RwLock<T>>` for read-heavy shared config — but check it's not held across `.await` ([`async-and-concurrency.md`](async-and-concurrency.md)).
-
-## Comment templates
-
-- "Why `Arc<Mutex<…>>` here? Caller decides synchronization. Move this out of the constructor."
-- "`Arc<Box<…>>` — drop the `Box`, `Arc<…>` already heap-allocates."
-- "`tx` is already a cheap handle; the extra `Arc` is noise."
-- "`Rc<RefCell<…>>` in a module that's used from `tokio::spawn` will explode. Use `Arc<Mutex<…>>` or redesign."
-
-## Trace up
-
-If a module is drowning in `Arc<Mutex<…>>`, the symptom is "we share state everywhere." The fix isn't a different wrapper — it's deciding which task *owns* the state and routing access through it (message passing). See `/m09-domain` for that framing, `/m07-concurrency` for the async-specific angle.
diff --git a/.agents/skills/rust-code-reviewer/references/type-driven-design.md b/.agents/skills/rust-code-reviewer/references/type-driven-design.md
deleted file mode 100644
index 9be37991e..000000000
--- a/.agents/skills/rust-code-reviewer/references/type-driven-design.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Type-driven design review
-
-**Open when the diff has**: `PhantomData`, marker traits, newtypes, builder patterns, type-state transitions, or types that "encode an invariant."
-
-**Companion skill**: `/m05-type-driven`.
-
-## The design question
-
-**Can the type system make this invalid state unrepresentable?** Most "validate at runtime" code is "we didn't model it at the type level." Rust's expressive types pay back the up-front cost in deleted runtime checks.
-
-## Red flags
-
-### 1. Boolean fields that should be enums
-```rust
-// Smell
-struct Request { is_streaming: bool, is_anthropic: bool, is_responses: bool }
-// What does (true, true, true) mean? Nothing. But it compiles.
-
-// Better
-enum Format { OpenAiChat, OpenAiResponses, Anthropic }
-struct Request { format: Format, streaming: bool }
-```
-If two booleans can't both be true, that's an enum. If three can't all coexist, definitely an enum.
-
-### 2. `String` for things with structure
-`model: String` where the legal values are `"openai/gpt-4"`, `"anthropic/claude-3"`, etc. Wrap it in a newtype that parses on construction: `Model::parse(&s)` returns `Result<Model, ParseModelError>`. Every other function in the codebase can then take `&Model` knowing it's valid.
-
-### 3. Validation that runs on every method
-```rust
-impl Connection {
- fn send(&self, msg: Msg) -> Result<()> {
- if !self.is_open { return Err(NotOpen); }
- …
- }
- fn close(&self) -> Result<()> {
- if !self.is_open { return Err(NotOpen); }
- …
- }
-}
-```
-The `is_open` check is everywhere because the type doesn't encode the state. Typestate would: `Connection<Open>` has `send`/`close`; `Connection<Closed>` has neither. The check becomes a compile error instead of a runtime one.
-
-### 4. Builder with `Option<T>` for every required field
-```rust
-// Smell — caller can call build() with nothing set
-struct ServerBuilder { host: Option<String>, port: Option<u16> }
-impl ServerBuilder {
- fn build(self) -> Result<Server> {
- Ok(Server {
- host: self.host.ok_or("host required")?,
- port: self.port.ok_or("port required")?,
- })
- }
-}
-```
-A type-state builder uses different types for "configured" vs "missing" so `.build()` only compiles when everything is set. Worth it for builders with many required fields and confusing failure modes.
-
-### 5. `PhantomData` without explanation
-`PhantomData<T>` is meaningful — it tells the compiler the type "owns" a `T` for variance/dropck. If you see it without a comment, ask why. Often it's leftover from a refactor.
-
-### 6. Newtype with all the inner type's methods re-exposed
-If you write `pub struct Email(pub String)` and then `impl Email { pub fn as_str(&self) -> &str { &self.0 } pub fn into_string(self) -> String { self.0 } }` and `pub` the inner field — you've added zero safety, just noise. The point of a newtype is to *restrict* what callers can do.
-
-## Acceptable cases
-
-- `PhantomData<&'a T>` for explicit variance on lifetime-parameterized types — write a comment.
-- A boolean field when the two states are genuinely orthogonal to everything else.
-- A builder with `Option<T>` for *optional* fields (with sensible defaults at `build()`).
-
-## Comment templates
-
-- "Three booleans that can't coexist — should be an enum."
-- "`String` model name — could be a `Model` newtype that parses at the boundary, so the rest of the code doesn't re-validate."
-- "Every method checks `is_open` — typestate would make this a compile-time guarantee."
-- "`PhantomData` without a comment — what's it doing?"
-
-## Trace up
-
-Type-driven design is the bridge from Layer 1 (mechanics) to Layer 2 (design). When you see a lot of runtime validation, the issue isn't "missing checks" — it's that the domain model is shaped wrong (`/m09-domain`).
diff --git a/.agents/skills/switchyard-codebase-exploration/SKILL.md b/.agents/skills/switchyard-codebase-exploration/SKILL.md
deleted file mode 100644
index c91609c98..000000000
--- a/.agents/skills/switchyard-codebase-exploration/SKILL.md
+++ /dev/null
@@ -1,244 +0,0 @@
----
-name: switchyard-codebase-exploration
-description: Use when modifying, debugging, reviewing, refactoring, renaming, restructuring, or planning any Switchyard change — even if the user only names a symptom, test failure, CLI flag, endpoint, model route, or file path. Triggers on phrases like "fix this bug", "why is X failing", "where does Y live", "add a new profile", "rename X to Y", "refactor this", "explain how X works", or any request that will touch `switchyard/`, `tests/`, or `examples/`. Forces a fresh impact map before editing so agents do not edit from stale memory, and routes the agent to the matching workstream skill (`switchyard-lib-core`, `switchyard-coding-agent-launchers`, `switchyard-testing-ci`) before reading source.
----
-
-# Switchyard Codebase Exploration
-
-> Rust crates under `crates/` are active on the Rust core branch. Inspect
-> `crates/switchyard-core`, `crates/switchyard-components`,
-> `crates/switchyard-server`, `crates/switchyard-translation`,
-> `crates/switchyard-py`, and `crates/*/tests`
-> directly when a change touches Rust. The libsy algorithm layer lives in
-> `crates/libsy` (core + `observability.rs` telemetry), `crates/libsy-protocol`
-> (conversation IR), and `crates/libsy-examples` (reference algorithms).
-> Direct PyO3 bindings for concrete components live under
-> `crates/switchyard-py/src/component_bindings/` with Python lazy exports in
-> `switchyard_rust/components.py`.
-
-## Overview
-
-**Read the current checkout before you edit it.** Branch state, profile wiring, exports, tests, and optional-dependency boundaries drift faster than any memorized map. This skill produces a fresh impact map for the specific change, so the edit plan is grounded in what is actually there — not what was there last week.
-
-**Load the matching workstream skill before diving into source.** Once you have classified the change (see [§ Decompose, step 1](#1-scope-packet)), open the workstream SKILL.md — [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md) for anything under `lib/`, [`switchyard-coding-agent-launchers`](../switchyard-coding-agent-launchers/SKILL.md) for `cli/launchers/` work. Skipping this step is how agents reinvent construction paths, stats collectors, and CLI flags.
-
-If you are about to run validation (`pytest`, `ruff`, `mypy`, CI gates), pair this skill with [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md): explore here first, then pick the validation set there.
-
-## Quick Reference
-
-| You need to… | Command |
-|---|---|
-| Map current diff | `git status -sb && git diff --stat && git diff --name-only` |
-| Map a specific file's importers and tests | `rg -n "module_stem|ClassName|function_name" switchyard tests docs AGENTS.md` |
-| Map by symbol (class/function name) | `rg -n "ProfileSwitchyard|RandomRoutingPresets" switchyard tests docs AGENTS.md` |
-| List source and tests by area | `find switchyard tests examples crates -maxdepth 3 -type f | sort` |
-| Find class/function definitions across repo | `rg -n "class \|def \|async def " switchyard tests` |
-| Trace a symbol through the codebase | `rg -n "<symbol-or-route-or-flag>" switchyard tests docs AGENTS.md` |
-
-## Operating Rule
-
-Read the current checkout before editing. Do not rely on a memorized architecture map: branch state,
-profile wiring, exports, tests, and optional dependency boundaries move often.
-
-Before making a code change, be able to name:
-
-- the client ingress path: CLI, FastAPI endpoint, Python API, or route-table host
-- the chain slot touched: request-side component, `LLMBackend`, response-side component, `TranslationEngine`, or wiring only
-- the wire formats involved: OpenAI Chat, Anthropic Messages, OpenAI Responses, streaming/non-streaming
-- the profile/route-table/export path that exposes the behavior
-- the focused tests and the broad validation gate to run
-
-## Manual Map First
-
-From the repo root, build a fresh impact map every time the branch, diff, or task changes:
-
-```bash
-git status -sb
-git diff --stat
-git diff --name-only
-```
-
-If there is no diff yet, search likely owners explicitly:
-
-```bash
-rg -n "ProfileSwitchyard|RandomRoutingPresets" switchyard tests docs AGENTS.md
-rg -n "class |def |async def " switchyard tests examples
-find switchyard tests examples crates -maxdepth 3 -type f | sort
-```
-
-For a specific file, search by the module stem, primary class/function names, and public flags:
-
-```bash
-rg -n "random_routing|RandomRouting|strong_probability" switchyard tests docs AGENTS.md
-rg -n "test_.*random|random_routing" tests
-```
-
-Ignore generated docs build artifacts (`docs/.venv-docs/`, `docs/_build/`, `site/_build/`) and
-local virtualenvs when building the map; remove them if they pollute `git status`.
-
-## Examples
-
-Input: `fix the --preset help regression in launch claude`
-Output: Map with `--symbol RandomRoutingPresets`, **load [`switchyard-coding-agent-launchers`](../switchyard-coding-agent-launchers/SKILL.md)** (ingress area), then inspect CLI parser, launcher wiring, slim-smoke command, and launch/verify tests before editing.
-
-Input: `add a new routing preset opus_qwen3` (or any "add a preset" / "new shipping pair" request)
-Output: profile/preset area → **load [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md)** for the profile-owned config pattern and the "no parallel stats collector" rule. Also load [`switchyard-coding-agent-launchers`](../switchyard-coding-agent-launchers/SKILL.md) when launchers expose the preset. Then map `--symbol RandomRoutingPresets` to confirm test/CLI/cost-estimator touch points before adding the new id.
-
-Input: `this responses streaming test is failing`
-Output: Map the touched test or `ResponsesApiStreamingChatResponse`, **load [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md)** (chain-core + wire-types area) and [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md), then read response types, translation engine, SSE helpers, endpoint code, and focused streaming tests before changing shapes.
-
-Input: `rename random_routing to weighted_routing everywhere`
-Output: **Load [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md) first** — it flags random routing as a reference profile and lists the anti-patterns that block thoughtless renames of public/profile identifiers. Then map every importer and CLI flag before proposing the plan.
-
-Input: `add intake telemetry that records routing decisions`
-Output: Observability/state area → **load [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md)** for the "don't fork the stats stack" rule and the existing intake processor wiring, then map `processors/intake_*`, `processors/stats_*`, and the profile that owns the existing routing-decision payload.
-
-## Decompose the Exploration
-
-Use these packets independently, then merge the findings into one edit plan.
-
-### 1. Scope Packet
-
-```bash
-git status -sb
-git diff --stat
-git diff --name-only
-```
-
-Classify the task as one or more of:
-
-- chain-core: `roles.py`, `switchyard.py`, profile runtimes, `ProxyContext`
-- wire-types/translation: `chat_request/`, `chat_response/`, `translation/`, `translators/`
-- backend/routing: `backends/`, profile routing helpers, health polling, tier config
-- profiles/route-table: `profiles/`, `route_table.py`, `route_table_builders.py`
-- ingress: `cli/`, `server/`, `lib/endpoints/`
-- observability/state: stats, live stats, intake, metadata, cost estimator
-- public/package: `switchyard/__init__.py`, `pyproject.toml`, optional extras, entry points
-- tests/docs/skills: `tests/`, `.agents/skills/`, docs, CI-only validation
-
-**Then load the matching workstream skill — before reading source.** Skipping this step is the single most common way agents reinvent existing infrastructure.
-
-| If the area is… | Load this skill next |
-|---|---|
-| chain-core, wire-types/translation, backend/routing, profiles/route-table, observability/state | [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md) — profile pattern + anti-patterns (no new stats collectors, no factory reinvention, preserve chain shape) |
-| ingress (CLI launchers, server, endpoints) | [`switchyard-coding-agent-launchers`](../switchyard-coding-agent-launchers/SKILL.md) — launchers build profile-backed apps or route tables |
-| any planned edit followed by validation | [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — picks the smallest local validation set that is CI-equivalent |
-| public/package, tests/docs/skills | Use the lib-core skill if the public API touches `lib/`; otherwise testing-ci's skill/docs gate |
-
-### 2. Runtime Path Packet
-
-Trace the request end-to-end for the affected surface. Prefer `rg` over guessing:
-
-```bash
-rg -n "<class-or-function>|<route>|<flag>|<config-field>" switchyard tests docs AGENTS.md
-rg -n "ProfileSwitchyard|RouteTable|build_switchyard_app|app.state.switchyard" switchyard tests
-```
-
-Read the nearest owner files plus their call sites. For runtime behavior, include at least one
-upstream entry point and one downstream test.
-
-### 3. Role Contract Packet
-
-When touching any chain component, reread:
-
-- `switchyard/lib/roles.py`
-- `switchyard/lib/switchyard.py`
-- `switchyard/lib/proxy_context.py`
-
-Keep the logical shape fixed: request-side work → `LLMBackend` → response-side work → `TranslationEngine`.
-Processor components use async `process(...)`; backend and translation role methods are async. Use `ctx.metadata` for cross-component state.
-
-### 4. Wiring Packet
-
-For behavior exposed outside a unit test, inspect each applicable wiring layer:
-
-- public API: `switchyard/__init__.py` and `__all__`
-- profiles: `switchyard/lib/profiles/`
-- route tables: `switchyard/lib/route_table.py`, `switchyard/lib/route_table_builders.py`
-- server: `switchyard/server/switchyard_app.py`, `switchyard/server/server_util.py`
-- endpoints: `switchyard/lib/endpoints/*.py`
-- CLI: `switchyard/cli/switchyard_cli.py`, `switchyard/cli/launch_command.py`, launcher/config modules
-- packaging: `pyproject.toml` extras and `project.scripts`
-
-Do not add a class without checking whether it needs an import/export, profile config,
-CLI flag, endpoint mount, or test fixture update.
-
-### 5. Test Packet
-
-Search by symbol and module stem to catch direct and indirect coverage:
-
-```bash
-rg -n "<symbol>|<module-stem>" tests switchyard
-```
-
-Run focused tests first. Use hermetic broad tests by default:
-
-```bash
-uv run pytest tests/test_<area>.py -v -o addopts=
-uv run pytest tests/ -v -m "not integration"
-```
-
-Run live `tests/e2e/` only when the user explicitly wants provider calls and credentials are
-intentionally available.
-
-## Path-Specific Read Rings
-
-Use these rings as starting points, not replacements for dynamic search.
-
-- CLI launch/config: `switchyard/cli/switchyard_cli.py`, `launch_command.py`, `launchers/*`,
- `config/user_config.py`, `server/server_util.py`, plus `tests/test_launch_*`,
- `tests/test_user_config.py`, `tests/test_model_discovery.py`.
-- FastAPI endpoints/server: `server/switchyard_app.py`, `lib/endpoints/*`, request/response
- types, translators, `tests/test_switchyard_app_factory.py`, `tests/test_endpoint_state_contract.py`,
- endpoint-specific tests.
-- Translation: `lib/translation/request_engine.py`, `response_engine.py`, provider conversion
- modules, `lib/translators/default_response_translator.py`, translation chaos tests.
-- Routing/backends: `llm_target.py`, `backend_format_resolver.py`, concrete backend,
- `multi_llm_backend.py`, stats wrapper, profile config for that router, routing tests.
-- Profiles/route tables: profile config/runtime module, route-table builders, YAML tests,
- public exports.
-- Stats/intake: request processor, response processor, accumulator/live collector/client, stats
- endpoint, intake processors, metadata tests.
-- Skills/docs-only: parse frontmatter/YAML, run `git diff --check`, and remember `.agents` is
- gitignored so use `git add -f` when publishing.
-
-## Common Traps
-
-- `switchyard` is the package and CLI name; do not reintroduce `nemo_switchyard` imports or docs.
-- Do not change Rust-owned backend role classes, chain shape, public API exports, HTTP endpoints, or dependencies without
- explicit user intent.
-- Keep optional heavy/server/CLI/intake dependencies out of top-level imports and default install
- paths. Lazy imports in profile/backend helpers and `switchyard/__init__.__getattr__` are deliberate.
-- Treat NVIDIA Inference Hub and OpenRouter as OpenAI-compatible upstreams unless the current code
- proves otherwise. Prefer provider/base-url/API-key config and existing OpenAI-compatible backends
- before adding provider-specific translation paths or backend roles.
-- Backends should declare `supported_request_types` and normalize with the translation engine rather
- than assuming OpenAI Chat input.
-- Endpoints read `request.app.state.switchyard`; it may be a single profile-backed runtime or a `RouteTable`.
-- Random routing uses `strong_probability` (`rng.random() < strong_probability`); do not revive the
- old inverted threshold semantics.
-- Stats paths often require a shared `StatsAccumulator` across request/response processors and
- `StatsLlmBackend`.
-- Pytest has `addopts = "-x"`; use `-o addopts=` when triaging all failures.
-- Generated docs artifacts and local virtualenvs are not CI inputs; remove them or keep them out of
- local validation.
-
-## Edit Plan Output
-
-Before editing, write a compact internal plan with:
-
-```text
-Change: <one sentence>
-Ingress: <CLI/server/Python/profile/route-table>
-Chain slots: <roles touched>
-Files to read: <source + tests>
-Files to edit: <minimal set>
-Validation: <focused tests + broad gate>
-Risk: <optional deps/live calls/public API/streaming/stats>
-```
-
-After editing, report exactly what ran and whether live provider calls were involved.
-
-## Related Skills
-
-- [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — after the impact map is in hand, use that skill to pick the smallest local validation set that is genuinely CI-equivalent for the files you touched.
diff --git a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md b/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
index 8af847140..18a7d9e2d 100644
--- a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
+++ b/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
@@ -1,125 +1,48 @@
---
name: switchyard-coding-agent-launchers
-description: Use when editing `switchyard launch claude` / `switchyard launch codex` / `switchyard launch openclaw` or anything under `switchyard/cli/launchers/`, `switchyard/cli/launch_command.py`, `switchyard/cli/routing/`, `switchyard/cli/model_catalog/`, or `switchyard/cli/config/user_config.py`. Triggers on "modify the claude launcher", "wire codex to a new model", "add an openclaw launcher flag", "saved user defaults", "routing profiles", or "first-run configure".
+description: Modify or debug Switchyard's Claude Code, Codex CLI, or OpenClaw launchers. Use for changes under switchyard/cli/launchers, launch_command.py, launcher configuration, temporary agent workspaces, model catalogs, or launcher smoke tests.
---
-# Switchyard Coding-Agent Launchers
+# Coding-Agent Launchers
-## Overview
+Launchers start a local Switchyard server and configure an external agent process to use it. Read
+the current launcher, its dispatch path, and its tests before editing; routing construction changes
+often, while the process-specific contracts below are stable.
-CLI launchers are thin shells over profile-backed `SwitchyardApp` values:
+## Process Contracts
-- Single-model launches build a passthrough profile with
- `build_tier_passthrough_switchyard(...)`.
-- Multi-route launches load routing-profile YAML with
- `load_route_bundle_table(...)`, which returns a `RouteTable`.
-- The FastAPI app receives either a single profile-backed runtime or a
- `RouteTable` and serves it through `build_switchyard_app(...)`.
+- Claude Code is configured through Anthropic environment variables.
+- Codex receives a temporary provider and model catalog through CLI configuration.
+- OpenClaw receives a temporary state directory and `openclaw.json`.
+- Temporary files, environment changes, and child processes must be cleaned up on success, error,
+ and interruption.
+- Secrets may be passed to child processes but must not be logged, persisted in committed files, or
+ rendered in status output.
-Do not reintroduce `SwitchyardRecipes`, factory registries, middleware bundles,
-or request/response pipeline wrappers in launcher code.
+## Workflow
-`--routing-profiles` is a global switchyard flag before the subcommand.
-`--model` stays on the launcher subcommand. They are mutually exclusive for
-the launcher entry points that need a single initial model.
+1. Trace the command from `switchyard/cli/switchyard_cli.py` through
+ `switchyard/cli/launch_command.py` into the selected launcher.
+2. Read the launcher-specific tests and any shared server/configuration helpers it calls.
+3. Keep launcher code focused on external-process configuration. Routing policies and LLM behavior
+ belong in the shared server or library path, not launcher-only branches.
+4. Preserve optional-dependency boundaries with lazy imports.
+5. Run the focused launcher tests discovered for the changed command, then the CLI help smoke.
-Pair this skill with [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md)
-before editing and [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md)
-after.
-
-## Quick Reference
-
-| You need to… | Command / file pointer |
-|---|---|
-| Launch claude with a single model | `switchyard launch claude --model nvidia/moonshotai/kimi-k2.5` |
-| Launch codex with a single model | `switchyard launch codex --model nvidia/moonshotai/kimi-k2.5` |
-| Launch openclaw with a single model | `switchyard launch openclaw --model nvidia/moonshotai/kimi-k2.5` |
-| Launch a one-off OpenRouter model | `switchyard launch codex --model openai/gpt-5.2 --base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY"` |
-| Save OpenRouter provider defaults | `switchyard configure --provider openrouter --base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY"` |
-| Launch with a YAML route bundle | `switchyard --routing-profiles ~/.config/switchyard/profiles.yaml launch claude` |
-| Standalone proxy server | `switchyard --routing-profiles routes.yaml serve --port 4000` |
-| Build one launcher chain | `build_tier_passthrough_switchyard(...)` in `switchyard/lib/route_table_builders.py` |
-| Build/merge YAML routes | `load_route_bundle_table(...)` / `build_route_bundle_table(...)` in `switchyard/cli/route_bundle.py` |
-| Look up upstream model catalogs | `fetch_model_ids(...)` in `switchyard/cli/model_catalog/model_discovery.py` |
-| Add a deterministic route | Add `type: deterministic` in route YAML; `_deterministic_switchyard` maps it to `DeterministicRoutingProfileConfig`. |
-| Add a preset | Put it beside the profile config under `switchyard/lib/profiles/`; presets return typed config objects, not runnable apps. |
-| Inspect saved defaults | `switchyard configure --show` reads `switchyard/cli/config/user_config.py` and renders via `switchyard/cli/status.py`. |
-
-## Launcher Pattern
-
-1. Parse CLI args in `switchyard/cli/switchyard_cli.py` and dispatch through
- `switchyard/cli/launch_command.py`.
-2. Resolve credentials, endpoint, saved defaults, and routing-profile path.
- Use OpenRouter through the OpenAI-compatible path: pass
- `--base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY"`
- for a one-off launch, or save provider defaults with `switchyard configure`.
- Do not assume launcher subcommands accept `--provider`; provider ids are a
- configure/defaults concern.
-3. Build a `StatsAccumulator` once for the launcher process.
-4. Build the single-target profile-backed app with
- `build_tier_passthrough_switchyard(...)`, or load route YAML with
- `load_route_bundle_table(...)`.
-5. If both a launcher model and YAML table are present, wrap the single model
- in a `RouteTable` with `build_single_model_table(...)` and merge YAML entries.
-6. Call `build_switchyard_app(...)`, start uvicorn in a daemon thread, wait for
- `/health`, then spawn the external CLI.
-
-Claude, Codex, and OpenClaw differ only in how they configure the external
-agent process:
-
-- Claude uses environment variables such as `ANTHROPIC_BASE_URL` and
- `ANTHROPIC_MODEL`.
-- Codex injects a transient provider with repeated `-c` flags and a temporary
- model catalog.
-- OpenClaw writes a transient `openclaw.json` workspace and points the process
- at it with `OPENCLAW_STATE_DIR`, `OPENCLAW_HOME`, and
- `OPENCLAW_CONFIG_PATH`.
-
-## RouteTable Behavior
-
-`RouteTable` maps inbound request `model` values to profile-backed runtimes.
-Route YAML and launchers share this model-dispatch path:
-
-- `type: model` registers only the YAML key as an alias to one target.
-- `type: passthrough` registers the YAML key and discovered direct models.
-- `type: random_routing` registers the YAML key as the routing profile plus
- direct strong/weak passthrough entries.
-- `type: deterministic`, `type: escalation_router`, and `type: stage_router`
- register the route key plus direct strong/weak passthrough entries.
-- `type: latency_service` and `type: noop` register the
- route key.
-
-Runtime-only hooks such as intake are passed to route-table builders as kwargs;
-route YAML does not declare arbitrary Python processors.
-
-## Anti-Patterns
-
-| Anti-pattern | What to do instead | Why |
-|---|---|---|
-| Adding a launcher flag for a routing policy. | Add a route field in `switchyard/cli/route_bundle.py`. | Routing policies are composable YAML/profile concerns; launcher flags should stay small. |
-| Building `Switchyard(...)` manually in launcher code. | Use `build_tier_passthrough_switchyard(...)` or `load_route_bundle_table(...)`. | Launchers should not own chain internals or stats ordering. |
-| Reintroducing recipes, factories, middleware bundles, or pipeline wrappers. | Put construction in profile configs and dispatch with `RouteTable`. | Those abstractions were removed to keep construction flat and profile-owned. |
-| Writing a new stats collector in launcher code. | Pass one `StatsAccumulator` into the profile/route-table builder. | Live stats and `/v1/routing/stats` must read the same accumulator. |
-| Implementing routing backends inside `switchyard/cli/launchers/`. | Add backend/profile logic under `switchyard/lib/` or Rust components, then expose it through route YAML. | CLI-only routing drifts from `switchyard serve`. |
-| Importing heavy packages at launcher module top level. | Lazy-import inside the function that needs them. | Slim installs must still run `switchyard launch <agent> --help`. |
-
-## Testing Launcher Changes
-
-Run focused launcher tests plus route-bundle coverage:
+Find the current focused tests rather than maintaining a static test inventory:
```bash
-uv run pytest tests/test_launch_claude.py tests/test_launch_codex.py \
- tests/test_launch_openclaw.py tests/test_launch_route_builder.py \
- tests/test_user_config.py tests/test_model_discovery.py \
- tests/test_verify.py tests/test_route_bundle.py -v -o addopts=
+rg --files tests | rg 'launch|openclaw|codex|claude|user_config|model_discovery|verify'
```
-When a change touches optional dependencies or top-level CLI imports, also run
-the slim-install smoke gate from `switchyard-testing-ci` and verify all three
-launcher help commands.
+For OpenAI-compatible providers such as OpenRouter or NVIDIA endpoints, prefer existing base URL,
+API key, and model configuration. Add provider-specific launcher behavior only for a real process,
+authentication, or protocol difference.
-## Related Skills
+## Anti-Patterns
-- [`switchyard-lib-core`](../switchyard-lib-core/SKILL.md) — profile-backed construction and lib-level contracts.
-- [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) — map importers and tests before editing.
-- [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — choose validation gates after editing.
+- Adding one launcher flag per routing algorithm.
+- Building a separate routing stack inside a launcher.
+- Importing server or provider dependencies at module import time.
+- Leaving temporary catalogs, config files, or modified environment variables behind.
+- Assuming the three external agents accept the same configuration mechanism.
diff --git a/.agents/skills/switchyard-docs/SKILL.md b/.agents/skills/switchyard-docs/SKILL.md
index 812628b86..731b1f7c4 100644
--- a/.agents/skills/switchyard-docs/SKILL.md
+++ b/.agents/skills/switchyard-docs/SKILL.md
@@ -1,125 +1,46 @@
---
name: switchyard-docs
-description: Use when adding or editing pages on the published Switchyard MkDocs site (`docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`), wiring a new page into the nav, debugging a `mkdocs build --strict` failure, previewing the site locally, or reviewing changes to the docs CI workflow. Triggers on phrases like "add a docs page", "the docs site is broken", "mkdocs strict is failing", "preview docs locally", or any edit under `docs/**` that should reach the published Pages site.
+description: Edit or debug the published Switchyard MkDocs site. Use for docs pages, mkdocs.yml navigation, mkdocs_hooks.py source links, strict build failures, local previews, or .github/workflows/docs.yml.
---
-# Switchyard Docs Site
+# Switchyard Documentation
-## Overview
+The published site is the subset of `docs/` selected by `mkdocs.yml`. Strict MkDocs warnings fail
+CI, so fix warnings rather than weakening validation.
-**The published site is a deliberately small subset of `docs/`.** Most files under `docs/` are internal design notes; only the pages listed in `mkdocs.yml`'s `nav:` (and not in `exclude_docs`) ship to the public site. When in doubt, prefer not to publish — add a file as internal first, then promote it once the content is stable.
+## Source Of Truth
-**Strict mode is the contract.** `mkdocs build --strict` runs in CI (`.github/workflows/docs.yml`) and locally via `make publish`. Any warning — missing link target, unrecognized anchor, ambiguous file reference — fails the build. If you broke strict, fix the warning rather than relaxing the gate.
-
-Repository files outside `docs_dir` are linked with paths relative to the Markdown source. The
-`mkdocs_hooks.py` `on_page_markdown` hook rewrites valid in-repository targets to source URLs using
-`repo_url` and `extra.source_ref` from `mkdocs.yml` before MkDocs validates links. The source ref
-comes from `MKDOCS_SOURCE_REF`, with `main` as the local fallback. CI sets it to the PR head SHA or
-push SHA so preview and published links resolve against the exact source commit. Missing targets and
-paths that escape the repository remain relative so strict validation still exposes them.
-
-The docs site uses the same `uv` toolchain as the rest of the repo. Dependencies live in the `docs` group in `pyproject.toml`; there is no separate `requirements*.txt`.
-
-## Quick Reference
-
-| Situation | Command |
-|---|---|
-| Sync the docs dependency group | `cd docs && make env` (= `uv sync --only-group docs`) |
-| Live-reload preview at http://127.0.0.1:8000 | `cd docs && make live` |
-| One-shot strict build (mirrors CI) | `cd docs && make publish` |
-| Plain incremental build | `cd docs && make html` |
-| Remove `site/` | `cd docs && make clean` |
-| List published pages | `grep -A20 "^nav:" mkdocs.yml` |
-| List excluded `docs/*.md` | `grep -A10 "^exclude_docs:" mkdocs.yml` |
-
-The MkDocs config and the workflow live at the repo root; `docs/Makefile` cd's there for you.
-
-## Where Things Live
-
-Before editing, discover the current state — don't memorize it:
-
-- **Published page set** → `nav:` block in `mkdocs.yml`. The order there is the order on the site.
-- **Hidden-from-publish files** → `exclude_docs:` block in `mkdocs.yml`. Anything under `docs/` that isn't in `nav:` and isn't excluded will trigger a strict-build warning.
-- **Internal design notes** → also under `docs/`, but excluded. They live next to published pages so cross-linking from internal notes to public pages stays trivial.
-- **Build/preview entry points** → `docs/Makefile` (thin wrapper over `uv run --only-group docs mkdocs ...`).
-- **Docs dependencies** → `docs` group in `pyproject.toml`; resolved into `uv.lock` like the rest of the project.
-- **Site styling** → `docs/stylesheets/` (extra CSS) and the `theme:` block in `mkdocs.yml`.
-- **Repository source-link hook** → `mkdocs_hooks.py`, configured by `repo_url` and
- `extra.source_ref` in `mkdocs.yml`. `MKDOCS_SOURCE_REF` overrides the local `main` fallback.
-- **CI** → `.github/workflows/docs.yml`. Triggered on `docs/**`, `mkdocs_hooks.py`, `mkdocs.yml`,
- `pyproject.toml`, `uv.lock`, and the workflow file itself.
-
-Run `ls docs/` and `grep -A20 "^nav:" mkdocs.yml` to see the current set in one shot.
-
-## Adding a Page
-
-1. **Decide whether it's public or internal.** Internal design notes stay out of `nav` and go into `exclude_docs`. Don't ship anything that isn't stable enough to read cold.
-2. **Place the file under `docs/`.** Use existing naming: lower_snake or UPPER_SNAKE — match the surrounding pages on the same topic.
-3. **Wire it into `mkdocs.yml`** in two places:
- - Add the entry under `nav:` with a human-readable title.
- - Remove it from `exclude_docs` if a stale entry exists.
-4. **Use relative links between published pages** (e.g. `[Architecture](architecture.md)`). MkDocs strict mode resolves these against `docs_dir`.
-5. **Link to repository files outside `docs_dir` relative to the Markdown file.** For example,
- `docs/operations/example.md` links to `examples/config.yaml` as
- `../../examples/config.yaml`. The source-link hook turns an existing in-repository file into a
- `/blob/<source-ref>/...` URL and a directory into `/tree/<source-ref>/...` during the build.
-6. **Run `make publish` locally** before pushing. CI runs `mkdocs build --strict`; reproduce that locally.
-7. **Code samples in docs are tested by reading.** They are not executed by CI, so the burden is on the author. Verify imports resolve from `switchyard/__init__.py`'s `__all__` (anything else is an internal path that may move).
-8. **Provider examples must match CLI resolution.** NVIDIA examples may use `NVIDIA_API_KEY` where the CLI supports that fallback. OpenRouter examples should use `https://openrouter.ai/api/v1` and pass `"$OPENROUTER_API_KEY"` via `--api-key`, or save it with `switchyard configure --provider openrouter`, unless the code being documented actually adds an `OPENROUTER_API_KEY` fallback.
-
-## CI Hygiene
-
-`.github/workflows/docs.yml` mirrors the conventions in `ci.yml` — match them when editing:
-
-- **Path-filtered triggers** on `docs/**`, `mkdocs_hooks.py`, `mkdocs.yml`, `pyproject.toml`,
- `uv.lock`, and the workflow file. Keeps unrelated PRs out of the docs job graph.
-- **Docs-only PRs skip full CI.** The lightweight change detector and required `CI Success` job
- still run, while published-site validation remains owned by this workflow and the focused README
- or getting-started workflows run when their source pages change.
-- **Read-only default permissions** at the workflow level. Each job re-declares write scopes only when it needs them (`contents: write` for the Pages deploy, `pull-requests: write` for the preview comment).
-- **`concurrency` group `${{ github.workflow }}-${{ github.ref }}`** with `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`. Superseded PR runs are cancelled; main runs queue so the `gh-pages` writes don't race.
-- **Workflow-level `MKDOCS_SOURCE_REF`** resolves from
- `${{ github.event.pull_request.head.sha || github.sha }}`. Pull requests use the immutable head
- commit; pushes use the pushed commit. Keep this environment override on both build event types.
-- **`astral-sh/setup-uv@v6`** with `enable-cache: true` and `cache-dependency-glob: "uv.lock"`. Cache is keyed off the same lockfile the rest of the project uses.
-- **`uv sync --only-group docs --locked`** installs just the docs group, deterministically.
-- **`uv run --only-group docs mkdocs build --strict`** is the build step. The local equivalent is `make publish`.
-- **Preview job gated to same-repo PRs.** `GITHUB_TOKEN` from a fork PR has no write scope on `gh-pages`, so the `if:` clause checks `head.repo.full_name == github.repository`. Don't switch to `pull_request_target` to "fix" this — that runs untrusted PR code with write secrets.
-- **Single artifact handoff between jobs.** The `build` job uploads `site/`; `deploy` and `preview` download it. Don't duplicate the build inside either downstream job — it diverges from what was validated.
-
-If the workflow needs a new job (e.g. link check, spell check), keep it inside this file and gate it on the same path filter so it doesn't fan out to unrelated PRs.
-
-## Failure → Fix Map
-
-| Symptom | Fix |
+| Concern | File |
|---|---|
-| `WARNING - A reference to 'X.md' is included in the 'nav' configuration ... is not found in the documentation files` | The nav points at a file that doesn't exist under `docs/`. Add the file or drop the nav entry. |
-| `WARNING - Doc file 'X.md' contains a link 'Y.md', but the doc does not exist` | Bad relative link. Use a path relative to the Markdown file. Existing targets outside `docs_dir` are rewritten by `mkdocs_hooks.py`; missing and repository-escaping paths intentionally remain visible to strict validation. |
-| `WARNING - Doc file 'X.md' is excluded from the build but its 'nav' entry references it` | The file is both in `nav:` and in `exclude_docs:`. Pick one. |
-| `WARNING - The following pages exist in the docs directory, but are not included in the "nav" configuration` | Either add the page to `nav:` (publish it) or add it to `exclude_docs:` (hide it). The "do nothing" option doesn't exist under strict. |
-| Repository links in a PR preview point at `main` | Confirm `MKDOCS_SOURCE_REF` is present in the build job and resolves to `github.event.pull_request.head.sha`; local builds intentionally fall back to `main`. |
-| Preview job fails with `Permission to <repo>.git denied to github-actions[bot]` on a fork PR | Expected — the preview job is gated to same-repo PRs. If the gate is firing on a same-repo PR, check that `github.event.pull_request.head.repo.full_name` resolves correctly. |
-| GitHub Pages site loses PR previews after a `main` deploy | Confirm `keep_files: true` on the `peaceiris/actions-gh-pages` step. The main deploy must not wipe `pr-preview/*`. |
-| `make env` fails with `uv: command not found` | Install `uv` per the project Setup docs (see `AGENTS.md`). The Makefile shells out to `uv`; no separate Python toolchain is bootstrapped. |
-
-## Anti-Patterns
-
-- **Publishing internal design notes.** Anything under `docs/` that isn't a user-facing walkthrough or reference belongs in `exclude_docs`, not in `nav:`. Internal notes drift faster than the public surface and confuse users who land on them from search.
-- **Hard-coded same-repository GitHub blob/tree URLs.** They pin the repository and source ref,
- which breaks forks and branch-specific builds. Use a path relative to the Markdown file and let
- `mkdocs_hooks.py` derive the source URL from `mkdocs.yml`.
-- **Disabling `strict: true`** to make a CI failure go away. The warning is the bug. The two legitimate fixes are: fix the broken reference, or add the file to `exclude_docs`.
-- **Importing internal symbols in published examples.** Code in published pages must import from `switchyard` (the public API), not from `switchyard.lib.*` or any other internal path. Anything outside `switchyard/__init__.__all__` can move without a deprecation.
-- **Reintroducing a separate `requirements-mkdocs.txt`.** Docs deps belong in the `docs` group in `pyproject.toml` so `uv.lock` is the single source of pinned versions. Two pinning surfaces drift.
-- **Switching the preview job to `pull_request_target`** to make fork previews work. That trades a missing preview for a real supply-chain risk. The current `if:` gate is the right answer.
-
-## References
-
-- `mkdocs.yml` — published-site config
-- `mkdocs_hooks.py` — repository-relative source-link rewriting
-- `docs/README.md` — local build instructions
-- `docs/Makefile` — `env / html / publish / live / clean`
-- `.github/workflows/docs.yml` — build + deploy + preview pipeline
-- `pyproject.toml` — `[dependency-groups]` `docs = [...]`
-- [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — broader CI/validation guidance (ruff, mypy, pytest gates)
-- [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) — load before editing docs that cite specific symbols, file paths, or APIs
+| Navigation, exclusions, theme | `mkdocs.yml` |
+| Source-link rewriting | `mkdocs_hooks.py` |
+| Local commands | `docs/Makefile` |
+| Build, preview, deployment | `.github/workflows/docs.yml` |
+| Documentation dependencies | `pyproject.toml` `docs` group |
+
+## Workflow
+
+1. Decide whether a new page is public. Public pages go in `nav`; internal notes go in
+ `exclude_docs`.
+2. Match the surrounding file naming and documentation style.
+3. Use relative links. For repository files outside `docs/`, use paths relative to the Markdown
+ file and let `mkdocs_hooks.py` produce the source URL.
+4. Verify public examples use supported public imports and current CLI syntax.
+5. Run the strict build:
+
+```bash
+cd docs
+make publish
+```
+
+## CI Constraints
+
+- Keep the docs workflow path-filtered.
+- Keep default permissions read-only and grant write access only to deployment jobs.
+- Keep PR previews limited to same-repository pull requests.
+- Do not use `pull_request_target` to run untrusted documentation code with write permissions.
+- Build once and pass the `site/` artifact to preview and deployment jobs.
+- Preserve `keep_files: true` so a main deployment does not remove PR previews.
+
+Common strict-build fixes are direct: add or remove a missing nav entry, repair the relative link,
+or explicitly exclude an internal page. Do not disable strict mode.
diff --git a/.agents/skills/switchyard-lib-core/SKILL.md b/.agents/skills/switchyard-lib-core/SKILL.md
deleted file mode 100644
index be4e8e026..000000000
--- a/.agents/skills/switchyard-lib-core/SKILL.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-name: switchyard-lib-core
-description: Use when adding, modifying, refactoring, renaming, restructuring, deprecating, or reviewing anything under `switchyard/lib/` — profiles, request/response processors, backends, translators, stats collection, intake, telemetry, observability, routing decisions, or CLI wiring that builds a runnable profile. Triggers on phrases like "add a profile", "new processor", "new backend", "wire stats", "add a preset", "track per-tier …", "intake telemetry", "rename random_routing", "refactor construction", or any edit to `switchyard/lib/profiles/`, `processors/`, `backends/`, `translators/`, or route-table code.
----
-
-# Switchyard Lib Core
-
-## Overview
-
-Switchyard construction is profile-backed. A typed profile config owns how its
-runtime is built, and serving through the current Python endpoints adapts that
-runtime with `ProfileSwitchyard`. Do not reintroduce factories, recipes,
-middleware bundles, request/response pipeline wrappers, or resource-cache
-construction paths.
-
-The chain executor still runs the same logical stages:
-
-```text
-request-side work -> LLMBackend -> response-side work -> TranslationEngine
-```
-
-Profiles make that shape local to the behavior being implemented instead of
-splitting it across factory hooks and global registries.
-
-Pair this skill with [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md)
-before editing to build an impact map, and with
-[`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) after to pick the
-right validation set. If the change is driven by a launcher need, also read
-[`switchyard-coding-agent-launchers`](../switchyard-coding-agent-launchers/SKILL.md).
-
-## Quick Reference
-
-| I want to add or change… | Start here |
-|---|---|
-| A new profile | Add a typed config + runtime under `switchyard/lib/profiles/`. The config should expose `build()` and return a profile runtime. Wrap with `ProfileSwitchyard` only when the existing Python HTTP endpoint contract needs `.call(...)`. |
-| A new request-side behavior | Prefer making it profile-local. If it still needs to be reusable before the backend call, implement a plain component with async `process(ctx, request)` and compose it inside the owning profile config. |
-| A new response-side behavior | Prefer making it profile-local. If it still needs to be reusable after the backend call, implement a plain component with async `process(ctx, response)` and compose it inside the owning profile config. |
-| A new backend | Subclass the Rust-owned `LLMBackend` from `switchyard/lib/roles.py`; place it under `switchyard/lib/backends/`. Declare `supported_request_types` so translation can normalize. Compose it from the profile config that owns the behavior. |
-| An OpenAI-compatible provider target such as NVIDIA Inference Hub or OpenRouter | Use the existing OpenAI-compatible backend/profile with `base_url`, `api_key`, and model id wiring. Add a new backend only when the provider has a real wire-format, auth, retry, or health contract that cannot fit that path. |
-| Direct Rust component bindings | Add concrete PyO3 classes under `crates/switchyard-py/src/component_bindings/`, keep config bindings near the component binding that consumes them, and expose them lazily from `switchyard_rust/components.py`. Do not keep growing `core_bindings.rs` or `switchyard_rust/core.py` with concrete component classes. |
-| Route YAML / model dispatch | Use `switchyard/cli/route_bundle.py` and `switchyard/lib/route_table_builders.py`. They build `RouteTable` entries from profile-backed runtimes and keep launchers plus `switchyard serve --routing-profiles` on one path. |
-| Route sub-agent traffic to a fixed worker target | Set `subagent_target: <target-id>` in any profile's common envelope (consumed like `type` in Rust `SerializedProfileConfig`, `crates/switchyard-components-v2/src/config/parsing.rs`). The Python loader (`switchyard/lib/profiles/loader.py`) wraps the built profile in `SubagentOverrideProfile`; detection is the Rust-bound `is_subagent_request(headers)` from `switchyard_rust.profiles`, a thin wrapper over `Metadata::from_headers` + `Metadata::is_subagent_work` in `crates/protocol/src/metadata.rs` (the canonical lineage fact and work-vs-maintenance policy). On the libsy `Algorithm` path, wrap with the `SubagentOverride` combinator (`crates/libsy/src/algorithms/subagent_override.rs`; Python: `switchyard.libsy.algorithms.subagent_override`). Do not re-implement header sniffing inside individual profiles or algorithms. |
-| Shared/persistent session-affinity pins across workers or pod churn | Configure the latency route with `session_affinity: true` + `affinity_store: redis` + `affinity_store_url` (optional `affinity_store_ttl_seconds`, `affinity_key_prefix`); the escalation_router route takes the same `affinity_store*` keys (no `session_affinity` flag — its latch is always on; default prefix `swyd:esc:`). `SessionAffinity` keeps the Rust `SessionCache` as L1 and reads/writes through the `AffinityPinStore` L2 (`switchyard/lib/redis_pin_store.py`), fail-open behind a 0.1s socket timeout and a 3-failure/10s-cooldown circuit breaker (`switchyard_affinity_l2_breaker_open` gauge). Requires the `switchyard[affinity-redis]` extra. |
-| Stats / telemetry | Reuse `StatsRequestProcessor`, `StatsResponseProcessor`, `StatsLlmBackend`, and `StatsAccumulator`. A profile config should thread one accumulator through all three when stats are enabled. Do not write a parallel collector. |
-| A fixed-path endpoint contributed by per-route components | Set `Endpoint.register_once = True`; `build_switchyard_app(...)` mounts the first instance while still running every component's lifecycle. Leave the default `False` for configurable endpoint classes that may mount distinct instances. |
-| Per-endpoint attribution on `/metrics` for a Python backend that can't be wrapped by `StatsLlmBackend` | Set `ctx.selected_model = endpoint_id` before returning the response. Also set `ctx.backend_call_latency_ms = upstream_call_ms` so the response processor can compute routing overhead. `LatencyServiceLLMBackend.call` is the reference. |
-| Spend/tokenomics attribution when a front proxy (LiteLLM) sits above Switchyard | Stamp each upstream attempt with the `x-litellm-spend-logs-metadata` request header (selection re-stamped per failover attempt, one `router_correlation_id` uuid per client request) and record the successful attempt's selection in `ctx.metadata[CTX_ROUTE_SELECTION]`; the endpoint layer maps it to the `x-switchyard-*` response headers via `route_selection_headers` in `lib/endpoints/route_selection.py` — stamped by `dispatch.serialize_chain_result` on success and by `upstream_error.handle_chain_exception` when a failure follows a billed upstream success. Header values are sanitized there (client-controlled `router_model` must stay legal header material). `LatencyServiceLLMBackend.call` is the reference; the payload contract lives on `CTX_ROUTE_SELECTION` in `switchyard/lib/proxy_context.py`. |
-| State metrics on `/metrics` | Register a `PrometheusEmitter` via `switchyard.lib.endpoints.prometheus_emitter.register(...)` and unregister on `shutdown()`. This is for backend-owned state, not request-flow counters. |
-| Error-rate / retry-recovery counters | Use `switchyard.lib.endpoints.outcome_metrics`. FastAPI middleware records client outcomes. A retrying Python backend records each upstream attempt itself (and `record_retry_recovered()`) and sets `CTX_UPSTREAM_ATTEMPTS_RECORDED` so the endpoint skips its fallback — `LatencyServiceLLMBackend.call` is the reference. Single-attempt backends (Rust native / passthrough / multi) record nothing themselves; the endpoint fallback (`record_upstream_attempt_success` / `record_upstream_attempt_failure` in `upstream_error.py`, called from `dispatch_chat_request` and `handle_chain_exception`) counts their one attempt. Don't add a `model` label — these counters are layer-aggregate. Keep labels bounded. For a per-model error breakdown, emit a backend-owned counter via the `PrometheusEmitter` instead (labels bounded to config-derived ids: the route id `config.route_model` + endpoint ids, else the `other` sentinel) — `LatencyServiceLLMBackend._render_prometheus_lines` exposes `switchyard_latency_upstream_attempts_total{requested_model,upstream_model,outcome,code}` next to the aggregate, leaving the shared counter model-free. |
-| Per-event error log | Use `switchyard.lib.endpoints.upstream_error_log.log_upstream_attempt_failure(...)` on the failure path. Events belong in logs/traces, not Prometheus sample timestamps. |
-| CLI launcher integration | Build one profile-backed `SwitchyardApp` with `build_tier_passthrough_switchyard(...)` for single-target mode, or merge route YAML with `load_route_bundle_table(...)`. Hand the result to `build_switchyard_app`. |
-| A new preset | Put preset helpers beside the profile config they produce, under `switchyard/lib/profiles/`. Presets should return typed config objects, not runnable chains. |
-
-## Profile Pattern
-
-Profile-owned construction keeps the full behavior in one reviewable module:
-
-1. Define a typed config with validation close to the profile.
-2. Implement `build()` on the profile config.
-3. Construct request-side helpers, backend, response-side helpers, and shared
- stats accumulator inside `build()`.
-4. Return the profile runtime.
-5. Use `ProfileSwitchyard(config.build())` only when serving through the
- existing Python endpoint contract.
-
-Random routing, deterministic routing, escalation-router, passthrough, no-op,
-stage-router, and latency-service profiles are the reference set under
-`switchyard/lib/profiles/`.
-
-## Anti-Patterns
-
-| Anti-pattern | What to do instead |
-|---|---|
-| Reintroducing factories, recipes, middleware bundles, request/response pipeline wrappers, or a resource cache to build a chain. | Put construction in the owning profile config. Use `RouteTable` only for model-id dispatch across already-built profile-backed runtimes. |
-| Writing a new stats collector beside the existing stats stack. | Thread one `StatsAccumulator` through `StatsRequestProcessor`, `StatsLlmBackend`, and `StatsResponseProcessor`. |
-| A CLI launcher assembling divergent chains inline. | Use `build_tier_passthrough_switchyard(...)` for one target or `load_route_bundle_table(...)` for route YAML. |
-| A new role-shaped abstraction invented outside the backend role. | Keep pre-call logic in request-side profile code or plain request components, call logic in `LLMBackend`, post-call logic in response-side profile code or plain response components, and final wire conversion in `TranslationEngine`. |
-| Adding an OpenRouter-specific backend or translator just to point at `https://openrouter.ai/api/v1`. | Route it through the OpenAI-compatible backend/profile and provider configuration. Keep provider-specific code for actual protocol differences. |
-| Making route YAML declare arbitrary Python processors. | Route YAML is deployment config for supported profile route types. Runtime-only hooks such as intake are injected by the caller through the route-table builder kwargs. |
-| Hand-billing token costs from raw stats fields — charging `prompt_tokens` at the fresh-input rate and adding `cached_tokens` on top. | `prompt_tokens` in stats snapshots is **total** input: `uncached + cached_tokens + cache_creation_tokens` (Anthropic's three sibling usage counters are normalized into it). Fresh input = `prompt − cached − creation`. Use the built-in estimators — the snapshot's own `cost_estimate`, `estimate_model_cost()` in `cost_estimator.py`, or Rust `stats/cost.rs` — instead of ad-hoc math; ignoring the subtraction overstates cost ~5× on cache-heavy agentic traffic. |
-
-## When Something Genuinely Doesn't Fit
-
-Ask before changing Rust-owned backend role classes, public API exports, HTTP endpoints,
-or dependencies. Bring the smallest concrete delta you can describe. If the
-change needs reusable request-side or response-side behavior, first prove why a
-profile-local helper is insufficient.
-
-## Related Skills
-
-- [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) — run before any change here to map importers, profiles, and tests.
-- [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — run after to pick the smallest local validation set that mirrors CI for the surface you touched.
diff --git a/.agents/skills/switchyard-pr-reviewer/SKILL.md b/.agents/skills/switchyard-pr-reviewer/SKILL.md
deleted file mode 100644
index e0c8e05dc..000000000
--- a/.agents/skills/switchyard-pr-reviewer/SKILL.md
+++ /dev/null
@@ -1,202 +0,0 @@
----
-name: switchyard-pr-reviewer
-description: >
- Multi-mode, adversarially-verified PR review for switchyard that drafts inline comments
- the maintainers' way. Use when asked to "review this PR", "do a live/code review", "walk
- me through this PR and flag anything", "check correctness / tests / design vs the ticket",
- "is this serious / blocking?", "review the Rust changes", or "post comments on a PR".
- Sequences correctness, test-quality, ticket-coherence, simplify, docs, stale-comment, and
- Rust-craft modes; dispatches Rust to rust-code-reviewer. Every phase has a self-contained
- manual path; when the host CLI provides them, built-in slash skills are optional
- accelerators. Drafts first, posts only the approved subset, never auto-posts.
----
-
-# Switchyard PR Reviewer
-
-The switchyard-specific **orchestrator** that sequences review MODES and enforces two
-contracts: **adversarial verification** (every finding refuted-or-confirmed against real
-code) and **anti-slop** (no obvious/restating comments, no auto-posting). It routes Rust to
-the `rust-code-reviewer` skill. **The workflow is self-contained** — the built-in slash
-skills named below are *optional accelerators* for hosts that have them (e.g. Claude Code);
-where they're absent, run the phase's manual steps.
-
-Three pointers (the phases below carry the full contract):
-1. Draft first; post only the approved subset (Phases 8–9).
-2. Verify every finding against real code before reporting (Phase 3).
-3. Comments-only intent never edits code (dispatch table + Phase 2).
-
-**Prerequisites:** an authenticated `gh` CLI (PR data + posting) and, for ticket coherence, the `linear-server` MCP (optional — degrade to the PR description if absent).
-
----
-
-## When to use / dispatch
-
-Pick modes by what the diff touches and what the user asked. Run them as PHASES (below);
-multiple usually apply. The **Optional accelerator** column names a Claude Code slash-skill
-that can speed a phase up **if the host CLI has it** — it is never required; absent it, run
-that phase's manual steps. **Refer to, don't copy, any linked tool.**
-
-| Diff signal / user intent | Mode → Phase | Optional accelerator (else run the phase manually) |
-|---|---|---|
-| "review this PR", general bug hunt | Correctness (Phase 2/3) | `/code-review` if available (effort high→max = broader, may be uncertain) |
-| "walk me through it and flag" / "live review" | Guided walk-through (intent→plug-in→per-fn→tests, one chunk/turn) | — (interactive, no fan-out) |
-| Cleanup / "I dislike big docstrings" / quality, NOT bugs | Simplify: reuse / simplification / efficiency / altitude | Run the 4 angles **manually** for a comments-only review. `/simplify` (if available) is a shortcut ONLY when the user asked to APPLY cleanups — it mutates the tree by default, no comment-only flag. |
-| `crates/*` Rust, PyO3/FFI, translation, async, locks | Rust-craft (P0/FFI-first) | **rust-code-reviewer** skill — do NOT restate its rules |
-| New/changed tests, suspicious coverage | Test-quality (Phase 5) | — (fan-out one agent per test file) |
-| Linear ticket / "is this coherent with the ticket" / "done-when" | Design-coherence (Phase 4) | `mcp__linear-server__get_issue` (or read the ticket however the host exposes it) |
-| `*.md` / README / docs changed | Docs-accuracy + production-doc structural review (Phase 4b) | — (docs lens) |
-| In-code comments/docstrings that may contradict shipped code | Stale-comment coherence (Phase 2 finder) | — (grep) |
-| Security-sensitive (auth, secrets, headers, deserialization) | Security (Phase 2) | `/security-review` if available |
-| "approve it / LGTM" | Summary verdict | `gh pr review <N> --approve` |
-| "review thoroughly, give me your views" (structured artifact) | Verdict→Overview→Verification→Findings (Phase 8 format) | `/review` if available |
-
-Mixed Python + Rust: run Python modes here, dispatch `crates/*` hunks to
-`rust-code-reviewer` (P0-first if the user said "P0s only").
-
----
-
-## Severity taxonomy
-
-Use the word labels consistently. Correctness outranks cleanup/altitude when a cap forces a
-cut. Tag the finding TYPE in parens, e.g. `Blocking (vacuous — the "clip" test never clips)`,
-`Blocking (project rule)`, `Important (reuse — duplicates StageRouterFactory.validate)`.
-
-| Label | Meaning | Examples from past PRs |
-|---|---|---|
-| **Blocking** | Real bug, hard repo-rule violation, dead public/FFI surface, vacuous/misleading test, must-fix-before-merge | wrong-slot `extra_request_processors=`; `tests_passed` substring veto; "clip" test never clips |
-| **Important** | Correctness degradation, design/altitude leak, hot-path waste, contract/parity inconsistency — real but non-blocking | wire-format parsing in policy layer; 3-copy OpenAI `/v1/models` shape; type-safety hole |
-| **Minor** | Stale comment/doc, small footgun, missing intent comment, edge case acceptable-as-is | "15 scorers" where it's 14; dict-ctor skips `${ENV}` interpolation |
-| **Style** | Idiom, naming, redundant test, AI over-enumeration — fold into summary, rarely post individually | `plan` alias + self-justifying test; obvious `///` docs restating the fn name |
-
-Rust mode reports **P0 / P1 / P2**; map P0→Blocking, P1→Important, P2→Minor.
-
----
-
-## PHASES
-
-### Phase 0 — Scope & gather
-**Goal:** know exactly what the change CLAIMS to do before reading a line of logic.
-**How:**
-- `gh pr view <N> --json title,body,headRefOid,headRefName,commits`, `gh pr diff <N> --stat`, then full `gh pr diff <N>`.
-- Fetch the branch locally — **the code is often not on `main`:** `git fetch origin <branch>`, read source from it.
-- Pull the linked Linear ticket (SWITCH-*) named in the title/body via `mcp__linear-server__get_issue`; capture its scope and "Done when" criteria. No ticket → use the PR description as stated intent.
-- Record `HEAD_SHA=$(gh pr view <N> --json headRefOid -q .headRefOid)`.
-
-**Exit gate:** state in 1–2 lines "what this PR does" and "what the ticket asked for", and whether they're additive/bridge vs. behavior-changing.
-
-### Phase 1 — Dispatch to modes
-**Goal:** choose the minimal set of modes that fit this diff.
-**How:** apply the dispatch table. Honor explicit user scoping ("P0s only", "just the Rust", "design + ticket coherence", "tests for wrong reasons"). For "walk me through", switch to interactive one-chunk-per-turn cadence: system context (the 4-role chain) → the function's plug-in point → per-field behavior → tests, pausing each turn. Don't drop the user into a function cold.
-
-**Exit gate:** an ordered mode list, and whether posting/fan-out is in scope.
-
-### Phase 2 — Per-mode finders (fan-out)
-**Goal:** surface candidates with `file:line` + one-line summary + concrete failure/cost.
-**How** (read the actual current source, not just the diff; grep callers of changed signatures and references to deleted symbols):
-- **Correctness:** manual line-by-line scan + removed-behavior auditor + cross-file tracer (optionally accelerate with `/code-review` if the host has it). Trace each runtime field to where it's set, including into Rust. Carry a provisional **BUG / DEAD-CODE / DESIGN-CHOICE** label into Phase 3.
-- **Simplify:** run the 4 angles (reuse / simplification / efficiency / altitude) MANUALLY for a comments-only review, one angle per agent, in a single message. Use `/simplify` only if it's available AND the user asked to apply cleanups.
-- **Stale code-comment / coherence-with-shipped-code:** grep for comments that disagree with the code beside them — count comments that no longer match; docstrings/knob lists describing options the loader now rejects; mentions of a branch deleted in this PR; AGENTS.md-banned bookkeeping comments (`SWITCH-*`, `Phase-A`, commit hashes, `TODO(step-N)`). Minor normally, Important if it would mislead a maintainer.
-- **Test-quality:** one agent per changed test file (see Phase 5).
-- **Rust-craft:** the `rust-code-reviewer` skill on `crates/*` hunks.
-- **Big PRs:** the user may ask for an explicit N-agent sweep ("10 sub agents", "don't post anything") partitioned by area × lens. Honor "analysis-only".
-
-**Dedup:** collapse findings at the same line/mechanism; note convergence ("found by 2 agents") as a confidence signal — NOT extra severity.
-
-**Exit gate:** a deduped candidate list, each with evidence anchors and a provisional bug/dead/design label.
-
-### Phase 3 — Adversarial verification gate (mandatory)
-**Goal:** kill false alarms. **A candidate survives only if you re-read the code and it still holds.**
-**How — for each candidate, label CONFIRMED / PLAUSIBLE / REFUTED, and classify BUG / DEAD-CODE / DESIGN-CHOICE:**
-- Read the real code path end-to-end. Trace fields across the FFI boundary. Confirm wiring is live (endpoint mounted? export consumed?) before calling anything dead.
-- **Refute by execution or grep, not by reasoning.** If you reason instead of running, SAY SO ("this is reasoning, not a test").
-- **Prove a rule inert by cross-checking the PR's own calibration data and commits.** (Mined: a `=`-instead-of-`+=` scorer that fired 0/30,851 times AND was absent from `DEFAULT_WEIGHTS` → DEAD-CODE, not a live bug — which changes the fix.)
-- If a fan-out agent grepped, confirm it grepped the **right working tree** (classic false negative: grepping a sibling branch lacking this PR's Python).
-- Drop REFUTED. Keep CONFIRMED + PLAUSIBLE. De-escalate judgment calls to Minor/Style or a question.
-
-**Worked false-alarms to kill** (each really survived a finder and died on a re-read):
-
-| Candidate (sounds real) | Why it's REFUTED on reading the code |
-|---|---|
-| "streaming bypasses the detection path" | the status check precedes the stream branch; detection runs |
-| "error escapes the handler → 500" | always retried then translated to 400; never escapes |
-| "new error helper duplicates the existing one" | one passes the body verbatim, the other builds per-inbound envelopes — different jobs |
-| "this config / field has zero consumers" | agent grepped the wrong tree; it's wired on the PR branch |
-| "lazy singleton is a lifecycle leak" | the type is stateless — no startup/shutdown, not a leak |
-| "catch order shadows the broader error" | the errors are siblings, not parent/child — harmless |
-| local test run fails | diagnose env (e.g. toolchain version mismatch) — NOT a PR defect |
-
-**Exit gate:** every surviving finding has a "verified against `<file:line>`" note and a bug/dead/design label; every dropped one has a one-line reason.
-
-### Phase 4 — Design-coherence vs the ticket / stated intent
-**Goal:** does the implementation match what the PR/ticket CLAIMS, at the right altitude?
-**How:**
-- Compare impl to the ticket's scope and "Done when". Divergence is often *improvement* — say so — but isolate the one real gap (e.g. ticket promised "all multi-target routes" but impl is stage-router-only).
-- Altitude: special cases on shared infra, wire-format parsing leaking into the policy layer, tuning-data-masquerading-as-config → recommend generalizing.
-- Defend **intentional** asymmetries instead of manufacturing a finding.
-- Scope creep / mixed concerns / gratuitous churn → call out per commit-discipline.
-
-**Exit gate:** a coherence verdict (matches / improves-on / diverges-from) with the one real gap isolated.
-
-### Phase 4b — Production-doc structural review (when a `*.md` design/production doc changed)
-**Goal:** a credible, roughly-halved doc — not a render-only pass.
-1. **Lead with the credibility killer:** find the contradiction first (conflicting numbers / one story told several ways). A self-contradicting doc is untrustworthy regardless of prose.
-2. **Produce a CUT / FIX / KEEP plan with an explicit line budget**, targeting ~half: CUT fragile ASCII diagrams, derivable knob tables, drift-prone calibration dumps; FIX stale references deleted in this PR; KEEP the production core.
-3. Render bugs and conflicting numbers are Important/Minor; the CUT/FIX/KEEP plan is the deliverable.
-
-**Exit gate:** a CUT/FIX/KEEP plan with a target line count and the lead credibility-killer named.
-
-### Phase 5 — Test-quality pass
-**Goal:** catch tests that look rigorous but exercise nothing, and the missing core-path test.
-**Headline gate — the deletion/mutation test:** a test survives only if **deleting or mutating the branch it claims to cover makes it fail.** Apply this first to every changed test.
-- **Vacuous / passes-for-wrong-reason:** the "clip" test whose weight sum is already in range; a test pinned so the gated branch is never reached.
-- **Claims a path it doesn't run:** a "concurrent" test looping sequentially.
-- **Framework-only / tautological:** asserting `return request` is unmutated; `confidence == abs(score)`; a "rejects unknown picker" actually caught by a pydantic `Literal` a layer earlier.
-- **Over-enumeration (AI bloat):** collapse 4 near-identical "rejects bad key" to ~3; name it, don't post each.
-- **Misleading name:** `..._dispatches_and_translates` on an identity case.
-- **The biggest gap:** is the *core value path* exercised end-to-end?
-- Don't demand Rust unit tests for one-line PyO3 delegations — testing through Python matches repo style.
-
-**Exit gate:** each flagged test names the wrong-reason it passes (or the gap) and survives/fails the deletion test, with a concrete fix.
-
-### Phase 6 — Anti-slop filter
-**Goal:** drop low-value noise; enforce brevity. Run on every surviving finding AND your own comment bodies. See [`references/anti-slop-checklist.md`](references/anti-slop-checklist.md).
-**Drop / fold-into-summary if the comment:** restates a type-system guarantee (pydantic `Literal`/type hint); asserts an identity/tautology; duplicates a guard a layer earlier; restates the obvious; is an over-enumeration item; is pre-existing/out-of-diff; was retired by real-world context.
-**Enforce on bodies:** SHORT and direct; no thinking-out-loud or "wait… actually…"; no project-management refs; uncertain intent → frame as a question ("Intentional?"); never claim reasoning as tested. **Do flag** the author's own thinking-out-loud comments left in the diff (post as a Minor "drop this stray comment").
-
-**Exit gate:** a tight, post-able set; everything dropped has a one-line reason.
-
-### Phase 7 — Severity triage & dedup
-Assign Blocking/Important/Minor/Style (+ TYPE tag), merge duplicates, order most-severe-first (correctness before cleanup). Map any P0/P1/P2 from Rust mode onto the word scale.
-
-**Exit gate:** a single ranked list, no duplicates.
-
-### Phase 8 — Calibrate & present (draft first)
-Structure as **Verdict → What this PR does → Verified (with `file:line`) → Findings (ranked, severity-tagged, one-line fix each) → Style (folded) → Bottom line.** Separate **blocking/correctness** from **latent/nice-to-have**. When asked "these are nothing serious right?", answer directly — don't hedge. Offer: post all / a curated subset / hold and hand a summary. **Do not post yet.**
-
-**Exit gate:** user has the draft and has chosen what to post.
-
-### Phase 9 — Post (explicit request only)
-Post exactly the approved subset, anchored to the current head SHA, never auto. Verify each post landed **by content** (re-fetch threads), not by trusting the API response. Resolve only your OWN threads, after verifying the fix in code ("commit messages aren't proof"). Never touch or submit the user's pending review.
-
-**Exit gate:** approved comments posted, each on the right line; nothing else changed.
-
----
-
-## Posting mechanics
-
-```bash
-N=<PR>
-REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
-SHA=$(gh pr view "$N" --json headRefOid -q .headRefOid) # always fresh — head moves
-BODY_FILE=$(mktemp)
-printf '%s' 'short, direct, present-tense body' > "$BODY_FILE"
-post() { gh api "repos/$REPO/pulls/$N/comments" -f commit_id="$SHA" -f path="$1" -F line="$2" -f side=RIGHT -F body=@"$3" --jq '.html_url'; }
-post "<file>" <line> "$BODY_FILE"
-```
-`-f` = raw string (`commit_id`/`path`/`side`); `-F` = typed field (`line`, `body=@file`). Use temp-file bodies by default; inline `-f body="..."` only for a short single-line ASCII body with no shell metacharacters.
-
-**Anchoring learned the hard way:** modified files are commentable only on lines inside the diff hunk; very large single-file additions can return `thread:null` → re-anchor on a smaller consuming file/line, never probe-spam. **One pending review per user** — if the user has an open pending review, append via GraphQL `addPullRequestReviewThread` (don't submit) or hand paste-ready text; standalone REST only after they submit. Verify by content: `gh api repos/$REPO/pulls/$N/comments --jq '.[] | "\(.path):\(.line) | \(.user.login)"'`.
-
-**Other modes:** approve → `gh pr review <N> --approve --body-file file` (only when asked); long doc review → one summary comment at line 1; PR body edits → `gh api -X PATCH /repos/$REPO/pulls/<N> -F body=@file`.
-
-**Never:** auto-post, post the full agent dump, retry a failing mutation into the user's live review, or fix code when only comments were requested.
diff --git a/.agents/skills/switchyard-pr-reviewer/references/anti-slop-checklist.md b/.agents/skills/switchyard-pr-reviewer/references/anti-slop-checklist.md
deleted file mode 100644
index 58bb0f476..000000000
--- a/.agents/skills/switchyard-pr-reviewer/references/anti-slop-checklist.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Anti-AI-slop checklist
-
-Run this in Phase 3 (verification) and Phase 6 (slop filter). It encodes the real false
-alarms and over-flagging seen across past reviews. The bar: a comment must teach the author
-something true that they'd act on.
-
-## A. Refute-before-report (Phase 3)
-A candidate dies unless you re-read the code and it still holds. Refute by execution or grep,
-never by vibes.
-
-| Refute by checking… | Real false alarms it would have killed |
-|---|---|
-| Read the actual path end-to-end | "streaming bypasses detection" — it doesn't; "ContextWindowExceeded → 500" — it's caught/translated |
-| Confirm the grep tree is the PR branch | "zero consumers" false negative from grepping a sibling branch lacking this PR's Python |
-| Check the error hierarchy | "catch-order shadows ConfigError" — siblings, not parent/child; order is harmless |
-| Check lifecycle/statefulness | "lazy translator singleton is a leak" — stateless, no startup/shutdown |
-| Read both files before "duplication" | context_error vs upstream_error do different jobs — not reuse |
-| Diagnose the environment | local test failing on rustc 1.92-vs-1.94 is an env issue, NOT a PR defect |
-| Confirm wiring is live | call something dead only after grepping all consumers (incl. FFI re-exports + tests) |
-
-Self-correction rules:
-- **Verify a post by CONTENT, not the API response** (`thread:null` can be misleading; a
- comment that appeared may be the user's UI comment, not yours).
-- **Re-verify on the moving head** before every post; diff the new commits to confirm your
- anchor line is unchanged.
-- **Verify fixes against code, not commit messages** ("commit messages aren't proof"); catch
- PARTIAL fixes (e.g. `.expect()` fixed in the anchored file but still present in the sibling
- files your comment named) and leave that thread open.
-- If you reasoned instead of running, **say so** ("this is reasoning, not a test").
-
-## B. Don't-post / fold-into-summary (Phase 6)
-Drop or fold, don't thread:
-- Restates what the code obviously says; obvious nit matching the file's existing conventions.
-- AI over-enumeration: near-identical tests / repeated assertions → recommend collapsing to ~3, name it once.
-- Pre-existing / out-of-diff / "not introduced here" → mention once, no thread.
-- Retired by real-world context ("legacy path is going away").
-- Framework-only / tautological tests as if they were bugs → categorize, don't inflate.
-- Style nits not worth their own thread → fold into the summary.
-- Demanding Rust unit tests for one-line PyO3 delegations.
-
-## C. Body hygiene
-- SHORT and direct (most comments 1–3 lines). No thinking-out-loud, no "wait/actually".
-- No project-management refs in the comment (no step/plan IDs); a plain ticket cite in a
- proposed `// TODO(SWITCH-NNN):` is fine.
-- Uncertain intent → ask the author ("Intentional?"), don't assert a bug.
-- Flag the author's own thinking-out-loud comments left in source.
-- Severity honesty: judgment calls are Minor/Style or questions, not Blocking; correctness
- outranks cleanup.
-
-## D. Process hygiene
-- Draft first; post only the approved subset; never auto-post; never post the full agent dump.
-- Never probe-spam throwaway comments to find a commentable line — re-anchor on a consuming line.
-- Never retry a failing mutation into the user's live pending review; never touch/submit the
- user's comments. Resolve only your own threads.
-- Comments-only means comments-only: do not fix/commit when only comments were requested.
-- One chunk at a time when walking the user through; don't dump a wall of text.
diff --git a/.agents/skills/switchyard-rust-review/SKILL.md b/.agents/skills/switchyard-rust-review/SKILL.md
new file mode 100644
index 000000000..b9a404ac4
--- /dev/null
+++ b/.agents/skills/switchyard-rust-review/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: switchyard-rust-review
+description: Review Switchyard Rust changes for correctness and maintainability. Use for pull requests or diffs touching crates, PyO3 bindings, async runtime behavior, streaming, protocol types, translation, algorithms, or LLM clients.
+---
+
+# Switchyard Rust Review
+
+Review the changed code and its live callers, not the entire repository. Findings lead, ordered by
+severity and anchored to a file and line. Verify each candidate against the current code path before
+reporting it; do not turn general Rust preferences into findings.
+
+## Review Checks
+
+- **Errors:** Production and test code must not use `.expect()`. Avoid `unwrap()` or panics on
+ fallible paths; propagate typed errors. Convert every PyO3 boundary failure into `PyErr`.
+- **Ownership:** Question `Arc`, `Mutex`, `Box`, and clones only when the code lacks a concrete
+ ownership, sharing, trait-object, or concurrency requirement. Do not prescribe a wrapper by
+ reflex.
+- **Async:** Check for locks held across `.await`, blocking work on executor threads, unbounded
+ queues, untracked spawned tasks, missing cancellation, and ignored backpressure.
+- **FFI:** Preserve Python-visible types, defaults, exceptions, and lifetimes. Do not hold the GIL
+ during blocking or awaited work.
+- **Streaming:** Preserve event order, termination, partial chunks, usage accounting, and error
+ frames across every supported wire format.
+- **Boundaries:** Keep protocol types neutral, translation in translation code, LLM calls in
+ clients, and routing behavior in algorithms or server wiring.
+- **Observability:** Use structured `tracing` fields, appropriate levels, bounded metric labels,
+ and no prompt content or credentials in logs.
+- **Tests:** Require behavioral coverage for changed contracts, especially protocol/translation
+ parity, streaming termination, errors, and Python/Rust boundaries. Avoid repetitive input
+ enumeration.
+
+## Validation
+
+Select the narrowest test that exercises the changed contract, then run:
+
+```bash
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test -p <affected-crate>
+```
+
+Use `cargo test --workspace` for shared protocol, public API, or cross-crate changes. Run affected
+Python tests when PyO3 behavior changes. Report anything not run and why.
diff --git a/.agents/skills/switchyard-stage-router-scorer/SKILL.md b/.agents/skills/switchyard-stage-router-scorer/SKILL.md
deleted file mode 100644
index 46c3f3c5c..000000000
--- a/.agents/skills/switchyard-stage-router-scorer/SKILL.md
+++ /dev/null
@@ -1,97 +0,0 @@
----
-name: switchyard-stage-router-scorer
-description: Score benchmark run trajectories through the stage-router Rust scorer and picker, then visualise score distributions. Use when you want to replay trajectories through the picker, analyse routing splits, or compare score distributions across configs.
----
-
-# Skill: switchyard-stage-router-scorer
-
-## Scripts
-
-| Script | Purpose | Input | Output |
-|--------|---------|-------|--------|
-| `benchmark/score_staged_run.py` | Score a live run dir via real picker | run dir path | per-turn JSONL + per-task CSV |
-
-## Quick Reference
-
-```bash
-# Score a run
-uv run python benchmark/score_staged_run.py --run benchmark/tb_runs/<run-name>
-# → /tmp/<run-name>-scores.jsonl (per turn)
-# → /tmp/<run-name>-per-task.csv (per task)
-
-# Custom threshold or window
-uv run python benchmark/score_staged_run.py \
- --run benchmark/tb_runs/<run-name> \
- --threshold 0.15 --window 3
-```
-
-## Scoring pipeline (what score_staged_run.py does per turn)
-
-```
-trajectory step (tool_use + tool_result)
- → append to cumulative Anthropic messages list
- → ChatRequest.anthropic({"model": ..., "messages": messages}) # Rust binding
- → dc.process(ctx, request) # DimensionCollector — one per task, accumulates state
- → get_tool_result_signal(ctx) # read signal from ctx
- → stage_score_signal(signal) # raw (score, confidence) from the Rust scorer (for analysis)
- → pick_capable_first(ctx, threshold) # actual cf decision (same ctx, no re-process)
- → pick_efficient_first(ctx, threshold) # actual ef decision (same ctx, no re-process)
-```
-
-**Key:** `dc.process()` is called **once per turn** on a single ctx. Both pickers read the signal
-already stored in that ctx — no duplicate processing.
-
-**What the picker does beyond raw score:**
-- **escalate** (`should_escalate`): `compacted` OR `severity >= 1.0` → force CAPABLE
-- **de-escalate** (`should_deescalate`): `tests_passed AND recent_write+edit >= 1 AND severity <= 0` → force EFFICIENT
-- `confidence < threshold` → fall_open to default tier (CAPABLE for cf, EFFICIENT for ef)
-- Only when `confidence >= threshold`: route by score direction
-
-## Per-turn JSONL schema
-
-```json
-{
- "task_name": "terminal-bench/...", "trial_name": "...", "run_id": "...",
- "reward": 1.0, "turn_depth": 5,
- "score": -0.83, "confidence": 0.95,
- "tool_name": "Bash", "is_error": false,
- "write_count": 2, "edit_count": 1, "read_count": 3,
- "no_error_streak": 4, "pure_bash_streak": 2, "tests_passed": false,
- "pick_cf": 1,
- "pick_ef": 0
-}
-```
-
-`pick_cf` / `pick_ef`: `1` = CAPABLE (Opus), `0` = EFFICIENT (Nemotron)
-
-## Per-task CSV columns
-
-`run_id, task_name, reward, n_turns, mean_score, mean_confidence,
-pct_strong_clear, pct_strong_uncertain, pct_weak_uncertain, pct_weak_clear,
-opus_pct_cf, nemotron_pct_cf, opus_pct_ef, nemotron_pct_ef`
-
-`opus_pct_cf` / `opus_pct_ef` are derived from actual `pick_cf` / `pick_ef` decisions, not score bands.
-
-## Band definitions (for histogram colouring, threshold T)
-
-| Band | Score range | cf default | ef default |
-|------|-------------|------------|------------|
-| strong_clear | ≥ T | Opus | Opus |
-| strong_uncertain | (0, T) | Opus (fall_open) | Nemotron (fall_open) |
-| weak_uncertain | (-T, 0) | Nemotron (fall_open) | Nemotron (fall_open) |
-| weak_clear | ≤ -T | Nemotron | Nemotron |
-
-Overrides can change any band. Use `pick_cf`/`pick_ef` for the true decision.
-
-## Key findings (v0.2.0 baseline tarballs, T=0.20)
-
-- Distribution is **highly bimodal** — most turns land in strong_clear or weak_clear
-- `cf, t=0.20`: ~34% Opus on partial run; ~42% on full baseline
-- `ef, t=0.20`: ~20% Opus on partial run; ~41% on full baseline
-- Live routing split differs from shadow score — Nemotron trajectories are shorter and reshape the distribution
-
-## Anti-patterns
-
-- Don't call `dc.process()` multiple times per turn for different pickers — both pickers read from the same ctx. One `dc.process()` call per turn is correct.
-- Don't infer routing split from score bands alone — overrides and fall_open change the actual decision. Always use `pick_cf` / `pick_ef`.
-- Don't compare cost directly across configs: Nemotron has ~39% cache hit rate vs ~92% for Opus.
diff --git a/.agents/skills/switchyard-testing-ci/SKILL.md b/.agents/skills/switchyard-testing-ci/SKILL.md
index f49f4f5e1..9aed5cc4b 100644
--- a/.agents/skills/switchyard-testing-ci/SKILL.md
+++ b/.agents/skills/switchyard-testing-ci/SKILL.md
@@ -1,331 +1,80 @@
---
name: switchyard-testing-ci
-description: Use when validating a Switchyard change, preparing or reviewing a PR, debugging CI failures (ruff, mypy, SPDX, pytest, slim-install), choosing which local tests to run, or diagnosing dependency, optional-extra, stale-name, CLI, server, translation, routing, stats, or live e2e failures. Triggers on phrases like "is this ready to merge", "CI is failing", "which tests should I run", or "how do I reproduce this locally".
+description: Select or debug Switchyard validation and GitHub CI. Use when asked which tests to run, whether a change is ready, why a CI job failed, how to reproduce CI, or whether live provider tests are appropriate.
---
-# Switchyard Testing and CI
+# Switchyard Testing And CI
-## Overview
+Read `.github/workflows/ci.yml` before claiming local CI equivalence. Select tests from the current
+diff and symbol references rather than a static subsystem inventory.
-**Pick the smallest local gate that is genuinely equivalent to what CI will run, then map failures
-to targeted fixes.** The two goals — move fast locally, never report a green run weaker than the CI
-gate you are claiming — usually conflict; this skill resolves that conflict from the current diff
-rather than from memory.
+## Validation Matrix
-If your change also touches code you have not yet read, run [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) first so the validation set covers the real impact, not just the diff surface.
-
-Rust crates under `crates/` (`switchyard-core`, `switchyard-translation`,
-`switchyard-components`, `switchyard-server`, `switchyard-py`) are active on the Rust core branch.
-For Rust-touching diffs, include `cargo fmt --all --check`, `cargo clippy --workspace
---all-targets -- -D warnings`, and the smallest trustworthy `cargo test` scope;
-use `cargo test --workspace` before calling a broad Rust MR ready.
-
-## Quick Reference
-
-| Situation | Command |
+| Change | Minimum trustworthy validation |
|---|---|
-| Inspect all local changes | `git status -sb && git diff HEAD --stat && git diff HEAD --name-only && git ls-files --others --exclude-standard` |
-| Pre-PR hermetic gate (default) | `uv run ruff check . && uv run mypy switchyard && env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"` |
-| Mirror CI pytest with no live creds | `env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"` |
-| Rust component crate change | `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test -p switchyard-components` |
-| Rust server crate change | `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test -p switchyard-server` |
-| Broad Rust crate change | `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace` |
-| Slim-install regression guard | see [Slim-install smoke gate](#slim-install-smoke-gate) |
-| Live e2e (only on explicit user request) | `NVIDIA_API_KEY=… uv run pytest tests/e2e/ -v -m integration -o addopts= --maxfail=10` |
-| Skill/docs change only | YAML frontmatter check + `git diff --check` (see [Skill/docs-only gate](#skilldocs-only-gate)) |
+| Markdown or skill Markdown only | Parse skill frontmatter when applicable; `git diff --check` |
+| Python implementation | Focused pytest, `uv run ruff check .`, `uv run mypy switchyard` |
+| Broad Python or public API | Hermetic full pytest plus lint and mypy |
+| One Rust crate | `cargo fmt --all --check`, workspace clippy, focused crate tests |
+| Shared Rust/API/FFI | Rust workspace tests plus affected Python tests |
+| Packaging, extras, top-level imports | The slim-install smoke commands from the current CI workflow |
+| Live provider behavior | Focused integration test only after explicit authorization |
-## Diff Selection First
-
-From the repo root, inspect the diff before choosing focused gates:
-
-```bash
-cd "$(git rev-parse --show-toplevel)"
-git status -sb
-git diff HEAD --stat
-git diff HEAD --name-only
-git ls-files --others --exclude-standard
-```
+## Standard Gates
-For a not-yet-edited area, search likely owners and their tests explicitly:
-
-```bash
-rg -n "request_engine|RequestTranslationEngine" switchyard tests
-```
-
-Use the changed paths and search results to choose the smallest trustworthy gate, then add any tests
-revealed by code search or by a failure.
-
-## CI Gates and Local Equivalence
-
-The hard GitHub Actions gates live in `.github/workflows/ci.yml`:
-
-- A lightweight change-detection job keeps the required `CI Success` check present on every pull
- request. Clearly documentation-only pull requests skip the full lint, test, Rust, typecheck, and
- install-smoke suite; pushes to `main` always run the complete suite.
-- `uv run ruff check .`
-- SPDX header check for every Python file found by CI, including `.agents/skills/**/scripts/*.py`
-- `uv run pytest tests/ -v -m "not integration"` on Python 3.12 through 3.14
-- Rust workspace gate: `cargo fmt --all --check`, `cargo clippy --workspace --all-targets -- -D warnings`,
- and `cargo test --workspace`
-- slim-install smoke: isolated `uv run --with` default install/import checks, heavy-package
- absence, and CLI help checks with `nemo-switchyard[cli,server] @ file://...`
-- `uv run mypy switchyard` is a signal job (`continue-on-error`) but should still be run for typed
- package code, public APIs, profiles, route bundles, backends, request/response models, and translation changes.
-
-The local pre-commit config also runs the Rust fmt/clippy gate when Rust files,
-`Cargo.toml`, or `Cargo.lock` change. Treat those hooks as hard failures; do not
-bypass them with `--no-verify`.
-
-Documentation-only classification is intentionally narrow: `docs/**`, repository-root Markdown,
-README files, GitHub issue/PR templates, benchmark Markdown, and skill Markdown. Markdown used as
-runtime prompt content is not excluded and still runs full CI.
-
-A CI-equivalent `ruff` claim means a clean checkout or generated artifacts removed. Do not treat
-`uv run ruff check . --exclude docs/.venv-docs --exclude docs/_build` as canonical PR validation;
-that is only a dirty-workspace workaround.
-
-If generated docs artifacts exist locally, prefer:
-
-```bash
-rm -rf docs/.venv-docs docs/_build site/_build
-git status -sb
-uv run ruff check .
-```
-
-## Standard Command Sets
-
-### Fast local loop
-
-```bash
-uv run pytest tests/test_<area>.py -v
-uv run pytest tests/test_<area>.py::test_name -v
-uv run ruff check .
-```
-
-Pytest uses `addopts = "-x"`; use `-o addopts= --maxfail=10` when finding all failures:
-
-```bash
-uv run pytest tests/ -v -o addopts= --maxfail=10 -m "not integration"
-```
-
-### Pre-PR package-code gate
-
-Use the hermetic test gate by default so local credentials cannot trigger live provider calls:
+Python pre-PR gate:
```bash
uv run ruff check .
uv run mypy switchyard
-env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"
+env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY \
+ -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"
```
-If you need to mirror the CI pytest command locally, run from a clean checkout or explicitly remove
-provider credentials first:
+Rust workspace gate:
```bash
-env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
```
-### Live integration/e2e gate
+Use `-o addopts=` when the repository's pytest defaults would stop failure collection too early.
+Run focused tests first, then broaden only when the changed contract or shared ownership warrants it.
-Run this only when the user asked for live validation and accepts upstream API calls:
+## Live Tests
-```bash
-NVIDIA_API_KEY=... uv run pytest tests/e2e/ -v -m integration -o addopts= --maxfail=10
-```
-
-`tests/e2e/conftest.py` and per-file markers/skips own credential behavior. Do not run live e2e as
-a default PR gate.
-
-### Slim-install smoke gate
-
-Run after touching `pyproject.toml`, lockfiles, top-level imports, optional extras,
-`switchyard/__init__.py`, CLI/server exports, or anything that could pull heavy packages into the
-default install:
+Integration tests can spend money, require credentials, and contact real services. Never run them
+as an automatic pre-PR step. Provision `NVIDIA_API_KEY` through the environment or a secret manager
+before running the user-authorized path, and state which provider was called:
```bash
-SWITCHYARD_ROOT="$(git rev-parse --show-toplevel)"
-SWITCHYARD_DEFAULT_PACKAGE="nemo-switchyard @ file://${SWITCHYARD_ROOT}"
-SWITCHYARD_EXTRAS_PACKAGE="nemo-switchyard[cli,server] @ file://${SWITCHYARD_ROOT}"
-cd /tmp
-uv run --isolated --no-project --python 3.12 \
- --with "${SWITCHYARD_DEFAULT_PACKAGE}" \
- python - <<'PY'
-import importlib.util
-import switchyard
-print('import OK, version:', switchyard.__version__)
-from switchyard import RandomRoutingPresets
-print('preset import OK:', sorted(RandomRoutingPresets.PRESETS))
-forbidden = [
- 'torch', 'transformers', 'huggingface_hub', 'litellm',
- 'datasets', 'tokenizers', 'safetensors', 'pyarrow', 'agents', 'mcp', 'docx',
-]
-extras = [m for m in forbidden if importlib.util.find_spec(m) is not None]
-if extras:
- raise SystemExit(f'FAIL: heavy packages pulled into slim install: {extras}')
-print('OK: heavy packages absent')
-PY
-uv run --isolated --no-project \
- --python 3.12 \
- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \
- switchyard launch claude --help >/dev/null
-uv run --isolated --no-project \
- --python 3.12 \
- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \
- switchyard launch claude --help 2>&1 \
- | grep -q -- '--routing-profiles' || { echo 'FAIL: --routing-profiles flag missing from help'; exit 1; }
-uv run --isolated --no-project \
- --python 3.12 \
- --with "${SWITCHYARD_EXTRAS_PACKAGE}" \
- switchyard serve --help >/dev/null
+uv run pytest tests/e2e/<focused_test>.py \
+ -v -m integration -o addopts=
```
-### Skill/docs-only gate
+## Skill Validation
-For `.agents/skills/` changes, validate YAML frontmatter, whitespace, and any Python helper scripts:
+Each retained skill must have YAML frontmatter with `name` and `description`:
```bash
-python - <<'PY'
+uv run python - <<'PY'
from pathlib import Path
-import yaml
-for p in Path('.agents/skills').glob('*/SKILL.md'):
- text = p.read_text(encoding='utf-8')
- if not text.startswith('---\n'):
- raise SystemExit(f'{p}: missing frontmatter start')
- end = text.find('\n---\n', 4)
- if end == -1:
- raise SystemExit(f'{p}: missing frontmatter end')
- data = yaml.safe_load(text[4:end])
- if not isinstance(data, dict) or not data.get('name') or not data.get('description'):
- raise SystemExit(f'{p}: missing name/description')
-print('OK: skill frontmatter parses')
-PY
-git diff --check
-find .agents/skills -path '*/scripts/*.py' -print
-```
-For any listed skill Python helper, run targeted lint and SPDX checks:
+import yaml
-```bash
-.venv/bin/ruff check --isolated .agents/skills/<skill>/scripts/<helper>.py
-python - <<'PY'
-from importlib.machinery import SourceFileLoader
-from pathlib import Path
-spdx = SourceFileLoader('spdx', '.hooks/add_spdx_headers.py').load_module()
-paths = [Path('.agents/skills/<skill>/scripts/<helper>.py')]
-bad = [str(p) for p in paths if not spdx.has_required_header(p)]
-if bad:
- raise SystemExit('missing SPDX header: ' + ', '.join(bad))
-print('OK: SPDX headers present')
+for path in Path(".agents/skills").glob("*/SKILL.md"):
+ parts = path.read_text().split("---", 2)
+ data = yaml.safe_load(parts[1]) if len(parts) == 3 else None
+ if not isinstance(data, dict) or not data.get("name") or not data.get("description"):
+ raise SystemExit(f"{path}: missing name or description")
+print("skill frontmatter is valid")
PY
+git diff --check
```
-`.agents` is gitignored, so stage new or modified skills explicitly:
-
-```bash
-git status --ignored -sb .agents/skills
-git add -f .agents/skills/<skill>
-```
-
-## Failure Map
-
-### Ruff
-
-- Generated docs/venv paths (`docs/.venv-docs/`, `docs/_build/`, `site/_build/`) are local debris;
- remove them rather than editing vendored/generated files.
-- Use autofix narrowly, then inspect the diff:
-
- ```bash
- uv run ruff check --fix .
- uv run ruff check .
- ```
-
-### SPDX
-
-CI requires this exact header in every Python file, after an optional shebang:
-
-```python
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-```
-
-Fix with:
-
-```bash
-python .hooks/add_spdx_headers.py path/to/file.py
-uv run ruff check .
-```
-
-### Pytest
-
-Classify before editing:
-
-- Optional package import (`torch`, `fastapi`, `prompt_toolkit`, `nemo_platform`) → keep
- optional deps out of top-level/default install paths; use lazy imports and clear runtime errors.
-- Unit test makes network call → mock with `respx`, `httpx.ASGITransport`, or a fake backend.
-- Translation mismatch → run translation-focused tests before touching broad plumbing.
-- Streaming failure → inspect streaming response accumulator, SSE helpers, and translation-stream tests.
-- CLI/config regression → run launcher/config/model/verify tests.
-- Routing/stats regression → run the random-routing suite.
-
-Useful focused groups:
-
-```bash
-uv run pytest tests/test_anthropic_openai_translation.py tests/test_responses_openai_translation.py tests/test_translation_engine_chaos.py -v -o addopts=
-uv run pytest tests/test_launch_claude.py tests/test_launch_codex.py tests/test_launch_route_builder.py tests/test_user_config.py tests/test_model_discovery.py tests/test_verify.py -v -o addopts=
-uv run pytest tests/test_random_routing_config.py tests/test_random_routing_llm_backend.py tests/test_random_routing_presets.py tests/test_random_routing_profile.py -v -o addopts=
-```
-
-### Mypy
-
-Mypy is strict on `switchyard/` and ignores tests. Prefer concrete request/response subclasses after
-`isinstance` narrowing, `TYPE_CHECKING` imports for circular or optional types, and aliases from
-`switchyard/lib/roles.py` instead of broad `Any`. Use targeted ignores with error codes only when an
-external incompatibility is localized.
-
-### Slim install / dependencies
-
-Default install must not pull heavyweight packages:
-
-- `torch`, `transformers`, `huggingface_hub`, `litellm`, `datasets`, `tokenizers`,
- `safetensors`, `pyarrow`, `agents`, `mcp`, `docx`
-
-Keep them in optional extras or dev groups, not `[project.dependencies]`. Dependency changes require
-explicit user intent; after changing dependencies run `uv lock`, `uv sync`, and the selected tests.
-
-### Stale package names
-
-The distribution package is `nemo-switchyard`; imports and the CLI are `switchyard`. Do not
-introduce `nemo_switchyard` imports or publish docs that imply `pip install switchyard`. Check:
-
-```bash
-uv run pytest tests/test_cli_stale_names.py tests/test_no_stale_module_paths.py tests/test_version_package_name.py -v -o addopts=
-```
-
-## Common Mistakes
-
-| Mistake | Reality |
-|---|---|
-| Running `uv run ruff check . --exclude docs/.venv-docs --exclude docs/_build` and calling it CI-equivalent | That is a dirty-workspace workaround, not the CI command. Either remove the generated artifacts (`rm -rf docs/.venv-docs docs/_build site/_build`) or run from a clean checkout. |
-| Running `uv run pytest tests/ -v` with `OPENROUTER_API_KEY`/`NVIDIA_API_KEY`/`OPENAI_API_KEY`/`ANTHROPIC_API_KEY` set in your shell | Tests that mock providers can accidentally hit live endpoints. Default to `-m "not integration"`, or strip credentials with `env -u`. |
-| Treating mypy as optional because CI marks it `continue-on-error` | Mypy still catches real bugs in `switchyard/` typed code. Run it for any change to profiles, route bundles, backends, request/response models, or translation. |
-| Skipping the slim-install smoke gate after a dependency or top-level import change | This is the *actual* hard CI gate that catches `torch`/`transformers` accidentally landing in the default install. |
-| Claiming validation from `scripts/select_validation.py` without rerunning it after committing changes | The script diffs against `HEAD` plus untracked files; if your changes are already committed, `--changed` returns "no diff". Pass `--path` explicitly, or diff against the branch base. |
-| Adding `# noqa` or per-line ignores to make ruff green | Ruff is a hard CI gate. Fix the code or, if the rule is wrong here, lift the ignore to the file or project level with a one-line justification. |
-| Editing a generated artifact (e.g., `docs/.venv-docs/...`) because ruff complained about it | Delete the artifact instead. CI does not have it; you should not either. |
-
-## Report Format
-
-Report validation with exact commands and live-call status:
-
-```markdown
-Validation:
-- `uv run ruff check .` — pass
-- `uv run mypy switchyard` — pass / not run (<reason>)
-- `uv run pytest tests/ -v -m "not integration"` — pass / not run (<reason>)
-- Slim install smoke — pass / not run (<reason>)
-- Live provider tests — not run / pass (<explicit user request>)
-```
-
-## Related Skills
+## Reporting
-- [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) — run this **before** the testing-ci skill on any non-trivial change, so the validation set you pick covers every file the change actually touches (importers, profile builders, tests), not just the diff surface.
+Report exact commands, pass/fail status, and whether any live network call occurred. Do not call a
+focused test run "full CI", and do not treat mypy or clippy warnings as unrelated without checking
+whether the diff introduced them.
diff --git a/AGENTS.md b/AGENTS.md
index 5a97c7ba5..f33718f7c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,36 +89,51 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
- One focused commit per step; every changed line traces to that step.
- Single-line commit message in Conventional Commits form
(`type(scope): summary`). No body, no `Co-Authored-By` trailer.
+- Pull request titles use the same Conventional Commits form.
+- Use `git commit -s` so every commit carries the required DCO sign-off.
- Never commit unprompted. Show the diff, get approval, then commit.
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+Before repairing DCO, inspect every affected commit:
-## Start here: discover skills before doing anything
+```bash
+git log origin/main..HEAD --format='%h %an <%ae> %s'
+```
-This repo ships project-specific agent skills under `.agents/skills/`. **Before reading code, planning a change, debugging a failure, or running validation, list and consult these skills.** They encode the workflows the maintainers expect you to follow.
+If every affected commit is yours, add the trailers and update the remote safely:
```bash
-ls .agents/skills/
+git rebase origin/main --signoff
+git push --force-with-lease origin HEAD
```
-Two general-purpose entry points cover most tasks:
+For a mixed-author branch, use an interactive rebase and mark only your unsigned commits for
+editing. At each stop, run `git commit --amend --no-edit --signoff`, then
+`git rebase --continue`. Never add your sign-off to another contributor's commit.
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
-- `.agents/skills/switchyard-codebase-exploration/SKILL.md` — read-before-edit workflow; builds an impact map of the files, symbols, and tests touched by a change.
-- `.agents/skills/switchyard-testing-ci/SKILL.md` — picks the smallest trustworthy local validation set and maps failures to fixes.
-- `.agents/skills/switchyard-pr-reviewer/SKILL.md` — multi-mode PR-review workflow (correctness, tests, design-vs-ticket, simplify, docs, Rust-craft); adversarially verifies every finding and drafts comments before posting. Dispatches Rust to `rust-code-reviewer`. Use for any "review this PR / is this blocking? / post comments" request.
+### 7. Review Discipline
-Task-specific skills (publish-package, run-pre-merge-checks, etc.) live alongside them — scan the directory and read the SKILL.md of any whose `description` matches the task. If no skill applies, say so explicitly and proceed; do not silently skip discovery.
+- Verify every finding against the current code path before reporting it.
+- Draft findings before posting review comments unless the user explicitly asks you to post them.
+- Resolve only your own review threads, and only after verifying the fix in code.
-### Keep skills in sync with the code they cover
+## Task-Specific Skills
-A skill that points at stale `file:line` references, removed flags, or a renamed symbol is worse than no skill — it actively misleads the next agent. **If your change modifies code that a skill describes, update the skill in the same change.** Specifically:
+The repository keeps a small set of optional runbooks under `.agents/skills/`. Read a skill only
+when its description directly matches the task. Ordinary code exploration, implementation,
+testing, and review do not require loading a skill.
-- After editing any file referenced by a SKILL.md, re-grep the skill for the file path and verify each `file:line` and symbol still resolves.
-- If you rename a symbol, move a file, change a CLI flag, add or remove a factory/recipe/processor/backend/translator, or change a public export, update every skill that mentions it.
-- If you discover a workflow the skill does not cover but should, add a row to the skill's Quick Reference or Anti-Patterns table — do not let the gap survive the PR.
-- Anti-patterns called out in `switchyard-lib-core` and `switchyard-coding-agent-launchers` are the contract: if you change the golden patterns those skills describe (random-routing factory + recipe shape, CLI-launcher recipe consumption), update the skill first and have the skill change reviewed alongside the code.
+| Skill | Use it for |
+|---|---|
+| `publish-python-release` | Python wheel artifacts, PyPI releases, and release workflow changes |
+| `switchyard-coding-agent-launchers` | Claude Code, Codex, or OpenClaw launcher behavior |
+| `switchyard-docs` | Published MkDocs pages, strict builds, previews, and docs CI |
+| `switchyard-rust-review` | Focused review of Rust, PyO3, async, streaming, and crate boundaries |
+| `switchyard-testing-ci` | Selecting non-obvious validation or diagnosing CI failures |
-The skill files are part of the codebase. Treat them like tests or docs — drift is a real defect, caught only by the next person who consults the skill.
+Skills should contain stable operational constraints, not mutable architecture inventories. Read the
+current source and CI workflows for implementation details.
## Architecture: staged chain
diff --git a/benchmark/README.md b/benchmark/README.md
index 1dd64f6da..72e340ac8 100644
--- a/benchmark/README.md
+++ b/benchmark/README.md
@@ -297,6 +297,23 @@ trial, and within a trial the latest attempt is the one Harbor kept (it retries
discards earlier attempts), so tokens spent on retried-away attempts land in `retries` and can be
netted out of cost.
+### Replay Stage-Router Scores
+
+Replay completed trajectories through the stage-router scorer and both picker policies:
+
+```bash
+uv run python benchmark/score_staged_run.py \
+ --run benchmark/tb_runs/<run-name>
+```
+
+Use `--threshold` and `--window` to override the scorer defaults. The command writes per-turn JSONL
+to `/tmp/<run-name>-scores.jsonl` and a per-task summary to
+`/tmp/<run-name>-per-task.csv` unless `--output` or `--csv` is supplied.
+
+The script processes each turn once, then applies both pickers to the same signal. Use `pick_cf` and
+`pick_ef` for actual routing decisions; score bands alone do not include picker overrides or
+fall-open behavior.
+
## Docker Image Notes
Baseline runs build `switchyard-baseline:local` from `benchmark/switchyard-server.Dockerfile`.