docs: rule that a wait is a notification, never a tight poll loop (#2253)

Agents routinely spend turns tight-polling for a condition that was already
going to notify them — ~80 consecutive no-op turns waiting out one local:gate
run on #2250, with a completion notifier for that very process already armed.
The convention existed only in a per-user memory note, which is invisible to
anyone else and cannot be relied on mid-session.

- AGENTS.md gains a "Waiting on long-running work" section: arm a notifier and
  stop; one notification is a backgrounded command or a single `until` loop, many
  is a Monitor. It states the one genuine exception — state the harness cannot
  observe — and says where the poll belongs in that case, inside one backgrounded
  loop rather than spread across turns.
- pre-push-gate points at it where the gate is actually run.
- pr-flow §7 points at it where the Copilot review is actually waited on, with
  the loop written out. The count-not-existence trap is called out: on round two
  the first round's review is still there, so `-ge 1` returns immediately.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017nLLLTGc37hQiC8s3mNyhq
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-09-06 12:13:47 -04:00 • committed by GitHub
commit 27bf55e0e5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -240,7 +240,23 @@ gh api graphql -f query='
```
Poll for the review with a `startswith` match — the review login carries a
`[bot]` suffix.
`[bot]` suffix. **Put that poll in one backgrounded loop that exits when the
round lands, and wait for its notification** rather than re-fetching once per
turn; a review is remote state the harness cannot observe, which is exactly the
exception described in [Waiting on long-running
work](../../../AGENTS.md#waiting-on-long-running-work) — and exactly where the
poll belongs when one is needed.
```sh
until [ "$(gh api --paginate repos/modelcontextprotocol/inspector/pulls/<N>/reviews \
--jq '[.[]|select(.user.login|startswith("copilot-pull-request-reviewer"))]|length' \
| awk '{s+=$1} END{print s+0}')" -ge "$EXPECTED" ]; do sleep 20; done
```
`EXPECTED` is the review **count** you are waiting to reach, not `1` — on round
two the first round's review is still there, so an existence check returns
immediately. Give the inline comments a further ~60s after the body lands; they
arrive late (see step 8).
## 8. Respond to the review