Proposed work: align generic work-proof JSON availability keys

[LikeACloud7]

Bounty #649

Problem

submit_work_proof with format: "json" returns different top-level availability keys depending on whether the caller selected a concrete bounty.

For a concrete bounty, work_proof_guidance_json() includes the newer effective-availability fields:

• effective_awards_remaining
• effective_available_mrwk
• availability_state
• availability_note

For generic guidance with no selected bounty, generic_work_proof_guidance_json() omits those keys entirely while still returning older capacity keys such as awards_remaining, max_awards, awards_paid, reward_mrwk, and available_mrwk.

That makes the structured response shape less stable for agents that call submit_work_proof first without a bounty selector, then call it again with bounty_id or issue_number.

Current Evidence

• app/mcp_work_proof.py::work_proof_guidance_json() returns effective_awards_remaining, effective_available_mrwk, availability_state, and availability_note.
• app/mcp_work_proof.py::generic_work_proof_guidance_json() returns awards_remaining, max_awards, awards_paid, reward_mrwk, and available_mrwk, but not the effective-availability fields.
• tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_bounty_guidance checks the bounty-specific structured response.
• tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance hard-codes the generic structured response shape and currently omits the effective-availability keys.
• docs/api-examples.md tells agents to read effective availability fields before opening or claiming work, so the generic guidance should ideally expose the same keys as null when no bounty is selected.

Proposed Work

Add schema-stability null fields to generic work-proof guidance:

• effective_awards_remaining: null
• effective_available_mrwk: null
• availability_state: null
• availability_note: null

Then update focused tests for both the direct helper and /mcp structured response.

The behavior should remain advisory only: generic guidance still has availability: "unknown_without_bounty" and can_submit: null, and it should still tell callers to select a concrete bounty before submitting work proof.

Expected Value

This gives MCP/agent consumers a stable structuredContent shape across generic and bounty-specific work-proof calls. Agents can always read the same availability keys and check for null when no bounty has been selected, instead of branching on missing keys.

It also aligns generic work-proof output with the newer effective-availability model without changing bounty selection, payouts, proofs, ledger state, wallet behavior, or treasury execution.

Acceptance / Verification Notes

• Generic submit_work_proof JSON includes the four effective-availability keys with null values.
• Concrete bounty submit_work_proof JSON keeps returning populated effective-availability values.
• availability: "unknown_without_bounty" and can_submit: null remain unchanged for generic guidance.
• Focused tests cover generic_work_proof_guidance_json() and the /mcp structured generic response.

Duplicate Search

Searched existing issues for generic_work_proof, unknown_without_bounty, submit_work_proof effective_available_mrwk, and structuredContent effective_awards_remaining.

Related but distinct issues:

• Proposed work: add typed OpenAPI response schemas for public MRWK read APIs #688 covers broad typed OpenAPI response schemas for public read APIs.
• Proposed work: expose structured submission mode for non-PR bounties #676 covers structured submission mode for non-PR bounties.
• Proposed work: use effective availability in submission quality gate #681 covers submission quality gate effective availability.
• Proposed work: clarify partial pending-payout availability guidance #697 covers partial pending-payout guidance and MCP warning semantics.

This proposal is narrower: keep submit_work_proof generic JSON schema aligned with the concrete bounty JSON schema by adding null effective-availability fields.

Non-Goals

• No change to bounty selection, claimability, payout, proof, ledger, wallet, treasury, admin-token, or production mutation behavior.
• No new live bounty claim.
• No price, investment, exchange, liquidity, bridge, cash-out, private security detail, secret, credential, or fabricated payout claims.