Add structured MCP work-proof availability state

[AugmentSecurity]

Refs #315

Summary

• Add explicit structured availability fields to MCP submit_work_proof JSON guidance: availability, can_submit, and availability_warnings.
• Keep existing text-mode submit_work_proof behavior unchanged.
• Add focused MCP regressions for open, generic, paid, and closed guidance states.

Agent impact

Structured MCP callers can now decide whether a bounty is actually open for submissions without inferring from separate status and awards_remaining fields. Paid, closed, and exhausted bounties return can_submit: false, availability: "not_currently_open", and concrete warnings such as bounty is paid and bounty has no award slots remaining.

Generic no-selector guidance remains machine-readable but reports availability: "unknown_without_bounty" and can_submit: null because no concrete bounty was selected.

Validation

• ./.venv/bin/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
• ./.venv/bin/python -m pytest tests/test_api_mcp.py -q -> 74 passed
• ./.venv/bin/python -m pytest -q -> 319 passed
• ./.venv/bin/python -m ruff check app/main.py tests/test_api_mcp.py -> passed
• ./.venv/bin/python -m ruff format --check app/main.py tests/test_api_mcp.py -> passed
• ./.venv/bin/python -m mypy app/main.py -> passed
• ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• git diff --check -> clean

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

Summary by CodeRabbit

• New Features

  • Work proof submission guidance now includes structured availability metadata (submission eligibility, availability status, and warnings) based on bounty state.

• Tests

  • Added test coverage for work proof submission guidance on terminal bounties (paid or closed 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: 658c7473-19bc-49e9-8228-11bd1d085c05

📥 Commits

Reviewing files that changed from the base of the PR and between f4fa763 and ecc3dbb.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

This PR extends MCP work proof guidance responses to include structured availability metadata. The work_proof_guidance_json function now computes can_submit and availability_warnings based on bounty status and remaining award slots, while generic_work_proof_guidance_json returns default unknown values. Tests are updated to validate these fields across open and terminal bounty states.

Changes

Work Proof Availability Metadata

Layer / File(s)	Summary
Availability metadata computation in guidance responses app/main.py	work_proof_guidance_json computes can_submit and availability_warnings from bounty status and remaining award slots; generic_work_proof_guidance_json returns fixed unknown values (availability: "unknown_without_bounty", can_submit: None, empty warnings).
Availability metadata test coverage tests/test_api_mcp.py	Extended existing assertions to require availability, can_submit, and availability_warnings fields in structured guidance responses, and added new test validating terminal bounty availability (paid/closed states report can_submit == False, availability == "not_currently_open", and specific warning messages).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• ramimbo/mergework#315: Modifies MCP submit_work_proof structured JSON guidance with bounty availability and award-slot metadata fields.
• ramimbo/mergework#284: Updates MCP tool guidance responses and corresponding test assertions in the same files.

Possibly related PRs

• ramimbo/mergework#317: Introduced structured JSON support for submit_work_proof guidance; this PR builds on that foundation by adding availability metadata fields.
• ramimbo/mergework#287: Initial implementation of submit_work_proof guidance handler and tests; this PR extends with availability/warning fields.

Suggested reviewers

• TateLyman
• weilixiong
• Karry2019web

🚥 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 describes the main change: adding structured availability state fields to MCP work-proof guidance responses.
Description check	✅ Passed	The description provides comprehensive coverage including summary, agent impact, validation evidence, and related bounty reference, though Test Evidence checkbox items are unchecked.
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]

Reviewed PR #339 on head ecc3dbb.

No blockers found. The structured MCP submit_work_proof change is narrowly scoped and preserves the existing text response while adding machine-readable availability state.

Evidence checked:

• Inspected app/main.py and confirmed can_submit is derived from status == "open" plus remaining award slots, with paid/closed/exhausted bounties returning availability: "not_currently_open" and explicit warnings.
• Inspected tests/test_api_mcp.py and confirmed coverage for open bounty guidance, generic guidance, paid bounty guidance, and closed bounty guidance; the test also asserts structuredContent stays byte-for-byte aligned with the JSON text payload.
• Ran ./.venv/bin/python -m pytest tests/test_api_mcp.py -q -> 74 passed.
• Ran ./.venv/bin/python -m ruff check app/main.py tests/test_api_mcp.py -> passed.
• Ran ./.venv/bin/python -m mypy app -> passed.
• Ran git diff --check origin/main...HEAD -> passed.