Skip to content

levy-street/world-of-claudecraft / .claude/skills/release-merge-audit

release-merge-audit

Verified

FileKindSize
SKILL.mdskill md6.2 KB
---
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:

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:

```sh
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):

```sh
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):

```sh
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`).
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall