[OTHER] Retire superseded remote branches after VNext backlog canonicalization

[Joncallim]

Execution mode: implementation
Depends on: none

Issue Type

Repository hygiene / governance

Context

The 2026-09-03 aggressive VNext backlog/branch review has canonicalized useful design work into current main and current GitHub issues. PR #331 is closed/superseded; its valid verification-goal requirements live in #355/#356. The unmerged reviewer-scope branch's useful requirements live in #188/#337/#338. Several other refs are simply leftovers of already-merged PRs.

The connected GitHub surface used for planning cannot delete remote refs directly, so cleanup must be executed by a repository-authorized agent/CLI. Never delete by branch-name pattern alone. Re-read current remote SHA/open-PR/reachability immediately before each deletion batch.

Keep:

• main always;
• audit/vnext-instruction-boundary while PR docs: align repository agent instructions with VNext runtime truth #351 remains open. After docs: align repository agent instructions with VNext runtime truth #351 is explicitly merged/closed by the operator, ordinary merged-branch cleanup may remove it separately.

Desired Outcome

The remote branch list contains no reviewed superseded pre-VNext implementation/review branches. Every deleted ref is either already merged/reachable from main or has a documented supersession handoff preserving its useful requirements. No open PR/current implementation branch is removed, and PR/commit/issue history remains intact.

Tasks

Already-merged leftovers

Delete only after confirming the expected PR/commit is merged/reachable from current main:

• agent/normalize-execution-outcomes — PR feat: add canonical execution outcomes #324 / [FEATURE] Normalize execution outcomes and stop reasons #185 lineage.
• claude/forge-issue-review-arch-37iv2q — PR Add capability reliability ledger (#186) #326.
• codex/issue-187-registry-import-api — PR feat: add authenticated verification goal imports (#187) #329.
• codex/issue-187-verification-goal-registry — PR feat: add verification goal registry foundation (#187) #328.
• docs/forge-vnext-architecture — PR docs: lock Forge VNext general-agent architecture #345 / ADR 0014.

Superseded #187 / PR #331 lineage

PR #331 is closed without merge. Its valid requirements/test ideas are preserved in #187/#355/#356. Delete only after confirming no candidate has gained a new open PR or newer unported commits:

• architecture/issue-187-goal-run-policy-final — former PR feat: implement project verification goals and proof runs (#187) #331 head.
• architecture/issue-187-verification-goal-execution-policy
• architecture/issue-187-verification-goal-execution-policy-r1
• architecture/issue-187-verification-goal-run-policy
• architecture/issue-187-verification-goal-run-policy-v1
• codex/issue-187-goal-definition-v2

These are historical evidence only. New proof-run work starts from current main; never rebase/cherry-pick these branches wholesale.

Superseded reviewer-scope branch

• codex/reviewer-scope-controls — no PR; reviewed requirements are captured in [FEATURE] Add independent Verification Workforce execution #188/[FEATURE] VNext Phase 3 — complete Software Engineering as the first generic Workforce #337/[FEATURE] VNext Phase 4 — declarative Workforce packages and Software Engineering extraction #338 (change-scoped blocking findings, adjacent findings separate, read-only reviewer, bounded rework scope).

Before deletion, confirm its head has not acquired newer unported commits. If changed, stop and open a narrow preservation finding rather than deleting.

Implementation Sequence

1. Fetch immutable current inventory — git fetch --prune/GitHub branch + open-PR APIs; record branch -> current SHA -> open PR -> reachability/disposition table for only the named candidates.
2. Protect live refs — assert main exists/current; assert PR docs: align repository agent instructions with VNext runtime truth #351 head is excluded while PR docs: align repository agent instructions with VNext runtime truth #351 open; detect any new open PR/head created after this issue and exclude it automatically.
3. Merged-ref proof — for each merged candidate verify exact current head commit is an ancestor/reachable from current main and expected PR is merged; if head advanced after merge, stop that branch.
4. Superseded-ref proof — for each [EPIC] Verification goals and proof-run lifecycle #187/reviewer candidate verify no open PR and current head equals/is within reviewed superseded lineage; compare current commits against the relevant closed PR/issue handoff and stop on any unported new commit.
5. Dry-run deletion manifest — print exact candidate name + pre-delete full SHA + disposition + preservation issue/merged PR; require no wildcard/pattern expansion and no unexpected ref.
6. Delete in two batches — already-merged refs first; re-fetch/reconcile; then superseded unmerged refs. Use normal remote ref deletion/API, not force-moving refs.
7. Post-delete reconcile — refetch branch/open-PR state and prove every deleted ref absent, protected/live refs present and no open PR references deleted head.
8. Audit comment — concise exact deleted branch/pre-delete SHA list plus any deliberately skipped candidate/reason. Do not paste local paths/secrets.

Primary Code / Control Seams To Inspect First

This is remote Git governance rather than application code. Inspect:

• GitHub branches API / git ls-remote --heads origin / fetched remote refs;
• GitHub open/merged PR state and head branch mapping;
• current main ancestry via git merge-base --is-ancestor or equivalent exact commit comparison;
• PR feat: implement project verification goals and proof runs (#187) #331 supersession comment/body + [EPIC] Verification goals and proof-run lifecycle #187/[FEATURE] Complete verification-goal on-demand proof execution through VNext #355/[FEATURE] Schedule verification-goal proof runs through generic Triggers #356;
• [FEATURE] Add independent Verification Workforce execution #188/[FEATURE] VNext Phase 3 — complete Software Engineering as the first generic Workforce #337/[FEATURE] VNext Phase 4 — declarative Workforce packages and Software Engineering extraction #338 preservation of reviewer-scope behavior;
• PR docs: align repository agent instructions with VNext runtime truth #351 state/head before every deletion batch.

Do not edit application files merely to perform branch cleanup.

Orthogonal Checkpoints

1. Completeness: compare GitHub API and fetched Git remote inventory; detect refs created/changed since planning.
2. Merged reachability: branch head advanced after merged PR, squash/rebase ancestry edge cases, wrong PR association.
3. Supersession preservation: unmerged commits not represented in canonical issues; reviewer/[EPIC] Verification goals and proof-run lifecycle #187 requirement loss.
4. Open-PR safety: branch becomes PR head between inventory and delete; PR docs: align repository agent instructions with VNext runtime truth #351 state changes; new legitimate branch appears.
5. Destructive command safety: exact branch names quoted; no wildcard/regex; never main; no force-update as substitute for deletion.
6. Race/TOCTOU: re-fetch immediately before each deletion and compare expected SHA; delete only when ref still points to reviewed SHA.
7. Postcondition: only expected refs removed; Git history/PR/issues remain accessible; branch count/list understandable.

Acceptance Criteria

• Every deleted branch matches one explicit candidate name in this issue and still points to the reviewed expected SHA/disposition at deletion time.
• No open PR/current implementation branch is removed.
• main is never force-moved/deleted.
• PR docs: align repository agent instructions with VNext runtime truth #351 head remains while PR docs: align repository agent instructions with VNext runtime truth #351 is open.
• Already-merged branch heads are proven reachable from current main before deletion; advanced heads are skipped.
• Unmerged [EPIC] Verification goals and proof-run lifecycle #187/reviewer branches are deleted only after proving useful requirements are preserved in the named canonical issues and no newer unported commits exist.
• A branch whose SHA changes after dry-run is not deleted without a fresh review.
• Final remote branch inventory contains only main, the live PR docs: align repository agent instructions with VNext runtime truth #351 branch if still open, and any newly created legitimate branches not listed for deletion.
• No open PR references a deleted branch.
• Deletion uses normal remote-ref deletion (git push origin --delete / GitHub ref deletion), never force-moving stale refs onto another commit.
• Exact deleted branch names + pre-delete full SHAs are recorded in the issue; no tags/commits/PR/issue history is deleted.

Out of Scope

• Merging PR docs: align repository agent instructions with VNext runtime truth #351.
• Deleting GitHub PR/issue history.
• Garbage-collecting unreachable Git objects on GitHub.
• Deleting branches created after this issue without a fresh explicit review.
• Any application-code refactor.

Implementation Scope

Small but destructive - one repository-hygiene operation with two deletion batches and mandatory re-fetch/review gates.

Technical Notes

If any candidate fails its expected-state assertion, skip it and report the exact mismatch. Partial safe completion is preferable to deleting a branch whose current meaning changed.

[Joncallim]

Reviewed remote-ref snapshot — 2026-09-03

Live GitHub branch inventory at planning close contained exactly 14 refs: main, PR #351's live head, and the 12 deletion candidates already named in this issue. No unaccounted remote branch was present.

Protected/live — do not delete in this task

• main -> ef51411a9e48d3b6a48bfcd6366c0bdda7c83fd5
• audit/vnext-instruction-boundary -> d1325afee81435ce0bcf44b23fd95930a72c40a0 — current head of open PR docs: align repository agent instructions with VNext runtime truth #351

Already-merged candidate snapshot

• agent/normalize-execution-outcomes -> a9ee4a667e4f2facc62967d4f583a65a2d302434
• claude/forge-issue-review-arch-37iv2q -> e3661e4091e4ef295d0a20144e3b90ddc318fc57
• codex/issue-187-registry-import-api -> 0ed05885a8a79304f8c6ebb2e279eea40ec33c85
• codex/issue-187-verification-goal-registry -> fdc87012b7cec87e8e79ef9f56dd50b3b3754c4c
• docs/forge-vnext-architecture -> 196a4b376316a854c68f539b792a8b810ef160ed

Superseded #187 candidate snapshot

• architecture/issue-187-goal-run-policy-final -> 5d1aa853a71c38fcb21ce56637e9d9edfb3ce3d2
• architecture/issue-187-verification-goal-execution-policy -> 21ad3ea1f7d57281a79273612fd2a9d247c15e48
• architecture/issue-187-verification-goal-execution-policy-r1 -> 21ad3ea1f7d57281a79273612fd2a9d247c15e48
• architecture/issue-187-verification-goal-run-policy -> 21ad3ea1f7d57281a79273612fd2a9d247c15e48
• architecture/issue-187-verification-goal-run-policy-v1 -> 21ad3ea1f7d57281a79273612fd2a9d247c15e48
• codex/issue-187-goal-definition-v2 -> 5d1aa853a71c38fcb21ce56637e9d9edfb3ce3d2

Superseded reviewer candidate snapshot

• codex/reviewer-scope-controls -> c52db3a65a188ca006c43e4b9fd7e2ef82fef79f

Mandatory execution rule

These SHAs are review evidence, not authorization to delete later without checking. Immediately before each deletion batch, re-fetch the remote refs and open PR heads. Delete a candidate only if its full SHA still matches the reviewed/dispositioned state and it has not become a live PR/current work branch. Any mismatch is a stop/skip condition requiring fresh preservation review.

At snapshot time PR #351 was the sole open PR and remained open/unmerged/mergeable; its branch must be preserved.