opencode-workflow-guard 1.14.0 → 1.14.1

package/README.md

@@ -45,7 +45,7 @@ WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run policy probes with Ope
 
 The plugin enforces **24 deterministic policy rules** across four main pillars:
 
-* **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, enforces secondary review approval before PR creation by default, and requires PR changelogs / changesets.
+* **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, enforces secondary review approval (bound to the reviewed worktree content) before PR creation by default, and requires PR changelogs / changesets.
 * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks concurrent direct edits to the same canonical file across sessions, requires same-session fresh reads before `edit`/`write` can replace existing files, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
 * **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and `../` escape checks), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (`vim`, `nano`, `sudo`), and guards against dangerous package manager flags.

package/docs/agents/lessons.md

@@ -0,0 +1,9 @@
+# Agent loop lessons
+
+Append-only, evidence-backed lessons from base-loop iterations. Each item: id, evidence, one bullet.
+
+- **LL-001 — Git revision/pathspec argument order is a silent failure mode; assert on diff contents, not wrapper text.** Evidence: `guard_review_rubric` in `src/lib/custom-tools.ts` passed `--` before the revision (`git diff -- <base>...HEAD`, `git diff -- HEAD~1`), so git parsed the revision as a pathspec: `git diff -- HEAD~1` returned 0 bytes while `git diff --no-ext-diff HEAD~1` returned 68,709 bytes, and a live rubric call returned 1,714 bytes with an empty `diff` block (12 rubric invocations present in the device audit log). No existing test caught it because the rubric tests asserted the static heading `Code Diff Under Review` rather than the diff body; the fix (revision before `--`, plus `--no-ext-diff`) is covered by a regression test that asserts a changed path/content marker, and post-fix the live rubric grew to 31,714 bytes with real diff markers.
+- **LL-002 — Don't tighten a shell-pattern gate by replacing a quote-agnostic raw-string detector with a parsed-invocation-only detector; a "fail-closed" rewrite regressed quote-wrapped forms and unresolvable refs.** Evidence: the branch-base staleness fix (archived, not merged, on `loop/branch-base-start-point`) judged `git switch -c new <base>` by its start point; the dispatcher's fallback was changed to require a delimiter before `git` (`(?:^|[\s;|&/])git\s+`), so `bash -c "git switch -c new"` and `sh -c '...'` stopped matching even though the previous `GIT_BRANCH_CREATE_RE` raw regex matched the quoted text and ran the HEAD check. Separately, an unresolvable/variable start point (`git switch -c new $START`) passed because `rev-list` failed and the check reported not-behind, losing the old HEAD backstop. Four review rounds each surfaced another spelling (attached `-bnew`, `-B`/`-C`/`--force-create`, option reordering, `@`/`refs/heads/` aliases, quote wrappers, `$VAR`, `git -C<dir>`), showing branch-create detection needs a proper shell-token extraction or the original conservative HEAD check — not incremental regex patching. Negative result archived with the 1006-passing suite (the passing tests only prove the covered spellings); lesson: for adversarial shell gates, keep at least the pre-existing conservative detector as a fallback and add fail-closed handling for unresolvable operands rather than removing coverage.
+- **LL-003 — A freshness gate that only learns from reads makes agents re-read their own writes; seed observations from successful mutations, gated on actual change.** Evidence: the stale-write gate (`src/policies/stale-write.ts`) recorded per-session fingerprints only from successful `read`, so a follow-up `edit` to a file the session had just created or written was blocked with "has not been read by this session" — the top guard block on this device (64 of the audit's `stale_write` decisions, including agent-authored temp scripts such as `order-processing/.tmp-rsi-iter7/step1-transform.js`). The fix adds `recordMutationObservation(path, sessionID, beforeDigest)` called from the V1/V2 after-hooks over the existing post-edit snapshots; it seeds only when the pre/post digest differs, so no-op/failed calls seed nothing and external changes after the mutation still block (tests: write-then-edit allowed, edit-chained allowed, external change blocked, no-op `apply_patch` does not seed a later edit). Lesson: when a concurrency/freshness gate is keyed on prior observation, treat the session's own successful mutation as an observation of the resulting bytes (gated on the bytes actually changing), or it will generate pure-friction re-read loops.
+- **LL-004 — A token detector must distinguish command position from argument position; argument-position matches generate false positives that eventually block the guard's own tooling.** Evidence: `checkProcessMonitorCommand` (`src/policies/shell-safety.ts`) matched the monitor word anywhere as a whitespace-delimited token, so an Azure key-vault secret lookup whose `--name` value was that literal word was blocked as an "interactive process monitor" (device audit, `interactive_tty`), and during this loop the stale installed detector blocked a verification command and a commit whose text merely contained the word — proving the defect against real tooling. The fix flags only the executable of a quote-aware segment after wrapper unwrapping (`sudo`/`env`/`timeout`/…), handles `busybox <cmd>`, mirrors the pager recursion for `eval`/`sh -c`, scopes the batch-mode exemption to the monitor's own flags, and documents residual indirection (`watch`/`xargs`/`man`, `find -exec`/`su -c`, shell loop bodies) plus the pre-existing decode-escape quirk. Lesson: when a detector classifies a token as a command, verify it is in command position (executable after wrappers), and test both the false-positive argument case and the detection cases it replaced.
+- **LL-005 — Lifecycle tools must handle the partially-gone state idempotently, not just the happy path.** Evidence: `cleanupGitWorktree` (`src/lib/worktree.ts`) returned "Worktree path '...' does not exist." for a registered worktree whose directory was missing, so the prunable admin entries that `git worktree list` shows after a manual removal, a crashed add, or external cleanup could not be cleared through the tool. The fix validates ownership first and, for a missing registered path, deregisters the stale entry with `git worktree prune` (exit status reported via `describeGitFailure`) and returns success; outside-storage, unregistered, and primary-tree cases stay refused and no raw deletion is used. Tests assert the prunable state exists before cleanup, that cleanup succeeds and deregisters, and that an unregistered missing path is still refused. Lesson: a create/cleanup pair should treat "the artifact's directory/state is partly gone" as a first-class cleanup case (deregister what exists, refuse what is outside the owned scope), or agents accumulate stale metadata they cannot clear.

package/docs/installation.md

@@ -127,6 +127,8 @@ OpenCode's model/provider request timeout is separate from Workflow Guard. In Op
 
 Workflow Guard enforces secondary review approval (`requireReview`) by default during PR creation (`gh pr create` and `az repos pr create`). Before a pull request can be opened, an agent must invoke a secondary review subagent and record passing review approval using `record_review` evaluated against `guard_review_rubric`.
 
+The recorded verdict is bound to the reviewed repository content (commit hash + tracked-content worktree fingerprint of the directory it was recorded against), and the PR preflight accepts any approval whose binding matches the tree the PR would publish. A review recorded by a subagent rooted in a linked git worktree therefore satisfies a `pr create` run from that worktree, even from a different session than the one that spawned the reviewer. Review freshness is scoped to tracked content: deleting an untracked scratch file does not invalidate an approval, but any tracked edit or new commit does. Because reviewer agents are frequently configured with read-only toolsets that exclude `record_review`, the tool accepts recorders of any session type and binds the verdict to the recording session's directory; the audit trail records who recorded it and where it is bound.
+
 To opt out of the PR secondary review gate for a project, set `requireReview: false` in `.opencode/workflow-guard.json`:
 
 ```json

package/docs/policies.md

@@ -18,7 +18,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - **Durable Planning Context Discovery:** `guard_next_tasks` prefers a repository-root `TODO.md`; when it is absent, it reads conventional `ROADMAP.md`, `PLAN.md`, `TASKS.md`, `BACKLOG.md`, their `docs/` counterparts, and Markdown files under `docs/plans/`. The tool exposes candidate planning context without selecting, prioritizing, or sequencing tasks. These files never replace OpenCode's native runtime todo state.
 - **Subagent Mutation Budget:** Subagent sessions are protected by a mutation safety budget (`maxSubagentMutations` in project config or `WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS` env, default 100) to terminate runaway edit loops deterministically.
 - **Concurrent File Claims:** Direct `edit`, `write`, and `apply_patch` calls claim each canonical target for the tool-call lifetime. A different active session is blocked from racing the same file (including through symlink aliases); claims are released after the call, with session idle/deletion as stale-claim cleanup when an after hook is missed. Shell writers are not covered, and isolated worktrees remain preferred for substantial parallel mutations.
-- **Stale-Write Protection:** A successful `read` records a same-session fingerprint for an existing regular file using its canonical path, filesystem identity, size, nanosecond mtime, and SHA-256 content digest. Before `edit` or `write` replaces an existing file, that fingerprint must exist and still match; otherwise the call is blocked and must re-read. New-file creation is allowed without a prior read. Fingerprints are not inherited between parent/subagent sessions and are cleared on session idle/deletion. `apply_patch` and shell writers are deliberately outside this bounded mechanism; the pre-execution comparison also cannot make external changes between the check and OpenCode's write atomic.
+- **Stale-Write Protection:** A successful `read` records a same-session fingerprint for an existing regular file using its canonical path, filesystem identity, size, nanosecond mtime, and SHA-256 content digest; a successful `edit`/`write` also records the resulting bytes (only when the file actually changed), since the session authored them, so iterating on a just-created or just-modified file needs no redundant re-read. Before `edit` or `write` replaces an existing file, that fingerprint must exist and still match; otherwise the call is blocked and must re-read. New-file creation is allowed without a prior read. Fingerprints are not inherited between parent/subagent sessions and are cleared on session idle/deletion. `apply_patch` and shell writers are deliberately outside this bounded mechanism (an `apply_patch` result still seeds the session observation, but its clobbering itself is not pre-checked); the pre-execution comparison also cannot make external changes between the check and OpenCode's write atomic.
 
 ### 2. No Pushes to Protected Branches
 - `git push ... main` and `git push ... master` are blocked in all shell commands, including direct refs, refspecs (`git push origin HEAD:main`, `git push origin feature/x:main`), deletion refspecs (`git push origin :main`), and forced refspecs (`git push origin +main`).
@@ -149,7 +149,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - Only **README.md** (root or package level) and files under **`docs/`** count as documentation updates; arbitrary markdown (e.g. `.changeset/*.md` fragments or `CHANGELOG.md`) does not satisfy this gate.
 
 ### 22. Non-Interactive Shell & TTY Hang Guard
-- Blocks commands that spawn interactive text editors (`nano`, `vim`, `emacs`), interactive pagers (`less`, `more`) including through common shell wrappers, interactive monitors (`top`, `htop`), interactive rebase/patch prompts (`git rebase -i`, `git add -p`), `sudo`, or package managers missing non-interactive confirmation flags (`npm init` without `-y`, `apt-get` without `-y`). Pager names appearing only in command arguments are not treated as pager execution.
+- Blocks commands that spawn interactive text editors (`nano`, `vim`, `emacs`), interactive pagers (`less`, `more`) including through common shell wrappers, interactive monitors (`top`, `htop`), interactive rebase/patch prompts (`git rebase -i`, `git add -p`), `sudo`, or package managers missing non-interactive confirmation flags (`npm init` without `-y`, `apt-get` without `-y`). Pager and monitor names appearing only as command arguments (for example `az keyvault secret show --name top` or `echo top`) are not treated as pager/monitor execution; monitors are only flagged in command position (after wrappers such as `sudo`/`env`/`timeout`, through `eval` and `sh -c`, and via `busybox`), and `top` batch mode stays allowed. Indirection this does not model (`watch`/`xargs`/`man`, `find -exec`/`su -c`, and shell loop bodies such as `while true; do top; done`) is a known limitation.
 - Prevents subshell agents from hanging indefinitely waiting for user stdin in background execution.
 - **Desktop Notifications:** Emits native OS notifications (Linux `notify-send`, macOS `osascript`) when a policy blocks a command or when verification runs finish, keeping developers informed when their terminal is backgrounded. Configurable via `WORKFLOW_GUARD_NOTIFY=0`.
 
@@ -189,6 +189,7 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 ### `guard_worktree_cleanup`
 - Commits a final snapshot of any remaining changes (`chore(worktree): auto-snapshot before cleanup`, excluding the plugin-created `node_modules` symlink) and then removes the worktree directory with `git worktree remove --force`.
 - **Ownership validation:** only registered worktrees of the current repository under the configured worktree storage directory can be cleaned up; arbitrary directories, other repositories' worktrees, and the primary working tree are refused. A failed `git worktree remove` is an error, never a fallback to raw directory deletion.
+- **Idempotent for prunable entries:** a registered worktree whose directory is already gone (manual removal, a crashed add, external cleanup) is deregistered (`git worktree prune`, reported with its exit status on failure) and reported as cleaned, so stale admin entries that `git worktree list` shows as prunable can be cleared through the tool. The prune is repo-wide for the current repository: every worktree whose directory is missing at that moment is deregistered, so a temporarily unavailable path's admin entry can be dropped (worktree contents are never touched; use `git worktree repair` if a path returns).
 - **Lossless by construction:** if the snapshot commit cannot be established (failing hook, missing identity, lock error), cleanup aborts and the worktree is left fully intact.
 
 ### Hook-Context Safety
@@ -197,6 +198,8 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 ### Inspection Tools
 - `guard_status`, `guard_audit`, `guard_why`, `guard_review_rubric`, `record_review`, `guard_review_followups`, and `guard_review_followup_resolve` provide runtime introspection of guardrail state, audit entries, block explanations, reviewer rubric definitions, reviewer decisions, and durable local review debt. `guard_status` also exposes the effective Ralph opt-in, iteration budget, and calling-session outcome when applicable.
 - **Priority-Ranked Review Gate:** Secondary review approval (`requireReview`) is enforced by default during PR preflight (`gh pr create` / `az repos pr create`). Before creating a pull request, a secondary reviewer subagent must evaluate the changes using `guard_review_rubric` and record approval with `record_review`. Approvals that include active P0 (blocker) or P1 (major defect) issues are rejected until blockers are resolved. Projects can opt out via `.opencode/workflow-guard.json` (`{ "requireReview": false }`) or environment variable `WORKFLOW_GUARD_REQUIRE_REVIEW=0`. Conversely, `WORKFLOW_GUARD_REQUIRE_REVIEW=1` forces the review requirement regardless of project config.
+- **Review binding is content, not session identity:** a recorded approval satisfies the PR preflight when its binding (same repository, same commit hash, same tracked-content worktree fingerprint) matches the tree the PR would publish - regardless of which session records the verdict or creates the PR. Reviewers record from subagent sessions (binding the verdict to their parent or their own directory) and sessions can move between directories (`session_move`) or spawn subagents from other roots, so keying the gate on the PR-creating session's ID made the documented flow impossible to satisfy from linked worktrees. Freshness is scoped to the reviewed diff (tracked content): untracked scratch-file cleanup and mutations in sibling worktrees cannot invalidate an approval, while any tracked edit or new commit does.
+- **`record_review` accepts any recorder session:** reviewer agents configured with a read-only toolset (e.g. glob/grep/read/webfetch only) cannot call `record_review` themselves, so the tool no longer rejects root/orchestrator sessions; the verdict binds to the recording session's resolved directory, the tool result echoes that binding, and the audit entry (`record_review.verdict`) records the binding key and recorder lineage (`recorderRole: root | subagent`). Prefer relaying through an independent secondary reviewer subagent; the tool result reminds the recorder when it runs from a root session. A verdict recorded against a directory without a computable tracked fingerprint (not a git repository) is rejected loudly and never recorded.
 - **Durable Lower-Priority Follow-ups:** Accepted review summaries containing a P2 or P3 finding are persisted in the project's local Workflow Guard SQLite database. Open findings are included in compacted agent context and remain open across sessions until explicitly resolved with `guard_review_followup_resolve`; they are not silently discarded with the review session.
 - **Privacy-Safe Local Telemetry:** Guard decisions remain in the local audit JSONL. Tool after-hook observations add `callID` and duration records for local diagnosis and performance analysis; the current hook API does not distinguish success from every failure path, so these records do not claim a success outcome. Command and patch bodies are never written to the journal; only their byte count and SHA-256 fingerprint are retained for correlation.
 

package/docs/troubleshooting.md

@@ -100,3 +100,13 @@ After the command reports `Detected server + tui targets`, confirm it reports re
   1. V2 message parts record the tool name in the `tool` field; V1 used `name`. Code reading `part.name` silently gets `undefined` on V2.
   2. V2's builtin tool registry contains only `read`, `glob`, `grep`, `edit`, `write`, `patch`, `shell`, `webfetch`, `websearch`, `question`, `skill`, `subagent`, and `execute`. There is no builtin `todowrite` (the V1 name), and the V1 `task` subagent tool was renamed to `subagent`. `todowrite`/`bash` tool parts observed in V2 sessions come from ACP agents (for example pi) that supply their own tools; those tools are not in the server-side registry and cannot be reached by `ctx.tool.transform`.
 - **Solution:** Read the tool name as `part.tool ?? part.name` and treat tool-part names as agent-reported, not as the builtin registry. `ToolEditor.update` ignores missing IDs, so enriching a tool that does not exist is a harmless no-op.
+
+---
+
+### 12. Review recorded with `record_review`, but `pr create` is still blocked
+
+- **Symptoms:** `record_review` returned "Review recorded as APPROVED" and `guard_status` showed a fresh `lastReview`, yet `gh pr create` / `az repos pr create` was blocked with "Passing secondary review approval is required"; or re-calling `record_review` returned success but `guard_status` still showed no fresh review.
+- **Root Cause (fixed by content binding):** The PR preflight previously also required the review's target session to equal the PR-creating session's ID. `record_review` records from a secondary session (binding the verdict to its parent or its own directory), sessions can move between directories mid-flight (`session_move`), and subagents spawn from other roots — so a review recorded against a linked git worktree could never satisfy a PR created from another session there. Mutation invalidation additionally erased the whole review record on any mutation, including unrelated untracked-file cleanup.
+- **Binding rule:** a recorded approval satisfies the preflight when its binding matches the tree the PR publishes — same repository, same commit hash, same tracked-content worktree fingerprint. Review freshness is scoped to tracked content, so deleting an untracked scratch file does not invalidate it; a tracked edit or new commit does. When the tracked fingerprint is unchanged but HEAD moved (for example a review recorded with changes already staged, then committed), the preflight names the commit drift specifically.
+- **Diagnosis:** `guard_audit` now records the binding key (workspace, commit hash, fingerprint prefix, recorder session and `recorderRole`) on every `record_review.verdict` entry, and a `pr-preflight.review-binding` entry when a PR preflight accepts a review. If a verdict cannot bind at all (directory is not a git repository), `record_review` rejects loudly with the reason instead of returning a success string.
+- **Worktree creation failure leaving a branch behind:** `guard_worktree_create` failures previously surfaced only git's stderr (often checkout progress) and could leave a half-created branch. Failures are now reported with git's exit status, the created branch is rolled back (pre-existing branches are preserved), and stale worktree admin entries are pruned only for the newly-created path. A live registered worktree whose sanitized name collides with the requested branch is left fully intact — rollback never removes pre-existing worktrees. Large checkouts that exceed the 15s timeout can set `WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/custom-tools.ts

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 import { spawnSync } from "node:child_process";
-import type { LearningEvidenceKind } from "./types.ts";
+import type { AuditEntry, LearningEvidenceKind } from "./types.ts";
 import type { ProjectMemoryStore } from "./project-memory.ts";
 import {
 	exportProjectKnowledge,
@@ -34,7 +34,7 @@ import {
 } from "./state.ts";
 import { getRalphOutcome } from "../policies/continuation.ts";
 import { loadProjectConfig, projectRootKey } from "./project-config.ts";
-import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint } from "./verify.ts";
+import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { buildReviewRubric } from "./review.ts";
 import { createGitWorktree, cleanupGitWorktree } from "./worktree.ts";
 import { branchHasDocumentationChange } from "../policies/docs.ts";
@@ -218,7 +218,12 @@ export function createCustomTools(options: {
 				const verifyCommand = detectVerifyCommand(root);
 				const verifyFresh = Boolean(lastV && verifyEvidence && lastV.passed && lastV.command === verifyCommand && isEvidenceFresh(verifyEvidence, subject, lastMut));
 				const reviewRequired = isReviewRequired(root);
-				const reviewFresh = Boolean(lastR && reviewEvidenceRecord && lastR.passed && isEvidenceFresh(reviewEvidenceRecord, { ...subject, sessionID: lastR.targetSessionID }, lastMut));
+				// Review freshness is content-scoped, matching the PR preflight:
+				// the approval covers the tracked tree it reviewed, so it stays
+				// fresh until that content changes. Untracked scratch cleanup
+				// (or mutations in a sibling worktree) must not read as stale,
+				// while any tracked edit or new commit does.
+				const reviewFresh = Boolean(lastR && reviewEvidenceRecord && lastR.passed && isEvidenceFresh(reviewEvidenceRecord, { ...subject, worktreeFingerprint: getTrackedWorktreeFingerprint(root), sessionID: lastR.targetSessionID }, 0));
 				const documentationRequired = isDocumentationRequired(root);
 				const outstandingRequirements = [
 					...(verifyCommand && !verifyFresh ? ["verification"] : []),
@@ -258,18 +263,43 @@ export function createCustomTools(options: {
 				directory: tool.schema.string().optional().describe("Target repository directory being reviewed (defaults to parent session's repository or active directory)"),
 			},
 			execute: async (args, toolContext) => {
-				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict } });
-				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
-				if (!parentSessionID) { auditVerdict("rejected", "missing_parent_session"); return "[workflow-guard] Review rejected: record_review must be called from a secondary/subagent session."; }
+				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string, binding?: NonNullable<AuditEntry["evidence"]>["binding"]) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict, ...(binding ? { binding } : {}) } });
 				const axesRefs = ["test integrity", "task completeness", "cleanliness", "security", "platform"];
 				const referenced = axesRefs.filter((axis) => args.summary.toLowerCase().includes(axis));
 				if (referenced.length < 3) { auditVerdict("rejected", "insufficient_rubric_axes"); return `[workflow-guard] Review rejected: summary must reference the review axes (found ${referenced.length}/5). Call guard_review_rubric to get the rubric, evaluate each axis, and include findings per axis in the summary.`; }
 				if (args.passed && /(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) { auditVerdict("rejected", "approval_contains_blocker"); return "[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. Resolve all P0/P1 issues before approving or record review with passed=false."; }
+				// Any session may record a verdict so that reviewer agents whose
+				// toolset lacks record_review can have their verdict relayed.
+				// The verdict is bound to the reviewed DIRECTORY content (commit
+				// hash + tracked worktree fingerprint); the recorder's lineage is
+				// captured in the audit trail. The review-before-PR requirement
+				// itself is unchanged.
 				const reviewWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext.sessionID, directory: args.directory, fallback: toolContext.worktree || toolContext.directory || effectiveRoot });
-				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, reviewWorkspace);
-				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(reviewWorkspace) });
-				auditVerdict(args.passed ? "approved" : "changes_requested", args.passed ? "approved" : "changes_requested");
-				return args.passed ? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}.` : `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
+				const bindingFingerprint = getTrackedWorktreeFingerprint(reviewWorkspace);
+				if (!bindingFingerprint) {
+					auditVerdict("rejected", "review_workspace_unbindingable", { workspace: reviewWorkspace, recorderSessionID: toolContext.sessionID });
+					return `[workflow-guard] Review rejected: the verdict cannot be bound because no tracked-content fingerprint is available for '${reviewWorkspace}' (not a git repository, or git is unavailable). The verdict was NOT recorded. Call record_review with 'directory' set to the reviewed repository worktree, or run it from a session rooted there.`;
+				}
+				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
+				const bindingCommitHash = getCurrentGitCommitHash(reviewWorkspace);
+				const binding = {
+					workspace: reviewWorkspace,
+					commitHash: bindingCommitHash,
+					worktreeFingerprint: bindingFingerprint.slice(0, 16),
+					recorderSessionID: toolContext.sessionID,
+					recorderRole: parentSessionID ? ("subagent" as const) : ("root" as const),
+					targetSessionID: parentSessionID ?? toolContext.sessionID,
+				};
+				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID ?? toolContext.sessionID, reviewWorkspace);
+				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: bindingCommitHash });
+				auditVerdict(args.passed ? "approved" : "changes_requested", args.passed ? "approved" : "changes_requested", binding);
+				const recorderNote = parentSessionID
+					? `Recorded by secondary session ${toolContext.sessionID} for parent ${parentSessionID}.`
+					: `Recorded by root session ${toolContext.sessionID}; prefer relaying through an independent secondary reviewer subagent when one is available.`;
+				const boundTo = `Bound to ${reviewWorkspace} (commit ${bindingCommitHash?.slice(0, 12) ?? "unversioned"}, tracked fingerprint ${bindingFingerprint.slice(0, 12)}).`;
+				return args.passed
+					? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}. ${boundTo} ${recorderNote}`
+					: `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}. ${boundTo} ${recorderNote}`;
 			},
 		}),
 		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups (technical debt) for this project. Proactively check during planning or before final verification to address open findings.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
@@ -285,8 +315,8 @@ export function createCustomTools(options: {
 				const bases = sanitizedBase ? [sanitizedBase] : ["origin/main", "origin/master", "main", "master"];
 				const rubricWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext?.sessionID, directory: args?.directory, fallback: toolContext?.worktree || toolContext?.directory || effectiveRoot });
 				let diffText = "";
-				for (const base of bases) { const res = spawnSync("git", ["diff", "--", `${base}...HEAD`], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
-				if (!diffText) { const last = spawnSync("git", ["diff", "--", "HEAD~1"], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
+				for (const base of bases) { const res = spawnSync("git", ["diff", "--no-ext-diff", `${base}...HEAD`], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
+				if (!diffText) { const last = spawnSync("git", ["diff", "--no-ext-diff", "HEAD~1"], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
 				return buildReviewRubric(diffText);
 			},
 		}),

package/src/lib/guard-dispatcher.ts

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadReviewCache, loadVerifyCache } from "./audit.ts";
+import { audit, loadVerifyCache } from "./audit.ts";
 import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
 import { findGitRoot, isSameGitRepo, projectRootKey } from "./project-config.ts";
 import {
-	getLastReviewResult,
+	getLastReviewResultForWorkspace,
 	getLiveControlPlaneRoots,
 	getSdkClient,
 	getWorkspaceRoot,
@@ -15,7 +15,6 @@ import {
 	recordMutation,
 	recordVerifyResult,
 	sessionMutationTimestamps,
-	sessionReviews,
 	sessionVerifyResults,
 } from "./state.ts";
 import {
@@ -34,6 +33,7 @@ import {
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
 	getGitWorktreeFingerprint,
+	getTrackedWorktreeFingerprint,
 	runVerify,
 	resolveVerifyTimeoutMs,
 	snipVerifyOutput,
@@ -440,16 +440,45 @@ export async function guardToolCallImpl(
 				if (mergedStatus.merged) preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
 			}
 			if (isReviewRequired(prRoot)) {
-				let review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
-				if (!review) {
-					const diskCached = loadReviewCache();
-					if (diskCached && diskCached.passed && diskCached.workspace && (projectRootKey(diskCached.workspace) === projectRootKey(prRoot) || isSameGitRepo(diskCached.workspace, prRoot))) {
-						review = diskCached;
+				// Review evidence binds to the reviewed repository CONTENT: a
+				// passing approval satisfies this PR when its recorded subject
+				// (same repository, same commit hash, same tracked-content
+				// worktree fingerprint) matches the tree this PR would publish.
+				// It deliberately does NOT bind to the PR-creating session's ID:
+				// record_review records from a secondary session (binding the
+				// verdict to the recorder's parent or its own directory), and
+				// sessions can move between directories (session_move) and
+				// spawn subagents from many roots, so the previous
+				// session-identity requirement made the documented
+				// review->PR flow impossible to satisfy from linked worktrees.
+				// Content binding is the security property; the requirement
+				// itself is not removed or weakened.
+				const prCommitHash = getCurrentGitCommitHash(prRoot);
+				const prFingerprint = getTrackedWorktreeFingerprint(prRoot);
+				const review = getLastReviewResultForWorkspace(prRoot);
+				const matchedReview = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: prCommitHash, worktreeFingerprint: prFingerprint, sessionID: review.targetSessionID }, 0) ? review : undefined;
+				if (matchedReview) {
+					if (!context?.simulate) {
+						audit({
+							ts: new Date().toISOString(),
+							sessionID: context?.sessionID,
+							tool: "pr-preflight.review-binding",
+							decision: "allow",
+							phase: "event",
+							reason: "review_evidence_matched",
+							evidence: {
+								evidenceId: reviewEvidence(matchedReview).id,
+								reviewer: matchedReview.reviewer,
+								reviewTimestamp: matchedReview.timestamp,
+								binding: {
+									workspace: projectRootKey(prRoot),
+									commitHash: prCommitHash,
+									worktreeFingerprint: prFingerprint?.slice(0, 16),
+								},
+							},
+						});
 					}
-				}
-				const prFingerprint = getGitWorktreeFingerprint(prRoot);
-				const reviewMatchesContext = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: getCurrentGitCommitHash(prRoot), worktreeFingerprint: prFingerprint, sessionID: review.targetSessionID }, 0) && (!review.targetSessionID || review.targetSessionID === context?.sessionID);
-				if (!reviewMatchesContext) {
+				} else {
 					// When an approval exists but cannot be matched to this
 					// worktree, the message must name the actual cause instead
 					// of the generic "review required" (which sends the agent
@@ -457,13 +486,21 @@ export async function guardToolCallImpl(
 					// Cause attribution only makes sense for approvals of THIS
 					// repository; a review of another repo is not evidence here.
 					const reviewIsForThisRepo = typeof review?.workspace === "string" && (projectRootKey(review.workspace) === projectRootKey(prRoot) || isSameGitRepo(review.workspace, prRoot));
-					const sameRepoApproval = review && review.passed === true && reviewIsForThisRepo ? review : undefined;
-					if (sameRepoApproval && prFingerprint === undefined) {
+					const sameRepoReview = review && reviewIsForThisRepo ? review : undefined;
+					if (sameRepoReview && !sameRepoReview.passed) {
+						preflightFailures.push(`The most recent secondary review for this repository (by '${sameRepoReview.reviewer}') requested changes; address the findings and obtain a fresh passing approval with record_review.`);
+					} else if (sameRepoReview && prFingerprint === undefined) {
 						preflightFailures.push("Worktree fingerprint could not be computed (git unavailable or worktree unreadable), so review evidence cannot be bound to this worktree; resolve worktree readability and re-run the secondary review.");
-					} else if (sameRepoApproval && !sameRepoApproval.worktreeFingerprint) {
-						preflightFailures.push(`The recorded review approval from '${sameRepoApproval.reviewer}' has no worktree fingerprint binding (recorded against an unreadable worktree or an older guard version); re-run the secondary review and record it with record_review.`);
-					} else if (sameRepoApproval && sameRepoApproval.worktreeFingerprint !== prFingerprint) {
-						preflightFailures.push(`The recorded review approval from '${sameRepoApproval.reviewer}' does not match the current worktree contents (worktree fingerprint changed after review); re-run the secondary review and record it with record_review.`);
+					} else if (sameRepoReview && !sameRepoReview.worktreeFingerprint) {
+						preflightFailures.push(`The recorded review approval from '${sameRepoReview.reviewer}' has no worktree fingerprint binding (recorded against an unreadable worktree or an older guard version); re-run the secondary review and record it with record_review.`);
+					} else if (sameRepoReview && sameRepoReview.worktreeFingerprint !== prFingerprint) {
+						preflightFailures.push(`The recorded review approval from '${sameRepoReview.reviewer}' does not match the current worktree contents (tracked content changed after review); re-run the secondary review and record it with record_review.`);
+					} else if (sameRepoReview && sameRepoReview.commitHash && prCommitHash && sameRepoReview.commitHash !== prCommitHash) {
+						// Tracked fingerprint can be unchanged while HEAD moves
+						// (for example a review recorded with changes already
+						// staged, then committed): name the commit drift instead
+						// of the generic review-required message.
+						preflightFailures.push(`The recorded review approval from '${sameRepoReview.reviewer}' is bound to commit ${sameRepoReview.commitHash.slice(0, 12)} but this worktree is at commit ${prCommitHash.slice(0, 12)}; re-run the secondary review at the current commit and record it with record_review.`);
 					} else {
 						preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
 					}

package/src/lib/state.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
 import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
-import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
+import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { normalizeLiveControlPlaneRoots } from "./live-control-plane.ts";
 import type {
 	TodoSdkClient,
@@ -104,15 +104,14 @@ export function recordMutation(sessionID?: string, actorSessionID?: string): voi
 		sessionMutationTimestamps.set(id, lastMutationTimestamp);
 		sessionMutationCounts.set(id, (sessionMutationCounts.get(id) ?? 0) + 1);
 		sessionVerifyResults.delete(id);
-		sessionReviews.delete(id);
-	}
-	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID || lastReview.targetSessionID === actorSessionID) {
-		lastReview = undefined;
-		try {
-			const p = getReviewCacheFilePath();
-			if (existsSync(p)) unlinkSync(p);
-		} catch {}
 	}
+	// Review evidence is intentionally NOT erased here. Recorded approvals bind
+	// to the reviewed tracked content (commit hash + tracked worktree
+	// fingerprint), so freshness is re-evaluated against content at
+	// consumption time. Erasing on any mutation made an unrelated untracked
+	// scratch-file deletion (or a mutation in a sibling worktree) invalidate a
+	// valid approval and let a re-record silently fail to stick; any change to
+	// the reviewed tracked content still makes the evidence stale.
 }
 
 export function getMutationCount(sessionID?: string): number {
@@ -195,7 +194,7 @@ export function recordReviewResult(
 	passed: boolean,
 	targetSessionID?: string,
 	workspace?: string,
-): void {
+): ReviewResult {
 	const root = projectRootKey(workspace ?? getWorkspaceRoot());
 	lastReview = {
 		reviewer,
@@ -206,12 +205,15 @@ export function recordReviewResult(
 		workspace: root,
 		commitHash: getCurrentGitCommitHash(root),
 		gitStatus: getGitStatusSummary(root),
-		worktreeFingerprint: getGitWorktreeFingerprint(root),
+		// Bind to tracked repository content only: the review covered the
+		// reviewed diff, and untracked scratch files are not part of it.
+		worktreeFingerprint: getTrackedWorktreeFingerprint(root),
 	};
 	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
 	if (passed) {
 		persistReviewCache(lastReview);
 	}
+	return lastReview;
 }
 
 export function getLastReviewResult(): typeof lastReview {

package/src/lib/types.ts

@@ -130,6 +130,17 @@ export interface AuditEntry {
 		};
 		allowLive?: boolean;
 		reviewVerdict?: "approved" | "changes_requested" | "rejected";
+		evidenceId?: string;
+		reviewer?: string;
+		reviewTimestamp?: number;
+		binding?: {
+			workspace?: string;
+			commitHash?: string;
+			worktreeFingerprint?: string;
+			recorderSessionID?: string;
+			recorderRole?: "root" | "subagent";
+			targetSessionID?: string;
+		};
 	};
 }
 

package/src/lib/v2-plugin.ts

@@ -55,7 +55,7 @@ import { EDIT_TOOL_NAMES, fetchParentSession, fetchParentSessionID, effectiveTod
 import { currentGitBranch, isProtectedBranchName } from "../policies/git.ts";
 import { checkCompletionClaims } from "../policies/completion.ts";
 import { releaseFileClaims } from "../policies/file-claims.ts";
-import { beginReadObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
+import { beginReadObservation, recordMutationObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
 import { editTargets, runPostEditValidators, snapshotFile } from "../policies/post-edit-validation.ts";
 import { audit, summarizeInput } from "./audit.ts";
 import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
@@ -281,6 +281,9 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		const pending = toolLifecycle.takePostEditSnapshots(event.sessionID, event.id);
 		if (!pending) return;
 		await runWithRuntimeState(pending.root, client, async () => {
+			// Seed the session's observation of the bytes it just mutated so a
+			// follow-up edit needs no redundant re-read (V1 parity).
+			for (const before of pending.snapshots) recordMutationObservation(before.path, event.sessionID, before.digest);
 			const reports = await Promise.all(pending.snapshots.map((before) => runPostEditValidators(pending.root, before)));
 			const report = reports.filter((value): value is string => Boolean(value)).join("\n\n");
 			if (!report) return;

package/src/lib/verify.ts

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, type Hash } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { dynamicShellSyntaxIn, normalize } from "./shell.ts";
@@ -141,6 +141,35 @@ function warnFingerprintSkip(root: string, file: string, detail: string): void {
 	} catch {}
 }
 
+/**
+ * Content hash over tracked repository content only: the index listing
+ * (staged/tracked blob hashes) plus the worktree-vs-index diff (unstaged
+ * edits). Review evidence binds to this fingerprint, not to the full one:
+ * untracked scratch files are not part of the reviewed diff, so creating,
+ * modifying, or deleting them must never invalidate a recorded approval.
+ */
+function trackedContentHash(root: string): Hash | undefined {
+	const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	if (staged.status !== 0 || unstaged.status !== 0) return undefined;
+	return createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+}
+
+export function getTrackedWorktreeFingerprint(root: string): string | undefined {
+	try {
+		return trackedContentHash(root)?.digest("hex");
+	} catch {}
+	return undefined;
+}
+
 export function getGitWorktreeFingerprint(root: string): string | undefined {
 	try {
 		// Index listing captures the exact staged/tracked content (blob hashes);
@@ -148,23 +177,14 @@ export function getGitWorktreeFingerprint(root: string): string | undefined {
 		// contents cover files git does not yet track. Together these bind the
 		// fingerprint to file contents regardless of whether HEAD exists, so
 		// freshly initialized (commitless) repositories are covered too.
-		const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
+		const hash = trackedContentHash(root);
+		if (!hash) return undefined;
 		const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
 			cwd: root,
 			encoding: "utf8",
 			timeout: 5_000,
 		});
-		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
-		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+		if (untracked.status !== 0) return undefined;
 		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
 			// The path itself is always part of the fingerprint, so a skipped
 			// entry still binds its presence even when its contents do not.