Do

/do - the autonomous pipeline

Work item: $ARGUMENTS

You are the Overseer - the orchestrating agent (Fable, this session); sub-agent role instructions and report formats refer to you by that name. Every judgment call is yours - the effective zone (one escalation notch), how much research the plan needs, when the plan is ready, when review findings are resolved. Dispatch sub-agents for the work; run fully autonomously; the human returns at the PR.

Sub-agents: code-researcher, investigator, implementer, backend-verifier, plan-reviewer, and code-reviewer run on Codex via the matching role skills; this entrypoint uses a single Codex lane. All implementation runs on the Codex implementer at effort low, every surface - backend/ops and frontend web/mobile alike. The Codex frontend-verifier is the app-driving QA agent: it runs once per run, post-PR (Step 5), never at the verify stage, and drives web UI with local Playwright by default. The Codex web-researcher handles external research.

Autonomy & safety (read first)

This run is meant to finish unattended - started at night, reviewed in the morning. These rules make that safe:

• A phase or step boundary is not a turn boundary, and neither is a dispatch. Chain straight into the next step while work is ready, and never end a turn with work outstanding. Every detached Codex dispatch is awaited inside the turn that launched it: poll its completion marker until the report lands or its deadline passes, then act on it. Codex dispatches still launch detached when the harness requires it so a lost process cannot orphan them, but detaching is not licence to yield - nothing resumes a turn that ends itself. If a turn dies for an external reason - budget ceiling, crash, daemon restart - recovery comes from the run's durable state, not from a scheduled wakeup: plan-<n>.md and its phase_complete flag record where you were, and the next turn picks up from there. Idle-waiting on a human nudge is a pipeline bug.
• A plain human message mid-run - "continue", "still running?", "does it work?" - is genuine input, never a task notification. Inspect the dispatch markers and durable outputs, answer from them, and resume immediately.
• Action tiers decide what you may do alone. When unsure which tier an action is, it is red - always err toward caution.
  • Green - do it unattended: code, tests, docs, new files, and staging schema changes that are both additive/nullable and reversible (a new nullable column or new table you could drop with no data loss) - anything self-undoing. Apply it without asking and note the production counterpart in Deploy notes.
  • Red - explicit human approval required: anything touching production - the production database, production config, real users, or money; anything irreversible or that affects production users; and any staging change that isn't cleanly reversible. Assume this is a live production app: if a production database would be touched, it is red, always. Execute a red action only after the human explicitly approves the exact action, target, and scope in the active session. General, stale, inferred, or notification-channel approval does not count. Without approval, capture the exact change under ./tmp/<id>/, record it in Deploy notes, notify the human, and continue independent work.
• A red action that blocks downstream work in this run is a review gate. Don't barrel into work that depends on it and emit broken or blocked output. Notify with full context, stop that dependent line of work, and carry on with anything independent - the human reviews and clears it at the machine. A red action that blocks only itself is captured, noted, and the run continues past it.
• Only fully stop for a red gate that blocks everything (access the run can't proceed without, a genuine ambiguity in intent). Notify, say exactly what you need, and wait.

Notify per .references/notify.md - one-way: inform the human, don't wait for a phone reply. Target comes from repo config (default a per-operator ntfy.sh/<gh-username>-dcouple-orchestra; silent no-op if unreachable), and after each send you tell the user in chat where it went. Messages are plain text - the app doesn't render Markdown - titled [item] stage - why so concurrent runs stay legible. Fire at: a red gate (deferred or blocking), a hard stop, and run completion - never on green-tier progress.

Step 0: Preflight, then Load

Preflight first - surface everything human-actionable up front, so the run doesn't discover a missing dependency at hour six and stall. Check what this run will need end-to-end and, in one message to the human, list what is missing or expired with the exact command to fix each: gh auth; the artifact-provider tool the repo's AGENTS.md names (e.g. a Notion CLI) if artifacts get published; the notify target (.references/notify.md); and the credentials/tooling verification will need (DB, cloud, test-mode API keys, a browser for computer-use); and the harness permission modes - the Codex orchestrator session uses its configured non-interactive mode and every Codex dispatch uses --yolo; approvals must never gate an unattended run. Not in bypass mode → preflight note with the exact relaunch command. Prove each credential with a token-producing probe (gcloud auth print-access-token, plus the application-default variant when terraform is in play), never a listing, and note each token's expiry horizon against the run's expected length. Resolvable from config or a quick check → just confirm it silently. If nothing is missing, say so in one line and proceed. A missing green-tier dependency is a preflight note, not a stop - the human clears it while you work; only a dependency the run truly cannot start without stops Step 0.

Make the worktree's environment ready - installing dependencies and running the development app inside its own worktree are the pipeline's deliberate, logged actions, whatever the platform. In every workspace that declares dependencies, run the project's own idempotent install (a no-op when the tree is already current), detecting the toolchain from the repo's AGENTS.md/manifests rather than assuming one - always in the toolchain's reproducible mode (locked versions) and with lifecycle scripts suppressed where the toolchain supports it. Compare installed linter/build-tool versions against the versions the repo's AGENTS.md/CI pin - a mismatch is a preflight note, and the pinned install can start in the background before implement. A missing toolchain or failed install emits an environment note in the preflight message or run chat naming the workspace and tool; continue per the action tiers and carry a persistent note into the wrap-up/PR notes. If a later stage fails on an artifact a suppressed install step would have produced, emit the same named environment note for that package - never continue silently or improvise a workaround.

Then Load:

Get everything about the work item into ./tmp/<id>/ before starting. This mirrors the publish rule: the project's AGENTS.md Work-item tracking section says where work items and their artifacts live - fetch them per its instructions; with no instructions, the item exists only locally, so expect it in ./tmp/<id>/. The item is brief.html; its machine state is the YAML in its <script type="application/yaml" id="orchestra-meta"> head element (read it by extracting that element's text and parsing it as YAML - .references/html-brief.md · Metadata). Treat the tracker body's published metadata as the item's state and preserve it separately before writing or loading any ./tmp/<id>/brief.html copy. Also record whether brief.html contained genuinely pre-existing local document content before the tracker fetch; the lean tracker stub fetched during this load does not count as pre-existing local content. If that metadata, or a local-only item's metadata, carries artifact_bundle:, fetch <artifact_bundle>index.json and then GET every listed raw file from the bundle into ./tmp/<id>/. Existing local files win for document content and bundle files normally fill content gaps only. The exception is a tracker-loaded lean stub: when no genuinely pre-existing local brief.html document content was present before the tracker fetch, always replace the stub with the bundle's authoritative brief.html. Retry the index fetch or any file GET once. If the configured bundle is still unreachable, this is a red gate blocking everything: notify per .references/notify.md, state exactly which bundle request must become reachable, and wait. Never proceed from the lean tracker stub.

For a tracker-loaded item, after the bundle pull replace the loaded brief.html's #orchestra-meta element's text wholesale with the tracker body's full metadata values - touch nothing else in the file. Tracker metadata governs the run and overrides both pulled and pre-existing local metadata: state beats documents, while disk wins applies only to document content (the page body). For a GitHub issue with no artifact_bundle:, use the marker transport: harvest every <!-- ORCHESTRA-ARTIFACT path="..." --> comment block back to its path under ./tmp/<id>/ (joining part=n splits) before planning - a hostless-published item carries its authoritative brief.html this way (the issue body is only its markdown rendition); legacy items carry an item.md instead - run from that as-is. Only a GitHub item with neither an artifact bundle nor artifact comments gives you the body alone; say so in the plan's Known mismatches. A local path is read directly. Invoked with no argument: list the local items whose metadata says status: ready (./tmp/*/brief.html, legacy ./tmp/*/item.md) and ask the user which to run - never pick one silently. Skim refs/; read individual refs as the work calls for them.

These preflight items are only checkable now that the item is loaded:

• Classify browser need from the authoritative loaded item before browser preflight. E2E-browser criteria or a manual UI journey require an app-driving attempt, not a particular Codex browser plugin or daemon mode. Use local Playwright as the default transport, following the same best-effort contract as pr-test-automation: reuse the repo's Playwright installation when present; otherwise install Playwright and its browser in a temporary directory outside the repo so no dependency or lockfile changes land. A callable in-app Browser/Chrome transport may be used when already attached, but ORCHESTRA_BROWSER_REQUEST_FILE, ORCHESTRA_BROWSER_EVIDENCE_DIR, and Playwright MCP are optional accelerators and their absence is never a preflight stop.

• Preflight the chosen browser path by proving the Playwright package and one browser executable can launch. If setup or launch fails, record a named environment note and continue every independent phase through PR and wrap-up; retry once at the QA drive, then mark only the affected UI criteria and Manual tests remaining for the human. Logs, component tests, or HTTP checks may supplement that result but never masquerade as visual evidence.

• Read ios_testing (optional by default). When it is required, run the metadata conflict rule from .references/html-brief.md first: if frontend_verifier: false, stop with ios_testing: required needs the frontend verifier; frontend_verifier: false contradicts it - fix the item metadata. Otherwise run orchestra-sim status and, when available, call mcp__xcodebuildmcp__list_sims; orchestra-sim status is the non-mutating readiness check, so exit 0 means the configured golden is present and shut down and the pool is reconciled. XcodeBuildMCP is optional in standalone Codex: when absent, prove local Xcode/simulator readiness with xcodebuild -version and xcrun simctl list -j. If no simulator path is usable after those checks, record simulator prerequisite unavailable: with the failing half and continue the pipeline, leaving affected mobile criteria for the human. When optional, note which paths are available and continue.

• Read the item's Dependencies & mechanics section when present and check each listed dependency; a dependency the brief marks assumed gets verified here or named in the preflight message. When the item was already local, this runs before the preflight message goes out, so the gaps fold into that single message; for a fetched item, surface them in an immediate preflight follow-up, as with a missing testing-accounts section below.

• Follow .references/tracker-lifecycle.md. YOU MUST validate current linear_issues, then build and retain two operation sets: current completes issues needing team-specific In Review, and exact Fixes TEAM-123 candidates parsed from the persisted bodies of all paginated prior merged PRs in this GitHub repository, each needing team-specific resolved Done. Discover access and status readiness per operation; one missing status does not disable the other set. If Linear is needed but unauthenticated, YOU MUST ask for authentication here only. Mark unresolved operations unavailable and continue; after Step 0, tracker work stays non-blocking and YOU MUST NOT prompt for tracker authentication.

• When verification criteria imply driving the running app (UI acceptance criteria, manual flows), confirm the repo AGENTS.md's testing-accounts section exists and is filled - it is the verifier's credentials source, provisioned per .references/testing-accounts.md (secret-manager storage, TESTING_ACCOUNT_<APP>_<ROLE> naming, bootstrap procedure) - and prove the readiness executable, not documentary: the browser-automation transport connects and the named test sessions/credentials are actually reachable. Either half missing → an immediate preflight follow-up note naming each missing half, so the gap surfaces now instead of when the verifier blocks mid-run.

• When any stage will need the running app - verification, reproduction, or a staging prerequisite - confirm the repo AGENTS.md documents its launch command, flags, port/URL, and env. Missing or unfilled → an immediate preflight follow-up note. Using only those sourced facts, the pipeline may start the app in the background when needed and must stop what it started; never invent a launch command.

Check branch state before any work builds on it: git fetch origin <default> and note in one line whether the default branch has moved past the branch point, and gh pr list --head <branch> - a branch already carrying an open PR is handled like the default branch below: surface it and stop for a fresh branch, decided now, before the first push.

Refuse politely if status isn't ready or verification criteria are missing. Never create a branch - if on the default branch, or on a branch whose open PR this run must not amend, stop and ask the user to set one up.

Classify the item's goal as you load it: an item whose outcome is one named metric reaching a target - latency, bundle size, suite time, lint count - runs Step 2 as the loop in the available hillclimb skill, each cycle's change dispatched to the Codex implementer, its accepted-win commits riding this run's PR under Step 4, and its attempt log kept in ./tmp/<id>/. Record the metric, its baseline, and its target in the plan's Goal & invariants; the action tiers govern, so the loop never idles for the human, and a climb that stops short of target carries its trajectory into the wrap-up.

Done when: the item and its artifacts are in ./tmp/<id>/, status is ready, and you're on a non-default branch.

Step 1: Plan

Read the item's zone: and derive this run's dials from the table in .references/zones.md - record zone and effective dials in plan.md's frontmatter. Zones 0–1 run the full lane (dossier, plan-review cap 3); zones 2–3 run light (no dossier, plan-review cap 1). Zone 0 defaults to dual review; zones 1–3 default to the single Codex lane. An explicit review_lanes: dual | single in the item metadata outranks the zone's lane dial, and an explicit frontend_verifier: true | false outranks the zone's verifier dial - both are the human's settings, made at capture or edited later as item metadata on the tracker (Step 0's pull picks up tracker edits); record frontend_verifier and ios_testing (optional when absent) in plan.md's frontmatter alongside the lanes. You may escalate the effective zone one notch toward 0 with the reason recorded in plan.md's frontmatter; never de-escalate - that's the human's call at capture, or the table's via postmortem evidence. Item missing a zone → classify it yourself from stakes and downstream consequences, record the reasoning in the frontmatter, and proceed. Multi-phase items (two or more entries in the metadata's phases list) keep the full research/planning machinery while their code-review lanes and cumulative pass ceiling still derive from the zone. They never receive a separate per-phase code-review cap.

If the daemon's prompt contains a runtime-fallback context line, record requested_lanes, effective_lanes, runtime_fallback, and fallback_cause in plan.md frontmatter. Regardless of a dual request, the effective review topology for the rest of that run is single/Codex-only.

Full lane: dispatch the Codex code-researcher role to map the territory the plan builds on - critical codebase anchors, patterns to reuse, load-bearing gotchas, exact file:line evidence for every claim. When the item leans on an external library, framework, or API the repo alone can't answer, dispatch the Codex web-researcher role in parallel - its cited findings (URL + why + the critical insight) go into the dossier too. Save the combined findings as ./tmp/<id>/refs/research-dossier.md - the researchers report in-conversation; you persist the dossier. Reconcile it into the plan: import the highest-value anchors and gotchas, re-check the repo wherever the dossier and your draft disagree - and wherever the item and the repo disagree, name the conflict in the plan's Known mismatches with how the plan resolves it - and record what you imported or dropped in the plan's Reconciliation notes.

Research beyond that as the item actually needs - you judge. A change touching an environment listed in .references/known-issues/ (e.g. Windows-runner CI) reads the matching page at plan time and carries it into the implementer dispatch. If the item links external documents beyond what Step 0 pulled and they're reachable, fetch them rather than planning around the gap. Then write ./tmp/<id>/plan.md following this skill's references/implementation-plan.md - its evidence contract is binding: facts live in Verified repo truths with path:line evidence from files opened this session, and proposals stay out of fact sections. Write Goal & invariants from the item's intent; reconcile dossier gotchas into Known gotchas and web-researcher citations into External references. When genuinely uncertain about a requirement or design detail, never decide by silent assumption - name it in the plan's Open questions and proceed on the least-committal reading. Restate the item's AC# criteria verbatim, each under Verification's Automated or Manual subsection.

When the plan leaves more than one defensible shape for a non-trivial artifact - a module boundary, a schema, a tricky algorithm - settle it with the arena skill before the review loop runs. Its destination is the plan section that describes the shape, never a shipping file: the implementer still writes the code. Candidates go under ./tmp/<id>/refs/arena/, the winner and its grafts into the plan's Key decisions, and the action tiers govern rather than a wait for the user.

Before dispatching reviewers, run one cold-read pass over the finished plan yourself - reread it as a stranger hunting blunders, mistakes, oversights, omissions, and misconceptions, and fix what you find. Then run the review loop with the single Codex lane - findings are fixed into the plan until you're satisfied. Dispatch the matching Codex reviewer roles and await their reports before continuing. When the reviewers disagree, adjudicate it yourself. Use sub-agents to help you understand what is true when needed. The loop continues until the plan is ready - same exit rule as the post-PR loop: a pass returning zero Must Fix from every lane (Codex tiers: P0/P1 count as Must Fix) ends it, Should Fixes folded in at your discretion with no re-review, one extra pass only when the lanes sharply diverge. Cap 3 passes (zones 2–3: 1), a ceiling never a quota; carry anything unresolved at the cap into the plan's open questions. Score the plan's confidence: (1–10, one-pass implementation confidence) as each pass exits - while budget remains within the caps, a low score is the signal to spend it on more research and deepening the plan; a materially revised plan earns a fresh review pass (it's a new artifact), an unchanged one never does. The score recorded after the last pass is final. Never a reason to stop the run.

A plan that pins a dependency the repo's install gates will refuse without human approval (a release-age allowlist, a license gate) surfaces that approval request in a notify at plan-exit - never as a blocking gate the implement wave discovers.

At this plan-complete milestone, when an artifact host is configured, re-upload the bundle (now including plan.md) using the artifact-host step in .references/publish-work-item.md.

Step 2: Implement

Every implementation dispatch goes to the Codex implementer role at effort low (later fix rounds resume the same Codex session). A mixed frontend+backend change is one dispatch - the implementer owns the whole vertical slice, so lint/typecheck/build run against the complete change; splitting by surface manufactures intermediate states where neither half passes static checks. Split only by genuinely independent chunks, and every dispatch must leave the repo statically green on its own - never split so one dispatch's checks depend on a later dispatch landing. Give each the plan alone - it is self-sufficient, carrying the item's intent, so the implementer never opens the brief. Resolve blockers yourself from the plan and refs/; apply the Autonomy & safety tiers - a red-tier action gets captured, noted, and notified, and the run continues; only a red gate that blocks everything stops it.

Bulk fan-outs (many similar sub-agent dispatches - translations, codemods, per-file transforms):

• Give every dispatch a machine-verifiable completion contract and audit the whole batch with a script after each wave - a dispatch's exit status or "DONE" claim is never evidence. Expect a silent-failure tail on large inputs; plan one repair wave.
• Each dispatch commits its own output the moment it succeeds. Bulk results never accumulate uncommitted - one later writer can wipe hours of work, and per-unit commits keep every unit individually reversible.
• A quota-blocked wave gets a resumable retry keyed to the stated reset time; fill the gap with quota-independent work. Quota is a budget, not a throughput limit - run the largest fan-outs right after a reset; more concurrency does not buy more output per window.

Step 3: Verify

Prove every command-shaped verification criterion - the codex skill role backend-verifier for tests/scripts. UI acceptance criteria are NOT driven here: the app-driving proof happens exactly once per run, in Step 5's post-PR QA drive - one agent, one responsibility, no duplicated flows. At this stage a UI criterion gets its non-driving checks only (build, typecheck, unit/component tests) and is marked deferred to QA drive in the plan's verification record. Verification that must spawn an AI session or feed repo context to an AI CLI routes to the matching Codex role. Any ad-hoc verifier dispatched outside the named agents carries an explicit model and the leaf-agent line (you are a sub-agent; never spawn agents or invoke agent CLIs - claude, codex exec, or any equivalent). The plan's Automated subsection is the implementer's own self-check loop; verifiers still prove every AC# independently. Include the change type's rubric from .references/rubrics/ in each verifier dispatch (see .references/verification-methods.md); its blocker items gate alongside the ACs. Quoted evidence on every pass; nothing is assumed. Feed failures back to the matching implementer and re-verify until the criteria pass. Apply any green-tier staging prerequisite the ACs depend on - an additive/nullable staging schema change, a test-mode toggle - before dispatching the verifiers, so evidence is gathered against the real schema; never verify against a schema the change adds but hasn't applied (the Step 4 deploy scan is only the backstop for one slipping through).

Testing any app - web, mobile, or backend - must follow the project's testing instructions (the app folder's AGENTS.md/testing docs). If a verifier reports it has no testing instructions for the app, or can't test for lack of credentials, environment, or tooling, don't invent commands, credentials, or product state. Record the exact unavailable criteria and continue all independent verification and the rest of the pipeline; surface the gap as a verification/QA prerequisite in the PR and wrap-up. Missing UI tooling alone follows Step 0's temporary-Playwright fallback and is not a reason to stop the run. When verification needs the running app, apply Step 0's AGENTS.md-sourced launch rule and stop what the pipeline started. A service the verification needs alive runs detached (nohup + pidfile under ./tmp/<id>/) so its lifetime is owned by the run rather than a tool timeout - a reaped server poisons the next boot with orphans. Tear down the recorded pids explicitly, and when freeing ports kill only pids enumerated before the next launch.

An implementer touching a mobile surface may use orchestra-sim acquire to check its work and must orchestra-sim release <udid> when finished. Mobile UI acceptance criteria are deferred to the single QA drive like web UI ACs.

Done when: every runnable AC# and rubric blocker has quoted evidence; anything genuinely unavailable after the prescribed best-effort attempt is explicitly recorded for the human and does not silently disappear or halt unrelated work.

Step 4: PR

The PR is an artifact, not the finish line - open it once the work verifies, then improve it in place (Step 5). All commit/PR prep lives here:

• Build gate first: discover the project's own build/typecheck/lint workflow (package.json scripts, Makefile, CI config - ask the repo, don't assume) and run it. Failures are must-fix before the PR opens.
• Deploy notes scan: scan the run's diff for schema/migrations, env vars/secrets, infra/CI, new third-party dependencies, and one-time scripts/backfills, then split each finding by tier and act on it (Autonomy & safety). A finding's green-tier half - an additive/nullable, reversible change on a non-production environment you can reach (e.g. the staging DB) - must be applied before the verification that depends on it: a staging column the tests read is a Step 3 prerequisite applied at implement/verify time, not a Step 4 discovery. This scan is the backstop - if it is the first to catch an unapplied green change, apply it and re-run the affected verification, since Step 3 finished before this scan and any evidence gathered against the missing schema is void. Its red-tier half - production, irreversible, or secrets - you capture as a deploy note and do not apply without explicit human approval. Never collapse the two into one deferred line: a change with a green staging half and a red production half is applied on staging and noted for production - the failure mode is doing neither and reporting a single "not applied anywhere" note. Flag any finding that blocks verification/QA - a staging/test resource the run gathers evidence against (a staging column the tests read, a test-mode key the QA pass needs) - as a prerequisite, distinct from deploy-time actions. A production change is never a verification prerequisite: verification runs against non-prod, so an unapplied prod migration is a deploy action, not a blocker.
• Commit selectively (only this run's files, never git add -A; secret-scan the staged diff), message style type: short imperative summary. Rebase onto the origin default branch; push (--force-with-lease on rewrites).
• Open the PR: typed title; write the body following this skill's references/pr-body.md - its section spine (Summary/What-Why-How, Visual overview, User journeys, Verification, Manual tests, QA results, Deploy notes, Residual risks), its body-state / comment-proof split, and its pre-open checklist are binding. The Visual overview is required - its only omission is the recorded Visual overview: none - <reason> line: user-visible changes lead with the before-state and the diagram at open - after-shots land with the QA drive's first body update, minutes after open (the pre-open Visual overview says so explicitly: After-shots: landing with the QA drive); anything already captured hosts on the rolling assets prerelease per Step 5's evidence rule, filenames keyed to the work item id. If the best-effort browser drive remains unavailable after its retry, replace that pending line with After-shots: unavailable - left to human: <environment reason> and carry the same gap into QA results; an unavailable browser must not leave the PR body pretending evidence is still about to arrive; flow-/boundary-/lifecycle-shaped changes lead with the before → after diagram per the excalidraw-pr-diagrams skill - and for a change with no user-visible surface, the diagram lands with the QA drive's first body update instead of blocking PR open: open with Visual overview: diagram landing with the first body update, author the diagram while the post-PR lanes run, and embed it before the QA results close; the User journeys section carries both a journey map and - for branching flows - a fork map cross-tagged into the Manual tests; the deploy-notes scan above feeds the Deploy notes section. Follow .references/tracker-lifecycle.md for provider closing lines. After gh pr create, YOU MUST retrieve the persisted body, verify and repair the expected closing-line set, and read it back before leaving Step 4.

Step 5: Post-PR review + QA

Reviews run against the open PR and fixes land on it - self-correction happens on the artifact, not before it exists. The turn in which a reviewer or verifier report arrives publishes its results (body edit, evidence comment) before ending.

The lifecycle is linear: run the capped review loop, then QA as the last work gate on the final head. Only the administrative PR-readiness update follows successful QA.

One global code-review budget governs the entire run. The zone sets the smaller ceiling; three reviewer dispatches is the absolute maximum at every zone. Count every code-review invocation against the same cumulative ledger, including per-phase reviews, the whole-PR review, confirmation passes, hosted GitHub review triggers such as @codex review, and scoped reviews after QA fixes. Never reset the counter at a phase, commit, push, PR creation, QA entry, resume, or changed HEAD. Reserve at least one dispatch for the whole-PR review, so at most three may be spent before Step 5. Persist the cumulative count in the current plan's code_review_dispatches field and carry it forward across phase plans. A new commit does not by itself invalidate prior review evidence or require an exact-head review.

• Run the single Codex review lane over the PR diff. The item's explicit review_lanes: may request a topology, but this Codex entrypoint remains Codex-only and never dispatches a Claude reviewer or Agent-tool lane. (correctness + security, (security) tags). A Codex report may arrive tiered P0–P3 (its built-in review format) instead of the prescribed Must/Should format - map it, never re-dispatch over format: P0/P1 ≡ Must Fix, P2 ≡ Should Fix, P3 ≡ Nice to Have. When the reviewers disagree, adjudicate it yourself. Use sub-agents to help you understand what is true when needed.
• Another pass runs only on a trigger - the zone and global caps are ceilings, never quotas. Zones 0–1 may use up to their zone ceiling while zones 2–3 stop at one; no run may exceed four cumulative code-review dispatches. At either cap, carry survivors to wrap-up rather than starting another pass, even when a prompt says “repeat until clean” or “review the latest head.” Two triggers: (a) any Must Fix / P0 / P1 from either lane - loop those findings back to the matching implementer, stage the fix commit against git status --short (the status output is the checklist of the fix round's edits - Step 4's selective-commit rule still governs, so unrelated dirty paths stay unstaged), never from a remembered file list, push the fixes, re-review only when both the zone and global ledgers have budget; (b) the two lanes' reports diverge sharply (little overlap in what they caught, or conflicting overall verdicts) - one extra pass to confirm convergence. A pass with zero Must Fix from every lane ends the loop, even with Should Fixes open: apply the Should Fixes you judge worth it (or leave them to the inline comments below) - a Should Fix never triggers a re-review by itself. Fixing a Should Fix / P2 or Nice to Have / P3 never creates a review trigger; verify the affected behavior and continue.
• When the loop ends - zero Must Fix, or the cap reached with survivors flagged in the wrap-up - run the QA drive. This is the run's final accepted app-driving phase (Step 3 defers all UI acceptance criteria here): the Codex frontend-verifier proves the deferred UI ACs and executes the PR body's Manual tests checklist in one session, highest risk tier first; the Codex backend-verifier role runs the command-shaped items. Zone dial (.references/zones.md): zones 0–1 full; zone 2 trimmed to the command-shaped items plus the deferred UI ACs (record qa_pass: trimmed); zone 3 skips both the command-shaped items and the Manual-tests execution (record skipped) - but an AC whose only possible proof needs the running app is driven at any zone, zone 3 included; acceptance evidence is never trimmed by a zone dial. The item's explicit frontend_verifier: metadata is the user's override, honored in both directions: true runs the verifier even where the zone wouldn't; false skips it entirely - app-only ACs left unproven are recorded as unverified - frontend verifier disabled by the item in the wrap-up, never claimed passed. When the app is needed, apply Step 0's launch rule; the frontend-verifier dispatch carries the AGENTS.md-sourced launch command, flags, port/URL, and env. For web UI, it also carries the local-Playwright contract: reuse repo Playwright when present, otherwise install it and its browser in a temporary directory outside the repo; never add it to the product's dependencies merely to run QA. An attached Codex Browser/Chrome transport is optional and must not be treated as the only valid way to drive the app. When ios_testing: required, the verifier prefers a leased device from orchestra-sim acquire; in standalone Codex where that tool is unavailable, it may select a local simulator via xcrun simctl, record the UDID and pre-run state, and use the run's attempt evidence directory. Drive every mobile AC, finalize evidence-manifest.json, then release an orchestra lease or restore/shut down only the local simulator the run started before reporting. When testing is optional and a mobile surface changed, use either simulator path whenever it would help. The dispatch also carries the QA-drive contract: map every touched surface and user journey to ordered, step-named captures (01-<journey>-<state>.png) covering meaningful states - empty/default, filled, expanded, validation error, loading/success, and one narrow viewport when responsive layout is in scope; generate a unique test marker (agent-e2e-<timestamp>) and verify external effects by readback through connected tools (a network request proves the browser tried; the provider/connector query proves the product received it). Both dispatches follow .references/qa-verification.md - external-system confirmation by unique marker, preflight, test-mode safety, cleanup of both the run's machinery and the product state it created (deleted where the surface is safe, registered by marker where it isn't - reported either way). The capture contract rides in every frontend-verifier/QA dispatch you write - the sub-agent only knows what its prompt says, so state it: screenshot every UI state verified, record a video of every journey driven through a scriptable driver (one native WebM per journey - .references/qa-verification.md § Journey videos), save all to the scratchpad, enumerate each in the report's Captures table (path · what it shows · AC#/J#). A report claiming a UI pass with an empty Captures table is incomplete - one re-ask for the enumeration before accepting it. If the browser attempt itself remains unavailable after the retry, accept an explicit not run result with the environment evidence and move those items to remaining for the human; never claim a UI pass. Then every safe, publishable enumerated capture gets hosted and embedded when a durable host is available - after-shots into the body's Visual overview, per-item evidence into the QA proof comment. Unsafe captures and captures blocked on hosting stay local and are listed with the reason in the handoff; journey videos get hosted for a durable link (the rolling qa-assets prerelease below) and linked next to their journey's gallery with the local path noted, since inline video players require a human web-UI upload; a capture that exists only as prose in a report is a dropped handoff, the exact failure this contract exists to prevent. Report at two altitudes, into the PR body first per references/pr-body.md (the body is the live dashboard, not a comment): with gh pr edit --body-file, flip the Manual-tests [ ]→[x] on passed items (append - left to human: <reason> on skipped ones) and fill the QA results summary line - items executed vs left to the human, plus any bug the pass found and its fix - changing nothing else. Then post the evidence as a PR comment: each item with its quoted output or hosted-image screenshot evidence (never committed files) - screenshots render inline as grouped preview galleries, one <details open> block per journey/surface in chronological step order, each capture labeled with what the reviewer should notice (<img width="420"> when using HTML); a bare list of screenshot URLs is a failed handoff. The comment ends with an explicit split: passed automated vs remaining for the human, so the returning human's manual pass starts from the unchecked boxes and the remainder list. The QA drive's after-shots also complete the body's Visual overview (replacing its After-shots: landing with the QA drive note). **A bug

…(truncated)