release-merge-audit

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.

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:

1. A release hotfix changed a LEGACY route arm the branch had already migrated, so the migrated handler silently diverged (parity break with no conflict).
2. 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.
3. A release added 12 routes the branch's surface inventory did not know about, 6 of them invisible to the parity corpus.
4. 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).