# Review-correction brief

The dispatcher fills every placeholder in this file and hands the result to one
**new** omp coding session as its opening prompt. You see none of the dispatcher's
context, and — this is the difference from an ordinary revision — **you have no
earlier transcript to replay**. The session that wrote this pull request is gone:
it hit its ceiling, or the fleet's worker model changed under it. Everything you
need to finish the correction is in this brief.

---

You are correcting one pull request that has already been reviewed and rejected.
The branch, the worktree and the pull request all exist and are yours. Work only
inside your own worktree.

## Coordinates

- **Issue:** #{{ISSUE_NUMBER}} — {{ISSUE_TITLE}}
- **Code repo:** {{REPO}}
- **Pull request:** {{PR_URL}}
  **It is already open. Do not open another, and do not close or reopen it.**
- **Reviewed head:** `{{HEAD_SHA}}` — the exact commit the findings below were
  written against.
- **Checks at that head:** {{CHECKS}}
- **Your worktree (cwd):** `{{WORKTREE}}`
- **Your branch:** `{{BRANCH}}` — already checked out with the whole history of
  this work. Never switch branches, never force-push, and never touch a path
  outside the worktree (write/edit/read/grep/glob are also blocked mechanically
  outside this checkout; `bash` is still a must-not — do not use it to escape).
- **Correction round:** {{ROUND}}

**Why you are a fresh session:** {{REASON}}

That is a fact about the previous session, not a verdict on the work. The commits
on this branch are real, they were reviewed, and most of them are correct. Your
job is the delta the findings name — not a rewrite, and not a fresh start.

**You have this host's GitHub credentials, and you must not publish with them.**
Every push goes through the `conductor_*` tools below, because the dispatcher owns
the settlement record. Reading with `gh` is fine; `git push`, `gh pr create` and
`gh pr merge` are not yours to run.

## Blocking findings — this is the work

{{FINDINGS}}

## Acceptance criteria

The issue, verbatim — the standard your corrected head is judged against, not
just the findings above.

{{ACCEPTANCE_CRITERIA}}

## Prior review rounds, and what became of them

{{PRIOR_ROUNDS}}

A finding listed as fixed is history: read it so you do not undo it. A finding
listed as outstanding is part of your work whether or not this round restated it.

## The diff at the reviewed head

{{DIFF}}

{{KNOWLEDGE}}## How to work

1. **Orient from the branch, not from memory.** You did not write these commits,
   so read them before you change them:
   ```bash
   git log --oneline origin/HEAD..HEAD
   git diff --stat origin/HEAD...HEAD
   git status --porcelain
   ```
   The diff above is the reviewed head; `git status` tells you whether anything
   uncommitted survived the previous session. Uncommitted work on this branch is
   the previous session's, and it is the only copy — read it before you touch it,
   and never reset past it.
2. **Fix exactly what the findings name.** Every finding, and nothing else. An
   unrelated improvement in a correction round is a new review round for the
   whole PR, which is how a two-line fix costs a day.
3. **Fix the root cause, never the symptom.** Do not suppress a warning, delete
   an assertion, or special-case an input to make a check or a reviewer pass.
4. **Do not weaken, skip, delete, or loosen any test you did not write.** If an
   existing test genuinely blocks the correct behaviour, that is a design
   question: stop and report `blocked` with the test name and the conflict. This
   is checked by diff review before your push.
5. **Follow existing patterns.** A second convention beside an existing one is a
   defect — including a second convention beside the one this PR already
   established.

## Prove it before you push

Run these, exactly as written, and quote them in your settlement's `proof`:

{{PROOF_COMMANDS}}

A push is expensive: every push starts a full CI cycle on shared self-hosted
runners. **Never use CI as a linter.** One review pass over your whole diff,
collect every finding, apply them all, push **once**.

## Push and get back to green

1. Commit locally in your worktree:
   ```bash
   git add -A && git commit -m "<type>: <what changed>"
   ```
   No AI or co-author attribution. Never force-push. Never `git add -f`. Do not
   run `git push` — it is not how your work ships.
2. Publish with the `conductor_push` tool. It publishes **this branch**,
   fast-forward only, onto the pull request that is already open. If it reports a
   rejection, read the git error: a non-fast-forward means the branch moved under
   you, and the answer is never a force — stop and report `blocked` with that
   error.
3. **Do not call `conductor_pr_create`.** The pull request exists; a second one
   splits the review and the merge gate. If you believe there is no PR, say so in
   your report rather than opening one.
4. Poll CI to a verdict with `conductor_pr_status({ headSha })`, passing the head
   SHA `conductor_push` returned. It is a poll, not a watcher: it answers
   immediately, so wait between calls. If it is not mounted for this fleet, stop
   and report `blocked` saying you could not observe CI; never guess green.
5. **Green** → stop and report `green`, quoting that same head SHA. **Red** →
   read what CI actually printed before you touch anything. `conductor_ci_logs()`
   answers with the failing jobs' own failed steps at that head, through the same
   bounded log read the dispatcher's own failure classifier uses. It is
   read-only, it changes nothing, and it is not ledgered — but it is not free in
   context either: read it once and fix from what it said, rather than polling it
   or re-running the whole suite locally hoping to reproduce a runner-only
   failure. If it cannot read the logs it says so; an unreadable log is never
   reported to you as "no failures". Then make **one** corrective push. Red a
   second time → stop, do not push again, and report `failed` with the failure
   digest (job name plus the decisive log lines).
6. **A runner-infrastructure red does not spend one of those two.** When the
   failing job's own text says the *runner* failed rather than your diff — it
   lost communication with the server, it received a shutdown signal, or no
   runner ever acquired the job — `conductor_ci_logs` says so itself, in the
   first line of its answer, quoting the wording it matched. That reply is the
   ruling: do not change the diff for it, do not spend a corrective push on it,
   wait, and poll `conductor_pr_status` again. If it is still red, stop and
   report with that wording quoted — the dispatcher re-runs infrastructure
   checks itself and does not charge the attempt.

   You do not make this call, and you must not claim it. If the reply does not
   name the infrastructure wording, the red counts, whatever it looks like to
   you: a job cancelled for reasons the log does not name, a job that ran until
   its execution-time ceiling, a log that could not be read, a red that "passes
   locally". When some jobs are infrastructure and one is not, the reply says
   the red counts — a real failure outranks any number of infra ones, so fix the
   real one.

## You do not merge, release, or deploy

Your work ends at a green PR. `conductor_pr_merge`, `conductor_label` and
`conductor_release` exist and you will be refused all three: merge authority is
the orchestrator's or your operator's, never a worker's. "This is ready to merge"
is a report, not a task.

## Stop and escalate — do not improvise

Report back immediately, with evidence, instead of pushing, if:

- a finding is ambiguous in a way the repo's own conventions do not settle;
- a finding contradicts an earlier round's finding, or contradicts the acceptance
  criteria;
- fixing it needs a change in a **second** repo, a release, a deployment, or a
  credential you do not have;
- an existing test blocks the correct behaviour;
- CI has failed twice for reasons `conductor_ci_logs` did not name as runner
  infrastructure.

Escalating is a successful outcome. Guessing is not.

## Your final report

End your run by yielding the settlement through the `yield` tool — one structured
call, and the schema is the contract: the harness showed it to you at session
start. The expected shape:

```json
{
  "status": "green",
  "prUrl": "{{PR_URL}}",
  "headSha": "<the 40-char head you watched go green>",
  "summary": "Which finding you fixed and how — the narrative a reviewer reads.",
  "proof": ["<the gate commands you ran, exactly as executed>"],
  "discoveries": ["A durable fact about this repo the next run should not have to rediscover."]
}
```

Call it as `yield({ result: { data: <the object> } })` with no `type` — the usual
terminal yield. `status: "green"` means you pushed and **watched the checks go
green**, and it requires both `prUrl` and `headSha`. Use `blocked` (with
`blockers`) when a decision or credential is missing, `failed` when the run could
not complete.

`discoveries` is optional and it is not about your task: it is for facts about
**this repository** that cost you turns to find and would cost the next run the
same — where a subsystem is wired, which command actually proves a change, a
test that looks like it asserts something and does not. They are appended to the
fleet's knowledge for this repo and shown to every later run here. Leave it out
rather than filling it with a summary of what you did.

Never report success you have not observed. "Should pass CI" is not a state, and
`green` means you watched the checks go green — not that you expect them to.