rote-cli 0.1.0__py3-none-any.whl

rote/serve/registry.py

@@ -0,0 +1,201 @@
+"""Manifest registry for graduated pipelines served over MCP.
+
+The registry is a single JSON file (default ``~/.rote/registry.json``)
+listing every graduated pipeline the user wants exposed as an MCP tool:
+tool name, description, the pipeline.yaml it came from, a JSON Schema
+for the tool's input, and the runtime trigger config (Temporal address /
+task queue, Cloudflare workflow URL, …).
+
+``rote register`` writes entries; ``rote serve`` reads them. The file is
+the contract between the two commands — same philosophy as the driver
+layer's ``work_dir/pipeline.yaml`` contract.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from rote.ir import Pipeline, PipelineInput
+
+REGISTRY_SCHEMA_VERSION = 1
+
+#: MCP tool names must be safe for every client; Cloudflare's signal-name
+#: constraint ([A-Za-z0-9_-]+) is the strictest charset we target, so the
+#: registry enforces the same one for tool names.
+_TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+
+def default_registry_path() -> Path:
+    """The registry location used when ``--registry`` is not given."""
+    return Path.home() / ".rote" / "registry.json"
+
+
+class TemporalTrigger(BaseModel):
+    """How to start a graduated pipeline on a Temporal cluster."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    runtime: Literal["temporal"] = "temporal"
+    address: str = Field(
+        default="localhost:7233",
+        description="Temporal frontend address, host:port",
+    )
+    namespace: str = Field(default="default")
+    task_queue: str = Field(description="Task queue the graduated worker polls")
+    workflow_name: str = Field(
+        description=(
+            "Registered workflow *type* name. The Temporal adapter emits a "
+            "versioned name (PascalCase pipeline name + pipeline hash), so "
+            "this must match the emitted @workflow.defn name exactly."
+        ),
+    )
+
+
+class CloudflareTrigger(BaseModel):
+    """How to start a graduated pipeline deployed as a Cloudflare Worker.
+
+    The emitted ``src/index.ts`` fetch handler accepts a JSON POST body
+    (the workflow params) and responds with ``{id, status}``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    runtime: Literal["cloudflare"] = "cloudflare"
+    url: str = Field(description="Deployed worker URL (the fetch trigger endpoint)")
+    status_url: str | None = Field(
+        default=None,
+        description=(
+            "Optional status endpoint template containing '{workflow_id}'. "
+            "The emitted worker does not expose a status route by default, "
+            "so without this the companion status tool directs users to "
+            "`wrangler workflows instances describe` instead."
+        ),
+    )
+
+
+Trigger = Annotated[TemporalTrigger | CloudflareTrigger, Field(discriminator="runtime")]
+
+
+class RegistryEntry(BaseModel):
+    """One graduated pipeline exposed as one MCP tool."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="MCP tool name (unique within the registry)")
+    description: str = ""
+    pipeline_yaml: str = Field(description="Absolute path to the graduated pipeline.yaml")
+    input_schema: dict[str, Any] = Field(
+        description="JSON Schema for the tool input (the pipeline's input contract)",
+    )
+    trigger: Trigger
+    registered_at: str = Field(
+        default_factory=lambda: datetime.now(UTC).isoformat(),
+        description="ISO-8601 timestamp of the last register/update",
+    )
+
+    @field_validator("name")
+    @classmethod
+    def _validate_tool_name(cls, v: str) -> str:
+        if not _TOOL_NAME_RE.match(v):
+            raise ValueError(
+                f"tool name {v!r} must match [A-Za-z0-9][A-Za-z0-9_-]* (MCP tool-name safe charset)"
+            )
+        return v
+
+
+class Registry(BaseModel):
+    """The full registry file."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: int = REGISTRY_SCHEMA_VERSION
+    entries: list[RegistryEntry] = Field(default_factory=list)
+
+    def get(self, name: str) -> RegistryEntry | None:
+        for entry in self.entries:
+            if entry.name == name:
+                return entry
+        return None
+
+    def upsert(self, entry: RegistryEntry) -> bool:
+        """Insert or replace by tool name. Returns True if an entry was replaced."""
+        for i, existing in enumerate(self.entries):
+            if existing.name == entry.name:
+                self.entries[i] = entry
+                return True
+        self.entries.append(entry)
+        return False
+
+    @classmethod
+    def load(cls, path: str | Path) -> Registry:
+        """Load the registry; a missing file is an empty registry."""
+        p = Path(path)
+        if not p.exists():
+            return cls()
+        raw = json.loads(p.read_text(encoding="utf-8"))
+        return cls.model_validate(raw)
+
+    def save(self, path: str | Path) -> None:
+        """Write the registry atomically (tmp file + rename)."""
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(p.suffix + ".tmp")
+        tmp.write_text(self.model_dump_json(indent=2) + "\n", encoding="utf-8")
+        tmp.replace(p)
+
+
+def input_schema_for(pipeline_input: PipelineInput) -> dict[str, Any]:
+    """Derive the MCP tool's inputSchema from the pipeline's input contract.
+
+    Prefers a structured ``input_schema`` field if the loaded model carries
+    one (being added to :class:`rote.ir.PipelineInput` concurrently — coded
+    defensively via ``getattr`` so this works before and after that lands).
+    Otherwise synthesizes a permissive object schema from the required /
+    optional name lists, which are untyped in the current IR.
+    """
+    explicit = getattr(pipeline_input, "input_schema", None)
+    if isinstance(explicit, dict) and explicit:
+        return dict(explicit)
+
+    properties: dict[str, Any] = {
+        name: {} for name in [*pipeline_input.required, *pipeline_input.optional]
+    }
+    return {
+        "type": "object",
+        "title": pipeline_input.type,
+        "description": (
+            f"Input contract for the graduated pipeline "
+            f"(type {pipeline_input.type}; field types are untyped in the IR v0)"
+        ),
+        "properties": properties,
+        "required": list(pipeline_input.required),
+        "additionalProperties": True,
+    }
+
+
+def entry_from_pipeline(
+    pipeline: Pipeline,
+    pipeline_yaml: Path,
+    trigger: TemporalTrigger | CloudflareTrigger,
+    name: str | None = None,
+) -> RegistryEntry:
+    """Build a registry entry from a loaded pipeline IR.
+
+    Tool name defaults to ``pipeline.name`` with any charset-unsafe
+    characters replaced by ``-``; description comes from
+    ``pipeline.description`` (first paragraph, whitespace-normalized).
+    """
+    tool_name = name if name is not None else re.sub(r"[^A-Za-z0-9_-]+", "-", pipeline.name)
+    return RegistryEntry(
+        name=tool_name,
+        description=pipeline.description.strip(),
+        pipeline_yaml=str(pipeline_yaml.resolve()),
+        input_schema=input_schema_for(pipeline.input),
+        trigger=trigger,
+    )

rote/serve/server.py

@@ -0,0 +1,249 @@
+"""The ``rote serve`` MCP server.
+
+One FastMCP (>=3.4) server whose tools are sourced from the manifest
+registry (:mod:`rote.serve.registry`) via a custom v3 ``Provider``:
+
+* every registry entry becomes one MCP tool named ``entry.name`` whose
+  ``inputSchema`` is the entry's stored JSON Schema, and
+* a companion ``<entry.name>_status`` tool that polls the workflow.
+
+Freshness has two layers:
+
+1. The provider re-reads the registry file (cheap content-hash check)
+   on every ``tools/list`` / ``tools/call``, so a ``rote register``
+   issued while the server is running is visible on the next request.
+2. A background watcher polls the registry file and, when it changes,
+   sends ``notifications/tools/list_changed`` to every connected
+   session so clients that honor the notification (Claude Code does)
+   refresh without a reconnect. FastMCP 3.4 does not emit this
+   notification itself when providers change, so we track sessions via
+   middleware and use the low-level SDK's
+   ``ServerSession.send_tool_list_changed()`` directly.
+
+Long-running handling: graduated pipelines run minutes to days (HITL
+gates), and their durability lives in Temporal / Cloudflare — not in
+this process. Trigger tools therefore return ``{workflow_id, status:
+"started"}`` immediately and clients poll the ``_status`` companion.
+FastMCP 3.4 does ship server-side MCP Tasks support (SEP-1686), but the
+extension is still a spec RC and running the trigger as a task would
+tie a multi-day workflow's observability to this process's lifetime,
+so the poll-tool pattern is deliberate. Revisit once the 2026-07-28
+spec lands and Claude clients request task augmentation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import logging
+import weakref
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+import mcp.types as mt
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.providers import Provider
+from fastmcp.tools import Tool, ToolResult
+from mcp.server.session import ServerSession
+
+from rote.serve import backends
+from rote.serve.registry import Registry, RegistryEntry
+
+logger = logging.getLogger(__name__)
+
+#: How often the background watcher checks the registry file for changes.
+DEFAULT_POLL_INTERVAL_S = 1.0
+
+STATUS_TOOL_SUFFIX = "_status"
+
+
+# ───────── Tools ─────────
+
+
+class PipelineTool(Tool):
+    """Triggers the graduated workflow behind one registry entry."""
+
+    entry: RegistryEntry
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        try:
+            result = await backends.start_workflow(self.entry, arguments)
+        except backends.BackendError as e:
+            raise ToolError(str(e)) from e
+        return ToolResult(structured_content=result)
+
+
+class PipelineStatusTool(Tool):
+    """Polls the status of a workflow started by the companion trigger tool."""
+
+    entry: RegistryEntry
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        workflow_id = arguments["workflow_id"]
+        try:
+            result = await backends.workflow_status(self.entry, workflow_id)
+        except backends.BackendError as e:
+            raise ToolError(str(e)) from e
+        return ToolResult(structured_content=result)
+
+
+def _trigger_tool(entry: RegistryEntry) -> PipelineTool:
+    return PipelineTool(
+        name=entry.name,
+        description=(
+            f"{entry.description}\n\n"
+            f"Starts the graduated '{entry.name}' pipeline on "
+            f"{entry.trigger.runtime} and returns immediately with a workflow_id. "
+            f"Poll progress with the {entry.name}{STATUS_TOOL_SUFFIX} tool."
+        ).strip(),
+        parameters=entry.input_schema,
+        entry=entry,
+    )
+
+
+def _status_tool(entry: RegistryEntry) -> PipelineStatusTool:
+    return PipelineStatusTool(
+        name=f"{entry.name}{STATUS_TOOL_SUFFIX}",
+        description=(
+            f"Poll the status of a '{entry.name}' pipeline run previously "
+            f"started with the {entry.name} tool."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "workflow_id": {
+                    "type": "string",
+                    "description": f"The workflow_id returned by the {entry.name} tool",
+                },
+            },
+            "required": ["workflow_id"],
+            "additionalProperties": False,
+        },
+        entry=entry,
+    )
+
+
+# ───────── Provider ─────────
+
+
+class RegistryProvider(Provider):
+    """Sources MCP tools from the registry file, re-reading it on change.
+
+    Also owns the background watcher (started via the provider
+    ``lifespan``, which FastMCP scopes to the server's lifetime) and the
+    set of live sessions to notify. Sessions are held weakly so closed
+    connections never pin memory or receive sends.
+    """
+
+    def __init__(
+        self,
+        registry_path: str | Path,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_S,
+    ) -> None:
+        super().__init__()
+        self.registry_path = Path(registry_path)
+        self.poll_interval = poll_interval
+        self.sessions: weakref.WeakSet[ServerSession] = weakref.WeakSet()
+        self._digest: bytes | None = None
+        self._registry = Registry()
+        self._load_if_changed()
+
+    # ── registry loading ──
+
+    def _current_digest(self) -> bytes | None:
+        try:
+            return hashlib.sha256(self.registry_path.read_bytes()).digest()
+        except FileNotFoundError:
+            return None
+
+    def _load_if_changed(self) -> bool:
+        """Reload the registry if the file content changed. Returns True on change."""
+        digest = self._current_digest()
+        if digest == self._digest:
+            return False
+        self._digest = digest
+        self._registry = Registry.load(self.registry_path)
+        return True
+
+    # ── Provider hooks ──
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        self._load_if_changed()
+        tools: list[Tool] = []
+        for entry in self._registry.entries:
+            tools.append(_trigger_tool(entry))
+            tools.append(_status_tool(entry))
+        return tools
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        watcher = asyncio.create_task(self._watch_registry())
+        try:
+            yield
+        finally:
+            watcher.cancel()
+
+    # ── change notification ──
+
+    async def _watch_registry(self) -> None:
+        while True:
+            await asyncio.sleep(self.poll_interval)
+            if self._load_if_changed():
+                await self._notify_tool_list_changed()
+
+    async def _notify_tool_list_changed(self) -> None:
+        for session in list(self.sessions):
+            try:
+                await session.send_tool_list_changed()
+            except Exception:
+                # A torn-down session must not kill the watcher or block
+                # notifying the remaining live sessions.
+                logger.debug("failed to notify session of tool list change", exc_info=True)
+
+
+class SessionTrackingMiddleware(Middleware):
+    """Records every session that talks to us so the watcher can notify it."""
+
+    def __init__(self, provider: RegistryProvider) -> None:
+        self._provider = provider
+
+    async def on_request(
+        self,
+        context: MiddlewareContext[mt.Request[Any, Any]],
+        call_next: CallNext[mt.Request[Any, Any], Any],
+    ) -> Any:
+        fastmcp_ctx = context.fastmcp_context
+        if fastmcp_ctx is not None:
+            # No live session on this context (init edge cases) — skip.
+            with contextlib.suppress(AttributeError, ValueError):
+                self._provider.sessions.add(fastmcp_ctx.session)
+        return await call_next(context)
+
+
+# ───────── Server construction ─────────
+
+
+def build_server(
+    registry_path: str | Path,
+    poll_interval: float = DEFAULT_POLL_INTERVAL_S,
+) -> FastMCP[None]:
+    """Build the ``rote serve`` FastMCP server for a registry file."""
+    provider = RegistryProvider(registry_path, poll_interval=poll_interval)
+    return FastMCP(
+        name="rote",
+        instructions=(
+            "Tools on this server trigger graduated rote pipelines — "
+            "deterministic workflows produced from Anthropic-style skills. "
+            "Each pipeline has a trigger tool (returns a workflow_id "
+            "immediately) and a companion <name>_status tool for polling, "
+            "because pipelines can run for minutes to days (human-in-the-"
+            "loop gates)."
+        ),
+        providers=[provider],
+        middleware=[SessionTrackingMiddleware(provider)],
+    )

rote/skills/rote-graduate/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: rote-graduate
+description: >-
+  Analyze an Anthropic-style skill bundle (SKILL.md + references) and produce
+  a graduation plan that separates deterministic work into extracted Python
+  modules, LLM-as-judge work into typed DSPy/BAML signatures, agentic work
+  into bounded agent loops, and human-in-the-loop gates into durable suspend
+  points. Emit the whole pipeline as a runtime-agnostic intermediate
+  representation (pipeline.yaml) plus runnable code for a target workflow
+  engine (Temporal, Inngest, Restate, or plain async) via pluggable adapters.
+  Trigger phrases: "graduate this skill", "turn this skill into a workflow",
+  "harden this skill", "extract deterministic parts of this skill", "compile
+  skill to pipeline", "make this skill reliable in production", "analyze
+  skill for codification", "emit this skill as a temporal workflow", "rote
+  this skill".
+---
+
+# Skill Graduation
+
+You are the rote graduator. You read fuzzy AI skills and produce reliable
+workflows.
+
+**Input:** a directory containing a `SKILL.md` and an optional `references/`
+folder with sub-files.
+
+**Output:** an intermediate representation (`pipeline.yaml`) plus
+runtime-specific emitted code that the user can drop into their durable
+execution engine. Along the way you also produce a human-readable graduation
+report that highlights what was codified, what stayed agentic, and what
+judgment calls you made.
+
+The guiding philosophy: **keep the LLM at points where the input is unbounded
+or ambiguous (parsing, classifying, drafting, summarizing). Codify everything
+else — control flow, retries, parallelism, idempotency, side-effecting tool
+calls, fixed batching — into deterministic code.** Every token spent
+re-deriving a known-fixed procedure at runtime is waste.
+
+## Phase Routing
+
+| Entry Point | Start At | Example Triggers |
+|---|---|---|
+| Full graduation | Phase 1 → 7 | "graduate the bdr-outreach skill" |
+| Report only | Phase 1 → 5, skip 6 | "analyze this skill, don't emit code" |
+| Re-emit for different runtime | Phase 6 | "emit the existing pipeline.yaml for inngest" |
+| Update graduation after skill changed | Phase 1 → 7, diff | "regraduate bdr-outreach, it changed" |
+
+## Pipeline
+
+### Phase 1: Intake
+
+Read the target directory exhaustively:
+
+1. `SKILL.md` — parse the frontmatter (name, description, trigger phrases),
+   then read the full body. Note every named phase, gate, and rule.
+2. `references/` — read every sub-file. These are the rubric detail, the
+   API choreography, and the domain constraints.
+3. Build a mental model of: the skill's goal, its preconditions, its tools,
+   its explicit HITL gates ("present to user", "wait for approval"), and
+   any MANDATORY checklists enforced only by prose.
+
+Do not proceed to Phase 2 until you can restate the skill's phase structure
+in your own words.
+
+### Phase 2: Node Classification
+
+Read `references/node-kinds.md` before starting this phase.
+
+Walk through the skill from start to finish. For every distinct step, assign
+it exactly one of the five node kinds:
+
+| Kind | Signal |
+|---|---|
+| `pure_function` | Fixed logic, deterministic I/O, no LLM reasoning needed |
+| `llm_judge` | Fuzzy classification against a rubric, typed input/output |
+| `agent_loop` | Exploratory tool use, variable path, genuinely needs LLM orchestration |
+| `hitl_gate` | Explicit human review/approval required before proceeding |
+| `external_call` | Deterministic API call that needs retry/timeout semantics |
+
+When a step could be classified two ways, prefer the more deterministic
+kind. The goal is to push as much as possible into `pure_function` and
+`external_call`, and reserve `agent_loop` for steps where the procedure
+genuinely varies from run to run.
+
+Output: a table mapping each step to its kind, with a one-sentence
+justification per row.
+
+### Phase 3: Codification Scan
+
+Read `references/crystallization-heuristics.md` before starting this phase.
+
+For each node classified as `pure_function` or `external_call`, surface every
+codification opportunity:
+
+- **Literal pseudocode or Python pasted into the prompt.** The skill's
+  author already wrote it — you just need to lift it into a real module.
+- **Fixed constants** (batch sizes, taxonomy IDs, thresholds, retry counts,
+  timeouts). If the prompt says "batch of 10", that 10 is a constant, not
+  a judgment call.
+- **Deterministic loops** with clear termination conditions.
+- **String templates** for reports, output formats, or structured
+  responses.
+- **MANDATORY checklists** enforced by English prose. These are the highest
+  value extractions — moving a required check from prose into code makes it
+  impossible to skip accidentally.
+
+For each extraction, produce a record of: source file and line, the current
+prose, the proposed extracted function name and signature, and any constants
+to lift into config.
+
+### Phase 4: LLM-Judge Extraction
+
+Read `references/llm-judge-extraction.md` before starting this phase.
+
+For each `llm_judge` node, draft a typed signature using DSPy or BAML
+conventions:
+
+- **Input schema** (Pydantic / TypedDict): every field the LLM needs,
+  sourced from upstream node outputs.
+- **Output schema**: enum-bounded decisions plus structured rationale.
+  Prefer enums over free-text wherever the skill's rubric implies a
+  discrete choice.
+- **Seed examples**: harvest 3–5 examples directly from the skill's own
+  rubric. If the rubric says "discard MSLs", construct an example with an
+  MSL contact and the `discard` decision.
+- **Eval stub**: scaffold a pytest-style test file that asserts the
+  signature against each rule the rubric names.
+
+Output: a `signatures/<node_name>.py` file per `llm_judge` node, plus a
+matching `evals/<node_name>.jsonl` seed.
+
+### Phase 5: IR Assembly
+
+Read `references/ir-schema.md` before starting this phase.
+
+Assemble the full DAG as `pipeline.yaml`. Include:
+
+- `input.input_schema`: the full JSON Schema for the pipeline input
+  payload, promoted from the entry nodes' signature design (see
+  `ir-schema.md`).
+- `nodes`: every step from Phase 2, with its kind, input/output types,
+  `inputs:` data-flow bindings (param → `pipeline.input[.field]` /
+  `<node_id>.output[.field]`), timeout, retry policy, and (for
+  `pure_function` / `llm_judge`) a reference to the extracted module.
+- `edges`: data flow between nodes, including fan-out for batch
+  processing.
+- `hitl_gates`: for every `hitl_gate` node, the signal name, timeout,
+  and notification target.
+- `config`: top-level schedule, on_failure handler, observability
+  settings.
+
+The `pipeline.yaml` is the runtime-agnostic source of truth. Everything
+Phase 6 emits is derived from it.
+
+### Phase 6: Adapter Invocation
+
+**You do not emit runtime code yourself.** The rote project ships
+runtime adapters as Python code (`rote/adapters/temporal.py`,
+`rote/adapters/inngest.py`, etc.) that consume the `pipeline.yaml` you
+produced in Phase 5 and emit runnable code. Your job in this phase is
+to **validate that your IR is complete enough for the adapter to
+succeed**, then let the adapter run.
+
+Checklist before declaring Phase 5 done:
+
+- Every `pure_function` / `external_call` node has an `impl:` pointing
+  at a real file you created in Phase 3.
+- Every `llm_judge` node has a `signature:` pointing at a real file
+  you created in Phase 4.
+- Every `agent_loop` node has `tools:` listed.
+- Every `hitl_gate` node has a `signal:`.
+- Every node mentioned in `entry_nodes`, `exit_nodes`, `edges.from`,
+  `edges.to`, and `loop_body` exists in `nodes:`.
+- `rote.ir.load_pipeline(pipeline.yaml)` loads without validation
+  errors. If you can call this function, run it as a dry check.
+
+The `rote emit <pipeline.yaml> --runtime temporal --out <dir>` CLI
+command (or its programmatic equivalent) takes it from there. You do
+not need to read the adapter's implementation — treat it as a black
+box that accepts a valid IR and produces code.
+
+**Why the split:** the IR and its validation logic are the load-bearing
+parts of graduation. Code emission is template substitution and belongs
+in deterministic Python. Keeping the agent out of the emission step
+means the emitted output is reproducible and reviewable — every change
+to what Temporal code looks like is a change to the adapter, not a new
+agent trajectory.
+
+### Phase 7: Graduation Report
+
+Produce a human-readable Markdown report in `graduation-report.md` covering:
+
+- **Summary metrics**: total nodes, breakdown by kind, estimated token cost
+  reduction per run, list of HITL gates and what they block on.
+- **Crystallization log**: every prose-to-code extraction from Phase 3,
+  with before/after snippets.
+- **Open questions**: ambiguous judgment calls where you made a decision
+  but the human reviewer should verify. Be explicit about what you chose
+  and why.
+- **Suggested next steps**: what to dogfood first, which evals to run,
+  which node to regraduate after the first production run reveals new
+  information.
+
+## Invariants
+
+These rules apply across every phase:
+
+- **Never silently drop a MANDATORY check.** If the skill says a check is
+  required and you can't codify it, surface it as an open question in
+  Phase 7 — never as a silent omission.
+- **Prefer deterministic over agentic.** When in doubt, codify. Leaving
+  something agentic is a last resort for genuinely exploratory work.
+- **The IR is the source of truth, not the emitted code.** If the IR and
+  a runtime-specific artifact disagree, the IR wins and Phase 6 re-runs.
+- **Two adapters minimum before declaring the IR generic.** Until two
+  runtimes work, assume the IR is secretly shaped like the first one.
+- **Dogfood yourself.** Once a stable version exists, point rote-graduate
+  at its own SKILL.md. The parts that can be crystallized should be; the
+  parts that stay agentic are the real source of judgment.
+
+## Related Concepts
+
+- **"Workflow vs. agent"** — the distinction from Anthropic's *Building
+  effective agents* essay. This tool is fundamentally about moving steps
+  from the agent column to the workflow column when the data supports it.
+- **"Blueprint First, Model Second"** — the EBF paper's framing. The
+  blueprint is the `pipeline.yaml`; the LLM is a specialized tool at
+  specific nodes.
+- **DSPy compile** — what the `llm_judge` signatures graduate *into* once
+  you have enough examples. rote produces the signature; dspy.compile
+  optimizes the prompt and few-shots against your eval set.