overnight-verify-close-and-blocker-conversion

# Overnight verify-close and blocker conversion

## When to use

Use this in workspace-hub-style overnight batches when:
- several approved GitHub issues look suspiciously like they are already done
- issue comments mention landed commits, review artifacts, or approved revision passes
- you want backlog reduction without risky duplicate implementation
- a repair lane for a specific PR may actually be blocked by repo-wide CI drift

## Core idea

Do not default to implementation just because an issue is open.
For stale-open approved issues, assign **verification-first closeout lanes**.
For blocked PR repair, if the true root cause is outside the lane's owned paths, stop and create a dedicated blocker issue the same night.

## Part 1: verification-first closeout lanes

Create one lane per issue.
Each lane should have write ownership only over:
- one result artifact, e.g. `.nightly-results/<date>-issue-<n>.md`
- the GitHub comment/close actions for that issue

### Required verification sequence

1. `git fetch origin --quiet`
2. identify the candidate landing commit from issue comments or recent history
3. prove the commit is on `origin/main`
   - prefer `git merge-base --is-ancestor <commit> origin/main`
   - `git branch -r --contains <commit>` can be a secondary check only
4. verify expected artifacts exist on `origin/main`
   - use `git ls-tree`, direct file reads, or current checkout inspection after sync
5. map acceptance criteria to concrete evidence
   - for design/governance/doc issues, deterministic section/path inspection is often the right validator
   - do not force a runtime test if the deliverable is a document contract or review package
6. if auto-sync / merge-race risk exists, verify **content parity**, not just history containment
   - compare the landed commit's artifact content against `origin/main`
   - example: `git diff <candidate-commit> origin/main -- <artifact-path>` should be empty or have an explicitly explained delta
7. write the evidence report artifact
8. post the closeout comment first
9. close the issue second, in a separate command

### Why comment first

`gh issue close --comment` can be fragile in races or on already-closed issues.
Posting the evidence comment first makes the proof durable even if the close step races or becomes redundant.

### Stronger verification rules learned in practice

Use both of these before closing a stale-open issue:
- **history containment**: `git merge-base --is-ancestor <commit> origin/main`
- **content parity**: `git diff <candidate-commit> origin/main -- <artifact-path>` should be empty unless you can explain the delta

Reason:
- history containment alone does not prove the intended artifact content survived a merge race or later overwrite
- in auto-sync / concurrent-writer repos, the same issue can need both ancestry proof and artifact parity proof before "already done" is defensible

Operational note:
- leave the `status:plan-approved` label alone on a now-closed issue unless there is a separate governance reason to clean it up; that label is evidence of planning state, not an error by itself

### Good fit

This pattern worked well for stale-open issues where:
- revision/implementation commits were already on `origin/main`
- review artifacts and approval markers existed
- the issue simply had never been formally closed

## Part 2: blocked PR-repair lane -> blocker issue conversion

If a lane intended to repair a branch or PR discovers that the actual failure is due to repo-wide CI/governance drift outside the lane's owned paths, do not guess, broaden scope, or patch unrelated files.

### Required diagnosis output

Produce a blocker report containing:
- the failing workflow/check names
- exact missing/referenced files or scripts
- commit/history evidence showing when the breakage was introduced
- why the failure is repo-wide rather than branch-specific
- what could not be verified because of session capability limits

### Then immediately create or attach to a blocker issue

First check whether the blocker class is already tracked.
If an existing open issue already matches the exact blocker class, add fresh evidence there instead of opening a duplicate.
Only create a new blocker issue when no suitable existing tracker exists.

Examples from live use:
- create a new blocker issue when a PR-repair lane discovers a previously untracked repo-wide CI/workflow drift
- attach fresh evidence to an existing blocker issue when a local-ready implementation lane is blocked by a known pre-push / worktree / hook-coupling problem already under active tracking

This keeps overnight batches from creating duplicate blocker tickets while still preserving the new evidence.

### Also update the blocked issue

Post a comment on the originally targeted issue explaining:
- the blocker issue number
- that the branch was not changed because the failure is upstream/repo-wide
- the next correct sequence:
  1. fix blocker issue
  2. rerun/rebase blocked PR
  3. reassess remaining branch-specific failures

## Practical batch pattern

A high-yield overnight mix is:
- 2-3 verify-close lanes for stale-open approved issues
- 1 bounded branch-repair lane
- 1 true implementation lane

This gives you:
- backlog reduction from issue closure
- dependency clarification from blocker conversion
- one or more genuine code-execution lanes still making forward progress

## Pitfalls

- Do not treat commit containment alone as proof of completion when merge-race workflows exist.
- Do not keep a blocked PR-repair lane running after proving the root cause is repo-wide.
- Do not silently absorb a CI workflow fix into a feature-branch repair lane unless that workflow path is explicitly owned.
- Do not close a stale-open issue without explicit acceptance-criteria mapping and at least one concrete proof artifact.

## Reusable outcome

This pattern turned one overnight batch into:
- multiple stale-open issue closures with proof-rich comments
- one blocked PR lane converted into a newly tracked CI blocker issue
- clearer priority focus on the remaining true implementation lane