review-gate

Review Gate

Problem with this skill? Run kendex report — it files to the owning repo automatically. Do not hand-file.

The gate answers ONE question: has this exact PR head been reviewed? It posts that answer as a commit status the repo's branch rules require. It does not check CI, re-run anything, or reason about jobs.

Two greens do NOT mean a review happened. Under REVIEW_GATE_MODE = "off" the predicate evaluates no evidence and attests only that the repo disabled the gate; and merge-group statuses never read the mode, posting green as "merge-queue entry: post-approval by construction". Both: references/settings.md § REVIEW_GATE_MODE.

Decision table

Reading the gate's own pending text. no review evidence at <sha> yet; expected from <names> is the awaiting verdict. The names are the sources that could still open the gate at that head, resolved from the repo's own settings and filtered the way the evidence read filters them — the PR author never appears, and an empty trust list reads as any non-author review (or approval under REVIEW_GATE_REVIEW_OBJECT_MIN_STATE = "approved"). Past 140 characters the sha shortens to 12 and the names that do not fit are counted (and N more). A configured operator override is a source too, and is named with the rest. no configured source is eligible here means every configured login is the author and no override is set.

Act on the names, not on the pending state: where they are bots and one has already reviewed this head, dispatch the writer instead of waiting.

Working in a consumer repo

1. Read the current state before changing anything

# Is the engine vendored and committed?
git ls-files .agents/skills/review-gate/scripts/ | head

# Is anything wired to write the gate?
git ls-files '.github/workflows/*.yml' '.github/workflows/*.yaml' \
  | xargs grep -l 'review-writer\.sh' 2>/dev/null

# What does the repo say about itself?
.agents/skills/review-gate/scripts/validate.sh; echo "exit $?"

validate.sh prints one verdict line per check and every FAIL line names its own fix. Exit 0 = clean, 1 = findings, 2 = the check could not run at all (bad arguments, not a git repository, a missing file it derives checks from — fix that first; a 2 is never a pass). Run it after every step below.

2. Adopt, when nothing is wired

The precondition comes first: the repo needs a merge queue whose required contexts include the test aggregate, or no held-back jobs. Held-back jobs report skipped, which GitHub counts as satisfied, and a reviewed PR would merge untested. Confirm which one holds before wiring anything.

# 1. vendor the engine as TRACKED files (CI checks out nothing else)
kendex refresh
git add .agents/skills/review-gate

# 2. copy the writer VERBATIM — it carries no per-repo values
cp .agents/skills/review-gate/templates/review-gate-writer.yml \
   .github/workflows/review-gate-writer.yml

# 3. seed the repo's settings from the shipped example, then edit the
#    handful of values this repo actually decides (table below)
$EDITOR kendex.settings.toml

# 4. prove the install answers for itself
.agents/skills/review-gate/scripts/validate.sh

Then add the validate step to the repo's CI as its own job — no needs, no path filter, no gate condition:

  review-gate-validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@<pinned-sha>
        with:
          persist-credentials: false
      - run: .agents/skills/review-gate/scripts/validate.sh

Finish with the repo-side wiring — ruleset, merge queue, bypass actor — and delete the local machinery the writer supersedes, in the same PR: references/adoption.md.

3. The values a repo actually decides

Everything else has a working default. Full table: references/settings.md.

4. Repair, when validate reports FAIL

5. Operations

Watching one or many PRs without stalling. Never key a hand-rolled monitor on gate-state transitions. Run .agents/skills/review-gate/scripts/pr-watch.sh (optionally --heal) on the harness's wake-up mechanism: silence + exit 0 means nothing needs you; attention lines name exactly what does. See adoption.md § Watching PRs as an agent.

Reviewers are down / nothing is reviewing. Run the internal review loop: fix findings, resolve every thread, then post the override status with a real reason. It cannot bypass an objection or an open thread.

A PR that repairs the gate itself. The writer always runs the merged engine. Merge the repair PR with the ruleset's bypass actor and say so in the commit message.

A settings-change PR is judged by the OLD config — a PR adding a trusted login cannot have its own gate honor it. Merge via normal review or the bypass actor.

The engine

Evidence sources (.agents/skills/review-gate/scripts/review-predicate.sh)

Evidence for the CURRENT head is any of:

1. Review object at the exact head from a non-author, non-dismissed login — restricted to REVIEW_GATE_REVIEW_OBJECT_TRUSTED_LOGINS when set, and to APPROVED reviews when REVIEW_GATE_REVIEW_OBJECT_MIN_STATE = "approved". An approval is never superseded by a later COMMENTED from the same reviewer; only a later CHANGES_REQUESTED withdraws it. A row whose body's first line (after trimming leading whitespace and markdown quote markers) contains a REVIEW_GATE_REVIEW_OBJECT_ERROR_PATTERNS marker is NOT-EVIDENCE, never a failure.
2. Trusted clean-analysis check-run or commit status (REVIEW_GATE_TRUSTED_STATUS_CONTEXTS) succeeding on this head — but a pass must prove analysis RAN: a success matching REVIEW_GATE_CHECKRUN_SKIP_PATTERNS (e.g. "rate limited") is NOT-EVIDENCE, never a failure. On BOTH surfaces the NEWEST row/run per name decides: an older clean success never outlives its reviewer's newer pending/failed/skip-marked round.
3. Comment-form clean pass (REVIEW_GATE_COMMENT_REVIEWERS): an issue comment by a trusted bot login — never the PR author, even if configured — binding the evidence to this head's sha (floor REVIEW_GATE_SHA_PREFIX_FLOOR).
4. Operator override (REVIEW_GATE_OVERRIDE_CONTEXT, legacy name REVIEW_GATE_OUTAGE_CONTEXT): a trusted operator's status carrying a NON-EMPTY reason, which is enforced and surfaced in the gate detail. Substitutes for MISSING evidence ONLY — it never overrides a changes-requested or an unresolved thread; fix findings and resolve threads first, then attest.

With REVIEW_GATE_CARRY_FORWARD (off by default), evidence at an ancestor carries to head when the delta is provably in a class review would not re-examine — docs-only, comment-only, a committed kendex render tree, identical tree. Never a waiver: real evidence must exist, code changes outside those classes always require fresh evidence, and the fail-closed terms still apply.

Changes-requested and unresolved threads always fail closed. Every evidence read fails LOUD (exit 2, no verdict). Read bounds, retry budget and thread pagination: DEVELOPMENT.md § Evidence reads.

Trust model. Trust keys on names only GitHub controls: the author login of a review or comment, or the exact check/status context on repos where every publisher is trusted. A comment body never establishes trust — it is read only to BIND evidence to a commit. Where PR workflows hold statuses:write, the opt-in REVIEW_GATE_STATUS_PUBLISHER_REJECT list rejects statuses minted by a forgeable creator (typically github-actions[bot]) on both the trusted-context and override reads.

The writer (.agents/skills/review-gate/scripts/review-writer.sh)

One workflow, defined on the default branch, is the only thing that writes the gate status. It evaluates the predicate and converges the status — nothing else.

• Converge-all on every leg. Every invocation converges EVERY open PR.
• Relay / converge split. PR-attached legs (pull_request_target, pull_request_review, status, an opted-in check_run) do NOT run the engine: they run a group-less relay job that dispatches a converge pass and exits. Only workflow_dispatch and schedule hold the single-writer group. The relay costs one non-evictable run per PR-attached event — size that before adopting on a capacity-limited runner pool (references/adoption.md § Updating an already-adopted copy).
• The relay never exits non-zero — a pinned invariant. It holds no statuses scope. Every fault warns and exits 0, and every wait is bounded; a sustained dispatch outage surfaces as gate staleness, healed by the cron floor and pr-watch --heal.
• pull_request_target safety: the job never executes PR-controlled code. Every checkout pins the default branch with credentials dropped and refuses an empty default-branch resolution rather than falling back.
• Idempotent, and ordered. It no-ops when the current entry already matches, and defers a success post to any newer run's entry. Mechanics: DEVELOPMENT.md § Write ordering.

Scripts

# validate THIS repo's installation (env: none) — the consumer's CI step
.agents/skills/review-gate/scripts/validate.sh

# is the adopted workflow still the shipped template? (equality, not
# re-derivation) — usable alone when only the workflow copy changed
.agents/skills/review-gate/scripts/validate-workflow.sh

# verdict for one head (env: GH_REPO, PR_NUMBER, HEAD_SHA[, PR_AUTHOR])
.agents/skills/review-gate/scripts/review-predicate.sh

# validate settings values alone, no evidence read, no PR required
.agents/skills/review-gate/scripts/review-predicate.sh --check-config

# converge every open PR's gate status (env: GH_REPO)
.agents/skills/review-gate/scripts/review-writer.sh

# needs-attention reducer over open PRs (env: GH_REPO) — exit 0 nothing,
# 1 attention lines on stdout, 2 read errors. Flags: --heal (one writer
# dispatch on gate-stale, reported as an informational heal-dispatched
# line), --no-evaluate (predicate-skipping mode: thread,
# queue, and gate-status reads still run, so threads-open, disarmed, and
# the threads-driven gate-stale form all fire; verdict-driven forms need
# the predicate), --awaiting-after SECS (default: PR_REVIEW_WAIT_SECS)
.agents/skills/review-gate/scripts/pr-watch.sh [PR# ...]

The offline decision-table selftest and the live sandbox replay are the ENGINE's proofs and run in the kendex repo, not in a consumer's CI: DEVELOPMENT.md.

For re-vendor PRs, suppress duplicate findings with the remedy-locus reviewer instruction, never a reviewer path exclusion: references/vendored-paths.md. A committed kendex refresh tree is the same problem with no pin over it and a blast radius of every consuming repo; it routes every finding over the render upstream, with no carve-out: references/rendered-paths.md.