the deterministic conductor for verified agent work
pleach takes a plan, a DAG of agent tasks. It runs each one in its own git worktree and
publishes a node/<id> branch only for work that mechanically cleared its
gates. So a swarm of agents can build unattended without garbage reaching the trunk.
agents produce; code decides.
why pleach
An agent grades its own work green. Reviewing every diff defeats the point of delegating. The only honest answer is mechanically enforced gates, run by code the agent did not write.
A node agent declares its work done. Its branch is merged by downstream nodes. A broken implementation propagates down the DAG: wrong logic, unchecked conflict markers, a red smoke suite the agent quietly ignored. By the time anyone notices, 3 dependent nodes have built on top of garbage.
Gates run before any branch is published. A node that fails conflict-marker scan, smoke, or cross-provider audit is quarantined: no branch, no dependents built on it. Only verified work reaches the next layer of the DAG. Garbage stays isolated at the point of production.
the loop, walked
Every node in the plan passes through the same fixed ladder. The agent touches only beat 2, and everything else is code.
A detached git worktree is created from the verified branches of every upstream dependency. The agent starts from a clean, merged baseline, never from trunk directly.
git worktree add --detach node/<id>
The configured runner drives the worker inside the worktree: one unit of agent work, isolated, observable.
This is the only beat the agent controls. Two runners ship in the box: umbel drives interactive agent CLIs in tmux;
direct-cli needs only the claude and codex CLIs on PATH. A pleach.config.ts swaps in any other.
Conflict-marker scan catches unresolved merges. Smoke runs the node's declared test command. Cross-provider audit re-runs the plan's check command in a fresh session from a different vendor. If claude built the node, codex audits, so no model grades its own work.
The node/<id> branch is written to git before the ledger is notified.
The source of truth is the git object store, not an API response that could fail mid-flight.
Only verified nodes publish a node/<id> branch.
Dependents build from that branch, and pleach land merges the verified
result onto your working branch. A failed node publishes no node branch. Its final
tree is kept on quarantine/<id> as evidence, and its dependents are
skipped, not built on a bad base.
gates
3 gates run in order. Each must pass before the next begins.
Conflict-marker scan. A literal string search for <<<<<<<
in every tracked file. No parse, no heuristic. A marker present means the node is quarantined immediately.
Smoke. The node's declared test command runs inside the worktree. The test suite the agent itself wrote must pass. A red suite means the node never had a credible claim to done in the first place.
Cross-provider audit. An agent from a different vendor re-runs the plan's check command in a fresh session and relays its machine-parsed verdict. If claude built the node, codex audits. The auditor executes; it does not opine: and pleach refuses to run a gate the builder edited, so a node cannot rewrite its own audit. This is the gate that makes the others honest.
quarantine/<id> so the evidence survives. Its dependents are skipped,
they are not built on a bad base, and they are not marked failed either. They wait
until the upstream is resolved.
hover or focus a node to highlight its dependency edges
built with itself
The same gates that decide what lands in any other project decided what landed in pleach. The garden is real; the numbers are current.
The proof run reaches a full verified close: built, cross-provider audited, verified, published, no human reviewing diffs. It also conducts outside this repo and outside TypeScript. plotplot's stem, a released Rust binary, was built from pleach plans.
honest scope
start
Part of the plotplot garden. pleach runs standalone on git + any agent tool. With the claude and codex CLIs on PATH, --runner direct-cli needs nothing else; the bundled examples run on git + bun alone, no agent and no API keys; and your own code can drive the conductor with import { runPlan } from 'pleach'. tend2 and umbel are the batteries-included reference adapters; swap either via pleach.config.ts. Read the adapters guide →