From 447508d66b50b4d8c68e239cf9deb44a8a888a76 Mon Sep 17 00:00:00 2001 From: xiefuzheng713-alt <266900198+xiefuzheng713-alt@users.noreply.github.com> Date: Thu, 4 Jun 2026 22:32:04 +0800 Subject: [PATCH 1/2] Document live pending bounty preflight --- docs/agent-guide.md | 20 ++++++++++++++++++++ docs/api-examples.md | 13 +++++++++++++ tests/test_docs_public_urls.py | 7 +++++++ 3 files changed, 40 insertions(+) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 39e6ffe6..0441f066 100644 --- a/docs/agent-guide.md +++ b/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=" +``` + +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 +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 diff --git a/docs/api-examples.md b/docs/api-examples.md index f19fdc54..01dc061b 100644 --- a/docs/api-examples.md +++ b/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=" +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 +`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. diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py index 332822d3..e2391f2b 100644 --- a/tests/test_docs_public_urls.py +++ b/tests/test_docs_public_urls.py @@ -220,6 +220,10 @@ 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=" in guide + assert "/api/v1/treasury/proposals?action=create_bounty&status=pending" in guide + assert "Reserved on MergeWork" in guide def test_admin_runbook_warns_to_validate_production_admin_token() -> None: @@ -273,6 +277,9 @@ 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 "Reserved on MergeWork" in examples assert "capacity totals" in examples assert "full bounty" in examples assert "same optional `status`, `q`, `repo`," in examples From 4b735e701a76ab00aa873f02e3089e521a765b59 Mon Sep 17 00:00:00 2001 From: xiefuzheng713-alt <266900198+xiefuzheng713-alt@users.noreply.github.com> Date: Fri, 5 Jun 2026 01:38:48 +0800 Subject: [PATCH 2/2] Include bounty label in live preflight docs --- docs/agent-guide.md | 2 +- docs/api-examples.md | 2 +- tests/test_docs_public_urls.py | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 0441f066..7503f392 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -127,7 +127,7 @@ 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 -claims-open `Reserved on MergeWork` comment. A pending `create_bounty` proposal +`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. diff --git a/docs/api-examples.md b/docs/api-examples.md index 01dc061b..5274af89 100644 --- a/docs/api-examples.md +++ b/docs/api-examples.md @@ -125,7 +125,7 @@ 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 -`Reserved on MergeWork` claims-open comment. +`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. diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py index e2391f2b..47089f63 100644 --- a/tests/test_docs_public_urls.py +++ b/tests/test_docs_public_urls.py @@ -223,6 +223,7 @@ def test_agent_guide_tells_agents_not_to_claim_proposed_work() -> None: assert "live-vs-pending preflight" in guide assert "/api/v1/bounties?repo=ramimbo%2Fmergework&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 @@ -279,6 +280,7 @@ def test_api_examples_document_bounty_list_response_shape() -> None: 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