# Do

> Run the full autonomous pipeline against a work item - plan, implement, verify, PR, post-PR review + QA, wrap-up. Takes a work-item reference (issue

- Skill: `dcouple/do-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add dcouple/do-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dcouple/do-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: dcouple (https://skillmd.com/u/dcouple)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dcouple/do-2

---


# /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
`codex` skill; each
review runs the Codex and Claude reviewers in parallel and weighs both
reports at zone 0; zones 1–3 run the Codex lane alone. **All
implementation runs on the Codex `implementer`** at effort `medium`,
every surface - backend/ops and frontend web/mobile alike. The Claude
`frontend-verifier` is the app-driving QA agent: it runs **once per run,
post-PR** (Step 5), never at the verify stage. web-researcher is a Claude
sub-agent.

## 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 dispatch - detached Codex `codex
  exec` and Claude-lane Agent-tool sub-agents alike - 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
  (per the codex skill) so a lost harness 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 orchestrator session runs under `claude --dangerously-skip-permissions`
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 any browser
  preflight. E2E-browser criteria or a manual UI journey make the run browser
  required. On the initial daemon turn, if required and
  `ORCHESTRA_BROWSER_REQUEST_FILE` is present, atomically replace that file
  with JSON `{ "requested": true }` and return exactly
  `ORCHESTRA_BROWSER_RELAUNCH_REQUIRED` with no other terminal text. Never
  write the marker for a non-browser item. If browser proof is required but
  neither the request file nor `ORCHESTRA_BROWSER_EVIDENCE_DIR` is present,
  stop with an explicit browser-prerequisite failure.
- After relaunch, prove the attached MCP and Chrome by invoking
  `mcp__playwright__browser_snapshot`, then close the probe with
  `mcp__playwright__browser_close`. Classify MCP startup/connection, Chrome
  launch, and target-application reachability as separate prerequisite
  failures. None may fall back to scripts/logs as browser 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 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.
  If either check fails, stop with `simulator prerequisite failed:` naming
  the missing `orchestra-sim` or XcodeBuildMCP half, never “unverified.” When
  optional, note which halves 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 `.claude/skills/hillclimb/SKILL.md`, 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, cap 3); zones 2–3 run
light (no dossier, 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
full machinery and cap 3 while their lanes follow the same zone rule.

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` skill, role `code-researcher`, 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 `web-researcher` sub-agent 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 - this run's effective review lanes per the dials above (zone 0:
Codex + Claude in parallel; zones 1–3: Codex alone; `review_lanes:` override
honored in either direction, including on a multi-phase item) - findings
fixed into the plan - until you're satisfied. A dual-lane pass dispatches
both lanes in a single message - the Claude reviewer via the Agent tool,
the Codex reviewer as a detached dispatch per the codex skill - then awaits
the Agent-tool sub-agent within the turn and picks up the Codex report from its
marker; running one lane to completion before
starting the other serializes the pass and doubles its wall-clock.
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` skill, role `implementer`
(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 a **Claude**
verifier dispatch, never Codex. Any ad-hoc Claude verifier dispatched outside
the named agents (e.g. `general-purpose` for a live-app script check) passes
an explicit `model` (default `opus`) - never inherit the session model
silently - and its prompt carries the leaf-agent line (you are a sub-agent;
never spawn agents or invoke agent CLIs - `claude`, `codex exec`, or any
equivalent): the named agents get it from their charters, but an uncharted
type only knows what your dispatch tells it. 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 retry or improvise a
workaround - stop the verify loop and ask the user for the missing
instructions or access. 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 `AC#` and every rubric blocker has quoted passing
evidence.

## 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;
  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.

- Run the review lanes over the PR diff (zone 0: both reviewers,
  dispatched together in one message - Agent tool + detached `codex exec`
  - never serially; zones 1–3: Codex alone; the item's explicit
  `review_lanes:` outranks the zone default in either direction, including
  when set on a multi-phase item)
  (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 caps are ceilings, never
  quotas** (cap 3 passes; zones 2–3: 1; multi-phase items always 3 passes,
  with lanes derived from zone unless the item's own `review_lanes:` says
  otherwise).
  **The three-pass cap is absolute even when a prompt says “repeat until
  clean”; at the cap, carry survivors to wrap-up rather than starting a
  fourth pass.**
  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; (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.
- 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 `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` skill role `backend-verifier` 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.
  When `ios_testing: required`, the verifier must acquire a device with
  `orchestra-sim acquire`, drive every mobile AC, finalize the simulator
  `evidence-manifest.json`, and release the lease before reporting. When it
  is optional and a mobile surface changed, tell the verifier to acquire a
  device 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. Then
  **every enumerated capture gets hosted and embedded** - after-shots into
  the body's Visual overview, per-item evidence into the QA proof comment;
  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 the QA drive surfaces is never report-and-ship:** when the
  original review budget has a pass left, loop its fix to the implementer,
  then run one **scoped review pass over the fix's diff alone** - the zone's
  review lanes, using that remaining pass - before the QA results line
  closes. When no pass remains, stop with the bug as a blocker; do not change
  code or accept QA. The QA drive runs after
  the review loop exits, so without this pass a behavioral fix born from
  app-driving evidence (exactly the client-state bug a diff-reading
  reviewer can't see) would ship un-reviewed. Body carries state, comment
  carries proof - never
  leave the results only in a comment when the body has a checklist and a QA
  results line to update. After every body update, **YOU MUST** preserve and
  verify the persisted closing-line set per `.references/tracker-lifecycle.md`.
  Any code fix after QA begins invalidates that QA evidence: return to the
  review phase using only the original cap's remaining passes, then rerun QA
  from the start so the final accepted phase is QA.
- **Hosting evidence media**: when the consumer config sets
  `artifact_host:`, evidence media MAY be hosted as an artifact bundle per
  `.references/artifact-host-upload.md`; its stable viewer URLs are
  unauthenticated. For GitHub repos, the default remains screenshots, GIFs,
  and videos as assets on a rolling `qa-assets` **prerelease**
  (once per repo: `gh release create qa-assets --prerelease
  --title "QA evidence assets" --notes "Rolling QA evidence host - not a
  software release."` - the explicit `--title`/`--notes` matter: without
  them `gh release create` prompts interactively and a headless run hangs;
  then `gh release upload qa-assets <pr#>-<name> --clobber`) and reference the
  `releases/download/...` URLs - CLI-native, permanent, permission-scoped,
  any file type. This rule is step-agnostic: Step 4 hosts the
  Visual-overview captures here *before* the PR exists, so prefix filenames
  with the **work item id** (stable from Step 0; add the PR number once one
  exists if it helps browsing) so the rolling release
  stays browsable. Images/GIFs render inline in comments; videos land as
  links (GitHub only inline-plays web-UI uploads). Expiring temp hosts are
  forbidden for evidence - a dead link months later is no evidence at all.
  On a private repo, note that 

…(truncated)