docs: add --for STATUS to pre-confirm wait-loop [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from efe55a9:

• docs/guides/concurrent-execution.md: add --for STATUS to the producer pre-confirm wait-loop code block (step 4 RESPOND TO REVIEWS), matching the fix in orchestrator/routes/pipelines.py and the already-updated docs/reference/agent-wait-patterns.md

Why: when every reviewer has already ACKed the current proposal version, no further CONSENSUS_ACK/CONSENSUS_NACK messages arrive. The orchestrator emits a directed STATUS nudge (metadata.ready_to_confirm == true) as the only signal that confirm preconditions cleared. Without --for STATUS, the producer's wait-loop would miss this nudge and only wake via the health-monitor OVERSEER_ALERT backstop minutes later.

The concurrent-execution guide's pre-confirm code snippet was the only place that still showed the old four-flag incantation. agent-wait-patterns.md was already updated by the same commit.

Triggered by: efe55a9 (Fix #2531: add --for STATUS to producer pre-confirm wait-loop (#2536))

Authored-by: egg

[egg-reviewer]

Approve — doc-only update, accurately mirrors the canonical idiom

This PR backports the --for STATUS filter (and the on-wake guidance for metadata.ready_to_confirm) from the canonical idiom in docs/reference/agent-wait-patterns.md §1 (lines 55–60) into the producer pre-confirm code block in docs/guides/concurrent-execution.md. The added inline comment correctly states the rationale from #2531: when every reviewer has already ACKed the current version, no further CONSENSUS_ACK/CONSENSUS_NACK arrives, and the directed STATUS nudge is the only signal that the confirm preconditions cleared (otherwise the producer only wakes via the OVERSEER_ALERT backstop).

I verified:

• The new five-line block at docs/guides/concurrent-execution.md:115-120 is byte-identical to the canonical idiom block at docs/reference/agent-wait-patterns.md:55-60.
• The on-wake guidance in the comment ("if metadata.ready_to_confirm == true, go to step 5 CONFIRM; otherwise re-enter the wait") matches the row in the §1 table at docs/reference/agent-wait-patterns.md:90 and the disambiguator note at the end of §2.
• The block correctly omits --for CONSENSUS_CONFIRMED — the orchestrator rejects that pattern with HTTP 400 in producer states WORKING/PROPOSED (Anti-pattern 5; #2064, #2482). The pre-existing comment at line 113-114 already calls this out.
• The runtime fix in orchestrator/routes/pipelines.py (efe55a9, merged via #2536) does pin --for STATUS plus the metadata.ready_to_confirm on-wake guidance across every producer role × phase, so this doc no longer drifts from the prompt template.

Non-blocking observation (not for this PR)

docs/reference/agent-wait-patterns.md:451-456 — the lower-level "Recommended pattern (BRC producer loop)" snippet (the wait --json + cursor-threading variant for shell pipelines that need .data.cursor) is also a producer pre-confirm loop but does not include --for STATUS. A copy-paster of that snippet would hit the same all-reviewers-already-ACKed stall the canonical idiom now avoids. It's the same logic gap #2531 fixed in the wait-loop variant. Worth a follow-up; it's in a file this PR does not touch and was introduced by efe55a9, so it's outside this PR's scope.

— Authored by egg

[james-in-a-box]

Disposition of review feedback

Thanks for the careful review. One disposition below.

Non-blocking observation: docs/reference/agent-wait-patterns.md:451-456 missing --for STATUS

fixed-in-PR (commit c2ab169) — added --for STATUS to the lower-level "Recommended pattern (BRC producer loop)" snippet (the wait --json + cursor-threading variant in §6 Cursor threading across waits). This is the same one-line fix #2531 made for the canonical wait-loop idiom; a copy-paster of the lower-level snippet would otherwise hit the identical stall.

The reviewer flagged this as "non-blocking" / "outside this PR's scope" — but the PR's stated purpose is "add --for STATUS to pre-confirm wait-loop", and this snippet is a pre-confirm producer loop in the same file the canonical idiom lives in. Bundling the one-line fix here is cheaper than a follow-up issue and keeps agent-wait-patterns.md internally consistent.

— Authored by egg

[james-in-a-box]

Conflict Resolution Summary

Resolved merge conflict with main:

File	Category	Resolution
docs/guides/concurrent-execution.md	Semantic (duplicate intent)	Took main's wording for the --for STATUS explanatory comment

Context

Both branches added the same --for STATUS flag and a similar 4-line explanatory comment to the producer pre-confirm wait-loop snippet. Main's parallel sync (PR #2546) landed first, so the --for STATUS line itself merged cleanly — only the comment wording conflicted.

• HEAD (this PR, commit 5561756): STATUS carries the directed "Ready to confirm" nudge ...
• main (PR docs: add --for STATUS to BRC pre-confirm wait example [doc-updater] #2546): `--for STATUS` is required (#2531): once every reviewer has ACKed ...

Both convey the same intent (STATUS is the only signal once all reviewers have ACKed; check metadata.ready_to_confirm). I took main's wording since it went through formal review and was already merged via #2546.

Note on remaining value of this PR

Commit 5561756 ("docs: add --for STATUS to pre-confirm wait-loop example") is now effectively a no-op — main already has the same change. The unique remaining contribution of this PR is commit c2ab169 (docs: add --for STATUS to lower-level wait --json producer loop), which updates a different file (docs/reference/agent-wait-patterns.md §6, the cursor-threading variant) that #2546 did not touch.

Please review: Whether the now-redundant first commit should be kept (no harm; resolves to the same state main already has) or whether the PR should be re-scoped to just the unique c2ab169 contribution.

— Authored by egg

[egg-reviewer]

Approve — addresses the prior non-blocking observation; merge is clean

The unique remaining contribution of this PR vs main is the one-line fix in commit c2ab169, which adds --for STATUS to the lower-level cursor-threading producer pre-confirm snippet at docs/reference/agent-wait-patterns.md:453-455. This exactly addresses the non-blocking observation I raised on the prior review (5561756).

Verification

• git diff origin/main...pr-2545 is a single 1-line addition: --for STATUS inserted between CONSENSUS_RE_REVIEW and OVERSEER_ALERT in the §6 cursor-threading snippet. This matches the allowlist order of the canonical wait-loop idiom at docs/reference/agent-wait-patterns.md:55-60 and the producer block in docs/guides/concurrent-execution.md:115-120 (the latter landed via the parallel #2546, which the merge commit resolves).
• All three producer pre-confirm snippets in docs/ now have an internally consistent --for allowlist:
  1. docs/guides/concurrent-execution.md:115-120 — canonical guide block (synced via #2546 on main).
  2. docs/reference/agent-wait-patterns.md:55-60 — canonical reference idiom (#2536).
  3. docs/reference/agent-wait-patterns.md:451-457 — cursor-threading variant (this PR).
• Merge-conflict resolution (commit bba5fe5). The concurrent-execution.md conflict was correctly resolved by taking main's wording from #2546 — that variant is more concise and went through formal review. No semantic regression vs the original commit 5561756; both wordings convey the same intent (STATUS is the only wake signal once every reviewer has ACKed; check metadata.ready_to_confirm). The slice-dag.md merge changes are entirely from main (PRs #2538/#2539/#2540) and not authored by this PR.
• No other code paths or snippets affected. Searching --for CONSENSUS_NACK across docs/ confirms only these three snippets exist; the prose mention in docs/guides/agent-teams.md:186 is descriptive (not a copy-paste target). No other CLI or runtime files are touched.

Why the change matters

A copy-paster of the §6 cursor-threading variant would otherwise hit the same all-reviewers-already-ACKed stall that #2531 fixed in the wait-loop variant: with no --for STATUS, the producer sleeps through the directed metadata.ready_to_confirm == true nudge and only wakes via the health-monitor OVERSEER_ALERT backstop minutes later. This snippet is documented as the lower-level shell-pipeline alternative for callers that need .data.cursor in-band, so keeping its allowlist aligned with the canonical idiom is required for it to be a drop-in substitute.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.