Dev Delivery

Core principles: one writer; independent, read-only review; fail-closed acceptance; fixes go back to the writer. Multi-agent raises the floor (that's what gates are for) — the ceiling is still the main model. So the gates must be real, short, and evidence-backed.

0. Pick the path

• Full flow: multi-file / delivered for the user to run / touches data or security.
• Lite: single-file tools, exploratory scripts → the main session lists acceptance points → implement with self-test coverage → (optional) one static review pass.

1. HITL plan gate (big changes only)

Before spending budget, produce a 3-5 line plan: files touched, module boundaries/contracts, failure modes, how it will be accepted. Get the user's nod first — reworking a plan is far cheaper than reworking a heap of code.

2. QA-first: freeze the acceptance checklist

Dispatch reviewer (read-only) to produce the acceptance checklist: numbered items + the pass bar for each + severity P0-P3. The checklist must be frozen before implementation; changing requirements mid-flight = change the checklist and say so.

3. Single-writer implementation

Dispatch worker-coder, one module per dispatch. "One writer" is a per-workstream rule, not one writer for the whole project — independent workstreams may run in parallel (below).

• verification-before-completion: run verification yourself (tests/command output) before reporting back; no fresh run output → you may not say "done".
• Every workstream declares one exit-code verification command — a single command whose exit code decides the workstream's pass/fail (test suite, build, lint, script). The writer runs it and cites the command + exit code; the main session re-runs it at acceptance. A subagent reporting "tests pass" is a claim, not evidence — the exit code is the evidence. (This is the world.run lesson: judgment belongs to a command's exit code, not to a model's self-report.)
• Every dispatch declares its file boundary — the list of paths/globs the writer may touch. At acceptance the main session runs the boundary gate: node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <base-ref> (exit 0 required). An out-of-bounds edit is a P0 finding even if the code is perfect — it means two writers now collide.
• Report format: the pack-wide five-section shape (REPORT-CONTRACT.md) — files changed + run evidence under Verified (command + exit code each) + leftover risks under Not covered/Skipped.

Parallel workstreams (multi-module tasks)

Two modules are independent workstreams when their file sets are disjoint. Then dispatch N worker-coders in a single message (so they run in parallel), each carrying its own slice of the frozen checklist.

Safe to parallelize	Keep as one workstream
separate directories / modules / projects	the same file (entry point, router, registry, package.json, lockfile)
separate service boundaries behind a frozen interface	DB schema / migrations
docs vs code, in separate files	shared i18n / config files

Rules:

1. Freeze the interface before dispatch — function signatures, data shapes, file paths go into every dispatch note. A moving interface turns parallel work into rework.
2. Freeze each workstream's file boundary — the path/glob list the writer may touch, recorded with the dispatch. After merge, prove the boundaries held: node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <merge-base> must exit 0.
3. A shared file that must change is its own workstream: main session (or one writer) lands it first, the others build on the result.
4. Each workstream runs the same pipeline end to end: QA-first checklist slice → writer self-verifies → diff-only review → fail-closed acceptance. Parallelism changes how many writers run, not how each one is gated.
5. Integration belongs to the main session: merge, run the cross-module check, then re-run every workstream's acceptance items (including the exit-code verification command and the boundary gate) on the integrated tree — per-workstream review cannot see cross-module breakage.

4. Independent read-only review

Dispatch reviewer. Dispatch notes:

• Feed only the diff + requirements (+ optional commit SHA), never the conversation history — clean perspective, no contamination.
• Output: each finding = location (file:line) + phenomenon + severity (P0-P3); no unsubstantiated generic advice.
• finder ≠ fixer: the reviewer only finds; fixes go back to the single writer; one repair round, no recursion.

5. Fail-closed acceptance

• unknown = fail: anything unconfirmed counts as not-passed unless explicitly waived with a written reason.
• An empty diff needs an explicit waiver to count as "no change needed".
• Numeric assertions must trace to first-hand output (test logs / command output) — "I did run it" is not accepted.
• Mechanical gates run at acceptance (all must exit 0):
  • node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <base> — no file outside the declared boundary was touched.
  • node <pack-root>/tools/gates/report-lint.mjs <writer-report.md> — the writer's report satisfies the five-section contract (and no "skipped" check is disguised as blocked).
  • the workstream's declared exit-code verification command.

6. Visual gate (when the deliverable is UI / web / PPT)

• Render → screenshot → verdict (pass/fail + evidence, one line per page/screen) → fix → re-render and re-judge.
• Judge with visual-judge (zero write permission; sees only rendered images, never source files).
• Mechanical gate (optional): edited UI files but produced no screenshot evidence this turn → bounce at wrap-up to collect evidence. Example hook: hooks/ui-screenshot-gate.mjs in this repo.

7. Failure handling — attribute first, then act

"Retry once" is not one rule. The three failure classes have opposite correct actions:

• failed-transport (timeout, killed for inactivity, turn execution failed, provider 4xx/5xx): retries belong to the host/provider layer. Do not burn a protocol retry — wait, then re-check via the ledger. Record mark --status failed-transport.
• failed-protocol (agent returned malformed output, ignored the contract, edited out-of-bounds files, claimed done without evidence): re-dispatch once with a narrower scope; a second protocol failure means the brief is the problem → treat as failed-definition.
• failed-definition (the task itself was misspecified — wrong scope, duplicate of another workstream, unreachable as written): never re-dispatch as-is. Void the task, void any work that rested on it, and re-specify as a new dispatch.
• Circuit breaker: the same channel/model failing twice in a row → switch channel/model; do not hit it a third time.
• Silent model substitution: for third-party OpenAI-compatible endpoints, verify the response's model field matches the request (scripts/verify-model.mjs) — some endpoints answer with their own default model for unknown ids without saying so.
• Every outcome is recorded with tools/ledger/dispatch-ledger.mjs — an unlogged failure is a silent one.

8. Dispatch ledger (recommended for anything multi-dispatch)

• Mechanical record: node <pack-root>/tools/ledger/dispatch-ledger.mjs append|mark|status — append-only JSONL at <project>/.dispatch/ledger.jsonl (created on first use, with its own .gitignore). Each event carries the task id, lane, model, sha256 of the invariant brief and of the parameter block, output path, timestamp, and status (dispatched / succeeded / failed-transport / failed-protocol / failed-definition / verified / completed / voided).
• status answers "which conclusions are not yet verified" — the gap list reads itself from the ledger instead of from memory.
• Prose layer (optional, unchanged): save full task + raw output to <project>/.dispatch/<time>-<role>.md; multi-round progress in .dispatch/STATE.md.

Pre-delivery self-check (all must pass)

• Checklist items all verified? Un-passed ones explicitly waived with reasons?
• Review findings all carry location + evidence? P0/P1 fixed or explicitly declined with reasons?
• Fresh run output exists before any "done" claim?
• Visual deliverables: screenshot evidence + verdicts present?
• Dispatch ledger complete (if enabled)?