audit-pr

审核 PR

经理判断**“能否发布？”的关卡。先读后审计，覆盖整个 PR——包括其 SPEC、所有阶段、文档、CI 状态和审查凭据——并给出单一结论：可合并或按优先级排列的阻塞项**。**绝不编辑、重构或合并。**由人工合并，或由正在执行的 advance --fullauto 调用使用与 SHA 绑定的审计结论，并执行单独的失败即关闭合并步骤。

audit-pr 不会重新审查差异。它使用当前与 SHA 绑定的 review-change 凭据（REVIEW-PASS 评论标记）作为审查证据；如果凭据缺失或已过时，则会阻止操作并转交给 /review-change，同时独立评估下方的交付关卡。

回合约定——结束回合前核验

✓ 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 / 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

准备结束回合时，是否还有任何复选框未勾选？如果有，回合就尚未完成——先完成缺失项（弱模型容易忽略文档末尾的职责；因此特意将此列表放在最前面）。

适用场景

• 工作“完成”后、合并前——review-change 检查通过（已发布其 REVIEW-PASS 凭据）且所有阶段均已提交后的最终关卡。
• 当你希望得到一个有充分依据的“这个 PR 是否真的已准备就绪？”结论，而不是盲目信任所有零散事项都已处理完毕时。

review-change 审查差异的质量，并发布与 SHA 绑定的凭据；audit-pr 使用该凭据，审计作为完整交付单元的 PR——确认 SPEC 承诺的所有内容都已具备、可追溯且通过检查。凭据缺失或已过时属于阻塞项，必须转回 /review-change，而不是在此处重新审议。

范围

整个拉取请求：分支相对于默认目标分支的变更，以及其 SPEC 和规划材料、路线图条目、文档映射、PR 正文、议题链接和 CI。默认目标是当前分支对应的 PR；也可指定 PR 编号以审核其他 PR。

第 0 步——发现项目和 PR（始终首先执行）

1. 项目约定。按照 Agent 指南中的工作流约定和文档映射操作，然后阅读本技能所需的内容：路线图和项目的验证关卡（类型检查／测试／构建／CI）。不要加载完整的功能／修复模板——本次审计只读取下方的 SPEC 作为规划材料（AC 14）。
2. **PR。**识别 PR 并完整阅读（根据项目的工作流约定使用代码托管平台 CLI——示例使用 gh）：

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

   如果没有提供 PR 编号，则解析当前分支对应的 PR（gh pr view --json ...）。如果尚不存在 PR，则审计该分支相对于默认目标分支的变更，并说明“尚未打开 PR”——约定仍然适用。
3. **SPEC。**找到适用的 SPEC——docs/features/<NN>-<slug>/（功能）或 docs/fix/<n>-<topic>/（修复）——以及其中存在的规划材料（PLAN.md、TASKS.md、progress.md、testing.md、known-issues.md、decisions.md）。SPEC 是判断“完成”含义的事实依据。

步骤 1 — 获取评审回执（始终先于任何门禁）

评审证据是 review-change 在 PR 上发布的、与 SHA 绑定的 REVIEW-PASS 回执——绝不能在此处重新评审。一起获取 headRefOid 和 PR 评论，然后找到携带标记 ``:

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

• 当前 — 标记中的 sha 与该快照的 headRefOid（当前头部 SHA）相同。将其范围/维度、验收覆盖情况、不变量结果和手动检查作为评审证据予以认可，然后评估以下交付门禁。
• 缺失 — PR 上没有匹配的标记 → 阻塞项：头部没有评审证据；转交给 /review-change。
• 过期 — 存在标记，但其 sha 与 headRefOid 不同。在作废之前，先应用范围感知判定规则（fix/286，#182 AC 3/9）：记录了范围清单（标记中的 scope=<64-hex>）的回执，在头部差异（回执 sha → 头部，git diff --name-only）仅涉及非影响路径时仍视为当前——封闭类别（会话日志 docs/LOGS.md、Agent 工具状态/记忆 .engram/、.pi/、.serena/）由 scripts/scope-manifest.mjs 管理；任何不匹配已命名类别的路径都视为有影响。运行 bun scripts/review-receipt.mjs verify --pr <N>——该命令会在本地计算差异，并返回 current（退出码 0）或 stale（退出码 4，并列出有影响的路径）。没有 scope 属性的旧版回执、有影响的差异或无法解析的差异都会使回执失效 → 阻塞项：转交给 /review-change 重新评审。不要用本地 git diff 覆盖 PR 头部比较——差异检查只会让带范围的回执继续保持当前状态；绝不会为缺少 scope 的回执凭空赋予有效性。

绝不要根据差异编写、重建或“抽查”评审来清除缺失/过期的回执——这是 review-change 的职责；在此处重新争论评审维度，恰恰违背了回执门禁的目的（AC 13）。

渐进式加载 — 强制审核流程

参考资料的允许列表严格限定为下面链接的六个路径。绝不要臆造或读取其他 references/ 路径。完成发现和步骤 1 的回执检查后，每次审核都必须按顺序加载并应用以下五项必需资源：

1. 01 合并门禁，用于交付、CI、可追溯性、评审回执和可合并性证据。
2. 02 闭环与范围门禁，用于能力闭环和缩减范围的来源依据。
3. 03 审核流程，用于收集、判定、持久化阻塞项，并发布与 SHA 绑定的 MERGE-READY 评论。
4. 在输出前阅读 04 结论，然后阅读 05 路由与防护措施。这些必需资源规定了 docs/workflow/REPOSITORY_STATE.md 的证据规则和架构不变量门禁。

只有在所声明的 forge 或 Agent 确实缺少某项已命名的原语时，才阅读 可移植性；否则跳过。项目产物 docs/workflow/REPOSITORY_STATE.md 是证据，不是技能参考。所有资源距离此文件都只有一跳。缺少证据或必需资源均属阻塞项；绝不要推断为通过。

合并所有权

此技能绝不执行合并，即使项目文档中包含 merge: auto、用户此前批准过合并，或工具保留了先前的权限。这些信号都不能改变此技能先读取的边界。

唯一的自动合并权限属于正在调用的 advance --continue --fullauto 运行中的 AUDIT 阶段。其 MERGE-READY 评论是证据，而非授权；仓库包装器会独立验证该评论、forge 当前的 head/default base、检查是否全部通过，以及在该 head 获取的 merge: fullauto 决策。包装器负责重新执行同步检查、管理瞬态状态、执行合并、清理，以及发布自动合并 PR 评论。单独／手动调用此技能时，始终将 MERGE-READY URL 交给人工处理。

可移植性

转换 forge 命令，绝不更改门禁语义。使用 portability 中明确列出的回退方案。

与其他技能的关系

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        ──▶ unit-lane --fix
                               └─ deferral            ──▶ triage-issue

• 使用 review-change 的 REVIEW-PASS 回执（其范围／维度、验收覆盖情况、不变量结果、手动检查）以及 unit-lane／execute-phase 的产物（SPEC、阶段、文档、Closes #N）。
• audit-docs 用于跨文档一致性检查；audit-pr 用于逐 PR 检查合并就绪状态；product-audit 用于定期执行涵盖整个产品的全面审查。

完成条件

• 已使用评审回执：确认当前标记，或将缺失／过期的标记列为阻塞项并交由 /review-change 处理（此处绝不重新评审）。
• 每个适用的门禁都有通过／阻塞／不适用结论，并有引用证据支持。
• 报告单一的顶层结论（MERGE-READY 或 BLOCKED，并列出按优先级排序的阻塞项），标题中包含 PR 的完整 URL；每个阻塞项都已分派处理，并明确列出需要人工验证的事项。
• 如果结论为 MERGE-READY，则明确说明合并负责人：单独审计会将 URL 交给人工处理；正在运行的 advance --fullauto AUDIT 阶段会接收绑定 SHA 的结论，并负责后续的所有合并检查。
• 打印结束的 → Next: 区块（合并链接 → 然后通过 /unit-lane <unit> 或 /triage-issue 处理下一个单元；BLOCKED → 处理分派的修复，然后重新审计）。
• 未编辑、重构或合并任何内容。