Document agent-friendly bounty post template

[rebel117]

Problem

Bounty #456 asked for a canonical agent-friendly bounty post template so humans and agents can parse scope, reward, award slots, acceptance criteria, and evidence requirements without guessing.

Before this PR, bounty posts relied on convention rather than documented structure. The issue template (bounty.yml) did not enforce key fields like How To Submit or Out of Scope.

Changes

• docs/bounty-rules.md: Added a "Bounty Post Template" section with:

  • Required fields table (title format, reward, max awards, work needed, acceptance criteria, how to submit)
  • Optional fields table (out of scope, evidence/tests, duplicate-work rules, stale-work rules, public artifact cautions)
  • Copy-pasteable markdown template
  • Agent-readable fields guide explaining which fields agents need for GitHub, REST API, and MCP bounty workflows

• docs/admin-runbook.md: Updated "Post a Bounty" steps to reference the documented template and require the MRWK bounty: <amount> MRWK - <short scope> title format.

• .github/ISSUE_TEMPLATE/bounty.yml: Restructured to match the documented template — added How To Submit and Out of Scope fields, reordered to put Reward and Max Awards first.

• scripts/docs_smoke.py: Added checks for the new template section headings and key phrases.

Evidence

$ ./.venv/bin/python scripts/docs_smoke.py
docs smoke ok

$ ./.venv/bin/python -m pytest tests/ -q
414 passed in 53.37s

$ ./.venv/bin/python -m ruff format --check .
79 files already formatted

$ ./.venv/bin/python -m ruff check .
All checks passed!

$ ./.venv/bin/python -m mypy app
Success: no issues found in 30 source files

Compared the proposed template against existing bounty issues (#405, #406, #427, #456, #459) — all already follow this structure, confirming the template matches real-world usage.

Out of Scope

• No changes to app code, database models, or API endpoints
• No public artifact cautions beyond what existing docs already state
• No investment/price/liquidity claims

Summary by CodeRabbit

• Documentation
  • Updated bounty issue template: new title prefix "MRWK bounty:", consolidated required body with structured sections (Work Needed, Acceptance Criteria, How To Submit), clarified reward/max-awards fields, and added an optional Out of Scope field.
  • Expanded runbook and rules docs with a copy/paste bounty post template, field definitions, formatting guidance, and submission/agent-readable conventions for creating bounties.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR standardizes the bounty posting template and documentation across the repository. The GitHub issue template form is updated with a combined required body template and an optional out_of_scope field, reward/max_awards guidance, a new title format, expanded bounty-rules documentation, updated admin runbook steps, and smoke-test checks enforcing the docs.

Changes

Bounty Template and Documentation Standardization

Layer / File(s)	Summary
GitHub Bounty Issue Template Form .github/ISSUE_TEMPLATE/bounty.yml	Template title prefix changed to MRWK bounty: ; reward and max_awards labels/descriptions updated; separate work/acceptance textareas replaced by a required body textarea prefilled with a canonical bounty header (Work Needed, Acceptance Criteria, How To Submit); new optional out_of_scope field added.
Bounty Post Template and Rules Documentation docs/bounty-rules.md	Adds a "Bounty Post Template" section that lists required fields (title format, reward per award, max awards, Work Needed, Acceptance Criteria, How To Submit), optional fields (out-of-scope, evidence/tests), provides a copy/paste markdown template, and documents agent-readable fields for parsing reward/status/scope.
Admin Operational Bounty Creation Instructions docs/admin-runbook.md	Reorders and expands "Post a Bounty" steps to reference the GitHub template or canonical link, require an issue title format MRWK bounty: <amount> MRWK - <short scope>, clarify MRWK tiers and max_awards usage, and document the /admin or POST /api/v1/bounties admin-token flow.
Documentation Validation Enforcement scripts/docs_smoke.py	Extends REQUIRED_PUBLIC_PHRASES to require the "Bounty Post Template" section and specific field/heading phrases in docs/bounty-rules.md (Reward, Max awards, Work Needed, Acceptance Criteria, How To Submit).

Possibly related issues

• MRWK bounty: 150 MRWK - document agent-friendly bounty post template #456: Implements the agent-readable bounty post template and validation checks described in the issue.

Possibly related PRs

• ramimbo/mergework#433: Also updates bounty documentation and adds required-phrase checks for docs/bounty-rules.md.
• ramimbo/mergework#397: Also expands scripts/docs_smoke.py phrase-checking to enforce required documentation content.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Bounty Pr Focus	⚠️ Warning	Diff matches stated bounty files and includes test evidence, but YAMLlint empty-lines violation persists in bounty.yml lines 40–42 (3 blank lines exceed max 2), unaddressed by review feedback.	Remove one blank line from .github/ISSUE_TEMPLATE/bounty.yml between ## Work Needed and "Useful accepted work" to comply with max 2 consecutive blank lines.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Document agent-friendly bounty post template' directly names the primary surface changed—the bounty post template—and is concrete and specific.
Description check	✅ Passed	The description follows the required template structure and includes all core sections: Problem, Changes, Evidence (with test output), and Out of Scope. Test checklist completed; bounty reference provided.
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	No investment, price, cash-out, or fabricated payout claims found. MRWK correctly described as native project coin; documentation disclaims off-ramps and fiat pegs.

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

[jtc268]

Requested changes after reviewing PR #469 at head 85f36632451725817ce4951d6525a9a826e57101.

The new copy-paste template does not actually carry all of the stable headings Bounty #456 asked this PR to standardize. The #456 acceptance criteria explicitly call for stable fields covering evidence or tests, out of scope, duplicate-work rules, stale-work rules, and public artifact cautions. This PR documents those in the optional-fields table in docs/bounty-rules.md, but the actual template block only includes Work Needed, Acceptance Criteria, and How To Submit.

That leaves the canonical copy-paste path incomplete: a maintainer following the new template would still omit several fields that agents are supposed to parse consistently, so the change does not fully satisfy the bounty's agent-readable template requirement. Please add those optional headings/placeholders to the template block, or otherwise make the template itself preserve the complete documented field set.

Validation run locally:

• python3 scripts/docs_smoke.py -> docs smoke ok
• python3 -m pytest tests/test_docs_public_urls.py -q -> 23 passed
• .github/ISSUE_TEMPLATE/bounty.yml parses as YAML

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7ffd534f-ffc4-48d0-b678-d0039d8a32ca

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and 85f3663.

📒 Files selected for processing (4)

• .github/ISSUE_TEMPLATE/bounty.yml
• docs/admin-runbook.md
• docs/bounty-rules.md
• scripts/docs_smoke.py

[GHX5T-SOL]

Reviewed current head 85f36632451725817ce4951d6525a9a826e57101.

I am requesting changes because the new template still leaves the machine-readable reward/max-awards contract inconsistent. docs/bounty-rules.md says the canonical body fields are Reward: MRWK per accepted award and `Max awards: `<number> in body code-block lines, and the agent-readable section says agents should parse those body code blocks. However, .github/ISSUE_TEMPLATE/bounty.yml only collects reward and max_awards as separate issue-form inputs on lines 6-21; it does not guide maintainers to repeat the exact canonical body lines. A maintainer using the form can still create an issue body that lacks the body lines the new docs tell agents to parse.

The copy-paste block also has the same contract problem in a different form: lines 94-95 are inside a fenced markdown block but escape the backticks as \``. Copying that block produces literal backslash-backticks, not the canonical Reward: <amount>...`` / Max awards: ``` syntax described in the required-fields table.

The current docs smoke guard does not catch this drift: scripts/docs_smoke.py only checks bare tokens such as Reward: and Max awards:, which are already satisfied by the table text even if the copy-paste template or issue-form output is not canonical. That is why python scripts/docs_smoke.py passes on this head despite the template mismatch.

This is distinct from the existing review note about optional headings. The blocker here is the core reward/max-awards parse contract for the fields Bounty #456 explicitly asked the template and issue form to make agent-readable. Please either make the issue form / copy-paste template emit the exact canonical body lines, or adjust the documented parser contract and smoke checks so they match what maintainers will actually post.

Validation run locally:

• /home/kali/money/mergework/.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• /home/kali/money/mergework/.venv/bin/python -m pytest tests/test_docs_public_urls.py -q -> 23 passed
• /home/kali/money/mergework/.venv/bin/python -m pytest -q -> 414 passed
• /home/kali/money/mergework/.venv/bin/python -m ruff check . -> passed
• /home/kali/money/mergework/.venv/bin/python -m ruff format --check . -> 79 files already formatted
• /home/kali/money/mergework/.venv/bin/python -m mypy app -> success, no issues in 30 source files
• YAML parse check for .github/ISSUE_TEMPLATE/*.yml -> all templates parse as mappings
• git diff --check upstream/main...HEAD -> clean
• gitleaks detect --no-banner --redact --source . --log-opts upstream/main..HEAD --exit-code 1 -> no leaks found

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/bounty-rules.md (1)

61-64: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the required MRWK descriptor in this new template section.

Please include that MRWK is a native project coin and may support future snapshots, bridges, and onchain claims to keep public docs policy-consistent.

As per coding guidelines: “MRWK should be described as a native project coin that may support future snapshots, bridges, and onchain claims”.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a00a6827-5650-4dda-8448-fc462fe93086

📥 Commits

Reviewing files that changed from the base of the PR and between 85f3663 and 66dbbc1.

📒 Files selected for processing (3)

• .github/ISSUE_TEMPLATE/bounty.yml
• docs/bounty-rules.md
• scripts/docs_smoke.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix YAMLlint empty-lines violation in the template block.

Line 42 creates 3 consecutive blank lines in the scalar block, which violates empty-lines (3 > 2) and can fail CI linting.

Proposed fix

         ## Work Needed
 
-
-
         Useful accepted work can include:

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	Useful accepted work can include:
	Useful accepted work can include:

🧰 Tools

🪛 YAMLlint (1.38.0)

[error] 42-42: too many blank lines (3 > 2)

(empty-lines)

[GHX5T-SOL]

Reviewed current head 66dbbc173129ebfb0bcc469fcb0335137089d466 after the author follow-up.

My previous reward/max-awards parser-contract blocker is addressed on this head. The issue template now makes the main body textarea start with canonical Reward: / Max awards: lines, the docs copy-paste template no longer emits escaped backticks, and scripts/docs_smoke.py now checks the exact inline-code phrases instead of only bare tokens.

I am leaving this as a comment rather than an approval because the earlier optional stable-heading review still appears unresolved on this same head: the copy-paste template and issue-form default body still do not include Evidence or Tests, Out of Scope, Duplicate-Work Rules, Stale-Work Rules, or Public Artifact Cautions headings even though bounty #456 names those fields. I am not opening a second changes-requested review for that same blocker.

Validation on this head:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 23 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest -q -> 414 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff check scripts/docs_smoke.py -> passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff format --check scripts/docs_smoke.py -> 1 file already formatted
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m mypy app -> success, no issues in 30 source files
• YAML parse check for .github/ISSUE_TEMPLATE/*.yml and .yaml -> all issue templates parse as mappings
• git diff --check origin/main...HEAD -> clean
• git diff --no-ext-diff origin/main..HEAD | gitleaks stdin --no-banner --redact --exit-code 1 -> no leaks found