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.

[alan747271363-art]

Reviewed current head 4b735e701a76ab00aa873f02e3089e521a765b59 against current origin/main d7e9b530fffec7bd774da7708597648096a37393.

Scope inspected:

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

The visible PR diff is still docs/test-only and remains useful: it documents the live-vs-pending bounty preflight using the public bounty row and pending create_bounty proposal queue, keeps claimability tied to the public row, positive effective capacity, mrwk:bounty, and Reserved on MergeWork, and adds docs assertions so the guidance is not silently removed later. It does not change runtime behavior, proposal execution, payout execution, ledger, wallet, admin, private data, secrets, or off-ramp behavior.

Validation on this exact head:

• .\.venv\Scripts\python.exe -m pytest tests\test_docs_public_urls.py -q -> 35 passed.
• .\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• .\.venv\Scripts\python.exe -m ruff check docs\agent-guide.md docs\api-examples.md tests\test_docs_public_urls.py -> passed.
• .\.venv\Scripts\python.exe -m ruff format --check tests\test_docs_public_urls.py -> 1 file already formatted.
• git diff --check origin/main...HEAD -> clean.

Current blocker: GitHub now reports mergeStateStatus=DIRTY / conflicting. git merge-tree --write-tree origin/main HEAD exits non-zero with a current-main conflict in tests/test_activity.py. That file is not part of the visible PR diff, so this looks like a branch-base/rebase conflict rather than a documentation-content problem, but it still blocks merging and needs a rebase/resolve.

No private data, credentials, wallet material, production mutation, payout execution, treasury execution, ledger mutation, exchange, bridge, cash-out, price behavior, or fabricated payout claims were used.