DRAFT docs(recipe): Needs review is not shipped without a tip-native proof
Draft. Do not merge; do not undraft.
What
Adds one docs page: docs/proof-gate-needs-review-receipt.md. It states an operator rule — a workspace in the Needs review board column is not shipped until there is a tip-native proof artifact.
Tip-native proof = the pipeline produced it and it is pinned to the exact commit SHA at the branch tip: check runs that CI actually ran at that SHA (gh checks <sha>, all green), or a receipt that names the SHA.
The rule adds no board column. It cites only the columns the app already has (Needs review, Needs attention, Merged, Deleted) and leaves agentStatus untouched — that stays the single source of truth in its own work (#7007).
Why — first-person stakes
I am the operator who merges. If I read "Needs review" as "ready", I ship whatever the agent left: possibly failing CI, possibly a commit I never verified. A bot saying "looks good" is an opinion. A check run pinned to a concrete SHA is proof, because I can read it back and pin it to the same commit I will merge.
Not in scope
No product code, no new columns, no agentStatus changes, no hook changes.
Summary by cubic
Fixes premature completion announcements by deferring a parent's Stop until all its subagents finish. Adds a docs page stating that a workspace in "Needs review" requires a tip-native proof before shipping.
Behavior changes
- Parent Stop is held while subagents run and released exactly once when the last child clears.
- Child events that straggle after a stop no longer revive the child, except for Codex, which genuinely resumes via
send_input. - Permission requests still broadcast while children run; a new parent event supersedes the held Stop.
- Held Stops are dropped if the terminal dies or the status escape hatch fires.