Surface attempt state in MCP work guidance

[piaigmt]

Bounty #321

Summary

• Add live attempt-reservation context to structured MCP submit_work_proof guidance for concrete bounties.
• Return current active_attempts, attempt_warnings, and the advisory attempt-registration endpoint/TTL limits so agents can see overlap before opening work.
• Keep generic guidance explicit that no live attempt state is available until a concrete bounty is selected, and document the workflow in the agent guide.

Why this is distinct

• PR Add advisory bounty attempt reservations #326 added REST attempt registration/list/release behavior.
• PR Add MCP bounty attempt inspection #334 adds a dedicated read-only MCP attempt inspection tool.
• This PR closes the agent-flow gap in the existing submit_work_proof(format=json) path: agents already call it for submission instructions, but it did not surface active attempts or the reservation path, so callers could miss overlap unless they knew to call a separate tool/REST endpoint.

This remains advisory only. It does not create payments, claim acceptance, mutate ledger balances, register attempts, release attempts, or block maintainer decisions.

Validation

• uv run --extra dev 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_structured_guidance_includes_attempt_state tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance -q -> 3 passed
• uv run --extra dev ruff check app/main.py tests/test_api_mcp.py -> passed
• uv run --extra dev ruff format --check app/main.py tests/test_api_mcp.py -> passed
• uv run --extra dev 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

  • Work proof guidance now includes active bounty attempts and warnings when requested for a specific bounty.
  • Updated submission guidance flow to direct users to select a bounty and register advisory attempts before submission.

• Documentation

  • Added guide for retrieving machine-readable, bounty-specific submission guidance via MCP endpoint with example and response structure.

• Tests

  • Extended test coverage for structured work-proof guidance including attempt state validation.

[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: 5add2850-05f7-4af3-9f05-62500d2bb728

📥 Commits

Reviewing files that changed from the base of the PR and between a5cd307 and e968617.

📒 Files selected for processing (3)

• app/main.py
• docs/agent-guide.md
• tests/test_api_mcp.py

---

📝 Walkthrough

Walkthrough

The PR enhances the MCP submit_work_proof tool's JSON guidance responses. Bounty-specific guidance now fetches and includes up to 10 active BountyAttempt rows with computed warnings and advisory-only registration instructions. Generic guidance (no bounty specified) returns empty attempts and directs users to select a concrete bounty first. Test coverage and documentation are updated accordingly.

Changes

Work Proof Guidance with Active Attempt State

Layer / File(s)	Summary
Active attempt fetching and bounty-specific guidance response app/main.py	Queries active BountyAttempt rows (ordered by recency, limited to 10) and extends bounty-specific JSON guidance response to include active_attempts, computed attempt_warnings, and a structured attempt_registration object with advisory-only path, TTL bounds, and submission workflow instructions.
Generic guidance response and documentation app/main.py, docs/agent-guide.md	Generic (no-bounty) JSON guidance includes empty active_attempts, standardized "select a bounty first" warning, and None registration. New documentation section provides a curl example and explains the structured response fields and the requirement to specify a bounty for live attempt state.
Test imports and guidance validation tests/test_api_mcp.py	Adds datetime and BountyAttempt imports; new test creates two active BountyAttempt records and validates the MCP response includes correct attempt warnings, ordered active attempts, and advisory registration details; existing generic guidance test expectations updated to reflect new submission instructions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• MRWK bounty: structured MCP work-proof guidance #315: Implements structured JSON guidance with attempt-state fields for the MCP submit_work_proof endpoint, matching the PR's extension of attempt inspection and advisory-flow guidance.

Possibly related PRs

• ramimbo/mergework#326: Adds the BountyAttempt bounty-attempt reservation model and endpoints that the main PR's guidance now surfaces via active_attempts and advisory registration.
• ramimbo/mergework#334: Extends MCP bounty-attempt inspection by adding structured active_attempts with computed attempt_warnings, directly aligned with the main PR's guidance enhancement.
• ramimbo/mergework#317: Introduces structured JSON guidance for submit_work_proof in app/main.py and corresponding test validation, which the main PR builds upon with bounty-specific active_attempts and advisory registration fields.

Suggested reviewers

• TateLyman
• Karry2019web
• 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 accurately reflects the main change: surfacing attempt state in MCP work guidance, which aligns with all modified files.
Description check	✅ Passed	The description covers all required template sections: summary, evidence of the issue, validation test results, and bounty reference (Bounty #321). All checks are validated.
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.}

[TateLyman]

Reviewed the attempt-state guidance change.

What I checked:

• app/main.py: submit_work_proof(format=json) now queries active attempts for the concrete bounty, serializes them with bounty_attempt_to_dict, includes attempt_warnings, and returns advisory registration limits without mutating attempts, proofs, ledger rows, or payouts.
• tests/test_api_mcp.py: structured guidance covers empty attempt state, active attempt ordering/warnings, and generic no-bounty guidance.
• docs/agent-guide.md: documents the concrete-bounty MCP call and clarifies that generic guidance has no live attempt state.

Validation run locally:

• uv run --extra dev 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_structured_guidance_includes_attempt_state tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance -q -> 3 passed.
• uv run --extra dev python -m pytest tests/test_api_mcp.py tests/test_bounty_attempts.py -q -> 77 passed.
• uv run --extra dev ruff check app/main.py tests/test_api_mcp.py -> passed.
• uv run --extra dev ruff format --check app/main.py tests/test_api_mcp.py -> passed.
• uv run --extra dev mypy app/main.py -> passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.

I did not find a behavioral blocker in the patch itself. One repository-level note: GitHub currently reports the PR merge state as UNSTABLE, so it likely needs a maintainer-side refresh/rebase before merge even though the hosted quality check is green.

[ramimbo]

Closing this without opening a fresh #321 round. #321 is filled, and this overlaps the structured guidance surface accepted in this pass through #339/#315. A fresh maintainer-opened scope would be needed before reconsidering this work.