Plan Review Rerun CLI Drift And Git Contention

Plan Review Rerun: CLI Drift + Governance Hygiene + Git Contention

Use this when hardening a status:plan-review issue through repeated adversarial review waves, especially when provider dispatch partially fails or another agent/process is actively using git.

Trigger conditions

• A plan has old review waves (r2, r3, etc.) and new review findings against newer text.
• Provider fanout returns UNAVAILABLE due CLI syntax drift, not a substantive review.
• A fresh review identifies stale plan metadata, stale issue-status claims, or stale approval-artifact wording.
• git add, git status, git commit, or git push are blocked by active pre-push/git processes or .git/index.lock.

Workflow

1. Revalidate live state before editing.

   • gh issue view <issue> --json labels,state,comments,url
   • Read the plan header, ## Adversarial Review Summary, and docs/plans/README.md row.
   • Check local approval marker only after live labels: .planning/plan-approved/<issue>.md.

2. Treat provider wrapper failure as a tool problem, not review signal.

   • Current Codex CLI may reject codex exec --no-interactive with rc=2.
   • If plan-review-fanout.sh emits UNAVAILABLE (codex CLI failed ... unexpected argument '--no-interactive'), rerun Codex without --no-interactive or record Codex as unavailable.
   • Do not count an UNAVAILABLE artifact as approval.

3. Patch the actual plan blockers from substantive providers.

   • Example: if Gemini says tests install a dependency directly and bypass pyproject.toml, change the plan to reinstall from project metadata (uv pip install --python <venv>/bin/python -e .) rather than pip install package.
   • If adding a dependency absent from uv.lock, prefer bare uv lock plus diff inspection over uv lock --upgrade-package <pkg>.
   • If TDD-red tests might fail at collection time, require imports inside test functions so each intended test fails for the expected reason.
   • If a plan requires creating a follow-up issue, include that GitHub action in the explicit scope boundary.
   • For TOML/structured config edits, require TOML-aware edits or exact existing-array patches that preserve syntax.

4. Patch governance hygiene in the same pass.

   • Header status/revision should match current reality (draft v4, plan-review, etc.).
   • Evidence should state the current live issue label, not historical status:plan-approved drift after rollback.
   • Acceptance criteria should require fresh current-draft review artifacts, not stale -r3.md or old self-review artifacts.
   • Risks should explain any earlier approval drift as resolved if the issue is now correctly back in status:plan-review.

5. Re-review narrowly before broader rerun.

   • Use a delegated or independent reviewer for a fast governance-hygiene review after patches.
   • Ask specifically about stale status, stale review-artifact references, command-policy drift, and scope contradictions.
   • Keep the issue not approval-ready unless a fresh current-draft substantive review has no MAJOR findings.

6. Avoid git contention.

   • If git add/status fails with .git/index.lock, check ps -ef | grep '[g]it' before removing locks.
   • If an active git remote-https, pre-push hook, or quality gate is running, do not kill it just to land planning edits unless explicitly authorized.
   • Post a progress comment with exact local artifacts prepared for commit and leave the worktree for the active writer to clear.
   • Only remove .git/index.lock when no real git process is running.

7. Recover when the terminal/fanout path itself is unstable.

   • If the terminal tool fails before running commands (for example FileNotFoundError: [Errno 2] No such file or directory: '%s'), switch to execute_code with subprocess.run(..., cwd='<repo>') for git, gh, and review commands rather than abandoning the gate.
   • If a combined fanout command times out, rerun providers one at a time (for example --providers=codex then --providers=Codex) and read the regenerated provider artifacts directly.
   • If ad-hoc provider CLI reruns stall with empty stdout/logs, do not wait indefinitely: poll once or twice, kill the stuck process, preserve any successful provider output, and record the stalled provider as infrastructure/tooling state rather than substantive review signal.
   • For non-interactive reruns, prefer an explicit prompt file plus the provider's documented stdin mode. Avoid shell patterns that confuse the wrapper into waiting for stdin (for example a positional prompt while stdin is still open, or giant command substitutions that bypass expected file input). If a wrapper prints "Reading additional input from stdin..." or "no stdin data received" and then hangs, relaunch with corrected stdin handling or mark unavailable.
   • Treat review artifacts as stale unless they were generated after the latest plan commit or patch. A MAJOR artifact that predates the final patch is diagnostic input, not current gate evidence.
   • When a provider rerun downgrades to MINOR with an empty Blockers list, patch only governance/clarity minors that materially affect implementability before the final gate; do not churn the plan for cosmetic findings.
   • Before citing review artifacts in a committed plan, verify the artifact path is trackable in the target repo. If scripts/review/results/ is ignored, either use an already-tracked review-artifact location such as docs/reports/ or explicitly force-add only when repo policy allows it; do not cite ignored local-only files as durable approval evidence.

GitHub progress comment template

#<issue> plan-redraft/re-review progress update.

Review results:
- Codex: UNAVAILABLE because <tool failure>. No substantive signal.
- Gemini/other: <VERDICT> with blockers: ...

Plan patches applied locally:
- ...

Follow-up review:
- <reviewer> returned <VERDICT> for governance hygiene.

Current landing status:
- Local files are patched, but not committed/pushed because <active git/pre-push process>. Avoiding git contention.

Local artifacts prepared for commit once git clears:
- <paths>

Pitfalls

• Do not downgrade a plan to approved just because a prior self-review returned APPROVE; stale self-review artifacts do not satisfy a fresh current-draft review requirement.
• Do not let UNAVAILABLE Codex/Gemini artifacts hide the need for real cross-provider review.
• Do not run direct pip install <missing-dep> as the green proof for a dependency-declaration fix; it can bypass the project metadata and mask the core bug.
• Do not force-remove .git/index.lock while another agent's pre-push hook or git process is still active.