name: release-merge-audit
description: Audit a release/** merge into a long-lived feature branch for the known drift hazards. Use immediately after merging a release branch into a feature branch (or when reviewing such a merge commit): finds branch-owned files the merge touched, release changes landed on a legacy arm that a migrated handler must mirror, new routes missing surface-corpus rows, release-refactored helpers that need re-binding at their injection sites, and planning-doc premises the merge silently invalidated.
user-invocable: true
Release-merge audit
A release merge into a long-lived feature branch routinely lands surprises that neither CI nor
the merge conflict markers surface. This audit has paid for itself four times on
feature/api-re-architecture alone:
- A release hotfix changed a LEGACY route arm the branch had already migrated, so the
migrated handler silently diverged (parity break with no conflict).
- A release refactor added a parameter to a helper the branch receives BY INJECTION
(
passesTurnstile gained a secret argument); the un-re-bound injection site silently
disabled the gate.
- A release added 12 routes the branch's surface inventory did not know about, 6 of them
invisible to the parity corpus.
- A release hotfix pre-landed half of some planned work (the market realm-scoping) with a
different mechanism than the branch's plan assumed, invalidating the plan's premise.
Run every step; each targets one of those failure classes. No em dashes or emojis in anything
you write.
Step 1: identify the merge and its delta
The merge commit is the argument if given, else the most recent RELEASE merge. Both subject
forms occur in this history: the plain form (Merge branch 'release/v0.23.0' ...) and the far
more common remote-tracking form (Merge remote-tracking branch 'origin/release/v0.25.0' ...,
also with upstream/ or up/). Match both:
git log --merges -1 --format='%H %s' \
--grep="branch '\(origin/\|upstream/\|up/\)\?release/" HEAD
Print %s and read it: hand-written subjects (e.g. merge: resync with release/v0.23.0) do
not match this grep, and a bare git log --merges -1 can grab an unrelated merge, e.g. a
main-merge, so when in doubt pass the commit explicitly. The audit
assumes a true two-parent merge commit; a squash-merged release has no ^2, so pass the
commit explicitly and treat its own diff as the incoming delta. The incoming delta (what the
release brought, relative to the branch):
git diff --name-only <merge>^1..<merge>
^1 is the branch-side parent. Also record the merged release ref (git log -1 <merge>^2).
Step 2: intersect with branch-owned surfaces
Compute the files the BRANCH owns (changed on the branch before the merge):
git diff --name-only "$(git merge-base <merge>^1 main)"..<merge>^1
Intersect with Step 1's list. Every overlapping file is a manual-read item: the release and the
branch both changed it, and the merge resolution may have quietly dropped either side's intent.
For each overlap, read the merged result against BOTH parents (git show <merge>^1:<file>,
git show <merge>^2:<file>) and confirm no side's behavior was lost. A base-merge can silently
revert a feature in one hunk.
Step 3: legacy-arm divergence (migrated surfaces)
For each route or handler the branch has MIGRATED that the release touched: did the release
change land only on the legacy arm? If so, mirror it into the migrated handler and add a parity
case in the same change. On the API pipeline, remember a knownDeviation masks its WHOLE path,
so re-pin corpus fixtures via captureBothModes rather than widening a deviation.
Step 4: new endpoints and inventory rows
List any route, WS command, or endpoint the release ADDED (grep the delta for route tables,
dispatch cases, app./registry additions). Each needs: an owner on the branch's architecture
(for the pipeline: a RouteDef, router-owned AND legacy-served during rollback retention), and a
row in the surface inventory / parity corpus. A corpus-invisible route is unaudited by
definition.
Step 5: injected and re-bound helpers
For each function in the delta whose signature or closure changed: find every place the branch
passes it BY INJECTION (boot wiring, configure*Runtime calls, DI seams) and confirm the
injection site was re-bound with the new shape. A stale binding compiles fine and silently
skips the new behavior.
Step 6: planning-doc premise re-check
Locate the branch's planning docs first: they usually live under docs/<epic>/ (for the API
pipeline, docs/api-pipeline/), and files like state.md/progress.md name the work in
flight. Re-read whichever doc describes the ACTIVE work plus those two files. Did the merge
land code they assume absent, or implement a planned mechanism a different way? If yes,
correct the premise in the docs BEFORE implementing against it, and note the correction in
memory.
Step 7: report and fix
Produce a short report: overlaps read (Step 2), divergences mirrored (Step 3), inventory rows
added (Step 4), bindings re-checked (Step 5), premises corrected (Step 6), each with file:line.
Apply the fixes in the same change with a parity/regression test per divergence, then run the
targeted suites plus npx tsc --noEmit (or npm run gate if the merge was large).
Two recurring traps to check in the same pass:
- i18n merge mechanics. The aggregate baseline and status summary are no longer
committed, so a merge where both sides changed catalog keys only needs
npm run i18n:gen
to reconcile the committed line-item slices. Never re-baseline by hand; that historical
trap applies only to branches predating the baseline's removal.
- Stale db-mock export lists. A release-authored test that drives GameServer can mock
../server/db with the RELEASE tree's export list, so a db function the BRANCH added
throws "No X export is defined on the mock" only on the merged tree; neither parent
carries the fix and only the full gate catches it. After any merge bringing new
vi.mock('../server/db') sites, diff each mock's keys against what server/game.ts
imports on the branch and mirror the branch's canonical mock shape (template:
tests/character_lease_game.test.ts).
