@gtrabanco/pi-agentic-workflow 0.10.7 → 0.11.1

package/dist/extension/factory.d.ts

@@ -1,6 +1,7 @@
 import type { LoadedConfig } from "../config/load.js";
 import type { Catalogue } from "../routing/catalogue.js";
 import type { Router } from "../routing/dispatch.js";
+import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
 import type { ExtensionSurface, InvocationContext, ModelRef, RoutingControls } from "../routing/types.js";
 import type { HintStore } from "../routing/state.js";
 /**
@@ -43,5 +44,15 @@ export interface ExtensionDeps<M extends ModelRef = ModelRef> {
 export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     router: Router<M>;
     catalogue: Catalogue;
+    /**
+     * The Pi-free predicates the adapter (`index.ts`) binds to Pi's lifecycle
+     * events: the inline-receipt block guard and the dirty-worktree notice. They
+     * travel with the handle so the entry stays a thin translation layer and the
+     * decisions are unit-tested with no session (issue #182).
+     */
+    guards: {
+        receiptGuard: typeof receiptGuard;
+        dirtyWorktreeWarning: typeof dirtyWorktreeWarning;
+    };
 }
 export declare function createExtension<M extends ModelRef = ModelRef>(deps: ExtensionDeps<M>): ExtensionHandle<M>;

package/dist/extension/factory.js

@@ -1,6 +1,7 @@
 import { loadConfig } from "../config/load.js";
 import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
+import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
 import { SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 export function createExtension(deps) {
     const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
@@ -56,5 +57,5 @@ export function createExtension(deps) {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,
     });
-    return { router, catalogue };
+    return { router, catalogue, guards: { receiptGuard, dirtyWorktreeWarning } };
 }

package/dist/extension/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/load.js";
 import { createExtension } from "./factory.js";
+import { readGitStatusBounded } from "./receipt-guard.js";
 import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
 import { createHintStore, stateFilePath } from "../routing/state.js";
 import { runSettingsConsole } from "../settings/console.js";
@@ -97,7 +98,7 @@ function toRegistrar(pi) {
 export default function extension(pi) {
     const agentDir = getAgentDir();
     const hint = createHintStore({ path: stateFilePath(agentDir) });
-    const { router } = createExtension({
+    const { router, guards } = createExtension({
         registrar: toRegistrar(pi),
         // Resolved per call: the router must never hold a session-bound object
         // between turns, because Pi can hand a new session to the same extension.
@@ -126,7 +127,23 @@ export default function extension(pi) {
     });
     pi.on("model_select", (event) => router.noteModelSelect(event.model));
     pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));
-    pi.on("agent_settled", (_event, ctx) => void router.settle(toInvocationContext(ctx)));
+    // The inline-receipt path is impossible: a `gh pr comment` carrying a
+    // REVIEW-PASS / merge-ready marker is blocked before it runs, and the reason
+    // names the script that proves the receipt landed (issue #182).
+    pi.on("tool_call", (event) => {
+        const command = "command" in event.input && typeof event.input.command === "string" ? event.input.command : undefined;
+        return guards.receiptGuard({ toolName: event.toolName, command });
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        void router.settle(toInvocationContext(ctx));
+        // Terminal hygiene is said out loud once the turn is over; a clean tree
+        // stays silent. The probe is time-bounded (2000 ms) and swallows timeout,
+        // spawn error and non-zero status, so an unresponsive git can never park
+        // the settled turn — best-effort by construction (issue #182 F4).
+        const warning = guards.dirtyWorktreeWarning(readGitStatusBounded(ctx.cwd));
+        if (warning)
+            ctx.ui.notify(warning, "warning");
+    });
 }
 // Exported so the settings console (P4) names the same command without relisting it.
 export { SETTINGS_COMMAND };

package/dist/extension/receipt-guard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The inline-receipt guard and the dirty-worktree notice — the two Pi-free
+ * decisions the extension's lifecycle adapter binds (issue #182).
+ *
+ * `review-change` and `audit-pr` used to post their PR receipts through a bash
+ * heredoc: a model assembled the marker inline, ran `gh pr comment --body "…"`,
+ * re-read the thread and retried. Nothing proved the receipt landed, so a review
+ * could print `REVIEW-PASS` while the PR had no current marker. Two scripts now
+ * own that mechanically — `scripts/review-receipt.mjs emit` and
+ * `scripts/audit-pr-gate.mjs comment` — each posting the body from standard input,
+ * re-reading the PR and exiting 0 only when the marker names the reviewed head.
+ * This guard blocks the inline path before it runs, so the unverifiable route is
+ * impossible rather than discouraged.
+ *
+ * Pure on purpose: `index.ts` is the only file that imports Pi values, so these
+ * predicates compile and are tested with no session.
+ */
+/** The narrow slice of a Pi `tool_call` the guard reads. */
+export interface ToolCallLike {
+    toolName: string;
+    command?: string | undefined;
+}
+/** The Pi `tool_call` result shape: `block` plus an actionable `reason`. */
+export interface ReceiptGuardDecision {
+    block: boolean;
+    reason?: string;
+}
+/**
+ * The `tool_call` gate. Blocks exactly one shape: a bash command that invokes
+ * `gh pr comment` and carries a receipt marker as inline text. A `--body-file`
+ * invocation is the scripts' own path and is allowed; a command that merely
+ * mentions a marker (editing the skill docs) is allowed; every non-bash tool is
+ * allowed.
+ */
+export declare function receiptGuard({ toolName, command }: ToolCallLike): ReceiptGuardDecision;
+/**
+ * The `agent_settled` notice. `porcelain` is `git status --porcelain` output;
+ * an empty (or whitespace-only) string stays silent, and a non-empty one yields
+ * one concise warning naming what is dirty. Decision only — the adapter runs
+ * git and delivers the message.
+ */
+export declare function dirtyWorktreeWarning(porcelain: string): string | undefined;
+/**
+ * How long the settled-turn `git status` probe may run before it is abandoned.
+ * The probe is best-effort hygiene, not work: an unresponsive git must never
+ * park the turn the way the old unbounded `spawnSync` could (issue #182 F4).
+ */
+export declare const GIT_STATUS_TIMEOUT_MS = 2000;
+/**
+ * `git status --porcelain` for the settled-turn notice, time-bounded. A timeout,
+ * a spawn error and a non-zero exit all read as a clean worktree — the notice is
+ * best-effort by construction and must never fail a turn.
+ */
+export declare function readGitStatusBounded(cwd: string): string;

package/dist/extension/receipt-guard.js

@@ -0,0 +1,88 @@
+/**
+ * The inline-receipt guard and the dirty-worktree notice — the two Pi-free
+ * decisions the extension's lifecycle adapter binds (issue #182).
+ *
+ * `review-change` and `audit-pr` used to post their PR receipts through a bash
+ * heredoc: a model assembled the marker inline, ran `gh pr comment --body "…"`,
+ * re-read the thread and retried. Nothing proved the receipt landed, so a review
+ * could print `REVIEW-PASS` while the PR had no current marker. Two scripts now
+ * own that mechanically — `scripts/review-receipt.mjs emit` and
+ * `scripts/audit-pr-gate.mjs comment` — each posting the body from standard input,
+ * re-reading the PR and exiting 0 only when the marker names the reviewed head.
+ * This guard blocks the inline path before it runs, so the unverifiable route is
+ * impossible rather than discouraged.
+ *
+ * Pure on purpose: `index.ts` is the only file that imports Pi values, so these
+ * predicates compile and are tested with no session.
+ */
+import { spawnSync } from "node:child_process";
+/** `gh pr comment` as an invoked command, not as a quoted string elsewhere in it. */
+const GH_PR_COMMENT_RE = /\bgh\s+pr\s+comment\b/;
+const REVIEW_MARKER = "review-change:pass";
+const AUDIT_MARKER = "audit-pr:merge-ready";
+const BODY_FILE_FLAG = "--body-file";
+const REVIEW_REASON = "`gh pr comment` with an inline `review-change:pass` body is blocked: inline receipt bodies are unverifiable, so nothing proves the marker landed on the PR. " +
+    "Use `bun scripts/review-receipt.mjs emit --pr <N> --head <40-hex> …` instead — it posts the receipt, re-reads the PR, and exits 0 only when the marker names the reviewed head.";
+const AUDIT_REASON = "`gh pr comment` with an inline `audit-pr:merge-ready` body is blocked: inline receipt bodies are unverifiable, so nothing proves the marker landed on the PR. " +
+    "Use `bun scripts/audit-pr-gate.mjs comment --pr <N> --head <40-hex> …` instead — it posts the comment idempotently and confirms the marker names the audited head.";
+/**
+ * The `tool_call` gate. Blocks exactly one shape: a bash command that invokes
+ * `gh pr comment` and carries a receipt marker as inline text. A `--body-file`
+ * invocation is the scripts' own path and is allowed; a command that merely
+ * mentions a marker (editing the skill docs) is allowed; every non-bash tool is
+ * allowed.
+ */
+export function receiptGuard({ toolName, command }) {
+    if (toolName !== "bash")
+        return { block: false };
+    const text = command ?? "";
+    if (!GH_PR_COMMENT_RE.test(text))
+        return { block: false };
+    if (text.includes(BODY_FILE_FLAG))
+        return { block: false };
+    if (text.includes(REVIEW_MARKER))
+        return { block: true, reason: REVIEW_REASON };
+    if (text.includes(AUDIT_MARKER))
+        return { block: true, reason: AUDIT_REASON };
+    return { block: false };
+}
+/** How many porcelain lines the warning quotes before summarising the rest. */
+const WARNING_PREVIEW = 5;
+/**
+ * The `agent_settled` notice. `porcelain` is `git status --porcelain` output;
+ * an empty (or whitespace-only) string stays silent, and a non-empty one yields
+ * one concise warning naming what is dirty. Decision only — the adapter runs
+ * git and delivers the message.
+ */
+export function dirtyWorktreeWarning(porcelain) {
+    const lines = String(porcelain ?? "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return undefined;
+    const preview = lines.slice(0, WARNING_PREVIEW).join(", ");
+    const rest = lines.length > WARNING_PREVIEW ? `, +${lines.length - WARNING_PREVIEW} more` : "";
+    return `Uncommitted changes in the worktree (${lines.length}): ${preview}${rest} — commit or stash before this change is reviewed.`;
+}
+/**
+ * How long the settled-turn `git status` probe may run before it is abandoned.
+ * The probe is best-effort hygiene, not work: an unresponsive git must never
+ * park the turn the way the old unbounded `spawnSync` could (issue #182 F4).
+ */
+export const GIT_STATUS_TIMEOUT_MS = 2000;
+/**
+ * `git status --porcelain` for the settled-turn notice, time-bounded. A timeout,
+ * a spawn error and a non-zero exit all read as a clean worktree — the notice is
+ * best-effort by construction and must never fail a turn.
+ */
+export function readGitStatusBounded(cwd) {
+    const result = spawnSync("git", ["status", "--porcelain"], {
+        cwd,
+        encoding: "utf8",
+        timeout: GIT_STATUS_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return "";
+    return result.stdout ?? "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.10.7",
+  "version": "0.11.1",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.1.0
+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
@@ -34,6 +34,8 @@ independently evaluates only the delivery gates below.
   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
@@ -41,9 +43,9 @@ independently evaluates only the delivery gates below.
 ✓ 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
+✓ 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

package/skills/audit-pr/references/01_MERGE_GATES.md

@@ -16,6 +16,9 @@ A gate that can't be confirmed is a **blocker**, not a pass — never assume gre
 | **Closure integrity** | The governing **feature** SPEC's capability closure was taken and recorded — `design-feature` was actually run, not bypassed. Fix-governed PRs: `n/a` (no closure block by design). | A present `Capability closure` block has a blank row, or a resolved non-`n/a` row with no matching acceptance criterion. |
 | **Scope integrity (descope)** | An issue born during this unit that maps to an unmet SPEC acceptance criterion or phase task has a matching, user-approved, dated `## Amendments` entry — descoped scope was recorded, not silently exported. Detection is two-path: a slug/issue-number text match, **or** an issue linked from an `## Amendments` row (`#89`) — either is sufficient to enumerate the issue, so a descoped issue with a generic title/body is not invisible to the gate. | An issue born since branch divergence that references this unit (by either detection path) maps to an unmet criterion/task with no matching `## Amendments` entry, or an `## Amendments` row that is undated, unapproved, or unlinked to an issue. |
 | **Architectural invariants** | The **receipt** records the invariant result review-change took against the optional project invariant document; this gate confirms that result is explicit (`pass | blocker | n-a`) and does not reclassify it (AC 13). No document → `n/a: no project invariants declared`, not a blocker. | The receipt's invariant result is absent/ambiguous, or a recorded `blocker`/`violates`/`introduces`/`changes` lacks the cited decision the review surfaced. |
+| **Hygiene — tree clean** | `git status --porcelain` is empty at the audited head: every artifact is committed, so nothing rides along to the next conversation (the field failure of issue #182). | Any modified or untracked path — the blocker names each one. |
+| **Hygiene — branch pushed** | The branch is level with its remote, so the PR head the audit read is the head that was reviewed. | Local commits the forge has not seen. |
+| **Hygiene — PR ready** | The PR is not a draft. This is the one hygiene gate with a mechanical repair, so `audit-pr` flips it (`gh pr ready`) instead of reporting it. | Still a draft after the repair attempt. |
 
 > The review evidence is the receipt, never a re-review: verify the newest
 > `review-change:pass` marker's `sha` against the PR's head (Step 1). A current

package/skills/audit-pr/references/03_AUDIT_PROCESS.md

@@ -1,18 +1,24 @@
 ## Process
 
 1. **Gather** — Step 0: project contract, PR, SPEC + artifacts, CI status.
-2. **Consume the review receipt** — Step 1: fetch the PR's `headRefOid` and
-   comments in one query (`gh pr view <N> --json headRefOid,comments`) and take
-   the **newest** marker
-   `<!-- review-change:pass sha=<40-hex> contract=v1 -->`. Its `sha` must equal
-   that query's `headRefOid` current head SHA. Any mismatch is stale; do not
-   use a local diff to preserve a receipt for a different PR head.
-   - **current** → acknowledge scope/axes, acceptance coverage, invariant result,
-     manual checks; continue to the gates.
+2. **Consume the review receipt** — Step 1: run the receipt verifier, which
+   fetches `headRefOid` + comments and applies the currency rule itself:
+   `bun scripts/review-receipt.mjs verify --pr <N>` — exit `0` current, `3`
+   absent, `4` stale. Its `headRefOid` is the current head SHA: a marker for any
+   other SHA is stale, never preserved from a local diff.
+   - **current (0)** → acknowledge scope/axes, acceptance coverage, invariant
+     result, manual checks; continue to the gates.
    - **absent / stale** → **BLOCKER** (no review evidence at the head), routed to
      `/review-change`; never re-review from here.
-3. **Walk the contract** — evaluate every gate above against evidence. For each,
-   record pass / blocker / n-a with the specific artifact or check that proves it.
+3. **Walk the contract** — evaluate every gate above against evidence, recording
+   pass / blocker / n-a with the artifact that proves it. The three
+   terminal-hygiene gates (`tree-clean`, `branch-pushed`, `pr-ready`) are **read
+   from state, never asserted** — hygiene previously had no owner at merge time:
+   `bun scripts/audit-pr-gate.mjs hygiene --pr <N> --apply` (exit `0` clean, `2`
+   blocked). `--apply` performs the only mechanical repair there is (`gh pr
+   ready`, so a draft is flipped rather than reported); a dirty tree names its
+   paths and an unpushed branch its commit count — those stay the author's to fix.
+   Fold the three results into the gate map you decide on in step 5.
 4. **Confirm deferrals are real** — for anything postponed (an unchecked task, a
    review finding, a known issue), verify a tracked issue + trigger exists. A
    deferral with no destination is a blocker, not a pass.
@@ -40,30 +46,12 @@
    re-appended; a genuinely new blocker gets the next `Fn` id.
 7. **Post the MERGE-READY comment on the PR (MERGE-READY only).** The verdict
    must be visible on the PR itself — as a **comment**, never in a commit
-   message (a commit trailing "MERGE-READY" pollutes history and goes stale
-   the moment the branch moves). Write the body to a file (Markdown rule —
-   see Guardrails) and run
-   `gh pr comment <N> --body-file <path>` with exactly this body:
-
-   ```markdown
-   <!-- audit-pr:merge-ready sha=<head SHA> -->
-   ## ✅ audit-pr: MERGE-READY
-
-   - **Audited head:** `<head SHA>` · CI: <green|local-gate-green>
-   - **Review receipt:** `REVIEW-PASS` at `<head SHA>` (consumed, not re-reviewed)
-   - **Date:** <YYYY-MM-DD>
-   - **Before merge, a human should still verify:**
-     - <manual-verification item — or "nothing">
-
-   Any commit after `<head SHA>` voids this verdict — re-run `audit-pr`.
-   ```
-
-   **Idempotent:** first check the existing comments
-   (`gh pr view <N> --json comments`) for the `<!-- audit-pr:merge-ready -->`
-   marker — same SHA already commented → skip (say so); older SHA → post the
-   new comment (the newest marker wins). Never post a comment for a BLOCKED
-   verdict — blockers go in the chat report only, so the PR page never shows
-   a stale green flag.
+   message. Run `bun scripts/audit-pr-gate.mjs comment --pr <N> --head <head
+   SHA> --gates-json <gate map>`: it builds the fixed body, posts once, re-reads,
+   and **exits non-zero unless the newest `<!-- audit-pr:merge-ready sha=… -->`
+   marker names the head**. **Idempotent by marker** — same SHA skips, an older
+   SHA re-posts (newest wins) — and it **refuses to post for a BLOCKED verdict**,
+   so the page never shows a stale green flag.
 8. **Report** — the verdict block below, always headed by the PR's full URL.
    In an active `ship-roadmap --fullauto` AUDIT stage, return the verdict to the
    conductor; never run its merge wrapper from this skill.

package/skills/log-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: log-session
 user-invocable: true
-version: 2.1.0
+version: 2.2.0
 argument-hint: "[note to prepend to the entry]"
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -29,6 +29,7 @@ judgment. It must never reach for an expensive model.
 
 ```
 ✓ The entry was APPENDED to docs/LOGS.md (file edited, not just drafted) with accurate git facts
+✓ `bun scripts/session-close.mjs close` RAN and exited 0 (or 2, with the leftover paths named) — the entry is committed, not left riding along
 ✓ No past entry was edited
 ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
 ✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
@@ -93,27 +94,32 @@ the HEAD sha and start time at session open.
      review must chase (fix #157's F14). Write the actual state: "PR #N open,
      awaiting the human merge".
 
-4. **Append the entry** to `docs/LOGS.md`, newest at the bottom (append-only,
-   chronological). Use this format so the auto-hook entries and these stay
-   compatible:
-
-   ```markdown
-   ## <ISO-8601 timestamp> — <branch> — manual
-   - **Commits:** <n> (`<short-sha>…<short-sha>`)
-   - **Files:** <comma-separated paths, or a count if many>
-   - **Summary:** <what this session did>
-   - **Decisions:** <key choices + why; omit the line if none>
-   - **Next:** <the concrete next step>
+4. **Render the entry** — the mechanical facts (timestamp, branch, commit count
+   and range, files touched) are computed for you:
+
+   ```
+   bun scripts/session-close.mjs render --summary "<what this session did>" \
+     --decisions "<key choices + why>" --next "<the concrete next step>"
    ```
 
-   If the user passed a note as an argument, prepend it to the Summary.
+   It writes nothing: append its output to the **end** of `docs/LOGS.md`
+   (append-only, chronological) with your editing tool. Omit `--decisions` /
+   `--next` when there is nothing real to record — the script drops the line
+   rather than emitting an empty one. A user-supplied note is prepended to the
+   Summary.
+
+5. **Close the session** — commit the entry and prove the tree is clean:
+
+   ```
+   bun scripts/session-close.mjs close
+   ```
 
-5. **Commit policy.** `docs/LOGS.md` is documentation — keep it coherent, but do
-   **not** open a PR just for a log entry. If you're mid-feature on a branch,
-   the entry rides along with the next commit. If the working tree is otherwise
-   clean and the user wants it persisted, ask before committing a standalone
-   `docs(log): session <date>` commit. Never push without the project's push
-   convention.
+   It refuses unless `docs/LOGS.md` was **appended to** (a rewritten or truncated
+   log is not a session entry), commits that one file as
+   `docs(log): <the appended summary>`, and reports every path still uncommitted:
+   exit `0` clean, `2` the named leftovers are still dirty, `1` refused. Do not
+   open a PR just for a log entry, and never `git add -A` here — a concurrent
+   conversation's work must not be swept into a log commit.
 
 ## Guardrails
 

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.5.1
+version: 3.6.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -24,14 +24,16 @@ Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-e
 For a final PR review, the turn is incomplete until this additional box passes:
 
 ```text
-✓ Decision: REVIEW-PASS + PR exists → `gh pr comment <N> --body-file <path>` RUN;
-  then `gh pr view <N> --json comments` RUN and the newest exact-HEAD
-  `review-change:pass` marker is confirmed before printing `→ Next:`
+✓ Decision: REVIEW-PASS + PR exists →
+  `bun scripts/review-receipt.mjs emit --pr <N> --head "$(git rev-parse HEAD)" …`
+  RUN and exited 0 — the script posts the SHA-bound comment, re-reads the PR
+  comments, and exits non-zero unless the newest exact-HEAD
+  `review-change:pass` marker is confirmed, so its exit code IS this box
 ```
 
 The receipt closeout is a precondition of the report, not a follow-up: do not
-print the fixed report block until the comment is current. A clean report
-without that current receipt must not recommend `/audit-pr`.
+print the fixed report block on a non-zero exit. A clean report without a
+current receipt must not recommend `/audit-pr`.
 
 For `REVIEW-FAIL` or `NEEDS-DECISION`, list every open finding ID in the closing
 recommendation, joined with ` + `; the review must never hand off only the first

package/skills/review-change/references/PERSIST_AND_DECIDE.md

@@ -45,48 +45,33 @@ exact command tokens.
    `REVIEW-PASS` with a PR, the receipt comment (step 12) — it never runs a
    fold, executes a phase, or edits source (see the review-end turn boundary in
    the SKILL.md Turn contract).
-12. **Close out the final-review receipt before reporting.** First derive the
-   `Decision` from step 7 and persist step 11. Then, before printing any line of
-   the fixed report block or the `→ Next:` block, complete the receipt action
-   below. The receipt is a precondition of the report, not a follow-up.
-
-   The durable, audit-consumable receipt is one idempotent SHA-bound PR comment
-   (D6, D7). **Only on `Decision: REVIEW-PASS` AND when the PR exists** (the
-   mandatory final review; the PR always exists by then — the phase gate created
-   it). `REVIEW-FAIL` and `NEEDS-DECISION` post **no** passing receipt; continue
-   to step 13 after recording that status.
-
-   The reviewed head SHA is the value frozen by `git rev-parse HEAD` in the
-   review process. Resolve the PR identity immediately before this action with
-   `gh pr view --json number,headRefOid`. No PR → take the documented pre-PR
-   path. With a PR, its `headRefOid` **must equal the reviewed head SHA** before
-   querying or posting comments. A mismatch means the candidate changed during
-   review: do not post a receipt and re-run `/review-change` at the PR head.
-
-   For `REVIEW-PASS` with a PR, write the body below to a **temporary** Markdown
-   file (e.g. `$TMPDIR/review-receipt.md`), then run
-   `gh pr comment <N> --body-file <path>` — never inline `--body`, never commit
-   the file into the branch. Before posting, run `gh pr view <N> --json comments`
-   and inspect the newest matching marker. Same SHA → skip the post; older or
-   absent SHA → post. After posting, run the same comment query again and confirm
-   the newest marker equals the reviewed head SHA. If that confirmation fails,
-   retry the receipt action; do not print a `REVIEW-PASS` report or recommend
-   `/audit-pr` while the receipt is not current.
+12. **Close out the final-review receipt before reporting.** Derive the
+   `Decision` from step 7 and persist step 11 first. Then — **only on
+   `Decision: REVIEW-PASS` and when the PR exists** — run the receipt emitter,
+   which is a precondition of the report, not a follow-up:
+
+   ```
+   bun scripts/review-receipt.mjs emit --pr <N> \
+     --head "$(git rev-parse HEAD)" --scope "<reviewed surface>" \
+     --axes "<axes run and skipped>" --coverage "<criterion-to-evidence>" \
+     --invariants pass|n/a --proposals <n> --manual "<items or none>"
+   ```
 
-   Use **exactly** this body:
+   The script is the contract: it refuses a PR whose `headRefOid` differs from
+   the reviewed head, posts the one idempotent SHA-bound comment (skipping an
+   identical one), re-reads the comments, and **exits non-zero unless the newest
+   `<!-- review-change:pass sha=… contract=v1 -->` marker names the reviewed
+   head**. Never hand-assemble the body and never post it inline; the fixed body
+   lives in the script and its suite. A non-zero exit means no receipt landed —
+   fix that before printing anything in step 13, and never recommend
+   `/audit-pr` while the receipt is not current.
 
-   ```markdown
-   <!-- review-change:pass sha=<head SHA> contract=v1 -->
-   ## review-change: REVIEW-PASS
+   `REVIEW-FAIL` and `NEEDS-DECISION` post **no** passing receipt: record the
+   status and continue to step 13. No PR → the documented pre-PR path, and the
+   receipt box reads `n/a: no PR`.
 
-   - Reviewed head: `<head SHA>`
-   - Scope and applicable axes: <compact list>
-   - Acceptance coverage: concise criterion-to-evidence summary
-   - Architectural invariants: pass | n/a
-   - Current-unit findings open: 0
-   - Future-capability proposals: <count; no issues created>
-   - Manual verification: <items or none>
-   ```
+   Read-only check, any time: `bun scripts/review-receipt.mjs verify --pr <N>`
+   prints `current | absent | stale` and exits `0 | 3 | 4`.
 
 13. **Report block — Return exactly this structure** after step 12 succeeds
    (fixed chat-report block; this is not the end of the turn):