Document live bounty preflight checks

[xiefuzheng713-alt]

Summary

• Documents a live-vs-pending preflight for contributors and agents starting from a GitHub bounty issue.
• Shows the exact existing public bounty lookup and pending create_bounty proposal queue checks before opening or claiming work.
• Clarifies that a pending proposal with executes_after is opening-soon work, not a live claim lane, until the public bounty row and Reserved on MergeWork comment exist.
• Adds docs smoke assertions so the preflight guidance stays visible in the agent guide and API examples.

Bounty #845

Evidence

This is intentionally distinct from useful open contributor-flow PRs:

• It does not add or duplicate the Expose public work discovery queue #840 work-discovery endpoint; it documents a narrow preflight using existing /api/v1/bounties and /api/v1/treasury/proposals APIs.
• It does not overlap Show active attempt pressure on bounty cards #874's bounty-card active-attempt UI work.
• It does not touch bounty creation, proposal execution, payout, ledger, wallet, admin, exchange, bridge, off-ramp, or cash-out behavior.

Validation

• uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 35 passed
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev ruff check docs/agent-guide.md docs/api-examples.md tests/test_docs_public_urls.py -> passed
• uv run --extra dev ruff format --check tests/test_docs_public_urls.py -> 1 file already formatted
• git diff --check origin/main...HEAD -> clean
• git merge-tree --write-tree origin/main HEAD -> clean tree 74c5f4ba4b5d171d164f3cfaa94eccf148075d97

Scope

Docs and docs-smoke assertions only. No runtime behavior, tokens, secrets, private data, payout execution, or price/cash-out claims are changed.

Summary by CodeRabbit

• Documentation

  • Added guidance for agents to verify bounty availability before claiming work from GitHub issues.
  • Added a preflight checklist to distinguish live vs. pending bounties and when a bounty is “opening soon.”
  • Clarified when bounties become claimable and the role of the "Reserved on MergeWork" marker and the mrwk:bounty label.

• Tests

  • Added test coverage validating the new documentation and routing guidance for contributors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ec93331a-c5e8-4197-9349-5393629a81b2

📥 Commits

Reviewing files that changed from the base of the PR and between 447508d and 4b735e7.

📒 Files selected for processing (3)

• docs/agent-guide.md
• docs/api-examples.md
• tests/test_docs_public_urls.py

---

📝 Walkthrough

Walkthrough

Adds documentation and tests that require agents and contributors to verify a live public bounty row (by repo+issue_number) and check pending create_bounty treasury proposals, and to confirm the GitHub issue has the mrwk:bounty label plus a “Reserved on MergeWork” comment before treating the issue as claimable.

Changes

Live-vs-Pending Bounty Discovery

Layer / File(s)	Summary
Agent and contributor routing guidance docs/agent-guide.md, docs/api-examples.md	Adds "When starting from a GitHub issue" preflight in agent guide and a "live-vs-pending contributor routing" block in API examples; includes example curl requests for exact public bounty lookups and pending create_bounty proposal queries and defines claimability conditions (open public bounty row with positive effective_awards_remaining, mrwk:bounty label, and "Reserved on MergeWork" comment).
Documentation verification tests tests/test_docs_public_urls.py	Extends tests to assert both docs include the live-vs-pending preflight/routing text, the /api/v1/bounties?... and /api/v1/treasury/proposals?action=create_bounty&status=pending endpoint references, and the "Reserved on MergeWork" wording.

Possibly related issues

• ramimbo/mergework#709: Both add bounty-lifecycle and treasury-proposal discovery guidance to distinguish live bounties from pending create_bounty proposals.
• Proposed work: use effective availability in submission quality gate #681: Clarifies effective_awards_remaining and live-vs-pending gating semantics relevant to claimability checks.

Possibly related PRs

• ramimbo/mergework#648: Updates agent-facing bounty claimability docs and tightens tests around the same live-vs-pending guidance.
• Clarify README bounty claim states #674: Similar clarification of live vs pending bounty claim gating requiring open public bounty row plus "Reserved on MergeWork".
• docs: show effective bounty availability in API examples #685: Adds API examples and tests for live-vs-pending preflight routing using bounty availability and pending proposal state.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Document live bounty preflight checks' clearly and concretely names the main change: adding documentation about live bounty preflight checks.
Description check	✅ Passed	The description covers all required sections: summary of changes, evidence with context and validation steps, scope clarification, and a related bounty reference (Bounty #845).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	Documentation adds API preflight guidance with no investment, price, cash-out, payout, or security claims. Explicitly disclaims pending proposals as "opening-soon work, not live claim lanes."
Bounty Pr Focus	✅ Passed	Diff matches stated files (+20/+13/+9 lines), includes test assertions for preflight URLs and labels, zero app/migrations changes, avoids scope drift on bounty creation/execution/payouts.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[MolhamHamwi]

Current-head review for #838 on 447508d66b50b4d8c68e239cf9deb44a8a888a76.

Evidence checked:

• Inspected the doc-only changes in docs/agent-guide.md and docs/api-examples.md; the new live-vs-pending preflight points agents at the exact bounty row lookup plus the pending create_bounty proposal queue, and keeps the claimable boundary tied to an open public row, positive effective_awards_remaining, and the Reserved on MergeWork comment.
• Inspected tests/test_docs_public_urls.py; the assertions cover the new preflight language and both API paths so later edits cannot silently remove the contributor-routing warning.
• Verified GitHub reports head 447508d66b50b4d8c68e239cf9deb44a8a888a76, merge state UNSTABLE, with the project quality check successful and only CodeRabbit informational.
• Ran ./.venv/bin/python -m pytest tests/test_docs_public_urls.py -q locally: 35 passed.
• Ran ./.venv/bin/python -m ruff check docs/agent-guide.md docs/api-examples.md tests/test_docs_public_urls.py: passed.

No blocker found. The added guidance is narrowly scoped, public-safe, and helps prevent agents from claiming pending-only bounty proposals as live work.

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cbd65e27-4d0d-4e58-b8b7-7787cefa23e7

📥 Commits

Reviewing files that changed from the base of the PR and between d4d0e48 and 447508d.

📒 Files selected for processing (3)

• docs/agent-guide.md
• docs/api-examples.md
• tests/test_docs_public_urls.py

[mauricemohr88-debug]

Current-head review for #838 on 4b735e701a76ab00aa873f02e3089e521a765b59.

Evidence checked:

• Inspected the doc-only updates in docs/agent-guide.md and docs/api-examples.md; the new live-vs-pending preflight points agents at the exact public bounty row lookup and pending create_bounty proposal queue.
• Verified the claimable boundary stays tied to an open public bounty row, positive effective_awards_remaining, the mrwk:bounty label, and the Reserved on MergeWork claims-open comment.
• Inspected tests/test_docs_public_urls.py; the assertions cover the new guidance and both public API paths so the preflight warning cannot silently disappear.
• Confirmed the current GitHub head is 4b735e701a76ab00aa873f02e3089e521a765b59, the PR is open, merge state is clean, and both visible checks are successful.
• Ran uv run --python 3.12 --extra dev python -m pytest tests/test_docs_public_urls.py -q: 35 passed.
• Ran uv run --python 3.12 --extra dev ruff check docs/agent-guide.md docs/api-examples.md tests/test_docs_public_urls.py: passed.
• Ran uv run --python 3.12 --extra dev ruff format --check tests/test_docs_public_urls.py: 1 file already formatted.
• Ran uv run --python 3.12 --extra dev python scripts/docs_smoke.py: docs smoke ok.
• Ran git diff --check origin/main...HEAD and git merge-tree --write-tree origin/main HEAD: clean.

No blocker found. The current-head update is narrow, public-safe, and reduces the chance that contributors or agents claim pending-only bounty proposals as live work.