Preserved Plan Refile With Attested Review Wave

Preserved Plan Re-file With Attested Review Wave

Use when:

• an issue was previously closed or rolled back
• the repo still has a preserved docs/plans/... artifact
• #2405-style attested review infrastructure is available
• you need to reopen/re-file the issue without pretending the old plan is still valid

Why this exists

A preserved plan that survived a closed issue often contains stale workflow state, stale review-history claims, and assumptions that were never revalidated against live repo state. Simply reopening the issue and relabeling it wastes cycles. The reliable path is:

1. convert the plan back to draft
2. reopen the issue with a governance comment
3. run fresh attested adversarial review
4. tighten only the still-live blockers
5. do not advance to status:plan-review until reviewers stop returning MAJOR

Workflow

1. Verify live state first

Always check before editing:

• gh issue view <n> --json state,labels,title
• required healthcheck / test command for the infrastructure you rely on
• current origin/main tip
• existence of the preserved plan file

If the issue is closed, do not keep plan-review wording in the plan header.

2. Rewrite the preserved plan into a conservative draft

Update the plan file to:

• set Status: draft
• clearly mark it as a re-file draft, not approval-ready
• remove stale review-artifact claims unless the files still exist
• distinguish:
  • required inputs
  • optional/reporting-only inputs
  • degraded/fail-closed behavior
• make identity and matching contracts explicit
• make scheduler/publication behavior explicit if the plan mentions automation

Important: if a reviewer found a contradiction, rewrite the contract itself — do not just add commentary around the contradiction.

3. Reopen the issue with a scoped governance comment

Use gh issue reopen <n> -c "..." and explain:

• why the issue is being reopened
• that the plan is now back in draft/revision mode
• that fresh adversarial review follows

Do not add status:plan-review yet.

4. Run fresh attested adversarial review immediately

Use the standard adversarial prompt with the attestation-aware clause. Save canonical artifacts under scripts/review/results/.

Recommended naming:

• YYYY-MM-DD-vN-plan-<issue>-codex.md
• YYYY-MM-DD-vN-plan-<issue>-gemini.md

5. Tighten by converging on live blocker themes

After each wave, summarize the remaining blockers into a short list and edit only those.

Common blocker buckets seen in preserved-plan refiles:

• stale workflow state (closed issue but plan claims plan-review)
• missing or stale review artifact references
• undefined identity/matching contract
• undefined degraded-vs-fail-closed behavior
• scheduler/publishing semantics not specified tightly enough
• duplicate/deduplication behavior undefined
• output schema mismatches across plan sections
• source-surface deduplication missing for multi-inventory detectors (index.jsonl + ledgers/manifests + registries)
• cross-domain coverage semantics left implicit (doc_key match in wrong wiki/domain should not silently count as covered)
• exit-code contract missing even though the plan talks about dry-run, degraded runs, or scheduled publication
• publication mode ambiguous (CLI flag vs config-driven mode), which lets reviewers reject the plan for mismatched runtime vs scheduler behavior
• locking specified at two layers (shell + Python) without one authoritative owner, creating deadlock/ambiguity risk
• heterogeneous source schemas described with vague phrases like "field or equivalent" instead of concrete field names + fallback order

6. Keep GitHub and repo state aligned

After each major revision wave:

• post a short GitHub comment summarizing new artifacts and remaining blockers
• update docs/plans/README.md to reflect draft / re-file-in-progress state
• do not label status:plan-review while reviews are still MAJOR

7. Commit docs-only progress incrementally

Safe commit pattern:

• plan draft rewrite + first review wave
• later revision-wave tightening + new review artifacts

This preserves the tightening history and avoids losing learning between waves.

Operational rules

• A preserved plan is not approval-ready just because it already exists.
• Fresh MAJOR review evidence outranks older optimistic review history.
• Remove unverified or irrelevant live-state claims unless attestation covers them.
• If a blocker list narrows, keep the issue open and still in draft; do not prematurely advance labels.
• Approval readiness requires both plan quality and governance-state cleanliness.

Suggested commit messages

• docs(plans): reopen #NNNN with v4 review wave
• docs(plans): continue #NNNN adversarial revision wave
• docs(plans): tighten #NNNN review contracts

Exit condition

The issue is ready to move to status:plan-review only when:

• the plan header/readme row say draft -> plan-review consistently
• latest external review wave is no worse than MINOR
• GitHub comment history links the current canonical review artifacts
• no stale closed-issue or stale-approval contradictions remain