Merge Gate

Merge Gate (HMIS)

Full design rationale: developer_docs/git/2026-08-22-merge-gate-skill-design.md.

This exists because a past API-improvement PR shipped an NPE that broke all API functions, and neither CodeRabbit nor manual review caught it before merge. This skill adds a code-level review pass plus a live end-to-end sweep — including two fixed baseline checks unrelated to the PR's own scope — as a safety net for that class of regression.

This skill never merges anything. It ends with a report telling you which PRs are ready for your final review and merge.

Arguments

• $0, $1, ... — one or more PR numbers (not issue numbers). If a number given doesn't resolve to an open PR, say so and ask for the correct PR number rather than guessing which PR closes an issue.

Multi-PR handling

Process PRs sequentially, one fully through the pipeline (or blocked) before starting the next — only one branch/deployment can be live on local Payara at a time. Keep a running outcome table and print the final report after the last PR.

Pipeline (per PR)

0. CI gate

gh pr checks <PR>

• Failing → record BLOCKED-CI, post the PR status comment (see § PR status comment), stop this PR, move to the next.
• Pending → ScheduleWakeup ~270s (same cadence as dev-issue §14), recheck once. Still not green → BLOCKED-CI, post the comment, stop this PR.
• Passing → continue.

1. Fetch and checkout

git fetch origin
git checkout -- src/main/resources/META-INF/persistence.xml
gh pr checkout <PR>

The git checkout -- discards the previous PR's uncommitted local-JNDI edit first — skip it and the branch switch can fail or behave inconsistently whenever the committed persistence.xml differs between branches. Safe no-op on the very first PR (nothing to discard).

Then restore persistence.xml to local JNDI (jdbc/coop / jdbc/ruhunuAudit) per CLAUDE.md, left unstaged.

Phase 1 — Code-level regression review

Invoke the code-review skill against this PR at high effort with --comment, so findings post directly to the PR (reuses the existing review engine instead of duplicating its logic).

Before classifying anything, run the fallback below to confirm every finding the sub-agent claims to have posted actually landed — do this before the classification step decides to record BLOCKED-REVIEW and stop, not after. Running it after the stop decision defeats the point: by the time you've stopped this PR and moved to the next one, an unverified silent drop stays silently dropped.

Fallback — verify every finding actually landed as a comment

code-review --comment posts via GitHub's PR-review-comment API, which can only anchor a comment on a line that appears in this PR's own diff. A finding whose defect lives in a file the PR doesn't touch (e.g. a downstream method the new code merely calls) has nowhere to anchor — and can be silently dropped instead of posted, with no error surfaced back. Confirmed happening in practice (PR #23082, 2026-08-22: two blocking findings were returned by the sub-agent as "posted" but never actually appeared on the PR, because one lived in a file outside the diff and the anchor silently failed).

Before trusting the sub-agent's "posted successfully" claim, verify for every finding it returned (classification happens after this, once you know what's actually posted). Get the actual poster identity first (don't hardcode a username or just exclude coderabbitai[bot] — an unrelated human/bot comment at the same path:line would then be misread as confirmation), and always paginate — the default page size silently truncates past ~30 comments, which would make a real PR with substantial CodeRabbit + human discussion look falsely under-verified (or mask a genuinely missing finding sitting past the cutoff):

gh api --jq only accepts one filter-string argument — piping --arg and its value straight after it fails with accepts 1 arg(s), received 4. Pipe to a standalone jq instead:

me=$(gh api user --jq '.login')
gh api --paginate repos/hmislk/hmis/pulls/<PR>/comments | \
  jq --arg me "$me" '.[] | select(.user.login == $me) | "\(.path):\(.line)"'

Cross-check this list against the findings returned. For any finding missing from it (blocking or not — verify all of them, since classification hasn't happened yet):

1. Check whether its file is part of the PR's diff at all: gh pr diff <PR> --name-only.
2. File is in the diff, but the exact line isn't inside a commentable hunk (GitHub only allows anchoring within a hunk's context window — posting will fail with "could not be resolved"): get the real hunk boundaries with gh api repos/hmislk/hmis/pulls/<PR>/files --jq '.[] | select(.filename=="<path>") | .patch' and anchor on the nearest line that's actually inside it instead.
3. File isn't in the diff at all: anchor the comment on the calling line in a file that IS in the diff (typically the new code that invokes the problematic downstream method) and cite the true file:line of the actual defect explicitly in the comment body text, since the anchor line is just the closest available hook, not the defect's real location.
4. No related diff line exists at all: don't force a mis-anchored comment. Fold the finding into the top-level PR status comment instead (see § PR status comment) — that comment isn't line-anchored, so it can reference any file/line freely.

Post any recovered findings with gh api repos/hmislk/hmis/pulls/<PR>/comments -f commit_id=<head-sha> -f path=<path> -F line=<n> -f side=RIGHT -f body=<text> (head SHA from gh pr view <PR> --json commits -q '.commits[-1].oid'). Re-run the verification query once more before classifying anything — don't classify or stop on an unconfirmed assumption that everything posted.

Classify

Now that every finding is confirmed actually posted (or folded into the status comment per case 4 above), classify what the sub-agent returned:

No findings at all → continue to Phase 2.

Phase 2 — Identify affected workflows

gh pr diff <PR> --name-only

Use the Explore agent to map the changed files (controllers, services, entities, XHTML, REST resources) to the user-facing pages/flows that exercise them. Produce a short concrete list (e.g. "GRN receipt flow", "Stock Transfer approval"). Only pause for AskUserQuestion if the mapping is genuinely ambiguous (e.g. a shared utility touched by many unrelated flows) — don't ask when the diff makes the affected flow obvious.

2a. Build and local redeploy

Per playwright-e2e §0a / dev-issue §6:

$env:JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-11.0.23.9-hotspot"
& "D:\Program Files\NetBeans-18\netbeans\java\maven\bin\mvn.cmd" clean package -DskipTests
& "D:\Payara\bin\asadmin.bat" redeploy --name rh "D:\Development\2024\hmis\target\rh-3.0.0.war"

Check the server log for deployment errors before proceeding. If mvn clean package fails, asadmin redeploy fails, or the server log shows deployment errors, stop this PR here: capture the failure output, redact it of credentials/connection strings/hostnames (same rule as § Phase 3's evidence redaction), post the PR status comment (see § PR status comment) with the redacted excerpt, record BLOCKED-BUILD, and move to the next PR — don't attempt Phase 3 against a stale or undeployed build.