docs(orchestrator): add Handlers design & usage guide; link from README

Author: jeremi

orchestrator/README.md

@@ -72,6 +72,8 @@ Notes
 - Guardrails: diff budgets enforced in `adapters/git.py`.
 - Optional streaming logs: add `stream_logs: true` to an Odoo step to collect a follow
   log tail in artifacts.
+- Handlers: the engine runs steps via pluggable handlers (no hardcoded nodes). See
+  `orchestrator/docs/HANDLERS.md` for details.
 
 Configuration Reference
 

orchestrator/docs/HANDLERS.md

@@ -0,0 +1,130 @@
+# Orchestrator Handlers (Design & Usage)
+
+This document explains how the orchestrator executes recipe steps via pluggable handlers
+(no hardcoded step logic), how legacy `uses:` steps are mapped to handlers, what a
+handler looks like, and how to validate a recipe.
+
+## Why handlers?
+
+- Decouple the engine (graph, checkpoints, interrupts, guardrails) from side‑effects
+  (git, GitHub, Odoo, Task Registry, MCP tools).
+- Make it easy to add new step types without touching the engine.
+- Validate step arguments per handler before execution.
+
+## Built‑in handlers
+
+- `git.apply` — checkout/commit with diff guardrails
+- `github.open_pr` — open a PR using `gh` (REST fallback TBD)
+- `odoo.call` — call a tool on the Odoo MCP server (adapter safety still applies)
+- `tm.log_decision` — add a decision note to the current task
+- `tm.set_status` — update the current task status
+- `agent.wait` — write GOAL.md and interrupt to wait for human
+- `mcp.call` — generic MCP caller (server/tool/arguments)
+
+## Mapping legacy `uses:` to handlers
+
+You can keep your existing recipes. The engine maps legacy steps to handlers:
+
+- `uses: git` → `git.apply` (fields: `branch`, `commit`)
+- `uses: github` + `pr:` → `github.open_pr` (fields in `pr`)
+- `uses: odoo` → `odoo.call` (fields: `tool`, `args`)
+- `uses: tm` (`decision:` | `status:`) → `tm.log_decision` | `tm.set_status`
+- `uses: agent` → `agent.wait`
+- `uses: mcp` → `mcp.call` (fields: `server`, `tool`, `arguments`)
+
+You can also call a handler explicitly later (future), but legacy mapping is enough for
+all current recipes.
+
+## Handler interface (for reference)
+
+```
+# orchestrator/engine/handlers/base.py
+class NodeHandler:
+    name: str
+    def schema(self) -> dict: ...           # JSON Schema for arguments (optional)
+    def execute(self, *, args: dict, ctx: dict, **kw) -> ExecResult: ...
+
+class ExecResult:
+    ok: bool
+    output: dict
+    idempotency_key: Optional[str]
+
+class NodeInterrupt(Exception):
+    reason: str
+    payload: dict
+```
+
+- The engine provides adapters/clients via `**kw` when calling `execute` (e.g. `git`,
+  `github`, `odoo`, `tm`, `mcp_clients`, and the `logger`).
+- A handler can raise `NodeInterrupt` to yield control (the engine records a checkpoint
+  and returns `status=interrupted`).
+
+## Validation
+
+Handlers can expose a lightweight JSON Schema for their arguments. The doctor command
+uses it to validate recipes:
+
+```
+python -m orchestrator.main doctor validate-recipe --recipe <name>
+```
+
+This resolves each legacy step to a handler and checks the arguments against the
+handler’s schema so you catch mistakes early.
+
+## Return to agent on failure (policy)
+
+Any step can bounce control back to an agent when it fails:
+
+```
+steps:
+  - id: agent
+    uses: agent
+    goal: "Please implement X"
+  - id: tests
+    uses: odoo
+    tool: test_addons
+    args: { modules: ["{{ env.module }}"], dbname: "{{ env.db }}" }
+    on_error:
+      return_to_agent: agent   # required
+      tm_status: review        # optional convenience
+```
+
+On failure, the engine marks the failing node failed, resets the target agent node in
+checkpoints, and returns `status=interrupted` at that agent. Fix issues, then resume:
+
+```
+python -m orchestrator.main run_graph --task-id T1 --recipe R --resume <run_id>
+```
+
+## MCP: generic tool calling
+
+For ad‑hoc tools or new MCP servers, use `mcp.call`:
+
+```
+steps:
+  - uses: mcp
+    server: tm
+    tool: add_evidence
+    arguments: { id: T1, type: note, ref: ok }
+```
+
+This reuses the orchestrator’s persistent MCP clients for `odoo` and `tm`.
+
+## Parallel steps (sequential for now)
+
+`parallel:` steps execute their `children` sequentially today for safety. The internal
+`GraphExecutor` will fan out in true parallel once repo locking is in place.
+
+## Admin tools
+
+- List handlers: `python -m orchestrator.main doctor list-handlers`
+- Validate handler mappings + args:
+  `python -m orchestrator.main doctor validate-recipe --recipe <name>`
+- Reset a node in a run:
+  `python -m orchestrator.main doctor reset-node --run-id <id> --node-id <id>`
+
+## Roadmap
+
+- Discover additional handlers via entry points (packaged plugins) if needed.
+- Optional lockfile to pin handler name/version for reproducibility.
+- Full REST fallback for `github.open_pr` when `gh` is unavailable.