plan-review-queue-governance-cleanup

# Plan-Review Queue Governance Cleanup

Use when a repo has many open GitHub issues labeled `status:plan-review` and you need to determine which are:
- real plan-review items
- mislabeled missing-plan drift
- reviewed but blocked by fresh MAJOR findings
- plausible approval-track items

## Why this exists

A live `status:plan-review` label alone is not trustworthy. In practice, queues drift in two common ways:
1. issues get labeled `status:plan-review` before a canonical `docs/plans/` artifact exists
2. fresh adversarial review returns MAJOR, but the blocker evidence only exists in chat/logs and never becomes a durable repo artifact + GitHub comment

This skill keeps the queue operationally honest.

## Required evidence surfaces

For each issue, audit all of:
1. live GitHub labels/state
2. canonical local plan file under `docs/plans/*issue-<N>-*.md`
3. local review artifacts under `scripts/review/results/*-plan-<N>-*.md`
4. local approval marker `.planning/plan-approved/<N>.md` if relevant

## Classification

### A. Missing-plan drift
Criteria:
- issue still labeled `status:plan-review`
- no canonical `docs/plans/*issue-<N>-*.md`
- usually no plan-review artifacts either

Action sequence:
1. Post a short governance comment explaining the issue is mislabeled as `status:plan-review` without a canonical local plan artifact.
2. Remove the stale `status:plan-review` label.
3. Do not present the issue as pending approval or pending provider review.
4. Re-enter it into the queue only after a real canonical plan is drafted and review artifacts exist.

## B. Real plan file exists, but fresh review is blocking
Criteria:
- canonical plan file exists
- fresh review returns `MAJOR`
- issue is still being treated as approval-track or under-reviewed

Action sequence:
1. Save a durable repo artifact summarizing the fresh review under:
   `scripts/review/results/YYYY-MM-DD-plan-<issue>-<reviewer>.md`
2. Post a concise GitHub issue comment with:
   - verdict
   - top blockers
   - explicit statement: not approval-ready
   - required next step: revise plan, rerun adversarial review
3. Keep the issue out of approval-ready discussion until the plan is revised.

## C. Review-complete / possible approval-track
Criteria:
- canonical plan exists
- durable review artifacts exist
- no fresh unresolved MAJOR blocker in the latest review wave

Action:
- surface separately as the shortlist for user attention
- still verify latest review verdicts before calling anything approval-ready

## Durable-artifact rule for delegated/Hermes reviews

This is the key live-use lesson.

If you use `delegate_task` or Hermes subagents to review a plan:
- the chat/subagent output is **not** itself a canonical review artifact
- you must materialize a durable summary file in `scripts/review/results/`
- you should also post a concise GitHub issue comment in the same pass

Otherwise later queue audits will miss the blocker evidence because it only lived in chat history.

Recommended naming:
- `scripts/review/results/YYYY-MM-DD-plan-<issue>-hermes-parallel.md`
- or another reviewer suffix that truthfully identifies the source

## GitHub comment safety

When posting governance comments or review summaries, use `gh issue comment --body-file ...`.
Do not inline markdown-heavy comments with `--body`.

## Minimal execution pattern

1. Enumerate open `status:plan-review` issues.
2. For each issue, check plan-file existence and review-artifact existence.
3. Split into buckets:
   - missing-plan drift
   - fresh-MAJOR blocked
   - review-complete / shortlist
4. For missing-plan drift:
   - post governance comment
   - remove stale label
5. For fresh-MAJOR blocked:
   - save durable local review artifact
   - post concise blocker summary comment
6. Recompute the queue and only then present the cleaned shortlist to the user.

## Output format to user

Give counts first, then grouped issue lists:
1. removed from queue as drift
2. blocked by MAJOR findings
3. remaining review-complete shortlist

This makes the next action obvious and avoids mixing governance cleanup with approval decisions.