Deliver-stage preflight: guard against stale/diverged local main and behind-main feature branch

[davidmatousek]

Deliver-stage preflight: guard against stale/diverged local main and behind-main feature branch before any merge or direct-to-main doc push

ICE Score

Impact: —, Confidence: —, Effort: — = Not yet scored

Evidence

Retrospective: Emerged during delivery of Feature 338 (Restore F-248/F-256 Substitution Hardening).

During /aod.deliver 338 two latent hazards surfaced at the merge step:

1. The long-lived restore branch had fallen behind origin/main (Remediate dead citation URLs surfaced by the link-rot monitor (#332) #333 + the v4.45.0 release landed after it was cut), so the PR was CONFLICTING and GitHub could not even run CI on the test-merge. Conflicts were confined to 3 non-hardening metadata files, but the merge had to be performed and resolved mid-deliver.
2. Local main was a stale, unpushed /aod.update clobber (ad390f8 chore: apply aod.update → d8a66381) — the very regression class fix: restore F-248/F-256 substitution hardening reverted by AOD-Kit re-sync; gate tachi-pytest on push #338 fixes. Had the deliver-stage direct-to-main doc push (/aod.deliver Step 9) been executed from that diverged local main, it would have re-clobbered the hardening that had just been restored. The git reset --hard permission guard blocked the naive realignment and forced a read-only proof that origin/main already contained ad390f8's content (byte-identical update.sh/aod-kit-version), making the realignment provably loss-free.

Proposed

Add a deliver-stage preflight (in /aod.deliver Step 1 / the ~aod-deliver skill DoD gate) that, before any PR merge or direct-to-main doc commit:

• verifies the feature branch is current with origin/main (warn + offer auto-merge/rebase if git rev-list --count origin/main..HEAD shows it is behind);
• verifies local main is not diverged from origin/main (git rev-list --left-right --count main...origin/main) and refuses any direct-to-main push from a diverged local main until it is realigned (with a loss-proof check that the local-only commits' content is already on origin/main);
• is a natural extension of the existing /aod.update operator insurance (mandatory checkpoint + --dry-run + git diff --stat the at-risk hardening set).

Metadata

• Source: Retrospective
• Priority: Not yet scored
• Date: 2026-06-30
• Status: New (from retrospective)
• Origin Feature: 338-restore-substitution-hardening
• Related: fix: restore F-248/F-256 substitution hardening reverted by AOD-Kit re-sync; gate tachi-pytest on push #338 (origin), fix(338): restore F-248/F-256 substitution hardening #340 (PR), chore(main): release 4.46.0 #341 (release v4.45.1); BLP-06 Wave 2; the /aod.update clobber class (Evaluate wiring byte-identity baseline suite into CI to prevent silent red-main after ORDERED_FRAMEWORKS catalog growth #329 blind spot, prior occurrence 07236cf)