Share work proof remaining-awards helper

[alan747271363-art]

Summary

• Extract the repeated effective-awards lookup in app/mcp_work_proof.py into _effective_awards_remaining_from_payload().
• Reuse the helper for text guidance, submission availability, and structured JSON guidance.
• Add a focused assertion that the text guidance still reports the effective remaining award count.

Bounty

• Bounty MRWK bounty: 100 MRWK - code cleanup and maintainability improvements #846: MRWK bounty: 100 MRWK - code cleanup and maintainability improvements #846
• Public bounty row: https://mrwk.online/bounties/112

Scope / Safety

• Focused maintainability cleanup only.
• No API shape, MCP tool contract, bounty lifecycle semantics, ledger mutation, wallet behavior, treasury/proposal execution, payout execution, admin-token behavior, private data, credentials, exchange, bridge, cash-out, or MRWK price behavior changed.

Validation

• .venv\Scripts\python.exe -m pytest tests\test_mcp_work_proof.py -q -> 8 passed.
• .venv\Scripts\python.exe -m ruff check app\mcp_work_proof.py tests\test_mcp_work_proof.py -> passed.
• .venv\Scripts\python.exe -m ruff format --check app\mcp_work_proof.py tests\test_mcp_work_proof.py -> 2 files already formatted.
• .venv\Scripts\python.exe -m mypy app\mcp_work_proof.py -> success.
• .venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• git diff --check -> clean.
• git merge-tree --write-tree origin/main HEAD -> clean tree 9c2767b5a16feff1e787f4f144de44356d168701.

Summary by CodeRabbit

• Refactor

  • Consolidated effective award calculation logic for improved consistency across the application.

• Tests

  • Extended test coverage to verify accurate award count information in guidance output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cebadbea-8c19-4dc4-87d4-f8b2da4ae228

📥 Commits

Reviewing files that changed from the base of the PR and between d7e9b53 and da4056f.

📒 Files selected for processing (2)

• app/mcp_work_proof.py
• tests/test_mcp_work_proof.py

---

📝 Walkthrough

Walkthrough

The PR extracts effective-awards-remaining calculation into a new helper function _effective_awards_remaining_from_payload() and consolidates its use across submission availability and JSON guidance paths. The test is updated to verify the computed effective awards value appears in guidance text.

Changes

Effective Awards Remaining Consolidation

Layer / File(s)	Summary
Helper extraction and award-remaining consolidation app/mcp_work_proof.py	New _effective_awards_remaining_from_payload() helper computes effective awards remaining by preferring effective_awards_remaining with fallback to awards_remaining. Used in _submission_availability, work_proof_guidance_json for warning conditions, and returned in the JSON response instead of raw payload value.
Test assertion for computed effective awards tests/test_mcp_work_proof.py	Test verifies that work-proof guidance text includes the computed effective remaining award count ("effectively remaining: 6").

Possibly related PRs

• ramimbo/mergework#382: Both PRs modify app/mcp_work_proof.py's work-proof guidance logic and effective/remaining award availability computation used for warnings and JSON output.
• ramimbo/mergework#339: Both PRs adjust MCP work-proof JSON guidance to base availability-related fields and warnings on effective/remaining award slots logic.
• ramimbo/mergework#317: Both PRs touch the JSON work-proof guidance pipeline for submit_work_proof and refactor the effective_awards_remaining computation that feeds structured JSON fields.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Bounty Pr Focus	⚠️ Warning	83 files changed, not 2 as claimed. Major unrelated deletions in app/mcp.py (198 lines), app/json_payloads.py (68 lines), and 8 entire files deleted across codebase.	Rebase PR to include only app/mcp_work_proof.py and tests/test_mcp_work_proof.py. Defer other 81 files to separate PRs.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title names the changed surface—a new helper function for work proof remaining-awards lookup—and is concrete and descriptive.
Description check	✅ Passed	The description includes summary, bounty reference, scope/safety statement, and validation evidence. All key sections from the template are addressed.
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.
Mergework Public Artifact Hygiene	✅ Passed	Code refactoring with no investment/price/cash-out claims. README correctly states MergeWork does not currently operate cash-out/bridge/exchange, only describes future possibility with caveats.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[yui-stingray]

Reviewed PR #948 at current head da4056f558a063a12ee428606a92ed19b523ac3a as a non-author.

Evidence checked:

• inspected app/mcp_work_proof.py and tests/test_mcp_work_proof.py;
• confirmed _effective_awards_remaining_from_payload() centralizes the effective-awards fallback and is reused by text guidance, submission availability, and JSON guidance;
• confirmed JSON availability warnings now use the effective award slot count, keeping full/open decisions aligned with effective capacity;
• confirmed the added test locks the text guidance output for effectively remaining: 6;
• confirmed the hosted Quality check succeeded, CodeRabbit generated no actionable comments, there were no existing human reviews, and the #838 claim thread had no #948 claim immediately before this review.

No actionable concerns from this review.

[alan747271363-art]

Update after syncing with latest main:

• The initial PR diff was based on an older main and CodeRabbit correctly warned that it appeared to include unrelated files.
• I merged current origin/main into this branch and pushed the updated head 549195d.
• git diff --name-only origin/main...HEAD now shows only:
  • app/mcp_work_proof.py
  • tests/test_mcp_work_proof.py

Re-validation on the updated branch:

• .venv\Scripts\python.exe -m pytest tests\test_mcp_work_proof.py -q -> 8 passed.
• .venv\Scripts\python.exe -m ruff check app\mcp_work_proof.py tests\test_mcp_work_proof.py -> passed.
• .venv\Scripts\python.exe -m ruff format --check app\mcp_work_proof.py tests\test_mcp_work_proof.py -> 2 files already formatted.
• .venv\Scripts\python.exe -m mypy app\mcp_work_proof.py -> success.
• .venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.
• git merge-tree --write-tree origin/main HEAD -> clean tree 5816f1160bb4f12e89cd5be8c43e790c1b4656fe.

Scope remains the same: focused work-proof guidance maintainability cleanup only.

[mauricemohr88-debug]

Current-head review for #838 on 549195d56c3f61c70e28410fb47155648a97530d.

Evidence checked:

• Inspected app/mcp_work_proof.py; _effective_awards_remaining_from_payload() centralizes the effective-awards fallback and is reused by text guidance, submission availability, and structured JSON guidance.
• Verified the helper preserves the previous fallback behavior when effective_awards_remaining is absent, while JSON warnings and JSON output now use the same computed effective award count.
• Inspected tests/test_mcp_work_proof.py; the added assertion locks the visible text guidance output for effectively remaining: 6.
• Confirmed GitHub reports PR #948 open, current head 549195d56c3f61c70e28410fb47155648a97530d, merge state clean, and both visible checks successful.
• Confirmed the existing human review/claim for #948 was on older head da4056f558a063a12ee428606a92ed19b523ac3a; I found no current-head human review or current-head #838 claim before posting.
• Ran uv run --python 3.12 --extra dev python -m pytest tests/test_mcp_work_proof.py -q: 8 passed.
• Ran uv run --python 3.12 --extra dev ruff check app/mcp_work_proof.py tests/test_mcp_work_proof.py: passed.
• Ran uv run --python 3.12 --extra dev ruff format --check app/mcp_work_proof.py tests/test_mcp_work_proof.py: 2 files already formatted.
• Ran uv run --python 3.12 --extra dev mypy app/mcp_work_proof.py: success.
• Ran uv run --python 3.12 --extra dev python scripts/docs_smoke.py: docs smoke ok.
• Ran git diff --check origin/main...HEAD and git merge-tree --write-tree origin/main HEAD: clean.

No blocker found. The change is narrow, test-backed, and keeps the work-proof guidance paths aligned around one effective-awards calculation without changing ledger, treasury, payout, wallet, or API contract behavior.

[alan747271363-art]

Closing this because bounty #846 was filled and closed before my claim was posted, so this PR is no longer a good fit for a monetizable #846 submission. The branch remains available if maintainers later want the tiny cleanup separately.