feat(board): attach an externally opened PR to the card it belongs to (#402)

[mabry1985]

What was missing

The loop adopts a PR it didn't open in exactly one place: crash recovery (_reconcile_orphan) finds the PR whose head is the card's canonical branch and moves the card to in_review. A PR opened by a human had no edge.

The incident, on protoEngineer, 2026-09-07:

• bd-ezs7's coder left a finished implementation uncommitted in its candidate worktree (A coder can complete with real edits and publish nothing — no commit, no branch, no PR, no failure recorded #400).
• The operator promoted the work onto the card's own branch, feat/bd-ezs7-fix-a2a-make-poll-timeout-s-a-no-progres, and opened protoAgent#3369.
• The card stayed terminal-blocked while #3369 went through CI and review, invisible to the board. Re-dispatching the card would have force-removed the worktree the work still lived in.
• After the merge, the PM hand-closed the card with board_mark_done.

What this adds

board_attach_pr(feature_id, pr_url, reason) / POST /features/{fid}/attach-pr {pr_url, reason?, by?}. It is deliberately no wider than recovery's adoption.

Refused unless	Why
The PR is OPEN and in the card's project repo	A merged PR has nothing left to review, so the refusal points at board_mark_done.
Its head is the card's canonical branch feat/<id>-<slug>	Every later edge keys on it: fix rounds resume origin/<branch>, and so do recovery and the reap. The refusal gives the exact branch to push to.
It isn't from a fork, and it targets the project's base	Fix rounds push to this repo, and the rebase and merge edges work against that base.
The card is a coding feature that passed the Ready gate	Judged on its lane underneath any block (ready or in_progress), so a blocked backlog card has not passed. Tasks, epics and milestones are refused.
The card has no other PR, unless that PR is CLOSED	A closed PR can be replaced. An open one would be orphaned, a merged one means the card is done, and a PR under live review is never swapped.
The card already tracks this PR → no-op in review, refused anywhere else	Re-attaching a blocked card's own PR would lift a block that may be the review gate asking for a human. Unblocking stays a deliberate board_unblock_feature.
There is no open dependency, and the loop isn't working the card	Refused, not overridden, if there is a live drive, a claimed build or a running review gate.

Every refusal changes nothing (the tests assert this for each shape) and names what to do instead.

The write. It is one br update (store.attach_pr), run under the loop's claim lock.

• It leaves the card where open_review does: in_review with the PR on external_ref.
• It drops ready, the block and its class, and every verdict pinned to an earlier head: the review verdict and its sha pin, the reviewed-head stamp, and merged-verified.
• It arms review-pending when the review gate is on.
• The health sweep's moves take the same lock and re-read the card first, so a sweep can't requeue an attach it raced. If the sweep adopts the same PR first, the attach still arms the gate and records itself (already_attached: true).
• The attached PR: audit comment is written last. If that write fails, the attach still stands and the result carries a warning.

The attached code has not been through the board's pre-PR checks (fixups, the local gate, acceptance tests). CI, the review gate, rebase and merged-state verification still apply. A draft attaches, and auto-merge holds it until it is marked ready.

Seams, CI and guards

• worktree.pr_identity: a new gh seam, classified REAL. Its tests are in tests/test_attach_pr_gh_402.py, which needs no br. The test (real gh) CI job now runs that file against the pinned fixture ⚠️ CI FIXTURE — DO NOT MERGE, DO NOT CLOSE #370 (vars.PB_GH_FIXTURE_PR). The head check comes before the fork check, so the refusal test doesn't depend on where the fixture comes from.
• store.attach_pr is REAL: every shape goes through real br.
• Every gh read the attach makes converts WorktreeError/OSError into an actionable BoardError, so the tool and the route never raise.
• test_every_tool_returns_boarderror_as_result_never_raises now covers async tools. It used to skip them, which is how feat(loop): merge-poll Done-edge fallback + parallel drives (max_concurrent>1) #6 slipped through.
• The tools-doc guard only matched def board_*, so board_dispatch had shipped undocumented. It now covers async defs, and both tools are documented.
• Pre-existing bug fixed: the loop read review_gate with bool(), so "false" read as on. It now uses knob_bool, like every other surface.

Tests

• tests/test_attach_pr_402.py (real br, gh faked at the seam):
  • the incident end to end: a terminal-blocked card takes the operator's PR, and the real _reconcile_prs closes it as done when the PR merges;
  • ready and orphaned in-progress cards;
  • 12 refusal shapes;
  • replacing an earlier PR, which is only allowed once it's closed;
  • a live drive refuses; the same PR again is a no-op;
  • the attach waits for the claim lock;
  • the route (200/400) and the tool.
• tests/test_attach_pr_review_402.py (real br), one test per review finding: a blocked backlog card and a blocked epic are refused; a blocked card's own PR is refused naming the block; a fix round is refused; a replacement drops merged-verified and the merged state is gated; the sweep's orphan pass and blocked self-heal don't undo an attach (both race tests); D2 (sweep adopts first → already_attached, review-pending armed, audit written); a gh timeout or missing checkout returns Error:; a failed audit comment doesn't report an error; review_gate: "false" reads as off.
• tests/test_attach_pr_gh_402.py: the real-GitHub tier. I ran it locally against ⚠️ CI FIXTURE — DO NOT MERGE, DO NOT CLOSE #370: it passes.

Red-check:

• With origin/main's sources, the attach module doesn't exist, and the widened docs guard names board_dispatch.
• The 12 review tests fail on this PR's previous head 8c45cd7, each on its own assertion: the backlog card and the epic attach; the blocked card is unblocked; the stamp survives; the sweep undoes the attach; the D2 attach isn't armed; the gh failures raise; the audit failure errors; the loop reads "false" as on.
• All pass with the fix.

The _TaskStore/_BlockedStore fakes in tests/test_loop.py now model the re-read the sweep does. Their get_feature reflects a claim, and _BlockedStore gained one.

Rebased onto main (#430, #432, #435, #428 and #429 merged).

• The conflicts were adjacency only: api.py imports, and store.py around fix(board): delivered tasks read as delivered, repeats are no-ops, open requirements reach the verifier (#399, #403) #432's @_task_edge on record_delivery.
• The seam-ratchet counts were recomputed from the code, not taken from either side's constant: worktree 24 REAL / 3 EXEMPT / 0 UNCOVERED (main's 23 plus pr_identity), and store 18 uncovered against a ceiling of 18 (attach_pr is REAL).
• The async docs-guard widening and the board_dispatch ⚠️ row each appear once.
• New on top of the rebase: store.attach_pr takes fix(board): delivered tasks read as delivered, repeats are no-ops, open requirements reach the verifier (#399, #403) #432's per-card lock, because it is the same kind of read-validate-write sequence as the task edges, and a concurrent requeue of that card can't land in between.

Gates: ruff format --check ., ruff check . and pytest -q all pass after the rebase: 2041 passed, 16 skipped. The real-GitHub tier also passes against #370 (13 passed; the 2 write seams skip read-only).

Fixes #402

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2V6GRejF7mNukAoYjj2Av

[protoreview]

⚠️ QA panel exhausted — this PR has not been reviewed.
The review panel failed after 2 attempt(s) on head 27df8d9509c9. No verdict was posted.
A new push will re-trigger the review.

[protoreview]

⚠️ QA panel exhausted — this PR has not been reviewed.
The review panel failed after 2 attempt(s) on head 9102457d00c0. No verdict was posted.
A new push will re-trigger the review.