Merge remote-tracking branch 'origin/feature/handlers-docs' into 17.0

* origin/feature/handlers-docs:
  docs: document --format md|html for Mermaid exports
  feat(doctor): support --format md|html for graph exports; wrap output in Markdown or HTML (Mermaid via CDN)
  feat(doctor): Mermaid exporters (doctor graph, doctor run-graph) + USER_GUIDE Visualization section
  docs(handlers): add scaffold example and cross-links; feat(cli): --strict-validate flag for run_graph to validate handlers+args
  docs(orchestrator): add 'Extending Handlers' pointers and sample recipe mixing mcp.call with traditional step
  docs(orchestrator): add Handlers design & usage guide; link from README
  feat(orchestrator): per-handler JSON Schema validation; doctor validate-recipe checks handler args; add mcp.call schema
  feat(orchestrator): add generic mcp.call handler; expose handler registry; doctor commands (list-handlers, validate-recipe, reset-node); docs updated; tests added
  refactor(orchestrator): decouple node logic via handler registry; add handlers (agent, git, github, tm, odoo); route legacy 'uses' to handlers; keep parallel synthetic
  feat(orchestrator/graph): support return_to_agent on failure; fix parallel block; tests for interrupt/resume and agent return
  feat(orchestrator/graph): phase 1–3 — graph IR + SQLite checkpointer + interrupts + parallel (sequential); add CLI run_graph/resume
  ci: add job to run mcp-task-registry tests from ACN-org/acn-ai monorepo with coverage artifact
  ci(orchestrator): add GH Action with coverage; tests: e2e commit+PR (gh via PATH), mcp stub in conftest
  tests(orchestrator): add e2e commit+PR tests; fix formatting
  tests(orchestrator): add edge-case tests (allowed path guard, gh CLI unexpected output, smoke fail path, agent timeout & if-skip)
  tests(orchestrator): add retries, github fallback, agent gate, summary and adapter gate tests
  chore: remove redundant workflow (CI runs in openspp-tooling repo)
  feat(task-registry): add search resource; expand tests; add CI with coverage

Author: jeremi

.github/workflows/orchestrator.yml

@@ -0,0 +1,82 @@
+name: orchestrator
+
+on:
+  push:
+    paths:
+      - 'orchestrator/**'
+      - '.github/workflows/orchestrator.yml'
+  pull_request:
+    paths:
+      - 'orchestrator/**'
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov ruff
+
+      - name: Run orchestrator tests + coverage
+        env:
+          PYTHONPATH: .
+        run: |
+          pytest -q orchestrator/tests \
+            --cov=orchestrator --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage.xml
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-orchestrator
+          path: coverage.xml
+
+  task-registry:
+    name: mcp-task-registry (monorepo)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout monorepo ACN-org/acn-ai
+        uses: actions/checkout@v4
+        with:
+          repository: ACN-org/acn-ai
+          ref: main
+          fetch-depth: 1
+          # If the repo is private, create a PAT with repo:read and set as ACN_AI_PAT
+          # token: ${{ secrets.ACN_AI_PAT }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov
+          pip install -e packages/mcp-task-registry
+
+      - name: Run mcp-task-registry tests
+        env:
+          PYTHONPATH: packages/mcp-task-registry/src
+        run: |
+          pytest -q packages/mcp-task-registry/tests \
+            --cov=packages/mcp-task-registry/src/mcp_task_registry \
+            --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage.xml
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-mcp-task-registry
+          path: coverage.xml

orchestrator/README.md

@@ -0,0 +1,178 @@
+# Orchestrator (MCP‑First)
+
+This CLI coordinates Task Master tasks, Odoo operations via the Odoo MCP server, and
+code edits via agents, executing declarative recipes with guardrails and artifacts.
+
+Status: fully implemented. Uses persistent MCP sessions for Odoo and Task Master, runs
+declarative recipes with retries/timeouts, readiness gates, guardrails, artifacts,
+evidence/decisions, and PR creation via `gh` CLI. Steps are executed via pluggable
+handlers (no hardcoded nodes): `git.apply`, `github.open_pr`, `odoo.call`, `tm.*`,
+`agent.wait`, `mcp.call`.
+
+Quick Start (uv venv)
+
+- Requires: Python 3.10+ and `uv` (https://docs.astral.sh/uv/)
+- Requires: Node.js 18+ for Task Master MCP server
+- Requires: GitHub CLI `gh` (authenticated) for PR creation
+- From repo root:
+  - `uv venv`
+  - `source .venv/bin/activate`
+  - `uv pip install -r orchestrator/requirements.txt --python $(which python)`
+  - Copy `orchestrator/config.example.yaml` to `orchestrator/config.yaml` and adjust.
+  - `python -m orchestrator.main --help`
+
+Commands
+
+- `orchestrator loop` — polls Task Master (`next_task`) and runs the default recipe per
+  task.
+- `orchestrator run --task-id <ID> --recipe <name>` — runs a specific task using a named
+  recipe.
+- `orchestrator verify --task-id <ID>` — runs only `lint` + `test_addons` from the
+  default recipe.
+- `orchestrator pr --task-id <ID>` — opens a PR for `feature/<ID>` and adds PR evidence
+  to the task.
+- `orchestrator run_graph --task-id <ID> --recipe <name>` — graph execution with
+  checkpoints. Resume with `--resume <run_id>`.
+
+Layout
+
+```
+orchestrator/
+  main.py
+  adapters/
+    tm_mcp.py
+    odoo_mcp.py
+    agents.py
+    git.py
+    github.py
+  engine/
+    recipes.py
+    events.py
+    utils.py
+  schemas/
+    config.v1.json
+    recipe.v1.json
+  recipes/
+    odoo_create_or_update_module.yaml
+    odoo_upgrade_addon.yaml
+  engine/handlers/
+    (built-in handlers)
+  engine/registry.py
+  config.example.yaml
+  README.md
+  COOKBOOK.md
+```
+
+Notes
+
+- Odoo operations go through the Odoo MCP server (see `servers/odoo_mcp/server.py`) via
+  persistent stdio sessions. Ensure `uv` and `invoke` are available.
+- Task Master adapter maps spec names to server tools: `decision→log_decision`,
+  `evidence→add_evidence`.
+- 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
+
+- File: `orchestrator/config.yaml` (validated by `schemas/config.v1.json`)
+- Key sections used at runtime:
+  - `odoo.mcp.cmd`: stdio command to start the Odoo MCP server. Defaults to
+    `uv run --with modelcontextprotocol --with invoke python servers/odoo_mcp/server.py`.
+  - `tm.mcp.cmd`: stdio command to start Task Master MCP server. Defaults to
+    `node servers/claude-task-master/mcp-server/server.js`.
+  - `odoo.db` and `odoo.module`: default database and module name used in recipes.
+  - `odoo.readiness`: readiness probe defaults for `smoke_test` after restarts
+    (`attempts`, `timeout_seconds`).
+  - `guards`:
+    - `max_files_changed`, `max_total_additions`: diff budgets enforced before
+      committing.
+    - `require_confirm_for_destructive`: if true, destructive Odoo tools require
+      `confirm: true`.
+    - `allowed_environment`: destructive ops are blocked unless they target this
+      environment.
+      - Applies to `reset_db`/`restore_snapshot` when the target
+        `dbname`/`destination_db` equals `allowed_environment`.
+      - Applies to `stop_env` only when `purge: true`; in that case, the configured
+        `odoo.db` must equal `allowed_environment`.
+  - `github.base_branch`, `github.pr_labels`: PR base branch and default labels.
+  - `secrets.github_token_from_env`: env var for GitHub REST fallback (PRs currently
+    require `gh`).
+
+Recipe Format
+
+- Validated by `schemas/recipe.v1.json`.
+- Step keys supported:
+  - `uses`: `odoo | agent | git | github | tm | mcp`
+  - Odoo: `tool`, `args`, `timeout_seconds`, `retries`, `on_error`, `stream_logs`
+  - Agent: `goal`, `mode`, `context`
+  - Git: `branch`, `commit`
+  - GitHub: `pr { base, title, bodyFrom }`
+  - Task Master: `status { id }`, `value`, `decision { id, note }`
+
+Agent Behavior
+
+- Interactive agent steps write `agent/GOAL.md`, then wait until one of:
+  - working tree has changes (`git diff` not empty), or
+  - HEAD changes vs the initial `git rev-parse HEAD`, or
+  - `.orchestrator/continue` file exists in repo root.
+- Timeout controlled by `agents.timeout_seconds`.
+
+Destructive Operation Safety
+
+- The orchestrator enforces confirm + environment gates client‑side before calling Odoo
+  tools:
+  - `reset_db` / `restore_snapshot`: require `confirm: true` and
+    `dbname`/`destination_db` must equal `guards.allowed_environment` (when configured).
+  - `stop_env(purge=true)`: require `confirm: true` and configured `odoo.db` must equal
+    `guards.allowed_environment`.
+- Non‑purge `stop_env` is allowed without confirm by default.
+
+Artifacts & Summary
+
+- Artifacts live in `orchestrator/artifacts/<task-id>/`:
+  - `events.jsonl` (token‑redacted), `summary.json`, `odoo/<tool>.log`, optional
+    `odoo/logs_<id>.log`, `agent/GOAL.md`.
+- `summary.json` contains: `status`, `pr_url`, `commit`, `guards` diff stats, and
+  `timings { start, end }`.
+
+PR Creation
+
+- Uses `gh` CLI: `gh pr create --json url --jq .url` for a robust URL parse.
+- Adds PR evidence to Task Master automatically.
+
+Leasing
+
+- A local lease file is written to `.orchestrator/lease.json` when a run starts and
+  removed after completion.
+- Stale leases older than `locks.ttl_seconds` are cleared on startup.
+
+Testing
+
+- Tests run only for orchestrator code (see `pytest.ini`).
+- Run in the uv venv: `pytest -q`.
+- Coverage highlights:
+  - Readiness gate (smoke after restart), Odoo arg normalization, guardrail violation
+    path, token redaction, util helpers.
+
+See Also
+
+- Configuration cookbook with copy‑paste snippets: `orchestrator/COOKBOOK.md`
+- Handlers design & usage: `orchestrator/docs/HANDLERS.md`
+
+Sample: mixing a traditional step with a generic MCP call
+
+```
+steps:
+  - id: tests
+    uses: odoo
+    tool: test_addons
+    args: { modules: ["my_module"], dbname: "devel" }
+  - id: note
+    uses: mcp
+    server: tm
+    tool: add_evidence
+    arguments: { id: T1, type: note, ref: "tests:ok" }
+```