Add proposed-work queue fallback report

[Difficult-Burger]

Summary

Bounty #647
Source issue: #684

This PR adds a read-only proposed-work intake report so maintainer triage can include CLI/API-created proposed-work issues that did not receive the proposed-work label.

• Adds scripts/proposed_work_queue.py with JSON, text, and Markdown output.
• Includes labeled proposed-work issues and unlabeled issues whose title starts with Proposed work: and whose body contains the expected proposed-work sections.
• Flags missing labels and missing required sections without mutating GitHub issues.
• Uses a fail-closed gh read guard: only gh issue list/view are allowed, and gh api requires explicit GET/HEAD.
• Tests both read-only gh api --method GET/HEAD allowlist paths and mutating-command rejection paths.
• Fails fast when live issue collection hits the safety cap instead of silently trusting a truncated report.
• Documents Markdown/text/JSON output and offline --input fixture usage in docs/admin-runbook.md.

Verification

• PATH=/Users/a30706/miniconda3/envs/dollar-hunt-mergework/bin:$PATH python -m pytest tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -q -> 40 passed
• PATH=/Users/a30706/miniconda3/envs/dollar-hunt-mergework/bin:$PATH python -m ruff check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> All checks passed
• PATH=/Users/a30706/miniconda3/envs/dollar-hunt-mergework/bin:$PATH python -m ruff format --check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> 2 files already formatted
• PATH=/Users/a30706/miniconda3/envs/dollar-hunt-mergework/bin:$PATH python scripts/docs_smoke.py -> docs smoke ok
• git diff --check -> passed
• Hosted GitHub check Quality, readiness, docs, and image checks passed on previous head b97f4e9199c0ac9209f72cc038be3feae9d098f8; current head 5f108a17466721f5d7a15cfc5e06be6d7ad5ab9f is rerunning checks.
• Live read-only smoke on the earlier head: python scripts/proposed_work_queue.py --repo ramimbo/mergework --format json detected Proposed work: expose public deployment revision metadata for API and MCP #718 as title_body_fallback with missing_proposed_work_label, while Proposed work: filter treasury proposals by payout recipient #680/Proposed work: handle unlabeled proposed-work intake from CLI submissions #684 remained label_and_template.

Review follow-up

Addressed CodeRabbit's actionable comments:

• documented text/JSON output and offline --input fixture mode;
• hardened _run_gh_json() so future changes cannot accidentally run mutating gh issue or implicit-POST gh api -f/-F commands;
• added positive allowlist coverage for explicit gh api --method GET/HEAD;
• added a safety-cap boundary test for live issue collection.

Duplicate Check

• Open MRWK bounty: 150 MRWK - focused small fixes from confirmed project needs #647 PRs checked before submission; visible source issues covered Proposed work: expose structured submission mode for non-PR bounties #676/Proposed work: expose active-attempt summary on bounty API rows #677/Proposed work: classify pending payout proposals in claim inventory #678/Proposed work: use effective availability in submission quality gate #681/Proposed work: add availability-state breakdown to bounty summary #682/Proposed work: add effective-availability filtering to bounty discovery #683/Proposed work: add absolute proof links to accepted-work APIs #687/Proposed work: add typed OpenAPI response schemas for public MRWK read APIs #688/Proposed work: align generic work-proof JSON availability keys #698, but not Proposed work: handle unlabeled proposed-work intake from CLI submissions #684.
• Proposed work: Add proposed-work intake triage report #672 proposes a broader proposed-work intake report; Proposed work: handle unlabeled proposed-work intake from CLI submissions #684 is the accepted narrower fallback for unlabeled CLI/API-created proposed-work intake.
• This PR implements the narrow Proposed work: handle unlabeled proposed-work intake from CLI submissions #684 slice only.

Out of Scope

• No GitHub label mutation, issue edits, comments, bounty creation, claim acceptance, treasury execution, payout proposals, proof generation, ledger, wallet, balance, bridge, exchange, cash-out, or price behavior changes.
• No private data, credentials, admin token, production mutation, or private deployment reads.

Summary by CodeRabbit

• New Features

  • Added a proposed-work intake reviewer that analyzes queues (fixture or live) and emits text, markdown, or JSON reports showing detected items, missing required sections, and summary metrics.

• Documentation

  • Added runbook guidance on using the proposed-work queue report and its read-only semantics.

• Tests

  • Added end-to-end and safety tests for detection, report formatting, live-loading safeguards, CLI help/smoke, and error conditions.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: e13f1c63-849d-46be-8c10-58cd34ef7b1a

📥 Commits

Reviewing files that changed from the base of the PR and between b079b8a and c163b3b.

📒 Files selected for processing (2)

• scripts/proposed_work_queue.py
• tests/test_proposed_work_queue.py

---

📝 Walkthrough

Walkthrough

Adds a read-only CLI script to analyze GitHub intake issues tagged proposed-work or matching a Proposed work: title template, detect missing required markdown sections, produce text/markdown/JSON reports, support live gh collection with safety checks, and include tests plus an admin runbook entry.

Changes

Proposed-work intake queue analysis

Layer / File(s)	Summary
Data model and issue detection scripts/proposed_work_queue.py (lines 1–27, 30–127), tests/test_proposed_work_queue.py (lines 1–39)	Config constants define label, title regex, timeout, safety cap, and required markdown section groups. ProposedWorkRow dataclass and helpers extract labels/author, normalize headings, identify missing section groups, decide detection mode, and emit per-issue warnings.
Queue analysis engine scripts/proposed_work_queue.py (lines 129–160)	analyze_queue iterates input issues, applies detection logic, excludes non-matching items, records ignored proposed-title cases, sorts results, and computes aggregated metrics (seen, detected, detection-mode breakdowns, missing-label and missing-section counts).
Report formatting scripts/proposed_work_queue.py (lines 162–202), tests/test_proposed_work_queue.py (lines 99–122)	format_text_report renders a plain-text summary and per-issue lines. format_markdown_report emits a markdown report with summary bullets and a table of issues (links, detection, author, warnings, missing sections). Tests verify markdown pasteability and expected summary bullets and identifiers.
Live queue loading with safety guards scripts/proposed_work_queue.py (lines 204–268), tests/test_proposed_work_queue.py (lines 137–177, 179–192, 194–202)	_run_gh_json validates that gh subcommands are read-only (rejects mutation subcommands and non-GET/HEAD API methods), enforces a timeout, and parses JSON output. load_live_queue calls gh issue list with a configured --json field list and open-state filter, enforces a safety cap to avoid truncated results, and returns issues in the analyzer's input shape. Tests assert correct gh invocation and erroring when safety cap is reached or gh is missing.
CLI entry point and main integration scripts/proposed_work_queue.py (lines 270–301), tests/test_proposed_work_queue.py (lines 124–135, 249–271)	_load_input validates fixture JSON structure. main() parses arguments (--input vs --repo, --format), loads fixture or live data, runs analysis, formats output (json/markdown/text), prints to stdout, and returns exit code; module is wired as __main__. Tests verify --help output and that main() reads a fixture and emits expected JSON summary with exit code 0.
Admin documentation docs/admin-runbook.md (lines 274–301)	Adds a "Proposed-Work Queue" subsection documenting usage examples (markdown/text/JSON), inclusion rules (issues with proposed-work label or unlabeled issues whose title starts with Proposed work: and whose body matches the template), the offline --input fixture mode, and explicit non-actions (no labeling, bounties, comments, acceptance, or payouts).

Possibly related issues

• Proposed work: Add proposed-work intake triage report #672: Matches this PR's proposed-work intake script and docs; likely the same intake tooling.
• Proposed work: handle unlabeled proposed-work intake from CLI submissions #684: Aligns with the read-only detection behavior including unlabeled "Proposed work:" title-template fallback implemented here.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title concretely names the main change: a new proposed-work queue fallback report script and documentation.
Description check	✅ Passed	The description covers all required template sections with sufficient detail: summary with bounty/issue refs, evidence of confusion addressed, intended surfaces, test verification, and scope limits.
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	All modified files contain zero investment, price, cash-out, payout, or security claims. New documentation correctly describes the read-only intake review tool.
Bounty Pr Focus	✅ Passed	PR adds focused proposed-work queue: 3 files, read-only design, gh whitelisting, title+body fallback for #684, safety cap, error handling, 10 tests, no mutations.

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

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6f44ee71-203d-4574-b249-22e77fda2de4

📥 Commits

Reviewing files that changed from the base of the PR and between 6cd957c and 6351670.

📒 Files selected for processing (3)

• docs/admin-runbook.md
• scripts/proposed_work_queue.py
• tests/test_proposed_work_queue.py

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 333b59a9-fe85-4e7b-a948-310dc874dde4

📥 Commits

Reviewing files that changed from the base of the PR and between 6351670 and b97f4e9.

📒 Files selected for processing (3)

• docs/admin-runbook.md
• scripts/proposed_work_queue.py
• tests/test_proposed_work_queue.py

[xyjk0511]

Reviewed PR #720 at current head 5f108a17466721f5d7a15cfc5e06be6d7ad5ab9f.

No blocker found for the proposed-work queue fallback report.

What I checked:

• The new report includes both labeled proposed-work issues and unlabeled issues that match the Proposed work: title plus required template sections, which covers the #684 CLI/API label-loss case without mutating GitHub state.
• _run_gh_json() is fail-closed for issue commands (list/view only) and only allows gh api with explicit GET/HEAD; tests cover rejection of mutating issue/api paths and the positive GET/HEAD allowlist.
• The live loader fails when the safety cap is reached instead of silently trusting a truncated queue.
• Markdown/text/JSON output and offline fixture mode are documented in the admin runbook.
• The change is read-only reporting/docs/tests only; it does not label issues, create bounties, post comments, accept work, trigger treasury proposals, or touch payout/proof/wallet behavior.

Validation I ran locally from PR head:

• uv run --python 3.12 --with pytest pytest tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -q -> 40 passed.
• uvx ruff check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> passed.
• uvx ruff format --check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> 2 files already formatted.
• .\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.
• uv run --python 3.12 python scripts/proposed_work_queue.py --repo ramimbo/mergework --format json -> completed read-only live report and returned proposed-work rows including labeled/template detections.

No private data, credentials, wallet material, production mutation, price/exchange/bridge/off-ramp claims, or fabricated payout claims used.

[JONASXZB]

Reviewed current head 5f108a17466721f5d7a15cfc5e06be6d7ad5ab9f.

I found one live-mode CLI blocker before this report should be considered ready: --repo mode still raises a raw FileNotFoundError traceback when the GitHub CLI is not installed.

Evidence checked:

• inspected scripts/proposed_work_queue.py and tests/test_proposed_work_queue.py;
• confirmed _run_gh_json() has read-only command guards, timeout handling, and CalledProcessError handling, but does not catch FileNotFoundError from subprocess.run();
• reproduced from a fresh worktree in this environment, where gh is absent:

/Users/jonas/Downloads/microfix-leads/mergework/.venv/bin/python scripts/proposed_work_queue.py --repo ramimbo/mergework --format json
...
FileNotFoundError: [Errno 2] No such file or directory: 'gh'

The PR documents live --repo usage in the admin runbook, so the command should fail with a concise actionable message such as GitHub CLI executable 'gh' was not found; install gh and ensure it is on PATH before using live --repo mode, ideally with a regression test around load_live_queue() or the CLI entrypoint.

Validation run locally:

• /Users/jonas/Downloads/microfix-leads/mergework/.venv/bin/python -m pytest tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -q -> 40 passed
• /Users/jonas/Downloads/microfix-leads/mergework/.venv/bin/ruff check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -> passed
• /Users/jonas/Downloads/microfix-leads/mergework/.venv/bin/ruff format --check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -> 3 files already formatted
• /Users/jonas/Downloads/microfix-leads/mergework/.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• git diff --check origin/main...HEAD -> clean
• git merge-tree --write-tree origin/main HEAD -> clean tree 3aead442a342529eee73477c7d88fcb23b650aeb
• hosted Quality/readiness/docs/image check succeeded; CodeRabbit succeeded/skipped.

[Difficult-Burger]

Addressed the current-head review blocker in b079b8a72d58cff9995b45fa1efc70bb334d2f93.

Change:

• live --repo mode now catches a missing gh executable and raises a concise RuntimeError instead of exposing a raw FileNotFoundError traceback;
• added regression coverage for the missing-GitHub-CLI path.

Verification from isolated dollar-hunt-mergework conda env:

• PYTHONPATH=$PWD conda run -n dollar-hunt-mergework pytest tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -q -> 41 passed
• conda run -n dollar-hunt-mergework ruff check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> passed
• conda run -n dollar-hunt-mergework ruff format --check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py -> 2 files already formatted
• git diff --check -> clean

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

scripts/proposed_work_queue.py (2)

221-222: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Misleading rejection message in the catch-all branch.

This else fires for any gh command that isn't issue or api (e.g. gh pr list, gh repo view), yet the message claims "non-read-only gh issue command", which will mislead anyone debugging the guard.

Proposed fix

     else:
-        raise RuntimeError(f"refusing non-read-only gh issue command: {' '.join(args)}")
+        raise RuntimeError(f"refusing unsupported gh command: {' '.join(args)}")

---

289-289: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

--input "" silently falls through to live mode.

if args.input is falsy for an empty string, so --input "" routes to load_live_queue(args.repo) with args.repo being None, producing a cryptic TypeError inside subprocess.run instead of a clear input error. Guard on presence rather than truthiness.

Proposed fix

-    data = _load_input(args.input) if args.input else load_live_queue(args.repo)
+    data = _load_input(args.input) if args.input is not None else load_live_queue(args.repo)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 56f1fc93-d0c2-4095-8286-58ba87e7e6ec

📥 Commits

Reviewing files that changed from the base of the PR and between 5f108a1 and b079b8a.

📒 Files selected for processing (2)

• scripts/proposed_work_queue.py
• tests/test_proposed_work_queue.py

[Difficult-Burger]

Addressed the CodeRabbit follow-up comments in c163b3b623522c50280fa5c520f82d8a8fa15f59.

Changes:

• unsupported gh subcommands now fail with refusing unsupported gh command instead of the misleading issue-command message;
• --input "" now stays on the fixture-input path (args.input is not None) instead of falling through to live --repo mode;
• added regression tests for both cases.

Verification from isolated dollar-hunt-mergework conda env:

• PYTHONPATH=$PWD conda run -n dollar-hunt-mergework pytest tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -q -> 42 passed
• PYTHONPATH=$PWD conda run -n dollar-hunt-mergework ruff check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -> passed
• PYTHONPATH=$PWD conda run -n dollar-hunt-mergework ruff format --check scripts/proposed_work_queue.py tests/test_proposed_work_queue.py tests/test_docs_public_urls.py -> 3 files already formatted
• git diff --check -> clean

Hosted Quality/readiness/docs/image checks and CodeRabbit are green on the current head.

[prettyboyvic]

Reviewed current head c163b3b623522c50280fa5c520f82d8a8fa15f59 as a non-author.

Evidence inspected:

• scripts/proposed_work_queue.py: checked proposed-work detection for labeled issues and unlabeled Proposed work: title/body fallback, required-section normalization, read-only gh issue / explicit GET/HEAD gh api guardrails, missing-gh wrapping, timeout/error handling, and the live issue-list safety cap.
• tests/test_proposed_work_queue.py: verified coverage for fallback detection, missing-section warnings, markdown output, fixture input mode, read-only command allowlist/rejections, missing gh, and safety-cap failure.
• docs/admin-runbook.md: verified usage docs for live --repo, offline --input, text/JSON/Markdown output, and explicit read-only semantics.

Validation run locally on the PR worktree:

• git diff --check origin/main...HEAD -> clean.
• git merge-tree --write-tree origin/main HEAD -> 7a42977f58ff1471e12ee7b2d3cb7c1696812284.
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ..\mergework\.venv\Scripts\python.exe -m pytest tests\test_proposed_work_queue.py tests\test_docs_public_urls.py -q -> 42 passed.
• ..\mergework\.venv\Scripts\python.exe -m ruff check scripts\proposed_work_queue.py tests\test_proposed_work_queue.py -> passed.
• ..\mergework\.venv\Scripts\python.exe -m ruff format --check scripts\proposed_work_queue.py tests\test_proposed_work_queue.py -> 2 files already formatted.
• ..\mergework\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• ..\mergework\.venv\Scripts\python.exe scripts\proposed_work_queue.py --repo ramimbo/mergework --format json -> live read-only smoke succeeded, saw 43 open issues and 31 proposed-work rows.
• Hosted GitHub checks are green: Quality/readiness/docs/image passed; CodeRabbit passed/skipped.

No blocking issues found. The PR stays read-only, keeps the #684 scope narrow, and current-head follow-up addresses the earlier missing-gh raw traceback concern with a concise actionable error.