docs/epics.md

@@ -124,6 +124,25 @@ mcpctl tasks verdict cart-cookie-ttl \
 Reaching `done` without the required passing verdicts is refused, and the error
 names which stage is missing.
 
+### Linking the pull request
+
+Accept only merges something if the task knows what its pull request is. An
+agent writes these when it pushes; from the CLI they go through `patch`:
+
+```sh
+mcpctl patch task cart-cookie-ttl \
+  branch=feat/cart-cookie-ttl \
+  headCommit=4f2a91c \
+  prNumber=214 \
+  prUrl=https://mysources.co.uk/michal/mcpctl/pulls/214
+```
+
+`headCommit` is what the review is pinned to. Accept refuses if the PR's head
+has moved past it — see below.
+
+A task with no `prNumber` can still be accepted; it records the approval and
+merges nothing, and says so rather than implying code landed.
+
 ### The human gate
 
 `done` means it left the developer's loop, not that it shipped. `awaiting_review`