run-harness

run-harness - Drive-to-done loop

Role

Conductor of a multi-step run. Owns no domain expertise: reads the blackboard, decides the next step, dispatches it, records the result. Prompt-discipline plus advisory hook nudges - NOT a hard scheduler (never trap the main agent). Mechanism SSOT: docs/reference/workflow-harness.md §8 - this file is the operating procedure, that is the contract.

Out of Scope

• Authoring business artifacts → dispatches the specialist; only writes run-<id>.json.
• Planning / serializing the DAG → intake's Phase P. The driver only walks an EXISTING run-<id>.json; it never ingests a plan .md. A plan-producing skill (e.g. odoo-planning) routes it to intake Phase P (next: odoo-intake), NEVER next: run-harness with only a plan pointer - reaching this loop before serialization yields NEEDS_CONTEXT.
• Coercing the main agent → advisory nudges only (Hard rule #2).
• Crossing the Odoo↔general boundary → intake's routing decision.

Hard rules

1. Owns the blackboard. This is the orchestrator that walks the RUN-DAG; it owns the run state and controls dispatch, so it MUST NOT be invoked from inside a subagent.
2. Never hard-block the main agent - but that is not an open license to pause. This loop is prompt-discipline, not coercion: the Stop/PreToolUse hooks only nudge (advisory); they never deny a tool call or block a turn-end (quality-gate block is only ever for a subagent). That does NOT make "a node just finished" a reason to stop. The main agent auto-advances the run WITHOUT asking a human UNLESS one of the following ENUMERATED conditions holds - these are the ONLY legitimate reasons to end the turn and await a human "continue": (a) the node is L2 (§ Gate-tier resolution below - ALWAYS a human gate); (b) the run resolves to BLOCKED for ANY reason (§ Circuit-breakers below and every "STOP BLOCKED" in this file - examples, not a closed set); (c) NEEDS_CONTEXT; (d) the human issued an explicit stop/abort phrase (§ Circuit-breakers). Finishing a node, or any single subagent dispatch, is by itself never one of these - and a run that plows past a genuine (a)-(d) condition instead of stopping is BLOCKED behavior too (a real blocker ignored), not drive-to-done. (a)-(d) are the reasons to end a turn AWAITING A HUMAN; ending one to RECEIVE a dispatched agent's report is neither - that stop needs no human: the launch is asynchronous, so stopping is the ONLY point a result can reach you (§ The loop > dispatch), and the run resumes on the child's own completion.
3. Writes to run-<id>.json after creation are run-harness's alone. Intake's Phase P performs the one-time bootstrap write; from then only this loop writes it (hooks never write it - no race).
4. You dispatch; subagents do not. A step emits a Continuation Contract (a signal); acting on its next[] is THIS loop's job. Respect the worker-brief contract (snippets/worker-brief.md).
5. L2 is always a human gate. The autonomy dial can lower L1→auto-pass but NEVER L2 (irreversible/outward: shared instance, git MERGE to the principal branch, send to a third party). The merge is the ONLY OUTWARD L2 (owned by odoo-pr-monitoring) - not the only L2 a run hits: the REGISTRY also returns L2 for an instance-touching skill (odoo-i18n, odoo-acceptance), and the ephemeral ceiling lowers exactly the nodes THIS driver briefed against a throwaway database. No local merge into the principal checkout; no auto-merge. EVERY node's tier, integrate included, comes from the ONE total function in § Gate-tier resolution, never from a prose exception.
6. Worktree-always for SOURCE-writing dispatch (realizes intake Hard Rule 6). Before dispatching a node that writes the SOURCE tree (not the $ODOO_AI_HOME state root; same test as Gate-tier resolution), if it has no WORKTREE_PATH/TARGET: worktree:<path> and its approach is not a self-provisioning specialist (SSOT list: ${CLAUDE_PLUGIN_ROOT}/snippets/git-delegation.md § Self-provisioning specialists), INVOKE git-toolkit:git-ops for a dedicated worktree/branch, inject its path into the node's inputs, and write(RUN). NEVER dispatch a source-writing node against the principal checkout. A node writing only under the $ODOO_AI_HOME state root (e.g. odoo-code-review at TARGET=local) is NOT provisioned.