Verify Before Merge

---
name: verify-before-merge
description: 'Use when about to merge or approve a PR, reviewing a PR''s test plan, or deciding whether a change needs the integration run or the golden-change label.'
---

# Verify before merge

The checklist for whoever merges: CI, ShellCheck, golden results and call ceilings, the privacy grep, the cargo, parity, guard and integration commands, and a clean merge. The `golden-change` label, call-ceiling, privacy-grep and CI-green rules are also stated in CLAUDE.md ("Verification before merge") and hold whether or not this skill loads, as does the merge gate (CLAUDE.md, "Working the queue", with its steps in the `work-the-queue` skill). The three ask-gates are in "Merge policy" in CLAUDE.md. In the list below, "the maintainer's explicit OK" is the OK of that policy. The two `docs/testing.md` links carry the path from this directory.

## Verification before merge
Done by whoever merges:
- CI (`.github/workflows/ci.yml`) must be green. The Rust server is the only server (#356), so its job is the main check: `cargo build` and `cargo test --locked`, and the guard tests that start the binary. `cargo test` runs the parity cases (`tests/parity.rs`, with `parity_self_check.rs` proving the comparator can fail; #371), so it is the only CI check of the binary against the recorded results and mutation testing counts the cases. Nothing in Node compares a result any more (#379): the recorder is Rust too (`tests/parity_record.rs`), and the comparator's own rules are held by `tests/parity_comparator.rs` and `parity_harness.rs`. On a push to main and by hand, the same parity test also runs against the release build. The tooling job runs `npm run typecheck` and `npx vitest run tests/guards` on Node 22 and 24 (`engines.node` is `>=22.12.0`, the floor of the dev toolchain, vite 7). The integration tests and the measure scripts stay local.
- Mutation testing on the Rust crate (ADR-0033, #364) is not a CI job yet; the TypeScript Stryker job and its ratchet (ADR-0026 to ADR-0030) were removed with the TypeScript server (#356).
- **Shell scripts pass ShellCheck** (#381). The `shellcheck` job of `ci.yml` runs `shellcheck` on every tracked `*.sh` and `actionlint` (pinned by version and SHA-256) on the workflows, which ShellCheck-lints each `run:` block, and any finding fails it. A new shell script must pass at the default severity. A `# shellcheck disable=SCxxxx` needs its reason on the same line, such as `# shellcheck disable=SC2034 # read by the sourcing script`. Run `shellcheck $(git ls-files '*.sh')` locally.
- **The golden results** (the `expected` result of each case in `tests/data/parity/<group>.json`, and `tests/data/parity/tool-list.json`) are the tool contract: the parity test (`cargo test --test parity`) holds the Rust server to them. The `golden-files` job of `ci.yml` fails a PR that changes any of them unless it carries the `golden-change` label, and it names the files. It compares a group file by each case's name and `expected` alone (key order and layout aside, all the files as one list), so a change to a case's stub answers or arguments, to `clock-cases.json`, or a result moved to another file is not a golden change. **The label goes on only after the maintainer's explicit OK, recorded on the PR**, and the maintainer adds it. Nobody applies it on their own: not a PR's author, not a reviewer, and not under the feature-branch self-merge grant. The recorder (`PARITY_RECORD=1`, #379) writes a result only when its meaning changed, so a re-record that touches a golden result is a contract change, and a cosmetic one can't trip the check.
- **The call ceilings** (`tests/data/parity/call-ceilings.json`, a case name to the most LogSeq calls the tool may make for it; ADR-0034 Decision 5, ADR-0011) are held the same way. A PR that makes fewer calls has to lower a ceiling (a run that makes fewer than the ceiling fails; `PARITY_RECORD=1` lowers it) and needs no OK. A PR that **raises** one, or adds one, makes a tool cost LogSeq more, so the second step of the `golden-files` job fails it unless it carries the `golden-change` label, on the same rule as above: only after the maintainer's explicit OK, and only the maintainer adds it. Never raise a ceiling to make a case pass; a re-recorded call ([`docs/testing.md`](../../../docs/testing.md), "Re-recording a call") that needs more calls is a question for the maintainer.
- Privacy grep of the diff, commit messages, PR body and review comments/replies. Don't paste integration-test or measure-script output anywhere on GitHub. Report pass/fail and approximate counts only.
- `cargo test --locked`
- `cargo test --locked --test parity --test parity_self_check` is the parity check. The cases and their golden results are the files in `tests/data/parity/`, the only source (#379): edit a case there, leave out its `expected` if it has none yet, and record it with `PARITY_RECORD=1 cargo test --test parity_record -- --nocapture`. It refuses to run in CI. The parity test holds the LogSeq calls to a bounded count and an effect, not to exact text or order (ADR-0034 Decision 5): each call made has to match a recorded call in method, query text (layout aside) and inputs, at most the case's ceiling are made, and all are reads. [`docs/testing.md`](../../../docs/testing.md) ("Re-recording a call") has the steps to re-record a call. `cargo test` fails when a data file is not in the form the recorder writes
- `npm run typecheck` and `npx vitest run tests/guards tests/rust-guards`
- `npm run test:integration` against this worktree's fixture instance (`npx tsx scripts/logseq-instance.ts start`, the run, then `stop`; read-only). The instance opens a copy (#151), so afterwards the repo's status must still show no change under `tests/fixtures/graph/`
- `npx tsx scripts/measure-api-calls.ts` still runs (it needs the Rust binary: `cargo build --release --locked`, or `--rust-binary` for another)
- A clean merge against the PR's current base branch (`main`: the Rust server is on `main` after the cutover; `feature/rust-spike` only while that branch is still in use). If the base has moved, test the PR merged onto it.