/audit-pr

name: audit-pr
user-invocable: true
version: 5.2.1
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

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 `ship-roadmap --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 — verify before ending the turn

✓ 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
✓ 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
✓ Closure integrity was evaluated and its result stated explicitly: pass /
  blocker / warning / 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)
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

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.

• When you want one defensible answer to "is this PR actually ready?" rather than

trusting that every loose end was tied off.

`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.

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 **Workflow conventions** + **documentation map**, then read what THIS skill needs: the roadmap and the project's verification gate (type-check / tests / build / CI). Do **not** load full feature/fix templates — the SPEC below is the only planning artifact this audit reads (AC 14). 2. **The PR.** Identify it and read it in full (forge CLI per the project's Workflow conventions — examples use `gh`):

   gh pr view <N> --json number,url,title,body,baseRefName,headRefName,headRefOid,isDraft,mergeable,mergeStateStatus,files,commits,statusCheckRollup,closingIssuesReferences

If no PR number is given, resolve the current branch's PR (`gh pr view --json ...`). If none exists yet, audit the branch vs. the default base and say "no PR open yet" — the contract still applies. 3. **The SPEC.** Locate the governing SPEC — `docs/features/<NN>-<slug>/` (feature) or `docs/fix/<n>-<topic>/` (fix) — and its planning artifacts (`PLAN.md`, `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md`, `decisions.md`) when present. The SPEC is the source of truth for what "done" means.

Step 1 — Consume the review receipt (always, before any gate)

The review evidence is the SHA-bound `REVIEW-PASS` receipt `review-change` posts on the PR — **never** a re-review composed here. Fetch `headRefOid` and the PR's comments together, then find the **newest** comment carrying the marker `<