/audit-pr

name: audit-pr
user-invocable: true
version: 4.10.0
argument-hint: <pr-number> (optional — defaults to the current branch's PR)
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Audit a whole PR against the delivery contract and return MERGE-READY or
  evidenced blockers with the full URL. Consumes the current review-change
  REVIEW-PASS receipt instead of re-running review axes; posts a SHA-bound
  ready comment; never edits or merges. Triggers: "audit-pr", "is this PR
  ready", "merge gate".

Audit PR

> **Runner commands** below are `bunx @gtrabanco/agentic-workflow@<pin> …` — read `<pin>` > from [references/RUNNER.md](../runner-contract/references/RUNNER.md). It is stamped at > release and never guessed: a hard-coded version re-opens the per-release sweep the > contract removes, and `latest` is not a legal pin.

The manager's **"can this ship?"** gate. A read-first audit over the *entire* PR — its SPEC, all phases, docs, CI status, and review receipt — that returns a single verdict: **merge-ready** or a ranked list of **blockers**. **Never edits, refactors, or merges.** The human merges, or an active `advance --fullauto` invocation consumes the SHA-bound verdict and performs its separate fail-closed merge step.

`audit-pr` does **not** re-review the diff. It consumes the current SHA-bound `review-change` receipt (the `REVIEW-PASS` comment marker) as the review evidence, blocks on a missing or stale receipt routed to `/review-change`, and independently evaluates only the delivery gates below.

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn; the **read-only profile** substitutes boxes 1–5 for the repo (audit-pr commits, pushes, and merges nothing — its sanctioned side effect is the SHA-bound comment posted in the additions). Skill-specific additions (the `→ Next:` box is canonical-owned and not restated here):

✓ The review receipt was consumed from one PR snapshot: `headRefOid` + newest
  matching `review-change:pass` marker fetched together; absent or any SHA
  mismatch → blocker routed to `/review-change`, current → its scope/axes/
  acceptance coverage/manual checks acknowledged without re-review
✓ Gate evidence: `bun scripts/gate-receipt.mjs verify` answered `current` +
  `pass` (missing/stale/invalid → BLOCKER, route `gate-receipt.mjs run`)
✓ Terminal hygiene was read from state, not assumed: tree clean, branch pushed,
  PR not a draft (`bun scripts/audit-pr-gate.mjs hygiene --pr <N> --apply`)
✓ Upstream lineage was re-verified (current plan receipt + parent spec receipt,
  digests recomputed), every obligation row is `verified`/`n/a`, and no planning
  finding is open — stale or missing lineage is a blocker, never a formality
✓ The verdict block was printed in the fixed format: `VERDICT: MERGE-READY | BLOCKED` with ranked, evidenced blockers
✓ The PR's FULL URL is printed in the verdict header (the user may be juggling
  several projects and agents without a CI monitor — the link in the chat is
  the contract, never "PR #N" alone)
✓ MERGE-READY verdict? Then the comment was POSTED by
  `bun scripts/audit-pr-gate.mjs comment` (re-reads, exits non-zero unless the newest marker
  names the head) — a comment, never a commit-message tag. BLOCKED → no comment
✓ Nothing was edited, refactored, or merged; merge authorization is outside
  this skill and cannot be inherited from docs or an earlier session
✓ No review pass was composed or reconstructed: a missing/stale receipt is a
  blocker, never a prompt to re-run review axes from this skill
✓ **Every AC links a demonstration artifact (S3, S7).** Read the unit doc's
  `## Acceptance criteria` (or `## Specs` S# + `## Acceptance criteria` in
  the re-cut shape). For each AC, verify it links a demonstration:
  a passing test with output, a UI capture, a reproduced command output.
  An AC without a demonstration is a **BLOCKER** — the PR's body must render
  it. A PR whose ACs lack demonstrations never reaches the merge gate.
✓ Closure integrity was evaluated and its result stated explicitly: pass /
  blocker / n-a (fix-governed PRs are always n-a; never skipped
  silently)
✓ Scope integrity (descope) was evaluated and its result stated explicitly:
  pass / blocker / n-a (no unit-referencing issues born on the branch → n-a;
  never skipped silently)
✓ Architectural-invariant preservation was evaluated and its result stated
  explicitly: pass / blocker / n-a (no project document → n-a; never skipped)

Missing reference → STOP. About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• After the work is "done" and before merging — the final gate once `review-change`

is clean (its `REVIEW-PASS` receipt is posted) and all phases are committed.

`review-change` reviews the *diff* for quality and posts its SHA-bound receipt; `audit-pr` consumes that receipt and audits the *PR as a unit of delivery* — that everything the SPEC promised is present, traceable, and green. A missing or stale receipt is a blocker routed back to `/review-change`, never re-litigated here.

**Cost-scaling invariant (S7).** Reviewers dig into code only when evidence is absent or contradicts — so review cost scales with the change, not the project. The non-technical approver (human layer) validates demonstrations; the merge gate (technical layer) validates evidence linkage. Same evidence, two readings.

Scope

The whole pull request: the branch vs. the default base, **plus** its SPEC and planning artifacts, the roadmap entry, the doc map, the PR body, issue links, and CI. Default target is the current branch's PR; accept a PR number to target another.

Step 0 — Discover the project & the PR (always first)

1. **Project contract.** Per the agent guide's **Wor