audit-pr

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
✓ 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 MERGE-READY comment was POSTED on the PR
  (`gh pr comment --body-file` RUN, idempotent by SHA marker) — a comment,
  never a commit-message tag. BLOCKED → no comment posted
✓ 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 <!-- review-change:pass sha=<40-hex> contract=v1 -->:

gh pr view <N> --json headRefOid,comments

• current — marker sha equals that snapshot's headRefOid (the current head SHA). Acknowledge its scope/axes, acceptance coverage, invariant result, and manual checks as the review evidence, then evaluate the delivery gates below.
• absent — no matching marker on the PR → BLOCKER: no review evidence at the head; route to /review-change.
• stale — a marker exists but its sha does not equal headRefOid. Any SHA mismatch voids the receipt → BLOCKER: route to /review-change for a re-review. Do not use a local git diff to override the PR-head comparison.

Never compose, reconstruct, or "spot-check" the review from the diff to clear a missing/stale receipt — that is review-change's turn, and re-litigating axes here is exactly what the receipt gate removes (AC 13).

Progressive loading — mandatory audit route

The reference allowlist is exactly the six linked paths below. Never invent or read another references/ path. After discovery and the Step 1 receipt check, every audit loads and applies exactly these five mandatory resources in order:

1. 01 merge gates for delivery, CI, traceability, review-receipt, and mergeability evidence.
2. 02 closure and scope gates for capability closure and descope provenance.
3. 03 audit process to gather, decide, persist blockers, and post the SHA-bound MERGE-READY comment.
4. 04 verdict before output, then 05 routing and guardrails. These mandatory resources own the docs/workflow/REPOSITORY_STATE.md evidence rules and Architectural invariants gate.

Read portability only when the declared forge or agent actually lacks a named primitive; otherwise skip it. The project artifact docs/workflow/REPOSITORY_STATE.md is evidence, not a skill reference. All resources are one hop from this file. Missing evidence or a missing required resource is a blocker; never infer a pass.

Merge ownership

This skill never merges, including when project docs contain merge: auto, the user previously approved a merge, or a tool retained an earlier permission. Those signals cannot change this skill's read-first boundary.

The sole automated merge authority is the AUDIT stage of an actively invoked ship-roadmap --continue --fullauto run. Its MERGE-READY comment is evidence, not permission; the repository wrapper independently verifies that comment, the forge's current head/default base, green checks, and the merge: fullauto decision fetched at that head. The wrapper owns fresh sync checks, transient state, merge execution, cleanup, and the automerge PR comment. A standalone/ manual call to this skill always hands the MERGE-READY URL to the human.

Portability

Translate forge commands, never the gate semantics. Use the explicit fallbacks in portability.

Relationship to other skills

execute-phase (all phases done) ─▶ review-change (REVIEW-PASS receipt posted) ─▶ audit-pr ─▶ merge
                                                                                │
                     blockers ─┬─ receipt absent/stale ──▶ /review-change ──────┘ (re-review, re-audit)
                               ├─ in-scope            ──▶ execute-phase ────────┘ (fold, re-audit)
                               ├─ out-of-scope        ──▶ plan-fix
                               └─ deferral            ──▶ triage-issue

• Consumes the review-change REVIEW-PASS receipt (its scope/axes, acceptance coverage, invariant result, manual checks) plus the artifacts of plan-feature / plan-fix / execute-phase (SPEC, phases, docs, Closes #N).
• audit-docs is the cross-document coherence check; audit-pr is per-PR merge readiness; product-audit is the periodic, product-wide full sweep.

Done when

• The review receipt was consumed: a current marker was acknowledged, or a missing/stale one became a blocker routed to /review-change (never re-reviewed here).
• Every applicable gate has a pass / blocker / n-a verdict backed by cited evidence.
• A single top-line verdict (MERGE-READY or BLOCKED with ranked blockers) is reported with the PR's full URL in the header, each blocker routed, with the human's manual-verification list explicit.
• On MERGE-READY the merge owner is explicit: a standalone audit hands the URL to the human; an active ship-roadmap --fullauto AUDIT stage receives the SHA-bound verdict and owns every later merge check.
• The closing → Next: block is printed (merge link → then the next unit via /plan-feature --next or /triage-issue; BLOCKED → the routed fix, then re-audit).
• Nothing was edited, refactored, or merged.