Add expected PR size bounty guidance [Bounty #383]

[prettyboyvic]

Summary

• Add an explicit Expected PR size: prompt to the pull request template.
• Align the agent guide and bounty rules around the same claim-window packet: exact bounty, intended files/surfaces, expected PR size, test plan, evidence, and out-of-scope notes.
• Extend scripts/docs_smoke.py so the expected-size prompt is checked before future docs/template changes pass smoke.

Evidence

• Confusion, missing step, stale example, or bug this addresses: Bounty MRWK bounty: agent submission hygiene and claim-window docs #383 asks for claim-window guidance, and PR docs: clarify bounty submission hygiene #386 is held with mrwk:needs-info specifically because the PR template lacks an explicit Expected PR size: prompt.
• Bounty capacity and active attempts/open PRs checked: GET https://api.mrwk.ltclab.site/api/v1/bounties/58 returned status: open and awards_remaining: 1; GET https://api.mrwk.ltclab.site/api/v1/bounties/58/attempts returned no active attempts. PR docs: add pre-bounty preflight checks and rejection recovery guide [Bounty #383] #387 is paid; PR docs: clarify bounty submission hygiene #386 remains held on the missing expected-size prompt.
• Intended files or surfaces: .github/pull_request_template.md, docs/agent-guide.md, docs/bounty-rules.md, scripts/docs_smoke.py.
• Expected PR size: 4 focused files, docs/template plus one docs-smoke guard, about 26 added lines and 6 removed lines.
• Out of scope: runtime code, API behavior, MCP behavior, ledger behavior, payout logic, wallet logic, marketing copy, and broad docs rewrites.

Test Evidence

• uv run --extra dev python -m ruff check . -> passed.
• uv run --extra dev python -m ruff format --check . -> 65 files already formatted.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• uv run --extra dev python -m pytest tests/test_docs_public_urls.py tests/test_check_agents.py tests/test_submission_quality_gate.py -q -> 41 passed.
• uv run --extra dev python -m mypy app -> success.
• uv run --extra dev python -m pytest -q -> 377 passed.
• git diff --check -> clean.

MRWK

Bounty #383

No private keys, seed material, secrets, deployment credentials, private vulnerability details, payout credentials, or MRWK price claims are included.

Summary by CodeRabbit

• Documentation

  • Updated agent guide and bounty rules with a new bounty PR submission step requiring a written claim-window scope before coding
  • Introduced a "claim-window packet" format for PRs: bounty reference, intended files/surfaces, expected PR size, test plan, evidence, and out-of-scope items
  • Reordered checklist for clarity

• Chores

  • Added validation to enforce the new PR template requirements (including expected PR size)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ca6b6429-fe25-4cc2-973d-d80879ef4388

📥 Commits

Reviewing files that changed from the base of the PR and between 0ca1bd4 and 910f01b.

📒 Files selected for processing (1)

• scripts/docs_smoke.py

---

📝 Walkthrough

Walkthrough

This PR requires contributors to declare claim-window scope in PRs (exact bounty reference, intended files/surfaces, expected PR size, test plan, out-of-scope) via updated PR template, agent guide, and bounty rules, and adds a docs_smoke.py check to validate the template contains "expected pr size:".

Changes

Bounty Scope Documentation and Validation

Layer / File(s)	Summary
Bounty scope documentation .github/pull_request_template.md, docs/bounty-rules.md, docs/agent-guide.md	PR template checklist adds prompts for bounty capacity/active attempts, intended files/surfaces, expected PR size, and out-of-scope items; docs/bounty-rules.md documents the required claim-window packet in PR bodies; docs/agent-guide.md adds a checklist step to write scope before coding and renumbers subsequent steps.
PR template validation in smoke tests scripts/docs_smoke.py	Adds PR_TEMPLATE constant referencing the template path and updates main() to fail the docs smoke check if .github/pull_request_template.md is missing or does not contain the case-insensitive prompt "expected pr size:".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• MRWK bounty: agent submission hygiene and claim-window docs #383: The PR implements the same hygiene updates and smoke-test validation requested by this issue.

Suggested labels

mrwk:accepted

Suggested reviewers

• weilixiong
• tolga-tom-nook

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding explicit PR size guidance to bounty-related documentation and checks.
Description check	✅ Passed	The description comprehensively covers all required template sections including summary, evidence, detailed test results, and MRWK bounty reference with security note.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/docs_smoke.py`:
- Around line 67-74: The PR-template check is currently guarded by "if ok:" so
it is skipped when earlier checks fail; remove that conditional and run the
block unconditionally while keeping the existing checks that set the "ok" flag
(referencing pr_template, ROOT, PR_TEMPLATE, and ok) so template existence and
"expected pr size:" content are always validated and failures still aggregate by
setting ok = False when checks fail.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d2eaf4d3-3570-4af5-ab90-16dea5d991e7

📥 Commits

Reviewing files that changed from the base of the PR and between a1795ed and 0ca1bd4.

📒 Files selected for processing (4)

• .github/pull_request_template.md
• docs/agent-guide.md
• docs/bounty-rules.md
• scripts/docs_smoke.py

[tolga-tom-nook]

Manual review pass for bounty #340 on PR #392 at head 910f01b.

Evidence checked:

• Inspected .github/pull_request_template.md, docs/agent-guide.md, docs/bounty-rules.md, and scripts/docs_smoke.py.
• Verified the docs/template additions stay focused on claim-window scope, expected PR size, evidence, and out-of-scope notes for bounty submissions.
• Ran ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok.
• Ran ./.venv/bin/python -m ruff check scripts/docs_smoke.py -> passed.

I do not see a blocking issue in the docs behavior. The ruff format --check command is not meaningful for the Markdown files without Ruff preview mode, but the Python smoke script itself is clean.

[ayskobtw-lil]

No blockers from my follow-up review on current head 910f01b.

Evidence checked:

• Inspected .github/pull_request_template.md, docs/agent-guide.md, docs/bounty-rules.md, and scripts/docs_smoke.py against Bounty #383.
• Verified the PR template now has explicit claim-window fields for bounty capacity/open PR checks, intended files/surfaces, expected PR size, and out-of-scope notes.
• Verified the agent guide and bounty rules describe the same claim-window packet: exact bounty, intended surfaces, expected size, test plan, evidence, and out-of-scope notes.
• Verified the second commit addresses CodeRabbit's docs-smoke nit: the PR-template check now runs even if earlier docs checks have already set ok = False, so missing Expected PR size: cannot be masked by an earlier failure.
• Checked that scope is limited to docs/template/docs-smoke behavior and does not add payout, price, bridge, cash-out, runtime, API, ledger, wallet, or MCP claims.
• Hosted quality check was green in the PR metadata I inspected.

Local validation:

• python scripts/docs_smoke.py -> docs smoke ok
• python -m pytest tests/test_docs_public_urls.py tests/test_submission_quality_gate.py -q -> 39 passed
• python -m ruff check scripts/docs_smoke.py -> passed
• python -m ruff format --check scripts/docs_smoke.py -> 1 file already formatted
• python -m mypy scripts/docs_smoke.py -> success
• git diff --check origin/main...HEAD -> clean