Add structured work-proof submission requirements

[newmattock]

Bounty #315

Summary

• Add a structured submission_requirements object to submit_work_proof JSON guidance.
• Surface machine-readable reference formats, claim command, attempt endpoint, evidence requirements, acceptance trigger, public metadata exclusions, and state-aware next actions.
• Keep existing text-mode behavior unchanged and preserve the existing JSON guidance fields added by earlier PRs.

Why this is distinct

PR #317 added format: "json" and the core structured guidance payload. PR #339 added structured availability state. This PR adds the submission checklist/requirements layer so MCP agents can determine what concrete proof, references, claim command, and acceptance trigger are required without scraping docs or prose.

Validation

• uv run --with pytest pytest tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_bounty_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_structures_terminal_bounty_availability -q -> 3 passed.
• uv run --with pytest pytest tests/test_api_mcp.py -q -> 76 passed.
• uv run --with pytest pytest -q -> 335 passed.
• uv run --with ruff ruff check app/main.py tests/test_api_mcp.py -> passed.
• uv run --with ruff ruff format --check app/main.py tests/test_api_mcp.py -> 2 files already formatted.
• uv run --with mypy mypy app/main.py -> success.
• uv run python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check -> clean.

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

Summary by CodeRabbit

• New Features
  • Improved work proof submission guidance with structured requirements detailing reference formats, evidence criteria, acceptance conditions, and sequenced action steps
  • Enhanced clarity on submission prerequisites across different bounty states

[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: 47439f75-07e2-4578-9066-f0d3d9468587

📥 Commits

Reviewing files that changed from the base of the PR and between ac99d79 and d574f6d.

📒 Files selected for processing (2)

• app/main.py
• tests/test_api_mcp.py

---

📝 Walkthrough

Walkthrough

This PR adds a structured submission_requirements object to MCP work proof guidance outputs. A new helper function builds requirements with conditional next-action logic based on bounty submission readiness, then gets integrated into both bounty-specific and generic guidance JSON outputs. Tests validate the structure across all three guidance scenarios.

Changes

Work Proof Submission Requirements

Layer / File(s)	Summary
Submission requirements builder app/main.py	New work_proof_submission_requirements(...) helper conditionally selects first required action based on can_submit state and returns a dict with reference formats, claim/attempt endpoints, evidence constraints, acceptance triggers, prohibited metadata, and next-actions sequence.
Guidance output integration app/main.py	work_proof_guidance_json(bounty) and generic_work_proof_guidance_json() now include submission_requirements field, with bounty-specific version using bounty id/issue number and computed can_submit, and generic version using None placeholders.
Test validation tests/test_api_mcp.py	MCP tests expanded to assert presence and exact contents of submission_requirements in bounty guidance (with reference/claim metadata and next-actions IDs), generic guidance (with full structure including evidence/public-metadata rules and detailed next-actions), and terminal bounties (with choose_open_bounty routing).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• MRWK bounty: structured MCP work-proof guidance #315: Both changes target the MCP "submit_work_proof" guidance JSON—adding structured submission_requirements and richer machine-readable guidance (including fields/tests).

Possibly related PRs

• ramimbo/mergework#339: Both PRs modify the MCP work-proof guidance JSON shapes around can_submit and related structured fields in app/main.py and extend tests/test_api_mcp.py assertions for terminal/generic guidance.
• ramimbo/mergework#317: Both PRs update app/main.py/tests/test_api_mcp.py around the MCP submit_work_proof JSON guidance payload—Add structured MCP work proof guidance #317 introduces structured JSON/format: "json" support, while this PR adds a new submission_requirements object into the generated guidance JSON.
• ramimbo/mergework#287: Both PRs extend the MCP work-proof/submit_work_proof guidance flow in app/main.py and expand tests/test_api_mcp.py assertions around bounty-specific tool responses.

Suggested reviewers

• TateLyman
• weilixiong

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a structured work-proof submission requirements object to the guidance system.
Description check	✅ Passed	The description includes a clear summary, context, validation results, and follows the template structure with bounty reference, summary, and test 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.

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

[tolga-tom-nook]

No blockers found on the current PR #347 head (d574f6d).

What I checked:

• The new submission_requirements payload is added consistently to both bounty-specific and generic submit_work_proof MCP guidance.
• Terminal/closed/paid bounty guidance now switches the first required action to choose_open_bounty, which matches the existing can_submit = False availability behavior.
• The added metadata stays guidance-only and does not change ledger balances, payout flow, wallet handling, or proof submission side effects.

Validation run locally on PR head:

• ./.venv/bin/python -m pytest tests/test_api_mcp.py -q -> 76 passed
• ./.venv/bin/python -m ruff check app/main.py tests/test_api_mcp.py -> passed
• ./.venv/bin/python -m mypy app -> passed
• git diff --check origin/main...HEAD -> passed

[TUPM96]

Reviewed the MCP structured-guidance changes for #315/#340.

Evidence checked:

• Inspected app/main.py additions around work_proof_submission_requirements, including bounty-specific, generic no-selector, and terminal paid/closed next_actions behavior.
• Inspected tests/test_api_mcp.py coverage for reference_formats, claim_command, attempt_endpoint, evidence_required, metadata exclusions, and paid/closed first action handling.
• Verified the new requirements object is added only to JSON structured guidance and does not alter the existing text guidance path.

Commands run locally on PR head d574f6d:

• python -m pytest tests\test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_bounty_guidance tests\test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance tests\test_api_mcp.py::test_mcp_submit_work_proof_structures_terminal_bounty_availability -q -> 3 passed
• python -m pytest tests\test_api_mcp.py -q -> 76 passed
• python -m ruff check app\main.py tests\test_api_mcp.py -> passed

No blocking issues found in this scope.