Clarify bounty lifecycle for agents and maintainers

[ramimbo]

Summary

• add docs/bounty-lifecycle.md as the concise state/checklist for proposed, pending, live, pending-payout, paid, and closed bounty states
• link the lifecycle doc from README.md, AGENTS.md, the agent guide, bounty rules, and admin runbook
• extend docs smoke coverage and public docs tests so the critical claimability wording stays present

Maintainer Note

Maintainer documentation PR; not requesting a bounty.

This turns the treasury proposal flow described in Discussion #598 into current, agent-readable docs after the recent bounty lifecycle changes. The important rule is explicit: proposed work and pending create_bounty proposals are not claimable, and pending pay_bounty proposals are not paid until proof exists.

Validation

• ./.venv/bin/python scripts/docs_smoke.py
• ./.venv/bin/python -m pytest tests/test_docs_public_urls.py
• ./.venv/bin/python -m ruff format --check .
• ./.venv/bin/python -m ruff check .
• ./.venv/bin/python -m mypy app
• ./.venv/bin/python -m pytest

Summary by CodeRabbit

• Documentation

  • Added comprehensive bounty lifecycle guide clarifying when work becomes claimable and payment states.
  • Updated agent guide, admin runbook, and bounty rules with references to lifecycle documentation.
  • Updated project links in README.

• Tests

  • Added validation test for bounty lifecycle documentation content.

[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: 56ca6508-2a4c-4838-a195-a365fc49400d

📥 Commits

Reviewing files that changed from the base of the PR and between 48fcd53 and 79e4dec.

📒 Files selected for processing (8)

• AGENTS.md
• README.md
• docs/admin-runbook.md
• docs/agent-guide.md
• docs/bounty-lifecycle.md
• docs/bounty-rules.md
• scripts/docs_smoke.py
• tests/test_docs_public_urls.py

---

📝 Walkthrough

Walkthrough

This PR adds a comprehensive bounty lifecycle documentation guide and integrates it into the codebase by updating navigation across existing docs, establishing it as required documentation, and adding validation tests to enforce consistent messaging.

Changes

Bounty Lifecycle Documentation

Layer / File(s)	Summary
Core bounty-lifecycle documentation docs/bounty-lifecycle.md	Defines the bounty lifecycle states (claimable → proposed → pending → paid → closed), specifies claimability criteria with GitHub/MergeWork signal mapping, describes proposal action semantics (create_bounty, pay_bounty, close_bounty), and includes contributor/agent and maintainer checklists with examples.
Navigation and guidance cross-references AGENTS.md, README.md, docs/admin-runbook.md, docs/agent-guide.md, docs/bounty-rules.md	Updates five existing docs to add inline references and links pointing readers to docs/bounty-lifecycle.md at relevant checkpoints: agent pre-checks, project links, admin runbook intro, treasury-proposal guidance, and proposed-work lifecycle sections.
Validation and enforcement updates scripts/docs_smoke.py, tests/test_docs_public_urls.py	Registers docs/bounty-lifecycle.md as a required doc in the smoke test validator, adds required-phrase validations for bounty-lifecycle and related docs to ensure consistent messaging, and adds a new test that verifies bounty-lifecycle doc contains agent-readable claimability and state-transition keywords.

Possibly related issues

• ramimbo/mergework#646: This PR directly implements the requested bounty lifecycle documentation and validation improvements described in that proposal.

Possibly related PRs

• ramimbo/mergework#640: Both update bounty claimability wording and enforce consistency across docs/agent-guide.md, docs/bounty-rules.md, and scripts/docs_smoke.py.
• ramimbo/mergework#397: Both strengthen scripts/docs_smoke.py by adding new required documentation validation rules and enforcing doc-content phrases.
• ramimbo/mergework#433: Both add or update bounty claimability rules and smoke-guard checks in docs/bounty-rules.md and scripts/docs_smoke.py to prevent premature claim language.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately names the main change: clarifying bounty lifecycle documentation for agents and maintainers.
Description check	✅ Passed	The description includes all required sections with concrete details on summary, evidence, maintainer context, and validation evidence.
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	All references to investment, price, cash-out, and fabricated payout are prohibitions, not claims. MRWK correctly described as native coin supporting future snapshots/bridges. No false claims made.
Bounty Pr Focus	✅ Passed	All 8 stated files present. No app code changes. Test assertions pass. Documentation covers bounty states, proposal actions, checklists, and required keywords. No scope creep detected.

_{✏️ 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.}

[Zejia]

Reviewed current head 79e4decfcafe5141c4203ccc30d1a1689c77e388 for #601.

No blocker found. This is a focused docs/process PR that makes the bounty state machine explicit for agents and maintainers.

Evidence checked:

• Inspected AGENTS.md, README.md, docs/admin-runbook.md, docs/agent-guide.md, docs/bounty-lifecycle.md, docs/bounty-rules.md, scripts/docs_smoke.py, and tests/test_docs_public_urls.py.
• Verified the new lifecycle doc separates proposed work, pending create_bounty, live bounty, pending pay_bounty, paid, and closed/exhausted states.
• Verified the claimability rule requires mrwk:bounty, Reserved on MergeWork, an open public bounty row, remaining practical capacity, and matching acceptance criteria.
• Verified it explicitly says pending create_bounty proposals are not live bounties and pending pay_bounty proposals are not paid work.
• Verified maintainer checklist covers result.github_issue_finalization and manual recovery when finalization partially fails.
• Confirmed docs smoke and tests/test_docs_public_urls.py cover the new doc and cross-links.

Validation:

• GitHub CI for this head is successful.
• python -m pytest tests/test_docs_public_urls.py -q -> 31 passed.
• python scripts/docs_smoke.py -> docs smoke ok.
• Ruff check on docs smoke/test files -> passed.
• Ruff format check on docs smoke/test files -> 2 files already formatted.
• git diff --check origin/main...HEAD -> clean.
• git merge-tree --write-tree origin/main HEAD -> clean merge tree 7cdb108f2d08a6b762ff5ac76ae518f1868445f2.

No private data, credentials, wallet material, production mutation, signing, transfers, price/liquidity/exchange/bridge/off-ramp claims, or fabricated payout claims were used.

[chinook1001]

Reviewed current head 79e4decfcafe5141c4203ccc30d1a1689c77e388.

I approve this docs-only lifecycle clarification. I inspected the new docs/bounty-lifecycle.md state table/checklists, the links from README.md, AGENTS.md, docs/agent-guide.md, docs/bounty-rules.md, and docs/admin-runbook.md, plus the added guards in scripts/docs_smoke.py and tests/test_docs_public_urls.py.

The important safety distinction is preserved: proposed work and pending create_bounty proposals are not claimable, and pending pay_bounty proposals are not paid until proof exists. Local validation passed:

• ./.venv/bin/python scripts/docs_smoke.py
• ./.venv/bin/python -m pytest tests/test_docs_public_urls.py (31 passed)
• ./.venv/bin/ruff check AGENTS.md README.md docs/admin-runbook.md docs/agent-guide.md docs/bounty-lifecycle.md docs/bounty-rules.md scripts/docs_smoke.py tests/test_docs_public_urls.py

[Thanhdn1984]

Reviewed head 79e4decf — second independent review.

Files inspected: docs/bounty-lifecycle.md (94 lines, new), AGENTS.md, README.md, docs/admin-runbook.md, docs/agent-guide.md, docs/bounty-rules.md, scripts/docs_smoke.py, tests/test_docs_public_urls.py.

Checks:

• CI green: "Quality, readiness, docs, and image checks" → success.
• Merge state: clean, no conflicts.
• Lifecycle state table is accurate: proposed → pending create → live → pending payout → paid → closed. Each state correctly notes claimability.
• Critical safety rule verified: proposed-work and pending create_bounty are NOT claimable; pending pay_bounty is NOT paid until proof exists.
• Cross-links from README, AGENTS.md, agent-guide, admin-runbook, and bounty-rules all point to docs/bounty-lifecycle.md correctly.
• scripts/docs_smoke.py adds 2 assertions checking lifecycle doc presence and key wording.
• tests/test_docs_public_urls.py adds lifecycle doc content validation (12 lines).
• No secrets, no investment claims, no spam content.
• Maintainer note confirms this is docs-only, no bounty requested.

LGTM — clear, well-structured lifecycle documentation that helps both agents and humans avoid premature claims.