| name | plan-review-approval-shortlist-audit |
| description | Audit a status:plan-review queue to identify true approval candidates without being fooled by stale labels, conditional review summaries, or unresolved prerequisite blockers. |
| version | 1.0.0 |
| author | Hermes Agent |
| category | coordination |
| tags | ["github","planning","queue-triage","approval-readiness","governance"] |
Plan-Review Approval Shortlist Audit
Use when the user asks which status:plan-review issues are actually ready, closest to ready, or should be surfaced for approval next.
Why this exists
A naive queue sweep will misclassify issues if it relies only on:
- the presence of a
status:plan-review label
- the newest review artifact filename
- a single overnight
MINOR or approval-ready (conditional) summary
In practice, the real blocker state often lives across several surfaces at once.
Required audit surfaces
For each candidate issue, check all of these:
- Live GitHub issue state
- current
status:* labels
- issue still open
- recent comments for rollback notes, blocker updates, or recommendation caveats
- Canonical local plan state
docs/plans/YYYY-MM-DD-issue-NNN-*.mddocs/plans/README.md row status
- Review evidence
- latest canonical artifact under
scripts/review/results/*-plan-NNN-*.md
- whether the artifact is real provider review vs placeholder/fallback
- whether a newer GitHub comment sharpens or contradicts the artifact conclusion
- Approval evidence
.planning/plan-approved/NNN.md- absence of this marker means the item is still only a recommendation candidate, not approved
- First verify that the checkout used for marker inspection is not stale or behind the target branch. If the active worktree is behind
origin/main, either fast-forward/use a fresh worktree or inspect the committed remote tree directly (for example git ls-tree -r --name-only origin/main -- .planning/plan-approved/NNN.md) before reporting the marker as missing. Stale governance worktrees can otherwise misclassify truly committed approval markers.
- Explicit prerequisites
- machine constraints (
machine:* labels)
- blocked-on-other-issue or blocked-on-artifact conditions
- prerequisites documented in comments or review artifacts (e.g. unreadable source PDFs, missing summaries, provider rerun still required)
Classification buckets
A. Clean approval candidate
Use only when:
- canonical plan exists
- review coverage is present and recent
- no fresher comment says
needs-revision / not ready for user approval
- no unresolved prerequisite blocker is still active
- issue is still in
status:plan-review
- no local approval marker yet
B. Best available approval candidate with caveat
Use when:
- item is stronger than the rest of the queue
- latest review is
MINOR or approval-ready (conditional)
- but a residual condition still exists (for example specific machine requirement)
State the caveat explicitly. Do not silently upgrade to “cleanly approval-ready.”
C. Needs revision
Use when:
- latest or recent review/comments still record
MAJOR, needs-revision, or unresolved review findings
- approval-readiness depends on provider reruns that have not happened yet
- plan quality may be high, but the review/governance standard has not yet been met
D. Governance drift / not actually in plan review
Use when:
- live
status:plan-review exists but there is no canonical plan file
- or there are no review artifacts yet
- or the queue state implies a maturity level the artifacts do not support
Decision rules
MINOR or approval-ready (conditional) is not enough by itself.- Recent issue comments can overrule simplistic artifact parsing if they document fresher blocker state.
- A best-in-queue recommendation is not the same as certifying all blockers are gone.
- Never describe an item as already approved unless both live state and local approval evidence support that claim.
Output format
For a shortlist, return:
- Approve now
- issue number + title
- why it is the strongest candidate
- residual caveat, if any
- Keep in revision lane
- issue number + title
- 3-6 bullet punch-list of remaining blockers
- Optional queue note
- whether the queue still contains governance drift items that should be cleaned before more approval triage
Practical pattern
If you need a fast but trustworthy pass:
- enumerate live
status:plan-review issues
- separate missing-plan / missing-review drift first
- inspect latest review artifacts for the remaining set
- inspect recent GitHub comments for contradiction or conditionality
- verify no local approval marker exists
- produce a small shortlist with caveats instead of overclaiming certainty
