feat: revalidate live GitHub blockers without unblocking items

[unbraind]

Blocked pm items retain static GitHub blocker text after an upstream issue closes. The motivating pm-rl records stayed blocked for 27 days after unbraind/pm-cli#854 closed on 2026-08-01. This adds pm github blockers to surface those stale blockers without changing item status.

The command certifies the complete SDK read, selects blocked items and non-terminal items with external GitHub blocked_by dependencies, deduplicates references from dependency targets/reason/description/comments, and queries live issue/PR state in GraphQL batches of 25 using the existing auth and rate-limit client. Reports use the host TOON/JSON renderer. Exit 4 alerts on clearance or partial clearance; query or annotation failures take precedence with exit 1. Optional comments group newly cleared reference states once per fully cleared item, with per-reference state/timestamp markers under a lock. The reusable sync warns on exit 4, writes no comments, and stops on failures. README documents examples and the required PM CLI 2026.10.5 compatibility floor.

Before: a closed GitHub blocker leaves a static blocked item with no live-state receipt. After: a report identifies its current state, reason, date and verdict for human revalidation; status remains blocked. Private/missing GitHub references can both appear as not_found, and unknown references never clear an item.

Validation uses real scratch trackers and recorded public GitHub GraphQL responses, recaptured with the query builder. Permission denials are explicitly constructed around recorded data; no private-resource fixture is published. Behavioural revert proof disabled only the parser body, then only the verdict body in separate isolated copies: each made its unit regression and the real-tracker mixed scenario fail, 0/2 passing per revert, exit 1. The production source stayed intact. A final-head CodeQL alert identified polynomial marker matching; the matcher now uses repository grammar and cannot span HTML delimiters. Restoring only the old regex makes its bounded performance regression time out (0/1 pass); the fixed regression completes promptly. Provenance hints are validated before GraphQL, and reference handling covers .github-style repo names, HTTP/case variants and unresolved-form deduplication. Both complete gates were rerun after these corrections.

Gate	Result
npm run release:check, isolated HOME/Git identity	553/553; zero fail/skip/cancel/todo
bun run release:check, isolated HOME/Git identity	553/553; zero fail/skip/cancel/todo
All authored-source coverage, unchanged thresholds	12 modules; exact 100% lines/statements/branches/functions
pm-linked blocker suite	32/32
pm-linked scheduled report acceptance	1/1
Installed packed artifact, Node + native Bun, live GitHub	2/2; one grouped scratch comment; repeat skipped; status remained blocked

Both release gates also passed typecheck/build, docstrings, lint, zero duplication, privacy, audit, pack dry-run, changelog and attestation checks. The required identity-isolated npm command used env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1. Source checksums stayed unchanged across both release runs. Scratch workflow fixtures isolate unrelated global extensions so host/SDK skew cannot contaminate health checks.

Read-only fleet acceptance: pm-rl read 78 items with zero candidates (both historical motivating items are now closed); the companion read 937 items with six candidates, two cleared and four unresolvable. Item/history/settings bytes stayed unchanged. --comment was used only on scratch trackers. No merge, release, tag or publication is requested; callers must pin a release containing this command before adopting the updated reusable workflow.

Owner item: pm-github-fmrf (proposed). Companion context: pm-cli-website-5o9j. The owner item remains in_progress and its claim was released for orchestrator verification.

Summary by Sourcery

Add report-only GitHub blocker revalidation so stale blocked items can be identified for human follow-up without automatically changing their status.

New Features:

• Add pm github blockers to report the live state of GitHub issue and pull-request blockers without changing item status.
• Support optional idempotent comments that notify users when blockers are fully cleared.
• Integrate report-only blocker revalidation into the scheduled GitHub sync workflow with warning-based clearance alerts.

Bug Fixes:

• Surface stale blocker references after their upstream GitHub issues or pull requests close or merge.

Enhancements:

• Require PM CLI 2026.10.5 or newer for complete reads and structured exit statuses.
• Resolve and deduplicate GitHub references across blocker fields, dependencies, descriptions, and comments, including repository provenance hints.
• Provide verdicts, live state metadata, failure handling, and exit-code semantics for cleared, partially cleared, still-blocked, and unresolvable items.

Build:

• Update package and lockfile compatibility requirements to PM CLI 2026.10.5.

CI:

• Extend workflow and acceptance coverage for scheduled blocker reports, clearance warnings, query failures, and workspace isolation.

Documentation:

• Document blocker revalidation usage, output verdicts, exit codes, comment behavior, and compatibility requirements in the README.

Tests:

• Add comprehensive parser, candidate-selection, GraphQL batching, verdict, comment-idempotency, failure-path, renderer, and real-tracker acceptance tests using recorded GitHub responses.

Chores:

• Add PM feature metadata and history for blocker revalidation.

[sourcery-ai]

Sorry @unbraind, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 19 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 92e33f5c-a8d8-4b12-9f4f-b8c4f155c3c7

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

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

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.