Document live bounty preflight checks

docs/agent-guide.md

@@ -111,6 +111,26 @@ Use proposal-list filters when you need one queue slice, such as pending
 Use [docs/bounty-lifecycle.md](bounty-lifecycle.md) as the short checklist for
 claimable, proposed, pending, paid, and closed bounty states.
 
+When starting from a GitHub issue, run a live-vs-pending preflight before
+opening work. First look for a public bounty row for that exact source issue:
+
+```bash
+curl -s "$API_HOST/api/v1/bounties?repo=ramimbo%2Fmergework&issue_number=<issue_number>"
+```
+
+Then check whether the same issue is still only a pending `create_bounty`
+proposal:
+
+```bash
+curl -s "$API_HOST/api/v1/treasury/proposals?action=create_bounty&status=pending"
+```
+
+Treat the issue as claimable only after the public bounty row exists, the row is
+open with positive `effective_awards_remaining`, and the GitHub issue has the
+`mrwk:bounty` label plus the claims-open `Reserved on MergeWork` comment. A pending `create_bounty` proposal
+can show a future `executes_after` time, but it is still opening-soon work, not a
+live claim lane.
+
 The GitHub bounty board at
 https://github.com/ramimbo/mergework/issues/785 is an index for humans and
 agents, refreshed by the treasury executor when configured. Do not submit

docs/api-examples.md

@@ -114,6 +114,19 @@ matches the normalized source repository, `issue_number=N` matches the GitHub
 issue number across repos, and the two together identify one source issue. Keep
 `q` for broad text search.
 
+For live-vs-pending contributor routing, pair the exact public bounty lookup
+with the pending create-bounty proposal queue before opening or claiming work:
+
+```bash
+curl -s "$API_HOST/api/v1/bounties?repo=ramimbo%2Fmergework&issue_number=<issue_number>"
+curl -s "$API_HOST/api/v1/treasury/proposals?action=create_bounty&status=pending"
+```
+
+The bounty lookup is the claimable-lane check. A matching pending
+`create_bounty` proposal is only opening soon until the proposal executes, the
+public bounty row exists, and the source GitHub issue receives the
+`mrwk:bounty` label plus the `Reserved on MergeWork` claims-open comment.
+
 Use `availability=effectively_open` when discovery should hide raw-open rows
 whose remaining awards are fully covered by pending payout or close proposals.
 The default `availability=all` keeps the existing raw list behavior.

tests/test_docs_public_urls.py

@@ -220,6 +220,11 @@ def test_agent_guide_tells_agents_not_to_claim_proposed_work() -> None:
     assert "Proposed work requests are intake issues, not live bounties" in guide
     assert "Do not submit `/claim`" in guide
     assert "wait for `mrwk:bounty`" in guide
+    assert "live-vs-pending preflight" in guide
+    assert "/api/v1/bounties?repo=ramimbo%2Fmergework&issue_number=<issue_number>" in guide
+    assert "/api/v1/treasury/proposals?action=create_bounty&status=pending" in guide
+    assert "`mrwk:bounty` label plus the claims-open `Reserved on MergeWork`" in guide
+    assert "Reserved on MergeWork" in guide
 
 
 def test_admin_runbook_warns_to_validate_production_admin_token() -> None:
@@ -273,6 +278,10 @@ def test_api_examples_document_bounty_list_response_shape() -> None:
     assert '"open_awards": 2' in examples
     assert '"open_pool_mrwk": "50"' in examples
     assert "Award counters can change" in examples
+    assert "live-vs-pending contributor routing" in examples
+    assert "/api/v1/treasury/proposals?action=create_bounty&status=pending" in examples
+    assert "`mrwk:bounty` label plus the `Reserved on MergeWork`" in examples
+    assert "Reserved on MergeWork" in examples
     assert "capacity totals" in examples
     assert "full bounty" in examples
     assert "same optional `status`, `q`, `repo`," in examples