--- name: audit-pr user-invocable: true version: 5.0.3 argument-hint: (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 ✓ 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 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`): ```sh gh pr view --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/-/` (feature) or `docs/fix/-/` (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 ``: ```sh gh pr view --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](references/01_MERGE_GATES.md) for delivery, CI, traceability, review-receipt, and mergeability evidence. 2. [02 closure and scope gates](references/02_CLOSURE_AND_SCOPE_GATES.md) for capability closure and descope provenance. 3. [03 audit process](references/03_AUDIT_PROCESS.md) to gather, decide, persist blockers, and post the SHA-bound MERGE-READY comment. 4. [04 verdict](references/04_VERDICT.md) before output, then [05 routing and guardrails](references/05_ROUTING_AND_GUARDRAILS.md). These mandatory resources own the `docs/workflow/REPOSITORY_STATE.md` evidence rules and Architectural invariants gate. Read [portability](references/PORTABILITY.md) 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](references/PORTABILITY.md). ## 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.