docs: add claim window and evidence guidelines (Bounty #383)

[Karry2019web]

Summary

• Add claim-window and evidence guidelines to docs/bounty-rules.md and docs/agent-guide.md, aligning contributor and agent-facing guidance with discussion Public contributor activity and proof dashboard roadmap #128's claim-window expectations.

Evidence

• Confusion this addresses: agents opening PRs for fully-subscribed bounty rounds, or submitting without understanding which evidence is expected for different work types.

Test Evidence

• ruff format --check .
• ruff check .
• mypy app
• pytest
• python scripts/docs_smoke.py

MRWK

Related bounty: Bounty #383

Summary by CodeRabbit

• Documentation
  • Added "Claim Window Etiquette" guidance for multi-award bounty PRs, including estimating remaining capacity and avoiding oversubscription or exhausted/closed bounties
  • Published "Claim Window and Award Capacity" policy clarifying how capacity is determined and single‑award closure behavior
  • Added "Evidence Guidelines for Claims" with required evidence types and key acceptance rules (no duplicates, vague or self-reviewed claims)

[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: 08300824-518c-4c0e-900e-60cee64b4d86

📥 Commits

Reviewing files that changed from the base of the PR and between 288e013 and 1124383.

📒 Files selected for processing (1)

• docs/bounty-rules.md

---

📝 Walkthrough

Walkthrough

Documentation formalizes claim window and award-capacity policies and adds evidence requirements; agent-facing etiquette guidance for validating capacity and including evidence in multi-award bounty PRs is added.

Changes

Claim Window and Evidence Documentation

Layer / File(s)	Summary
Bounty claim policy and evidence guidelines docs/bounty-rules.md	"Claim Window and Award Capacity" subsection defines how max_awards caps apply, when additional PRs should be opened, and how to estimate pending claims. "Evidence Guidelines for Claims" specifies required evidence types by work category and lists key acceptance rules: claims must be specific, reviewable, avoid duplicates, avoid self-review, and respect mrwk:needs-info pending status.
Agent claim window etiquette docs/agent-guide.md	New "Claim Window Etiquette" section instructs agents to verify award capacity, estimate remaining slots, avoid exhausted bounties, and include required evidence in PR bodies before opening multi-award bounty claims.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• MRWK bounty: agent submission hygiene and claim-window docs #383: Updates to docs/agent-guide.md and docs/bounty-rules.md with claim window etiquette and evidence/award-capacity guidance directly address the requested documentation changes in this issue.

Possibly related PRs

• ramimbo/mergework#387: Both PRs enhance bounty submission guidance in docs/agent-guide.md around pre-submission validation and claim handling, with this PR focusing on "Claim Window Etiquette" and the related PR covering "Recovering from Rejection" in the same workflow.

Suggested labels

mrwk:accepted

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main changes: adding claim window and evidence guidelines to the documentation, and references the related bounty.
Description check	✅ Passed	The description follows the template structure with all required sections completed: Summary explains the purpose, Evidence describes the problem being addressed, Test Evidence shows the checklist status, and MRWK identifies the related bounty.
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 `@docs/bounty-rules.md`:
- Line 66: The rule currently compares pending claims to max_awards; change it
to compare pending claims to remaining slots by computing remaining_slots =
max_awards - awarded_count (where awarded_count includes prior accepted and paid
awards) and then use "If pending claims >= remaining_slots, the bounty is
oversubscribed and new PRs may not get a slot." Update the text to reference
remaining_slots (or an equivalent term used elsewhere like available_slots) and
ensure awarded_count is clearly defined as prior accepted/paid awards.

🪄 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: f6ecb1fc-9d14-4598-b32d-15d1a4c62679

📥 Commits

Reviewing files that changed from the base of the PR and between a1795ed and 288e013.

📒 Files selected for processing (2)

• docs/agent-guide.md
• docs/bounty-rules.md

[Zejia]

I would fix one capacity-accounting detail before merging this.

The new guidance in docs/bounty-rules.md says to count /claim comments and then treat pending claims >= max_awards as oversubscribed. That is only correct before any awards have been accepted or paid. Once a round is partially paid, the check needs to compare pending claims against remaining slots, not the original cap.

Concrete example from the current Bounty #383 thread: max_awards = 2, PR #387 has already been paid, and there are later pending claims. Under the current text, a contributor could see one pending claim and think 1 < 2, even though only one award slot remains. The rule should be closer to:

remaining_slots = max_awards - accepted_or_paid_awards; if pending_claims >= remaining_slots, treat the round as oversubscribed unless a maintainer says overflow will be accepted.

Everything else looks directionally useful, but this line is the core claim-window rule, so it needs to be precise.

Validation run locally:

• /Users/jimmy/Documents/Playground/bounty-work/mergework/.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• /Users/jimmy/Documents/Playground/bounty-work/mergework/.venv/bin/python -m ruff check docs/agent-guide.md docs/bounty-rules.md -> no Python files under those paths; command exited cleanly
• git diff --check origin/main...HEAD -> clean

[Karry2019web]

Addressed Zejia's review feedback: the oversubscription check now uses remaining_slots = max_awards - accepted_or_paid_awards instead of comparing pending claims directly against max_awards. This correctly handles partially-paid rounds like Bounty #383 (max_awards=2, one award already paid, remaining_slots=1).

@Zejia please re-review when you have a moment. The fix is in the Claim Window and Award Capacity section of docs/bounty-rules.md.

[tolga-tom-nook]

No blockers from this follow-up docs review.

Evidence checked on head 1124383:

• Inspected docs/bounty-rules.md and docs/agent-guide.md after the oversubscription wording update.
• Verified the new guidance covers remaining-slot calculation, pending-claim oversubscription risk, evidence expectations for PR submissions/reviews/docs/bug reports, duplicate/vague/self-review rejection cases, and no fiat/price/bridge/cash-out language.
• Ran ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok.
• Ran ./.venv/bin/python -m ruff check docs/agent-guide.md docs/bounty-rules.md -> no Python files / no issues.
• Ran git diff --check origin/main...HEAD -> clean.

Note: ruff format --check on Markdown still reports Ruff's Markdown formatter as experimental unless preview mode is enabled, so I did not treat that as a blocker.

[aiautotool]

The docs content itself looks directionally useful, but this PR is not reviewable as a focused Bounty #383 docs submission yet.\n\nFinding: the PR body describes only claim-window/evidence documentation changes, but the actual diff includes a large stack of unrelated code and test files: app/accounts.py, app/activity.py, app/admin.py, app/hub.py, app/ledger_views.py, app/mcp_work_proof.py, app/main.py, multiple route tests, and submission_quality_gate changes. That mixes several prior code-health/refactor scopes into a docs bounty PR, makes acceptance/award attribution ambiguous, and raises merge risk unrelated to the stated docs change. Please rebase/cherry-pick this onto current main so the PR contains only docs/agent-guide.md and docs/bounty-rules.md changes for #383.\n\nLocal evidence:\n- git diff --stat origin/main...HEAD -> 20 files changed, including app/.py and tests/.py outside the docs bounty scope\n- python scripts/docs_smoke.py -> docs smoke ok\n- git diff --check origin/main...HEAD -> pass

[ramimbo]

Closing as not accepted for Bounty #383. The claim-window/submission-hygiene round was filled by PR #392, and this PR overlaps that docs scope after the accepted update. No fresh #383 round is needed right now; useful review work on this PR was handled separately through the review-bounty flow.