git-orchestrator

Files (2)

• SKILL.md
• audit.mjs · scripts/

SKILL.md (first lines)

# The git orchestrator - the merge lane's runbook

## Active operator-selected direct workflow

`AGENTS.md` currently selects serial direct work. The coordinator implements,
self-reviews, runs focused checks and integrates through canonical main using
ordinary Git, then pushes, reads back the remote ref and leaves both trees clean.
No subagents in direct mode; no external inference agents or independent reviewer
are required. Explicit `/orchestration` on is the opt-in exception: native task
owners implement, self-review and use `integrate` under repository exclusion to
merge through canonical main, then report. No mid-task steering or recursion.
Only the coordinator publishes UI, handles `/update` or uses Sentinel. See
`docs/ORCHESTRATION-MODE.md`; this is not the historical parallel factory.
Never fabricate factory review/admission receipts to satisfy the historical
parallel procedure below. Full release gates run only on an explicit user request.

Runtime cleanup still requires exact owner/effect evidence through supported
recovery. Preserve drafts and unknown originals; a clean or merged branch does
not prove execution drain, task success or released workspace ownership. A named
runtime refusal blocks only its actual scope, not unrelated authorized direct work.
Use the focused instruction mutation check in `parallel-evolution` after changing
this policy; spell replay currently refuses mandatory session workspaces, so the
source CLI is the verified fallback.

**This file is the one home of the integration protocol.** `AGENTS.md` states each of its rules in
one line and points here; `skills/parallel-evolution/SKILL.md` is the producer's per-turn loop;
`docs/CONCURRENCY.md` owns the lane reservations; `docs/FACTORY.md` is the batch ledger, and its
own "The landing procedure" section is to be replaced by a pointer to this one. Keep LF, provenance,
tests and all existing work.

## The integration protocol

### The authority statement

**Who may move `main`: the merge lane, and only the merge lane.** A lane is a role a *run* takes,
not a person and not a session - the run the owner is talking to when it lands, a run started as
`/merge`, and any run opened for integration all take the same lane, and taking it is what
authorises reviewed merges and the push to `main`. **Merging a delivery is authorised without
asking each time**: a delivery an independent reviewer verified, whose branch is current with
`origin/main`, and whose own tree carries the producer proof required by admission, is admitted by the lane on its own. Routine shared runtime changes may carry actual focused checks with an independently anchored scope declaration. Only the user selects pre-release gating: source paths never infer a full or combined gate, and routine publication/deployment does not require one (`lane-policy.json`). Routine admission reports `gate_verified:false`, `release_verified:false`, and `requires_combined_gate:false`; an explicit pre-release claim still requires valid exact-tree full proof.
A coordinator merging each delivery by hand is the bottleneck this lane removes.

- **A producer or reviewer lane never moves `main`.** Its branch is its deliverable, and handoff is
a push, not a merge.
- **The merge lane lands in one sanctioned tree**: the canonical checkout, the only worktree whose
branch is `main`, addressed by absolute path (`git -C <canonical> ...`) - never by switching the
lane's own worktree onto `main`, and never in a node's or a producer's worktree.
- **One unlanded editor per hot file** - a file many branches touch (`scripts/test.sh`, a shared
module, this protocol). Not one per batch: every other concern runs in parallel, and the hot file's
change lands first because that is the shortest path to unblocking the rest.
- **A direct commit on `main` (no merge) is the exception**: it belongs to the run of a session, it
is for `main`'s own change (a document, a version bump), and it carries the trailer like any other
commit. The guard enforces this case and no other.

### Parallel lanes on one area, and the unmergeable tree (default)

The default is **many lanes at once, from empty contexts**, even when their concerns overlap in the
same files. Overlap is expected; the merge queue resolves it. This supersedes "one unlanded editor
per hot file" for the operator-selected direct workflow: that rule assumed a hand-merged queue, and
this one has a procedure.

- **A worker commits only.** Never merges, never deploys, never pushes `main`. Its branch is its
  delivery and its report is evidence, not verification.
- **First green lands first.** The first lane that passes the coordinator's own gate on a tree merged
  with current `origin/main` is merged and pushed; everything behind it waits.
- **A rebased branch is not green.** Every later lane is rebased onto the new `main` in a `tmp/`
  branch and re-gated. A receipt from before the rebase covers a tree that no longer exists.
- **An unmergeable tree is a routing decision, not a failure.** Two ways out, chosen by the conflict:
  - **rewake** (`subagent message`, `idempotency_key` required) when the conflict is *mechanical*: the
    same file with different hunks, or two assertions that need each other's strings. The child keeps
    its worktree, branch, diff and context; the brief is one line each - the new base SHA and the other
    lane's landing - then "rebase, re-run your focused checks, report".
  - **respin** (`subagent start`, new branch) when the conflict is *semantic*: both lanes changed the
    same logic, the new base invalidates the child's premise, or the same conflict already survived one
    rewake. A rewoken child defends its earlier reasoning; a fresh one holding both diffs does not.
    Preserve the old branch as `archive/<branch>`; never delete it.
- **Say which you chose, and why,** per case. "Rewoken because it was two probe strings" and "respun
  because its lifecycle change assumed the old fold" are different facts for the next reader.
- **The gate stays the coordinator's**, after every rewake and every respin, on a tree merged with
  current `main`. A skipped check is reported as skipped, never counted as green.

### The reviewer, and the switch that turns it on

The engine panel carries a `require reviewer` checkbox, **ON by default** (`wa.require-reviewer` in
localStorage, defaulting to on when nothing is stored), published to the page as
`window.waRequireReviewer()`. **This rule is what makes that switch mean something** — until it was
written here, the checkbox was a policy nobody read.

When it is **on**:

1. A worker's delivery is **not accepted on the coordinator's gate alone**. Before merging, start ONE
   reviewer child with: the worker's brief, its branch, and its report (if it made one).
2. The reviewer is a **second implementer, not a critic**: it reads the diff, pushes the branch further
   where it is wrong (same branch, its own commits), and answers once - `nothing required` or `changed
   X`. There is no agree/disagree round; that is what keeps the cost one extra step.
3. The reviewer **never merges and never deploys**. The branch is the mailbox; the coordinator lands.
4. Acceptance says which it was: `reviewed by <child id>` or `not reviewed (require_reviewer off)`. If
   the switch cannot be read, **review** - an unreadable policy is not permission to skip it.

When it is **off**: the delivery is accepted on the coordinator's gate plus its own diff review, and
the report line says so. That is the operator's explicit choice, not a silent default.

What the reviewer is worth, measured today rather than argued: three deliveries settled with
`"report":"absent"`, one worker deleted another lane's 27-line doc section out of scope, and one lane
was killed by a deploy restart. The reviewer is the step that reads the branch instead of the claim.

**What a landing must carry.** A landing missing any of these is not a landing:

1. the **reviewer's independent verdict** on the exact tip, from a lane that did not produce it
   (an agent's report is evidence, not verification - `docs/FACTORY.md`, invariant 1);
2. the **merged tree's own gate receipt** *when the landing is a release* - exit status, skip count,
   log hash, and the tree it is bound to - because a merge changes the tree and the branch's receipt
   covers only the branch (no effect before its proof - invariant 2). Since 2026-10-02 the full gate
   is a **release's**, not a landing's: an evolution landing is merged, LF-checked and reported
   (`--gate-mode none`, the default; `release_verified: false` in its JSON), and
   `scripts/wave-release.mjs` is what gates an exact tree, records the receipt and names it. What did
   not change is invariant 2 itself - a branch's receipt never covers the merge - so a release is
   gated on the merged tree it will certify, never on the branch it came from;
3. the **provenance trailer** on every commit, and a merge whose subject names the branch it merged;

From Magaav/wasm-agent, MIT.

More from Magaav/wasm-agent