opencode-workflow-guard 1.16.0 → 1.17.0

package/docs/policies.md

@@ -1,32 +1,32 @@
 # Enforced Policies & Guardrails
 
-`opencode-workflow-guard` enforces workflow discipline through **deterministic TypeScript hooks** - not prompt rules that LLMs can ignore.
+`opencode-workflow-guard` enforces workflow discipline through **deterministic TypeScript hooks**. It does not rely on prompt rules that an LLM can ignore.
 
-On OpenCode 1.x those hooks are `tool.execute.before`, `experimental.session.compacting`, `shell.env`, `permission.ask`, and `event` journaling. On OpenCode 2.x they are `tool.hook("execute.before"/"execute.after")`, `session.hook("context"/"compaction"/"prompt")`, `command.transform`, `permission.hook("evaluate")`, `shell.hook("create.before")`, and `event.subscribe()`. V1 plugin implementations do not run on OpenCode 2, so the two lists describe separate entrypoints, not alternatives for the same host.
+On OpenCode 1.x those hooks are `tool.execute.before`, `experimental.session.compacting`, `shell.env`, `permission.ask`, and `event` journaling. On OpenCode 2.x they are `tool.hook("execute.before"/"execute.after")`, `session.hook("context"/"compaction"/"prompt")`, `command.transform`, `permission.hook("evaluate")`, `shell.hook("create.before")`, and `event.subscribe()`. V1 plugin implementations do not run on OpenCode 2. The two lists therefore describe separate entrypoints, not alternatives for the same host.
 
-It is a policy and enforcement layer, not an agent harness. Policies may constrain actions, record or explain decisions, and preserve bounded context; they do not plan, prioritize, delegate, or autonomously sequence work. Where Workflow Guard resumes an idle session, it only enforces already-owned todo lifecycle state and does not choose what the agent works on next.
+This is a policy and enforcement layer, not an agent harness. Policies may constrain actions, record or explain decisions, and preserve bounded context. They do not plan, prioritize, delegate, or autonomously sequence work. Where Workflow Guard resumes an idle session, it only enforces already-owned todo lifecycle state. It does not choose what the agent works on next.
 
 ---
 
 ## Policy Reference
 
 ### 1. Task Breakdown & Lifecycle (`todowrite`)
-- **Pre-edit Gate:** All file-editing tools (`edit`, `write`, `apply_patch`) are blocked while the session's effective todo list is known and contains no active task. On OpenCode 1.x the list comes from the native todo system (`todowrite`, persisted at `GET /session/:id/todo`). On OpenCode 2.x before 2.1.0 the builtin tool registry has no `todowrite`, and there is no todo endpoint, so the list is reconstructed from the newest applied `todowrite` tool call in the session history (ACP agents may supply that tool). OpenCode 2.1.x reintroduces a builtin `todowrite` behind the `experimental.todo` config key; the guard detects that capability by probing the host tool registry rather than inferring it from history. Verified on 2.1.3: `ctx.tool.list()` exposes `todowrite` when the flag is on, and omits it when off. The gate distinguishes a **definitively empty** list (the capability exists and reports no active task → still blocked) from an **undeterminable** one (no todo capability, or the history cannot be read → the gate fails open and records that once per session at warn level). This keeps builtin-only V2 sessions usable instead of deadlocking every edit forever.
+- **Pre-edit Gate:** All file-editing tools (`edit`, `write`, `apply_patch`) are blocked while the session's effective todo list is known and contains no active task. On OpenCode 1.x the list comes from the native todo system (`todowrite`, persisted at `GET /session/:id/todo`). Before 2.1.0, the OpenCode 2.x builtin tool registry has no `todowrite`, and there is no todo endpoint. The list is then reconstructed from the newest applied `todowrite` tool call in the session history, which ACP agents may supply. OpenCode 2.1.x reintroduces a builtin `todowrite` behind the `experimental.todo` config key. The guard detects that capability by probing the host tool registry rather than inferring it from history. Verified on 2.1.3: `ctx.tool.list()` exposes `todowrite` when the flag is on, and omits it when off. The gate distinguishes a **definitively empty** list from an **undeterminable** one. A definitively empty list means the capability exists and reports no active task, which stays blocked. An undeterminable list means no todo capability, or the history cannot be read. The gate then fails open and records that once per session at warn level. This keeps builtin-only V2 sessions usable instead of deadlocking every edit forever.
 - **Flexible Task Execution:** Tasks can be completed in any order as work concludes without artificial sequential blockers, maintaining maximum pair-programming DX.
 - **No Silent Deletion:** Each `todowrite` update replaces the complete list. Active tasks must remain in subsequent updates until they are explicitly marked `completed` or `cancelled`.
-- **Per-Task Completion Evidence (enforced):** Because a `todowrite` call replaces the whole list, a model can mark work `completed` without doing it. A task may therefore enter `completed` only when the session recorded at least one file mutation inside that task's active window. One mutation cannot vouch for several completions, so N completions require N mutations counted from the earliest of them, and mutations spent before a task became active never count toward it. A blocked write names the task and the remedy, and the check runs in simulation too, so `guard_why` predicts the gate instead of reporting a falsely permissive verdict. A finished or dropped task releases its window, so reusing the same task text starts clean. Tasks are matched to their prior occurrences by count, so duplicate text cannot hide a new completion behind an already-completed item; the mutation counter records permitted mutation calls, not confirmed byte changes.
-  - **Planned late:** a task first observed already `completed` has no window to judge, so it is scored against the session's mutation history instead. This is the deliberate path for an agent that did the work before writing the list, and it stays bounded by the one-mutation-per-completion rule.
-  - **Read-only escape:** a task whose text carries `[read-only]` (also `[read_only]` / `[read only]`) completes without a mutation, because review, investigation, and reading are legitimate work that changes no file. The marker is an annotation, not part of task identity, so it can be appended to an already-planned task without reading as a deletion. Every use is journaled as `todo_completed_read_only`, so relabeling real work as read-only is visible in the audit trail rather than silent; that journal is the only counterweight in a repository with no detectable verify command. Work that was deliberately dropped uses `cancelled` instead.
-  - `guard_status` reports `taskEvidence` (`active`, `completed`, `tasksWithoutRecordedWork`, `readOnlyTasks`) so the requirement is visible before it blocks anything. This is not task authority: fresh verification evidence and the review gate remain the authority on finalization.
-- **Todo Capability Visibility:** Because the gate depends on the host exposing `todowrite` at all, `guard_status` reports `todoCapability` (`available` / `unavailable` / `unknown`), so a fail-open gate is visible rather than decorative.
-- **No Silent Early Exit:** When an owning session becomes `session.idle` with unfinished native todos, the guard asynchronously asks OpenCode to resume the existing run. This enforces the session's existing lifecycle state: Workflow Guard does not choose the next task, reorder work, create work, or delegate it. Ordinary automatic continuations are capped at three consecutive attempts and the budget resets on genuine user input. User-initiated interrupts (Esc) surface as `MessageAbortedError` and suspend automatic continuation for that session until genuine user input arrives, mirroring the ralph `user_stopped` semantics. The independently opt-in `ralphMode` uses `ralphMaxIterations` (1-100, default 10) instead; genuine user input terminates an active Ralph run, and unfinished work at the budget limit reports `budget_exhausted` rather than inferring a policy block. Ralph remains disabled by default under every operation profile. Use OpenCode's native `question` tool when user feedback or a decision is required; question and permission interactions wait inside the active run rather than producing an idle completion.
-- **Subagent Inheritance & Role Confinement:** Subagents automatically inherit active tasks from their parent session via the `parentID` hierarchy. Subagents spawned with read-only roles (`reviewer`, `planner`, `advisor`, `critic`, `explorer`, `scout`, `evaluator`) are hard-confined: file mutations, lifecycle tools, and mutating shell commands are strictly blocked. On OpenCode 2 the confinement is two-layered: `session.hook("context")` deletes the mutating tools (`write`, `edit`, `patch`, `apply_patch`, `shell`, `bash`, `execute`, `todowrite`, `subagent`/`task`, worktree lifecycle tools) from that role's per-request tool snapshot, and `execute.before` stays as the backstop for tools supplied outside the snapshot (ACP agents, nested Code Mode calls). The pruning is journaled as `session.context` / `read_only_role_tools_pruned`.
+- **Per-Task Completion Evidence (enforced):** Because a `todowrite` call replaces the whole list, a model can mark work `completed` without doing it. A task may therefore enter `completed` only when the session recorded at least one file mutation inside that task's active window. One mutation cannot vouch for several completions, so N completions require N mutations counted from the earliest of them. Mutations spent before a task became active never count toward it. A blocked write names the task and the remedy. The check also runs in simulation, so `guard_why` predicts the gate instead of reporting a falsely permissive verdict. A finished or dropped task releases its window, so reusing the same task text starts clean. Tasks are matched to their prior occurrences by count, so duplicate text cannot hide a new completion behind an already-completed item. The mutation counter records permitted mutation calls, not confirmed byte changes.
+  - **Planned late:** a task first observed already `completed` has no window to judge, so it is scored against the session's mutation history instead. This is the deliberate path for an agent that did the work before writing the list. It stays bounded by the one-mutation-per-completion rule.
+  - **Read-only escape:** A task whose text carries `[read-only]`, also `[read_only]` or `[read only]`, completes without a mutation. Review, investigation, and reading are legitimate work that changes no file. The marker is an annotation, not part of task identity, so it can be appended to an already-planned task without reading as a deletion. Every use is journaled as `todo_completed_read_only`, so relabeling real work as read-only stays visible in the audit trail. In a repository with no detectable verify command, that journal is the only counterweight. Work that was deliberately dropped uses `cancelled` instead.
+  - `guard_status` reports `taskEvidence` (`active`, `completed`, `tasksWithoutRecordedWork`, `readOnlyTasks`), so the requirement is visible before it blocks anything. This is not task authority. Fresh verification evidence and the review gate remain the authority on finalization.
+- **Todo Capability Visibility:** Because the gate depends on the host exposing `todowrite` at all, `guard_status` reports `todoCapability` (`available` / `unavailable` / `unknown`). A fail-open gate is therefore visible rather than decorative.
+- **No Silent Early Exit:** When an owning session becomes `session.idle` with unfinished native todos, the guard asynchronously asks OpenCode to resume the existing run. This enforces the session's existing lifecycle state. Workflow Guard does not choose the next task, reorder work, create work, or delegate it. Ordinary automatic continuations are capped at three consecutive attempts, and the budget resets on genuine user input. User-initiated interrupts (Esc) surface as `MessageAbortedError` and suspend automatic continuation for that session until genuine user input arrives, mirroring the ralph `user_stopped` semantics. The independently opt-in `ralphMode` uses `ralphMaxIterations` (1-100, default 10) instead. Genuine user input terminates an active Ralph run, and unfinished work at the budget limit reports `budget_exhausted` rather than inferring a policy block. Ralph remains disabled by default under every operation profile. Use OpenCode's native `question` tool when user feedback or a decision is required. Question and permission interactions wait inside the active run rather than producing an idle completion.
+- **Subagent Inheritance & Role Confinement:** Subagents inherit active tasks from their parent session via the `parentID` hierarchy. Subagents spawned with read-only roles (`reviewer`, `planner`, `advisor`, `critic`, `explorer`, `scout`, `evaluator`) are hard-confined. File mutations, lifecycle tools, and mutating shell commands are strictly blocked. On OpenCode 2 the confinement is two-layered. `session.hook("context")` deletes the mutating tools (`write`, `edit`, `patch`, `apply_patch`, `shell`, `bash`, `execute`, `todowrite`, `subagent`/`task`, worktree lifecycle tools) from that role's per-request tool snapshot. `execute.before` stays as the backstop for tools supplied outside the snapshot, such as ACP agents and nested Code Mode calls. The pruning is journaled as `session.context` / `read_only_role_tools_pruned`.
 - **Handoff Safety:** An idle subagent whose effective todos are inherited from its parent is not auto-continued. Inherited work belongs to the parent and can be handed back normally.
-- **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. A claim created before its owner's last recorded idle timestamp cannot belong to an in-flight tool call, so when another session hits such a conflict the stale claim is released with an audited `stale_claim_takeover` entry — owners still mid-session (no idle timestamp), clients without a session lookup, and failed lookups keep the block (fail-closed). `guard_why` stays read-only and still reports the conflict as blocked. 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; 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.
-- **Shell-redirect seeding:** an allowed shell command that redirects into a workspace file (`cmd > file`, `cmd >> file`, fd forms) seeds the session's observation of the resulting bytes in the same change-gated way as direct edits, so a file this session just created or rewrote via a shell redirect can be edited without a redundant re-read. Redirects to `/dev/null`, the `/tmp/opencode` scratch directory, or outside the workspace seed nothing; an identical-byte (no-op) redirect does not seed; the not-read block message also suggests coordinating when another session may own the file. Shell writers themselves remain outside the bounded pre-check: only the observation seeding applies.
+- **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). The budget terminates 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. A claim created before its owner's last recorded idle timestamp cannot belong to an in-flight tool call. When another session hits such a conflict, the stale claim is released with an audited `stale_claim_takeover` entry. Owners still mid-session (no idle timestamp), clients without a session lookup, and failed lookups keep the block (fail-closed). `guard_why` stays read-only and still reports the conflict as blocked. Shell writers are not covered, and isolated worktrees remain the better choice for substantial parallel mutations.
+- **Stale-Write Protection:** A successful `read` records a same-session fingerprint for an existing regular file from five fields. Those fields are canonical path, filesystem identity, size, nanosecond mtime, and SHA-256 content digest. A successful `edit`/`write` also records the resulting bytes, and only when the file actually changed. The session authored those bytes, 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 and subagent sessions, and they are cleared on session idle or deletion. `apply_patch` and shell writers sit 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.
+- **Shell-redirect seeding:** An allowed shell command that redirects into a workspace file (`cmd > file`, `cmd >> file`, fd forms) seeds the session's observation of the resulting bytes. It does so in the same change-gated way as direct edits. A file this session just created or rewrote via a shell redirect can therefore be edited without a redundant re-read. Redirects to `/dev/null`, the `/tmp/opencode` scratch directory, or outside the workspace seed nothing. An identical-byte (no-op) redirect does not seed. The not-read block message also suggests coordinating when another session may own the file. Shell writers themselves remain outside the bounded pre-check, so only the observation seeding applies.
 
 ### 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`).
@@ -38,21 +38,25 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - `gh pr create` and `az repos pr create` are blocked unless:
   - The branch diff modifies a `CHANGELOG` file, OR
   - The branch diff adds/modifies a `.changeset/*.md` fragment file (Changesets workflow), OR
-  - The PR description (`--body`, `--description`, or `--body-file`/`-F`) contains a release-information section headed `Changelog`, `Changes`, `Release notes`, or `Summary`. Multiline Bash ANSI-C `\n`/`\r` quoting is supported for inline descriptions; inline descriptions that would render Markdown line breaks as literal `\n`/`\r` text are blocked with guidance to use real newlines or a description file.
-- **Lockfile Synchronization Gate:** Whenever package manifests (`package.json`, `Cargo.toml`, `go.mod`) are modified, PR creation is blocked until their corresponding lockfiles (`package-lock.json`/`bun.lock`/`pnpm-lock.yaml`/`yarn.lock`, `Cargo.lock`, `go.sum`) are updated. For `package.json` the demand is section-aware: it fires when a section the lockfile records changed (`dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`, `peerDependenciesMeta`, `engines`, `packageManager`, `overrides`, `resolutions`, `workspaces`, `pnpm`, or the project `name`/`version`). Scripts- or metadata-only manifest edits regenerate the lockfile byte-identical and pass without one. `Cargo.toml` and `go.mod` changes conservatively keep demanding their lockfiles.
+  - The PR description (`--body`, `--description`, or `--body-file`/`-F`) contains a release-information section headed `Changelog`, `Changes`, `Release notes`, or `Summary`. Multiline Bash ANSI-C `\n`/`\r` quoting is supported for inline descriptions. Inline descriptions that would render Markdown line breaks as literal `\n`/`\r` text are blocked. The block message directs the author to real newlines or a description file.
+- **Lockfile Synchronization Gate:** Whenever package manifests (`package.json`, `Cargo.toml`, `go.mod`) are modified, PR creation is blocked until their corresponding lockfiles are updated. Those lockfiles are `package-lock.json`/`bun.lock`/`pnpm-lock.yaml`/`yarn.lock`, `Cargo.lock`, and `go.sum`. For `package.json` the demand is section-aware. It fires when a section the lockfile records changed. Those sections are `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`, `peerDependenciesMeta`, `engines`, `packageManager`, `overrides`, `resolutions`, `workspaces`, `pnpm`, and the project `name` or `version`. Scripts- or metadata-only manifest edits regenerate the lockfile byte-identical and pass without one. `Cargo.toml` and `go.mod` changes conservatively keep demanding their lockfiles.
 - When multiple PR prerequisites fail at once, the guard reports all detected preflight failures together so they can be resolved before retrying PR creation.
 
 ### 4. Destructive CLI Operations Guard
 - Blocks destructive filesystem, infrastructure, cloud, database, and git operations unless the **user** explicitly overrides via environment variable.
 - **Blocked:**
-  - Filesystem & Disks: `rm -rf`, `rm -r`, forced deletion of system/home paths, disk wipes (`mkfs`, `wipefs`, `parted`, `sfdisk`), raw block writes (`dd of=/dev/...`, `shred /dev/...`), recursive permission/ownership clobbering (`chmod -R ... /`, `chown -R ... ~`), reverse shells & raw sockets (`/dev/tcp/...`, `nc -e`, `socat exec:`)
+  - Filesystem & Disks:
+    - `rm -rf`, `rm -r`, and forced deletion of system or home paths
+    - Disk wipes (`mkfs`, `wipefs`, `parted`, `sfdisk`) and raw block writes (`dd of=/dev/...`, `shred /dev/...`)
+    - Recursive permission or ownership clobbering (`chmod -R ... /`, `chown -R ... ~`)
+    - Reverse shells and raw sockets (`/dev/tcp/...`, `nc -e`, `socat exec:`)
   - Kubernetes: `kubectl delete`, `kubectl drain`, `kubectl cordon`, `kubectl rollout undo/restart`
   - Helm: `helm uninstall`, `helm rollback`, `helm delete`
   - IaC: `terraform destroy`, `tofu destroy`, `pulumi destroy`
   - Containers: `docker rm`, `docker container/system/image/volume prune`, `docker volume rm`
   - Cloud: `az ... delete/purge`, `aws ... delete/terminate`, `gcloud ... delete/abandon`
   - Hosted Git: `gh repo/issue/pr/release/secret/variable delete|close`
-  - Databases: `psql/mysql/mariadb/mongosh/redis-cli/sqlite3` drop, delete, truncate, flushall; `prisma migrate reset`
+  - Databases: `psql/mysql/mariadb/mongosh/redis-cli/sqlite3` drop, delete, truncate, and flushall, plus `prisma migrate reset`
   - Remote HTTP: `curl -X DELETE` against non-localhost endpoints
   - Git: `git push --force`, `git push +refspec`, `git clean -fdx`
 - **Allowed:** Non-destructive mutations (`kubectl apply`, `terraform apply`, `helm upgrade`, `az create/update`, DB inserts, `curl POST/PUT/PATCH`, `docker ps`, single-file `rm`).
@@ -61,7 +65,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - MCP tools that mutate live GitHub or Azure/DevOps systems (`create`, `update`, `delete`, `merge`, `push`, `close`, etc.) are blocked.
 - Server names are tokenized on all non-alphanumerics, so `mcp__azure-devops__...`, `mcp__gh__...` and flat legacy names (`azure_devops_*`) are matched.
 - Read-only tools (`get`, `list`, `search`, `query`, etc.) are permitted.
-- On OpenCode 2 the guarded server set is widened from the host's own MCP roster (`ctx.mcp.list()`), refreshed on `mcp.tools.changed`, so a renamed or enterprise instance of a guarded product is still matched. Widening is one-way by design: removing a server adds nothing, and the static token list stays the floor, because tool names are model-supplied text and this is a live-system rail.
+- On OpenCode 2 the guarded server set is widened from the host's own MCP roster (`ctx.mcp.list()`), refreshed on `mcp.tools.changed`. A renamed or enterprise instance of a guarded product is therefore still matched. Widening is one-way by design: removing a server adds nothing, and the static token list stays the floor. Tool names are model-supplied text, and this is a live-system rail.
 
 ### 6. Settings Tamper Guard
 - Prevents the agent from weakening its own permission gates **via shell or edit tools**:
@@ -69,28 +73,28 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
   - Direct edits of the same paths through the `edit`/`write`/`apply_patch` tools
   - Shell commands invoking `opencode auth`, `opencode config`, `opencode permission`, or `opencode run --auto`
   - Evasion-normalized: quote-concatenation (`open''code.json`), escapes (`open\c\ode`), and glob wildcards (`opencode.jso?`) are stripped before matching.
-- Collaboration commands (`gh issue`, `gh pr`, `glab issue`, `glab pr`, `az repos pr`) and document content mentioning guarded paths are not tampering: quoted arguments are command data, not shell syntax, and the redirect heuristic applies to shell commands only (write/edit content is guarded by the target path check instead).
-- Quoted data spans are not shell syntax: pattern matching runs on the quote-stripped residue, where redirect targets are honored quoted or not and quote-concatenated paths keep normalizing. A quoted span containing a guarded path is never treated as a redirect or command verb; unquoted redirects into guarded paths stay blocked.
+- Collaboration commands (`gh issue`, `gh pr`, `glab issue`, `glab pr`, `az repos pr`) and document content mentioning guarded paths are not tampering. Quoted arguments are command data, not shell syntax. The redirect heuristic applies to shell commands only. Write and edit content is guarded by the target path check instead.
+- Quoted data spans are not shell syntax. Pattern matching runs on the quote-stripped residue, where redirect targets are honored quoted or not, and quote-concatenated paths keep normalizing. A quoted span containing a guarded path is never treated as a redirect or command verb. Unquoted redirects into guarded paths stay blocked.
 - Plan files under `.opencode/plans/` are exempt: opencode's plan mode writes agent-authored plan markdown there, and plans are content, not configuration. Everything else under `.opencode/` (including the directory itself) stays protected.
 - **Read-only access is allowed** (`cat`, `less`, `grep`, `head`, `tail` on config files) - only modification attempts trigger the guard.
-- **Live control-plane facts (`liveControlPlanePaths`, opt-in):** declare the absolute paths of the live control plane (for example `~/.config/opencode`, or the guard's own install) in `.opencode/workflow-guard.json` or via `WORKFLOW_GUARD_LIVE_CONTROL_PLANE_PATHS` (comma-separated). When set, config-path protection classifies by runtime consumption instead of filename segments: only targets that resolve under a live root are protected (symlink-aware), so copying **from** a config path into a sanctioned workspace draft is no longer blocked (the copy destination is what matters) and versioned drafts such as a project `.opencode/` or a dotfiles `.config/opencode` are editable. Roots must be absolute (`~`/`$HOME` are expanded); an unusable root rejects the whole set and falls back to the legacy fail-closed segment matching. Unset keeps the legacy behavior.
+- **Live control-plane facts (`liveControlPlanePaths`, opt-in):** Declare the absolute paths of the live control plane in `.opencode/workflow-guard.json` or via `WORKFLOW_GUARD_LIVE_CONTROL_PLANE_PATHS` (comma-separated). Examples are `~/.config/opencode` and the guard's own install. When set, config-path protection classifies by runtime consumption instead of filename segments. Only targets that resolve under a live root are protected (symlink-aware). Copying **from** a config path into a sanctioned workspace draft is therefore no longer blocked, because the copy destination is what matters. Versioned drafts such as a project `.opencode/` or a dotfiles `.config/opencode` are editable. Roots must be absolute (`~`/`$HOME` are expanded). An unusable root rejects the whole set and falls back to the legacy fail-closed segment matching. Unset keeps the legacy behavior.
 
 ### 7. Feature-Branch Workflow
-- When the workspace git repository is on `main` or `master`, all file mutations and history-changing git commands (`commit`, `merge`, `rebase`, `cherry-pick`, `revert`, `apply`, `am`, `reset`, `restore`, `stash pop`, `update-ref`, `filter-branch`, `branch -D/-M`) are blocked.
+- When the workspace git repository is on `main` or `master`, all file mutations and history-changing git commands are blocked. Those commands are `commit`, `merge`, `rebase`, `cherry-pick`, `revert`, `apply`, `am`, `reset`, `restore`, `stash pop`, `update-ref`, `filter-branch`, and `branch -D/-M`.
 - Git global flags are parsed, so `git -C /repo commit` is gated on `/repo`'s branch, not the workspace's.
 - The agent is prompted to create a feature branch first (`git switch -c feat/my-feature`).
 
 ### 8. Workspace Boundary Guard
-- File modification tools (`edit`, `write`, `apply_patch`) and recognized shell mutations (redirection `>`, `>>`, `&>`, `>&`, `tee`, `sed -i`, `cp`/`mv`/`ln`, `touch`, `mkdir`, `rm`, `truncate`, `dd of=`, `git apply`/`git am`) are validated to ensure detected targets cannot escape the current workspace root via `../` traversal, symlinks, absolute paths, or shell expansions (`~`, `~user`, `$HOME`). Unresolvable `$VARIABLE` references fail closed. This is command-level enforcement, not filesystem sandboxing; arbitrary programs and dynamically computed paths require the OS isolation described under Known Limits.
-- **Unresolvable variable cause attribution:** a target containing an unresolvable `$VARIABLE` reference (for example `mkdir -p $D/sub` or `> $CACHE/out.txt`) is indeterminate without executing shell semantics, so it is treated as outside the workspace — and the block message says so ("contains an unresolvable variable reference … use a literal workspace-relative path") instead of the generic escape message. Deterministically expandable forms (`~`, `~user`, `$HOME`, `${HOME}`) keep the generic message; cache-path and other literal destinations inside the workspace are unaffected.
-- **Scratch-directory cause attribution:** `/tmp/opencode` is the environment's designated agent scratch space, but the workspace boundary is workspace-absolute and does not cover it — writes there stay blocked. The block message names the directory and points to the remedy (an untracked scratch file inside the workspace, for example `.tmp-notes.md`) instead of reading as a guard bug; the enforcement decision is unchanged.
-- **Symlink-alias acceptance:** a target whose lexical path falls outside the workspace root but whose canonical resolution is inside it is accepted — for example `/home/<user>/...` on hosts where `/home` is a symlink into `/var/home` and the workspace root lives under `/var/home`. A target stays blocked whenever the canonical resolution is outside the canonicalized root, including symlinks inside the workspace that point outside and not-yet-created files under them (nearest existing ancestor), and when canonicalization is indeterminate the lexical verdict stands (fail closed). In other words, a path is outside the workspace only when both its lexical and its canonical resolution are outside.
+- File modification tools (`edit`, `write`, `apply_patch`) and recognized shell mutations are validated so detected targets cannot escape the current workspace root. The recognized shell mutations are redirection `>`, `>>`, `&>`, `>&`, `tee`, `sed -i`, `cp`/`mv`/`ln`, `touch`, `mkdir`, `rm`, `truncate`, `dd of=`, `git apply`, and `git am`. The check covers `../` traversal, symlinks, absolute paths, and shell expansions (`~`, `~user`, `$HOME`). Unresolvable `$VARIABLE` references fail closed. This is command-level enforcement, not filesystem sandboxing. Arbitrary programs and dynamically computed paths require the OS isolation described under Known Limits.
+- **Unresolvable variable cause attribution:** A target containing an unresolvable `$VARIABLE` reference is indeterminate without executing shell semantics. Examples are `mkdir -p $D/sub` and `> $CACHE/out.txt`. The guard therefore treats it as outside the workspace. The block message says so ("contains an unresolvable variable reference … use a literal workspace-relative path") instead of showing the generic escape message. Deterministically expandable forms (`~`, `~user`, `$HOME`, `${HOME}`) keep the generic message. Cache-path and other literal destinations inside the workspace are unaffected.
+- **Scratch-directory cause attribution:** `/tmp/opencode` is the environment's designated agent scratch space, but the workspace boundary is workspace-absolute and does not cover it. Writes there stay blocked. The block message names the directory and points to the remedy instead of reading as a guard bug. The remedy is an untracked scratch file inside the workspace, for example `.tmp-notes.md`. The enforcement decision is unchanged.
+- **Symlink-alias acceptance:** A target whose lexical path falls outside the workspace root but whose canonical resolution is inside it is accepted. One example is `/home/<user>/...` on hosts where `/home` is a symlink into `/var/home` and the workspace root lives under `/var/home`. A target stays blocked whenever the canonical resolution is outside the canonicalized root. That includes symlinks inside the workspace that point outside, and not-yet-created files under them (nearest existing ancestor). When canonicalization is indeterminate, the lexical verdict stands (fail closed). A path is outside the workspace only when both its lexical and its canonical resolution are outside.
 - `tee` flag parsing generically skips option flags (`-a`, `--append`, `-ai`, `--`) and validates all specified target files against the boundary.
-- Embedded non-shell comparisons are not mutations: a bare `>` whose target is purely numeric (`WHERE count > 5`, awk `$3 > 100`) and `>=`/`==` operators are treated as comparison operands, not redirects. Real redirects are unaffected (`> src/a.ts`, `>>`, `&>`, `>&`, fd targets like `/dev/null` still follow their existing rules).
-- `mv` sources are validated too: moving a file from outside the workspace (or a protected settings/plugin file to an innocuous name) is blocked, since `mv` mutates the source.
+- Embedded non-shell comparisons are not mutations. A bare `>` whose target is purely numeric (`WHERE count > 5`, awk `$3 > 100`) and `>=` or `==` operators are treated as comparison operands, not redirects. Real redirects are unaffected (`> src/a.ts`, `>>`, `&>`, `>&`, and fd targets like `/dev/null` still follow their existing rules).
+- `mv` sources are validated too. Moving a file from outside the workspace is blocked, since `mv` mutates the source. The same applies to moving a protected settings or plugin file to an innocuous name.
 - External repository git writes (`git -C /other-repo commit`, `git --git-dir=/other-repo/.git push`, `GIT_DIR=/other-repo/.git git push`, `GIT_WORK_TREE=...`) are also confined to the workspace.
 - The boundary has **no override**: `WORKFLOW_GUARD_ALLOW_LIVE=1` covers live-system commands only and never weakens the workspace confinement.
-- **The boundary is bound once, then only the host may widen it.** A session adopts its workspace from its own first tool-call context (a call-argument path, or the host-provided per-call worktree). After that, a path outside the boundary is foreign state: the boundary policy refuses mutations there, and the path never re-anchors the session. Only an explicit host-declared per-call worktree widens a bound session, because worktree isolation and relay flows set it deliberately. A subagent is bound by the same rule through its nearest bound ancestor: with no direct binding of its own it already inherits the parent's workspace for policy decisions, so its first foreign read is refused as a widening rather than adopted as a first bind. Every granted widening is journaled (`workspace.binding` / `workspace_rebind_host_worktree`) and every refused one is journaled with the read-or-mutation label (`workspace.binding` / `workspace_rebind_refused`). This closes the defect where one allowed read of a file in another repository moved the entire write boundary into that repository, because `external_directory` defaults to allow.
+- **The boundary is bound once, then only the host may widen it.** A session adopts its workspace from its own first tool-call context. That context is a call-argument path, or the host-provided per-call worktree. After that, a path outside the boundary is foreign state. The boundary policy refuses mutations there, and the path never re-anchors the session. Only an explicit host-declared per-call worktree widens a bound session. Worktree isolation and relay flows set it deliberately. A subagent is bound by the same rule through its nearest bound ancestor. With no direct binding of its own, it already inherits the parent's workspace for policy decisions. Its first foreign read is therefore refused as a widening rather than adopted as a first bind. Every granted widening is journaled (`workspace.binding` / `workspace_rebind_host_worktree`). Every refused one is journaled with the read-or-mutation label (`workspace.binding` / `workspace_rebind_refused`). This closes a defect where one allowed read of another repository moved the entire write boundary there, because `external_directory` defaults to allow.
 
 ### 9. Script-Laundering Guard
 - Content written via `edit`, `write`, or `apply_patch` is scanned for destructive CLI commands.
@@ -98,40 +102,40 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 
 ### 10. Evidence-Based Verification
 - When the agent attempts to mark **every** task completed (finalizing the request), the guard requires passing verification evidence.
-- Verification (`WORKFLOW_GUARD_VERIFY` env, project `verifyCommand`, or auto-detected test/typecheck runner across ecosystems: `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini`/`pyproject.toml` (`pytest`), or `deno.json` (`deno test`)) executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. Environment configuration takes precedence over project configuration.
-- The verification timeout defaults to 30 seconds and can be raised per project (`verifyTimeoutMs` in `.opencode/workflow-guard.json`) or per environment (`WORKFLOW_GUARD_VERIFY_TIMEOUT_MS`, which wins over project config); non-positive values are ignored and fall back to the default. Raise it for suites that legitimately exceed the default - for example this repository's own unit suite.
-- Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` (`*`, `**`, and `?` wildcards; brace expansion and character classes are not supported), a non-empty `command`, and an optional positive `timeoutMs`; invalid entries are reported as advisory feedback rather than silently ignored. Matching commands run from the workspace root with the same scrubbed verification environment. Validator failures and timeouts are appended to the edit result as advisory feedback and do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
-- With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list; subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
-- Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider/model parameters.
+- Verification executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. The command comes from the `WORKFLOW_GUARD_VERIFY` env, the project `verifyCommand`, or an auto-detected test or typecheck runner across ecosystems. Auto-detection covers `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini` or `pyproject.toml` (`pytest`), and `deno.json` (`deno test`). Environment configuration takes precedence over project configuration.
+- The verification timeout defaults to 30 seconds. Raise it per project with `verifyTimeoutMs` in `.opencode/workflow-guard.json`, or per environment with `WORKFLOW_GUARD_VERIFY_TIMEOUT_MS`, which wins over project config. Non-positive values are ignored and fall back to the default. Raise the timeout for suites that legitimately exceed the default, for example this repository's own unit suite.
+- Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` with `*`, `**`, and `?` wildcards. Brace expansion and character classes are not supported. Each entry also accepts a non-empty `command` and an optional positive `timeoutMs`. Invalid entries are reported as advisory feedback rather than silently ignored. Matching commands run from the workspace root with the same scrubbed verification environment. Validator failures and timeouts are appended to the edit result as advisory feedback. They do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
+- With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list. Subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
+- Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent. Set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider and model parameters.
 - **Git State & Snapshot Binding:** Verification evidence records the current git commit hash (`git rev-parse HEAD`) and working tree status. If unverified edits or index modifications occur after verification, fresh verification is enforced.
-- **Untracked Special Entries:** The worktree fingerprint binds untracked symlinks by their target string (git semantics - re-pointing a link moves the fingerprint, changing the link target's contents does not), FIFOs/sockets by path and mode, and skips unopenable entries with a `worktree-fingerprint` warning in the audit trail instead of voiding the whole fingerprint. One unreadable scratch symlink or `chmod 000` file can no longer make review/verification evidence permanently unfresh, and the PR preflight names the actual cause when an approval cannot be matched (no fingerprint binding, fingerprint mismatch, or uncomputable fingerprint) instead of the generic "review approval required". Documented tradeoff: the contents of a skipped entry are excluded from the fingerprint, so a file that stays unreadable to the guard's user across the entire window can change contents without moving the fingerprint; any readability transition is fingerprint-visible (fail-closed), and each skip is named in the durable audit trail.
-- **Durable Disk Cache:** Passing verification results (`~/.local/state/opencode/workflow-guard/last-verify.json`) and passing secondary review approvals (`~/.local/state/opencode/workflow-guard/last-review.json`) are cached to disk, allowing session restarts and multi-agent handoffs to retain valid verification and review evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
+- **Untracked Special Entries:** The worktree fingerprint binds untracked symlinks by their target string. It follows git semantics, so re-pointing a link moves the fingerprint and changing the link target's contents does not. FIFOs and sockets are bound by path and mode. Unopenable entries are skipped with a `worktree-fingerprint` warning in the audit trail instead of voiding the whole fingerprint. One unreadable scratch symlink or `chmod 000` file can no longer make review or verification evidence permanently unfresh. The PR preflight names the actual cause when an approval cannot be matched: no fingerprint binding, fingerprint mismatch, or uncomputable fingerprint. It no longer shows the generic "review approval required". Documented tradeoff: the contents of a skipped entry are excluded from the fingerprint. A file that stays unreadable to the guard's user across the entire window can therefore change contents without moving the fingerprint. Any readability transition is fingerprint-visible (fail-closed), and each skip is named in the durable audit trail.
+- **Durable Disk Cache:** Passing verification results (`~/.local/state/opencode/workflow-guard/last-verify.json`) and passing secondary review approvals (`~/.local/state/opencode/workflow-guard/last-review.json`) are cached to disk. Session restarts and multi-agent handoffs can therefore retain valid verification and review evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it. A passing run in one project can never satisfy finalization in another.
 - If verification fails, finalization is blocked with a structured summary of error markers, stack traces, and failure output.
-- OpenCode's current `lsp.client.diagnostics` event identifies the server and path but does not expose the diagnostics themselves, so the guard deliberately does not claim an LSP-clean finalization gate until the SDK provides a supported diagnostics source.
+- OpenCode's current `lsp.client.diagnostics` event identifies the server and path. It does not expose the diagnostics themselves. The guard therefore does not claim an LSP-clean finalization gate until the SDK provides a supported diagnostics source.
 - The verify command is **disabled** when `WORKFLOW_GUARD_VERIFY` is empty (`""`).
 
 ### 11. Secret-Content Scan
-- File payloads and recognized shell file-mutation commands are scanned for common credential material (AWS keys, private key headers, GitHub tokens, OpenAI/LLM keys, Google API keys, Slack tokens, explicit env-style assignments).
+- File payloads and recognized shell file-mutation commands are scanned for common credential material. That material includes AWS keys, private key headers, GitHub tokens, OpenAI and LLM keys, Google API keys, Slack tokens, and explicit env-style assignments.
 - Flagged content is blocked before the write with an actionable message. Secret-file reads also resolve existing symlink aliases, and copying/moving/linking a known secret path under another name is blocked.
 
 ### 12. Shell Environment Scrub
-- Sensitive environment variables (`AWS_*`, `KUBE*`, `OPENAI*`, `ANTHROPIC*`, `GOOGLE_/GCP_`, `AZURE_`, `SLACK_`, `NPM_`, `DOCKER_`, `KUBECONFIG`, and fixed names like `OPENAI_API_KEY`, `KUBECONFIG`, `NPM_TOKEN`) are **emptied** in agent shells by the `shell.env` hook. GitHub tokens (`GITHUB_TOKEN`, `GH_TOKEN`) are preserved so `gh` CLI and git operations function without recurring login prompts.
+- Sensitive environment variables are **emptied** in agent shells by the `shell.env` hook. The list covers `AWS_*`, `KUBE*`, `OPENAI*`, `ANTHROPIC*`, `GOOGLE_/GCP_`, `AZURE_`, `SLACK_`, `NPM_`, `DOCKER_`, `KUBECONFIG`, and fixed names like `OPENAI_API_KEY`, `KUBECONFIG`, and `NPM_TOKEN`. GitHub tokens (`GITHUB_TOKEN`, `GH_TOKEN`) are preserved so `gh` CLI and git operations function without recurring login prompts.
 - This prevents the agent from carrying live credentials by default. The user can still grant access through OpenCode's own permission system if a task genuinely needs it.
 
 ### 13. Command-Channel Audit
 - User-triggered slash commands (`command.executed` events) are journaled to the audit trail so agents cannot perform hidden work through a user-facing side channel.
 
 ### 14. Audit Trail & Permission Journaling
-- Every block/allow decision is appended to `~/.local/state/opencode/workflow-guard/workflow-guard.jsonl` (XDG_STATE_HOME respected) with a timestamp, session id, tool name, decision, subagent/parent session attribution, and reason - a durable record.
-- Permission prompts are journaled at request time via the typed `permission.ask` plugin hook, and `permission.replied` outcomes (including rejections) are preserved instead of being labeled as allows.
-- On OpenCode 2, the V2 plugin also *decides* at that seat: `ctx.permission.hook("evaluate")` maps the host's normalized `action`/`resources` back onto the policy core and sets `effect = "deny"` with an attributable message, so the tool never starts. Shell resources feed the shell, git, destructive, and workspace policies. `read` resources feed the secret policy. `edit`/`write`/`patch`/`apply_patch` resources feed the boundary, tamper, secret, protected-branch, and todo policies. Guarded MCP servers (`GitHub`, `Azure DevOps`) feed the MCP policy.
-- The seat can only tighten. An explicit configured `deny` is final and never reaches the hook, and an unmapped host action (`external_directory`, `glob`, `grep`, `webfetch`, `websearch`, `question`, `subagent`) is left to host policy. If the seat itself throws, it fails closed with a deny instead of becoming a pass.
-- `execute.before` is kept as the second, last-resort seat: it sees raw tool input, so todo lifecycle, stale-write observations, and post-edit snapshots stay there, and its thrown message carries the specific remediation text to the model.
+- Every block and allow decision is appended to `~/.local/state/opencode/workflow-guard/workflow-guard.jsonl`, with XDG_STATE_HOME respected. Each record carries a timestamp, session id, tool name, decision, subagent and parent session attribution, and reason. This is a durable record.
+- Permission prompts are journaled at request time via the typed `permission.ask` plugin hook. `permission.replied` outcomes, including rejections, are preserved instead of being labeled as allows.
+- On OpenCode 2, the V2 plugin also *decides* at that seat. `ctx.permission.hook("evaluate")` maps the host's normalized `action` and `resources` back onto the policy core and sets `effect = "deny"` with an attributable message, so the tool never starts. Shell resources feed the shell, git, destructive, and workspace policies. `read` resources feed the secret policy. `edit`, `write`, `patch`, and `apply_patch` resources feed the boundary, tamper, secret, protected-branch, and todo policies. Guarded MCP servers (`GitHub`, `Azure DevOps`) feed the MCP policy.
+- The seat can only tighten. An explicit configured `deny` is final and never reaches the hook. An unmapped host action (`external_directory`, `glob`, `grep`, `webfetch`, `websearch`, `question`, `subagent`) is left to host policy. If the seat itself throws, it fails closed with a deny instead of becoming a pass.
+- `execute.before` is kept as the second, last-resort seat. It sees raw tool input, so todo lifecycle, stale-write observations, and post-edit snapshots stay there. Its thrown message carries the specific remediation text to the model.
 - `client.app.log()` complements the on-disk trail with in-app logs.
 
 ### 15. Compaction State & Policy Context Preservation
-- Integrates with OpenCode's compaction hook to inject bounded active policy state before context summarization: `experimental.session.compacting` on OpenCode 1.x, `session.hook("compaction")` on OpenCode 2.x (stable in the installed 2.1.3 typings):
-  - Caps injected continuity context at 8,000 characters, preserving operational guard state first and filling the remaining budget with active tasks, review follow-ups, and fresh local project memory.
+- Integrates with OpenCode's compaction hook to inject bounded active policy state before context summarization. The hook is `experimental.session.compacting` on OpenCode 1.x and `session.hook("compaction")` on OpenCode 2.x, which is stable in the installed 2.1.3 typings:
+  - Caps injected continuity context at 8,000 characters. Operational guard state is preserved first. The remaining budget holds active tasks, review follow-ups, and fresh local project memory.
   - Active `todowrite` tasks with status badges and subagent hierarchy attribution.
   - Active Git branch name and protected branch status.
   - Test verification status (passed/failed, test command, and commit hash).
@@ -145,29 +149,29 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - The companion TUI plugin (`workflow-guard-ui.ts`) keeps `Workflow Guard 🛡️` static in the prompt bar. Block details remain in the warning toast rather than changing badge content or color.
 
 ### 17. Secret-File READ Block & Safe Schema Masking
-- Blocks reading sensitive credential files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`, `*kubeconfig*`, `*credentials*.json`, `service-account*.json`) through the `read` tool, shell commands (`cat`, `less`, `more`, `grep`, `awk`, `head`, `tail`, `base64`), or inline interpreter payloads (`python3 -c "open('.env')"`, `bash -c 'cat id_rsa'`).
-- **Safe Schema Masking:** On `.env*` reads via the `read` tool, the guard parses the variable names and comments, and returns a safe redacted schema mask with secret values masked as `********`, enabling agents to inspect variable existence without leaking secrets into model context.
+- Blocks reading sensitive credential files through the `read` tool, shell commands, or inline interpreter payloads. The credential patterns are `.env*`, `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`, `*kubeconfig*`, `*credentials*.json`, and `service-account*.json`. The shell commands are `cat`, `less`, `more`, `grep`, `awk`, `head`, `tail`, and `base64`. Interpreter payload examples are `python3 -c "open('.env')"` and `bash -c 'cat id_rsa'`.
+- **Safe Schema Masking:** On `.env*` reads via the `read` tool, the guard parses the variable names and comments. It returns a safe redacted schema mask with secret values masked as `********`. Agents can then inspect variable existence without leaking secrets into model context.
 - Standard non-secret fixtures (`.env.example`, `.env.sample`, `.env.template`) remain readable.
 
 ### 18. Interpreter Inline Evasion Scanner
-- Decodes and inspects inline interpreter payloads (`python -c`, `node -e`, `perl -e`, `ruby -e`, `osascript -e`, `bash -c`, `sh -c`, `zsh -c`, `powershell -enc`, `echo <base64> | base64 -d | sh`) to prevent smuggling live destructive commands, settings tampering, secret reads, or out-of-workspace writes past shell pattern checks.
+- Decodes and inspects inline interpreter payloads to prevent smuggling live destructive commands past shell pattern checks. Smuggled content includes settings tampering, secret reads, and out-of-workspace writes. The inspected forms are `python -c`, `node -e`, `perl -e`, `ruby -e`, `osascript -e`, `bash -c`, `sh -c`, `zsh -c`, `powershell -enc`, and `echo <base64> | base64 -d | sh`.
 
 ### 19. Conflict-Free Pre-Flight Guard
 - Evaluates `git merge-tree` against the base branch (`origin/main`, `origin/master`, `main`) before PR creation or final task handoff, ensuring changes can be merged cleanly without conflicts.
 
 ### 20. Merged Branch & Base Freshness Guard
 - Blocks pushing to branches already merged or associated with closed PRs in GitHub or Azure DevOps.
-- Blocks creating feature branches (`git switch -c`, `git checkout -b`) from a stale base: without an explicit start point, the current branch must be fresh against the remote default; an explicit start point that already contains the remote default (`origin/HEAD`) is accepted because the new branch is fresh by construction, and start points that cannot be resolved fail closed. Block reasons name the branch actually checked and remedies that work under the guard (rebase or ff-merge the branch, or branch from the remote default directly). Shell redirections attached to or following a branch creation (stdout/stderr redirection and fd duplication such as `2>&1`) are ignored when classifying the start point, because they never determine which commit the branch is created from.
-- Tag push refspecs are exempt: publishing an existing tag (`git push origin v1.2.0`, `git push origin refs/tags/v1.2.0`) and creating tags (`git tag v1.2.0`, `git tag -a -m ...`) are release operations, not branch mutations - only tag deletions (`git tag -d`, `git push origin :refs/tags/v1.2.0`, `--delete`) stay blocked.
+- Blocks creating feature branches (`git switch -c`, `git checkout -b`) from a stale base. Without an explicit start point, the current branch must be fresh against the remote default. An explicit start point that already contains the remote default (`origin/HEAD`) is accepted, because the new branch is fresh by construction. Start points that cannot be resolved fail closed. Block reasons name the branch actually checked. They also name remedies that work under the guard: rebase or ff-merge the branch, or branch from the remote default directly. Shell redirections attached to or following a branch creation are ignored when classifying the start point. Those redirections are stdout and stderr redirection and fd duplication such as `2>&1`. They never determine which commit the branch is created from.
+- Tag push refspecs are exempt. Publishing an existing tag (`git push origin v1.2.0`, `git push origin refs/tags/v1.2.0`) and creating tags (`git tag v1.2.0`, `git tag -a -m ...`) are release operations, not branch mutations. Only tag deletions (`git tag -d`, `git push origin :refs/tags/v1.2.0`, `--delete`) stay blocked.
 
 ### 21. Documentation Review & Synchronization Guard
 - Ensures that relevant documentation is updated whenever changes introduce new features, policies, or public tools before PR creation. Configurable via `.opencode/workflow-guard.json` (`requireDocumentation: true`) or `WORKFLOW_GUARD_REQUIRE_DOCS=1`.
-- 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.
+- Only **README.md** (root or package level) and files under **`docs/`** count as documentation updates. Arbitrary markdown does not satisfy this gate. That includes `.changeset/*.md` fragments and `CHANGELOG.md`.
 
 ### 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 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.
+- Blocks commands that spawn interactive text editors (`nano`, `vim`, `emacs`), interactive pagers (`less`, `more`) including through common shell wrappers, and interactive monitors (`top`, `htop`). It also blocks interactive rebase and patch prompts (`git rebase -i`, `git add -p`), `sudo`, and package managers missing non-interactive confirmation flags (`npm init` without `-y`, `apt-get` without `-y`). Pager and monitor names appearing only as command arguments are not treated as pager or monitor execution. Examples are `az keyvault secret show --name top` and `echo top`. Monitors are only flagged in command position. That means after wrappers such as `sudo`/`env`/`timeout`, through `eval` and `sh -c`, and via `busybox`. `top` batch mode stays allowed. Indirection this does not model is a known limitation. It covers `watch`/`xargs`/`man`, `find -exec`/`su -c`, and shell loop bodies such as `while true; do top; done`.
 - 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`.
+- **Desktop Notifications:** Emits native OS notifications when a policy blocks a command or when verification runs finish. The backends are Linux `notify-send` and macOS `osascript`. This keeps developers informed when their terminal is backgrounded. Configure it via `WORKFLOW_GUARD_NOTIFY=0`.
 
 ### 23. Package Supply-Chain & Dependency Hygiene Guard
 - Blocks destructive package manager actions that break dependency trees or pollute machines:
@@ -177,16 +181,32 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
   - `pip install --force-reinstall`: Enforces pinned requirements.
 
 ### 24. Completion Claims vs Evidence (Observability)
-- When the assistant's final response text asserts completion or passing verification ("all tests pass", "work is done", "verified"), the guard compares the claim against recorded verification evidence for that session.
-- Mismatches (failing verification, stale evidence due to mutations after the verify run, or no evidence at all) are journaled to the audit trail and logged at info level. This is **observability, not gating**: the response is never blocked, but a confident wrap-up cannot silently contradict a failing or absent verification state.
-- Uses the `experimental.text.complete` hook; claim detection is a conservative phrase heuristic to avoid false positives on casual wording.
+- When the assistant's final response text asserts completion or passing verification, the guard compares the claim against recorded verification evidence for that session. The trigger phrases are "all tests pass", "work is done", and "verified".
+- Mismatches are journaled to the audit trail and logged at info level. A mismatch means failing verification, stale evidence due to mutations after the verify run, or no evidence at all. This is **observability, not gating**. The response is never blocked, but a confident wrap-up cannot silently contradict a failing or absent verification state.
+- Uses the `experimental.text.complete` hook. Claim detection is a conservative phrase heuristic to avoid false positives on casual wording.
+
+### 25. Live-Documentation Research Floor
+- Closes the "guess from training data" loop. When a session accumulates **3 tool failures** with no live-documentation lookup since, the guard blocks the next **mutation or shell** call. It tells the agent to consult a current source (`websearch`/`webfetch`, or an MCP documentation tool) before retrying. Reads, greps, and research tools are never blocked, so the escape hatch is always the correct next action.
+- **Gated surface:** the floor covers `edit`/`write`/`patch`/`apply_patch`, the shell tools, and the guard's own mutating lifecycle tools (`guard_worktree_create`, `guard_worktree_cleanup`, `guard_recovery_restore`). A tool the guard provides must not be the way past a guard gate.
+- **Debt-based, not success-based:** the floor counts failures since the session last successfully consulted a live source. An unrelated successful tool does *not* clear the debt (unlike the circuit-breaker counter), so a benign `echo` cannot slip a guessed change back through. A successful research call clears it.
+- **A failed research attempt never accrues debt.** Only non-research failures count. Otherwise a flaky or rate-limited search would deepen the block the agent is trying to escape. The floor would then deadlock a session that followed its own advice.
+- **Research recognition:** the builtin names (`websearch`, `webfetch`, and common aliases) match outright. MCP sources match on documented server names, so `mcp__context7__*`, `mcp__deepwiki__*`, `mcp__tavily__*`, `mcp__brave__*`, and similar docs servers count. A guard inspection tool or a generic file reader cannot clear the debt by name accident. Add an unrecognised server with `researchTools` in project config, or `WORKFLOW_GUARD_RESEARCH_TOOLS` (comma-separated name fragments).
+- Prior art: iterative grounding / De-Hallucinator (arXiv 2401.01701), knowledge-lookup gates for agent writes, and deterministic supersession (STALE, arXiv 2605.06527). Failure-mode context: false/illusory completion (agents self-report done) and temporal obsolescence of training data.
+- Enabled **by default** to force the failover. Disable with `.opencode/workflow-guard.json` (`requireLiveDocs: false`) or `WORKFLOW_GUARD_REQUIRE_LIVE_DOCS=0`. Raise or lower the trigger with `liveDocFailureThreshold` or `WORKFLOW_GUARD_LIVE_DOC_THRESHOLD`. An unparseable, zero, or negative threshold falls back to the default of 3, so a typo cannot silently disable the floor. Decisions are journaled (`reason: live_docs_research_floor`) under both entrypoints. On OpenCode 1.x block feedback also reaches `client.app.log` at warn level. OpenCode 2 has no server-side log API, so V2 journals the decision and toasts instead.
+- **Known limit:** Code Mode `execute` is not gated, because the nested tools it calls do not pass through guard hooks. A session that reaches the floor can still mutate through that path, the same way it can through an unmodelled indirection described under Known Limits.
+- **Prerequisite:** the acting agent must be allowed to call a research tool. An agent whose toolset denies `websearch`/`webfetch` and exposes no MCP docs server cannot satisfy the floor. Grant one, or the agent will (correctly) stall on the block. This is an opt-out-able default for that reason.
+
+### 26. Sweeping Repository Claims vs Read Coverage (Observability)
+- Journal-only companion to Policy 25, covering the other failure mode. An agent skims one or two files and then asserts whole-repository facts. Examples are "the entire codebase uses X", "no other callers reference this", and "nothing depends on it".
+- Uses the `experimental.text.complete` hook to compare a sweeping claim against this session's read coverage (`sessionReadFileCount`: distinct files read or authored). A sweeping claim backed by fewer than 2 touched files is journaled to the audit trail (`Sweeping claim '<phrase>' with N file(s) read`) and logged at info level.
+- **Observability, not gating**, matching Policy 24. The response is never blocked or rewritten, because a grep-heavy investigation can legitimately support "no other callers" while touching few files. Prior art covers the EPISTEMIC LEDGER "bare assertion" (arXiv 2602.07549) and the agent-control-tower false-completion study. Both find that more context does not fix overclaiming, and that the check belongs in the system, not in self-report.
 
 ### Tool Description Honesty & Cross-Model Adherence
-- Via the `tool.definition` hook, the guard enriches tool descriptions to keep them honest and proactive across all model families (OpenAI, Gemini, Claude, and open-weights models):
+- Via the `tool.definition` hook, the guard enriches tool descriptions to keep them honest and proactive across all model families. The families are OpenAI, Gemini, Claude, and open-weights models:
   - `todowrite`: Explains its replacement-list lifecycle, finalization verification gate, and directs models to `guard_next_tasks` for roadmap discovery and `guard_status` for gate checks.
   - Mutating tools (`edit`, `write`, `apply_patch`): States preconditions (active todo, feature branch, prior read).
   - `task`: Guides orchestrator agents to isolate parallel mutations with `guard_worktree_create` and conduct secondary reviews via `guard_review_rubric` and `record_review`.
-- Via the `experimental.chat.system.transform` hook, the guard provides concise operational guidelines in the system prompt detailing available guard tools (`guard_next_tasks`, `guard_status`, `guard_review_rubric`, `guard_worktree_create`, `project_memory_*`, `learning_*`, `guard_why`), heavily encouraging open models and Gemini/Claude to proactively use workflow discipline features throughout development.
+- Via the `experimental.chat.system.transform` hook, the guard adds concise operational guidelines to the system prompt. The guidelines list the available guard tools: `guard_next_tasks`, `guard_status`, `guard_review_rubric`, `guard_worktree_create`, `project_memory_*`, `learning_*`, and `guard_why`. They strongly encourage open models and Gemini or Claude to use workflow discipline features throughout development.
 - Companion tools feature proactive action triggers ("Proactively call...", "Recommended at session start..."), and `guard_status` returns actionable `recommendedActions` directing models to the exact next step.
 
 ---
@@ -197,31 +217,32 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 
 ### `guard_worktree_create`
 - Creates an isolated git worktree for concurrent subagent execution: `guard_worktree_create(branch, baseBranch?)`.
-- Branch names are validated with `git check-ref-format --branch`; protected branches (the built-in `main`/`master` plus any configured via `protectedBranches` in `.opencode/workflow-guard.json`) are refused.
-- Worktrees are stored outside the repository under `~/.local/share/opencode/worktrees/<repo-name>/` (override with `WORKFLOW_GUARD_WORKTREE_DIR`), and the parent's `node_modules` is symlinked into the new worktree so tooling works without a fresh install.
-- If the branch already exists (as a local branch), the worktree is checked out on it; otherwise it is created from `baseBranch` (default `HEAD`).
+- Branch names are validated with `git check-ref-format --branch`. Protected branches are refused. These are the built-in `main` and `master`, plus any configured via `protectedBranches` in `.opencode/workflow-guard.json`.
+- Worktrees are stored outside the repository under `~/.local/share/opencode/worktrees/<repo-name>/`, which `WORKFLOW_GUARD_WORKTREE_DIR` can override. The parent's `node_modules` is symlinked into the new worktree, so tooling works without a fresh install.
+- If the branch already exists as a local branch, the worktree is checked out on it. Otherwise it is created from `baseBranch`, which defaults to `HEAD`.
 - Subject to the same todo gate as other mutations, and successful worktree mutations invalidate stale verification/review evidence.
 
 ### `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 are cleaned up. The path must be under the configured worktree storage directory, or be declared by the host's own worktree inventory (`ctx.worktree.list()` on OpenCode 2). 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.
-- On OpenCode 2, creation goes through the host worktree API when it is available, so the worktree lands in the operator's configured `worktree.directory` and appears in host inventory. The host's answer is validated independently (existing directory, registered worktree of this repository, not the primary tree) and any failure falls back to the guard's git path. Removal never delegates to the host: its `remove` takes a `force` flag with no snapshot step, so it could destroy uncommitted work that this policy preserves. After a successful removal the guard asks the host to refresh its inventory.
-- **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).
+- **Ownership validation:** Only registered worktrees of the current repository are cleaned up. The path must be under the configured worktree storage directory, or be declared by the host's own worktree inventory, which is `ctx.worktree.list()` on OpenCode 2. 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.
+- On OpenCode 2, creation goes through the host worktree API when it is available. The worktree then lands in the operator's configured `worktree.directory` and appears in host inventory. The host's answer is validated independently: an existing directory, a registered worktree of this repository, and not the primary tree. Any failure falls back to the guard's git path. Removal never delegates to the host. Its `remove` takes a `force` flag with no snapshot step, so it could destroy uncommitted work that this policy preserves. After a successful removal the guard asks the host to refresh its inventory.
+- **Idempotent for prunable entries:** A registered worktree whose directory is already gone is deregistered and reported as cleaned. The directory may be gone through manual removal, a crashed add, or external cleanup. Deregistration uses `git worktree prune`, which reports its exit status on failure. This lets stale admin entries that `git worktree list` shows as prunable 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. A temporarily unavailable path's admin entry can therefore be dropped. Worktree contents are never touched, so 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
-- All spawned git commands run with a sanitized environment: inherited git context variables (`GIT_INDEX_FILE`, `GIT_DIR`, `GIT_WORK_TREE`, ...) are stripped so the tools resolve the repository from their working directory alone. This makes them safe to invoke from inside git hooks, which export those variables.
+- All spawned git commands run with a sanitized environment. Inherited git context variables (`GIT_INDEX_FILE`, `GIT_DIR`, `GIT_WORK_TREE`, and others) are stripped, so the tools resolve the repository from their working directory alone. This makes them safe to invoke from inside git hooks, which export those variables.
 
 ### Inspection Tools
 ### `guard_status`
-- `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, a read-only `gitHygiene` snapshot (local branches already merged into the mainline, prunable worktree admin entries, and the current branch's base-behind distance — hygiene itself stays manual: the guard reports, it never prunes or deletes branches), and `pluginVersion`, the version of the loaded guard package, so a stale installation is visible.
-- On OpenCode 2 the same report is also reachable as the server-side `/guard-status` command (`ctx.command.transform`), which delivers the JSON as a synthetic message with no model turn. That path needs no separately installed TUI companion.
+- `guard_status`, `guard_audit`, `guard_why`, `guard_review_rubric`, `record_review`, `guard_review_followups`, and `guard_review_followup_resolve` provide runtime introspection. They cover 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, its iteration budget, and the calling-session outcome when applicable. It reports a read-only `gitHygiene` snapshot (local branches already merged into the mainline, prunable worktree admin entries, and the current branch's base-behind distance). Hygiene itself stays manual: the guard reports, it never prunes or deletes branches. `guard_status` also reports `pluginVersion`, the version of the loaded guard package, so a stale installation is visible.
+- On OpenCode 2 the same report is also reachable as the server-side `/guard-status` command (`ctx.command.transform`). It delivers the JSON as a synthetic message with no model turn. That path needs no separately installed TUI companion.
 - **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.
-- **`requireSubagentReview` strict recorder mode (opt-in):** projects that cannot tolerate root-session self-approval can set `requireSubagentReview: true` in `.opencode/workflow-guard.json`, or `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1` in the environment. In that mode `record_review` rejects APPROVALS recorded by the root session itself (a session with no parent) with an actionable message and a `subagent_recorder_required` audit entry; the verdict is not recorded and the review gate stays unsatisfied. Changes-requested verdicts remain relayable from any session, and `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0` disables the requirement even when project config enables it. The default keeps the documented relay flow for read-only reviewer toolsets.
-- **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.
+- **Review binding is content, not session identity:** A recorded approval satisfies the PR preflight when its binding matches the tree the PR would publish. The binding covers the repository, the commit hash, and the tracked-content worktree fingerprint. Any session may record the verdict or create the PR. Reviewers record from subagent sessions, binding the verdict to their parent or their own directory. Sessions can move between directories (`session_move`), and subagents can spawn from other roots. Keying the gate on the PR-creating session's ID would make the documented flow impossible to satisfy from linked worktrees. Freshness is scoped to the reviewed diff, which is tracked content. Untracked scratch-file cleanup and mutations in sibling worktrees cannot invalidate an approval. Any tracked edit or new commit does.
+- **Commit before you verify and review:** Both evidence gates bind to the HEAD commit hash, so a commit after either one invalidates it. Finish every tracked change first, then run verification, then record the review, then open the PR. That order satisfies both gates in one pass. Any other order costs a re-run. A review recorded before its change is committed keeps the same tracked fingerprint. The preflight then names the commit drift specifically and asks for the review again at the current commit.
+- **`record_review` accepts any recorder session:** Reviewer agents are often configured with a read-only toolset, for example glob, grep, read, and webfetch only. Such a reviewer cannot call `record_review` itself. The tool therefore accepts recorders of any session type and binds the verdict to the recording session's resolved directory. The tool result echoes that binding. 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.
+- **`requireSubagentReview` strict recorder mode (opt-in):** Projects that cannot tolerate root-session self-approval can set `requireSubagentReview: true` in `.opencode/workflow-guard.json`. They can also set `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1` in the environment. In that mode `record_review` rejects APPROVALS recorded by the root session itself, which is a session with no parent. The rejection carries an actionable message and a `subagent_recorder_required` audit entry. The verdict is not recorded and the review gate stays unsatisfied. Changes-requested verdicts remain relayable from any session. `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0` disables the requirement even when project config enables it. The default keeps the documented relay flow for read-only reviewer toolsets.
+- **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. They remain open across sessions until explicitly resolved with `guard_review_followup_resolve`, and 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.
 
 ---
 
@@ -234,7 +255,7 @@ The ONLY override is the **`WORKFLOW_GUARD_ALLOW_LIVE=1` environment variable**,
 
 Verification command selection uses **`WORKFLOW_GUARD_VERIFY`** (empty = auto-detect off, string = your command).
 
-There is **deliberately no in-command override** (no `# allow-live` marker): an override the agent can append to its own command - or is told about in an error message - is an override the agent will use.
+There is **deliberately no in-command override** and no `# allow-live` marker. An override the agent can append to its own command, or is told about in an error message, is an override the agent will use.
 
 **Workflow & security gates (Policies 1, 2, 3, 6, 7, 8) have no override** - by design.
 

package/docs/policy-posture.md

@@ -43,7 +43,7 @@ therefore looks applied on the other host and enforces nothing.
 
 Both hosts read only their own key, so carrying both cannot double-apply a rule
 or make them conflict. `--format 2.0` and `--format next` exist for a pinned
-host; `both` is the default because the silent no-op is the failure this
+host. `both` is the default, because the silent no-op is the failure this
 surface exists to prevent.
 
 Schema acceptance is not runtime acceptance. `@opencode/schema` 2.0.10 admits a

package/docs/testing.md

@@ -13,18 +13,18 @@ npm run typecheck   # or: npm run build
 ```
 
 ### 2. In-Memory Unit Tests
-Runs the comprehensive unit and adversarial tests covering all guard policies, lifecycle validation, subagent parent-chain resolution, privilege-isolated verification, and path/symlink boundary checks:
+Runs the unit and adversarial tests covering all guard policies, lifecycle validation, subagent parent-chain resolution, privilege-isolated verification, and path/symlink boundary checks:
 ```bash
 npm test            # runs test.mts with isolated XDG state/data (Node >= 22.18)
 ```
 
 ### 3. OpenCode Runtime & Install Tests
-Packs the npm tarball, installs it into an isolated project to verify the modular entrypoint resolves, then copies the server source into an isolated `.opencode/workflow-guard-source/` directory and exposes its `WorkflowGuard` plugin function through an explicitly registered `.opencode/plugins/` adapter. A provider-free config probe verifies OpenCode resolves that local plugin before the opt-in model-driven `opencode run` probes exercise its hooks:
+Packs the npm tarball into an isolated project to verify the modular entrypoint resolves. It then copies the server source into an isolated `.opencode/workflow-guard-source/` directory. That source's `WorkflowGuard` plugin function is exposed through an explicitly registered `.opencode/plugins/` adapter. A provider-free config probe verifies OpenCode resolves that local plugin before the opt-in model-driven `opencode run` probes exercise its hooks:
 ```bash
 npm run test:install # package install + provider-free OpenCode loader check
 WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # also run model-driven policy probes with OpenCode's most recently selected model
 ```
-Package and loader checks remain deterministic. Live probes explicitly select the first entry in OpenCode's persisted recent-model state (`${XDG_STATE_HOME:-~/.local/state}/opencode/model.json`) instead of silently inheriting the configured default model. Set `WORKFLOW_GUARD_LIVE_MODEL=provider/model` to override that selection; provider credentials still come from the normal OpenCode environment. If the selected model provider rejects a live prompt before guard behavior can run because credits, rate limits, capacity, overload, or an unresolvable model make the provider unavailable, that live case is reported as unavailable rather than as a guard failure. The classifier matches the host's literal `Model unavailable:` error line rather than the bare phrase, so model prose cannot mask a real guard regression. Other live-runtime failures still fail the suite.
+Package and loader checks remain deterministic. Live probes explicitly select the first entry in OpenCode's persisted recent-model state (`${XDG_STATE_HOME:-~/.local/state}/opencode/model.json`). They never silently inherit the configured default model. Set `WORKFLOW_GUARD_LIVE_MODEL=provider/model` to override that selection. Provider credentials still come from the normal OpenCode environment. A provider may reject a live prompt before guard behavior can run. That happens when credits, rate limits, capacity, overload, or an unresolvable model make the provider unavailable. Such a case is reported as unavailable rather than as a guard failure. The classifier matches the host's literal `Model unavailable:` error line rather than the bare phrase, so model prose cannot mask a real guard regression. Other live-runtime failures still fail the suite.
 
 ### 4. Full Verification Suite
 Runs typecheck, unit tests, and live runtime installation tests in sequence: