async-post-commit-hook-commit-orphaned-by-squash-merge

Async post-commit hook's commit is orphaned by a squash-merge

Problem

A repo has an async post-commit hook that fires in the background after each commit and creates its OWN follow-up commit — typically auto-generated docs, a site regen, or a "correct the design doc to match the code you just changed" edit (you'll see [post-commit] … running doc update in background… at commit time and an [auto-docs] … commit appear seconds-to-minutes later).

The race that loses content:

1. You commit your fix (feat/fix …).
2. git push -u origin <branch> runs — and completes before the async hook finishes, so the remote has only your fix commit.
3. You open the PR and squash-merge it. The squash-merge is built from the pushed remote state → it contains only your fix commit.
4. Then the background hook's [auto-docs] commit lands — local-only, on top of your branch. It's never pushed, never in the PR, never on main.

Now your local branch is [ahead 1] of origin/<branch>, holding a commit with real, useful content (e.g. a design doc corrected to match your change). If you delete the merged branch or just start the next task, that content is silently lost — and because it was the hook's job to keep the doc in sync, nobody re-generates it.

Context / Trigger Conditions

• The repo has a background/async post-commit hook (greppable: a post-commit hook that backgrounds work; commits prefixed [auto-docs] / chore: regenerate with no human author intent).
• You pushed → PR'd → squash-merged a branch this session.
• git status -sb on that (still-checked-out) branch shows ## <branch>...origin/<branch> [ahead 1] (or ahead N) even though you believe it fully merged.
• git log --oneline shows the top local commit is the hook's, authored after your work commit, and it touches files (a design doc, a site asset) — not empty.

Solution

Before deleting the branch or moving on, rescue the orphan.

1. See it. On the just-merged branch:

   git status -sb            # "[ahead 1]" of origin = unpushed local commit(s)
   git log --oneline -3      # top one is the [auto-docs]/hook commit?
   git show <sha> --stat     # what content did the hook generate?
   

2. Judge it. If the orphan is genuinely valuable (a doc corrected to match your merged change, a needed regen) → rescue. If it's noise (a no-op regen, already-correct) → discard, no action.
3. Confirm the target still exists on main (main may have moved many commits since your fix):

   git cat-file -e origin/main:<path-the-hook-edited> && echo EXISTS
   

4. Rescue by cherry-pick onto a fresh branch off origin/main (NOT onto the stale/merged branch), and fold it into your next PR — the session-handoff PR is the natural home:

   git fetch origin
   git checkout -b <handoff-branch> origin/main
   git cherry-pick <sha>           # the [auto-docs] commit applies cleanly
   # … add handoff docs, commit, PR, merge