opencode-turnstile 0.2.1 → 0.2.5

package/README.md

@@ -2,39 +2,49 @@
 
 An [OpenCode](https://opencode.ai) v2 plugin that mechanically enforces an
 agent pipeline: planner → plan-reviewer → executor → test-runner → reviewer.
-The workflow
-itself lives in a policy instruction file (e.g. `AGENTS.md`) that tells the
-agents what the pipeline is; turnstile complements that file rather than
-replacing it. The policy steers the agents, and turnstile blocks the
-dispatches that violate it.
+The pipeline policy is injected at runtime by the plugin: when the plugin is
+loaded, it prepends the orchestrator policy to the primary session's first
+task result every task (see [Policy injection](#policy-injection)), so a fresh
+install can never lose it and nothing is written to any instructions file at
+install time. Per-agent instruction lines live in each `agents/<name>.md`. The
+policy steers the agents, and turnstile blocks the dispatches that violate it.
 
 The entry point is `turnstile.ts`; behavior lives in focused modules under
-`src/` (one boundary per file: types, journal, state, markers, gates,
-setup). The plugin has zero runtime dependencies and fails open.
+`src/` (one boundary per file: types, config, policy, journal, state,
+markers, evidence, gates, tool-policy, setup). The plugin has zero runtime
+dependencies and fails open.
 
 Verify with:
 
 ```sh
 npm install
-npm run ci          # ci:host (lint, format:check, typecheck, check:markers, test) + install:check
+npm run ci          # ci:host (lint, format:check, typecheck, check:markers, test with a 100% coverage gate) — host chain only; green on a fresh clone
+npm run ci:installed  # install:check — run after `npm run init` on a machine with installed artifacts
 ```
 
 ## What it enforces
 
-| Gate                   | Behavior                                                                                                                                                                                                                                                                          |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Plan-approval gate     | `executor` subagent dispatches are blocked until a plan-reviewer result in the session recorded `VERDICT: APPROVE` (when any plan exists in `.opencode/plans/*.md`), or the dispatch prompt contains the literal marker `USER WAIVER:`; plan-file changes invalidate the approval |
-| Reviewer dispatch gate | `reviewer` subagent dispatches are blocked until a test-runner result in the session recorded `GATE: PASS`, or the dispatch prompt contains the literal marker `USER WAIVER:`                                                                                                     |
-| Reviewer round cap     | Max 2 `reviewer` dispatches per task without a `GATE: PASS`                                                                                                                                                                                                                       |
-| Decomposition gate     | `executor` dispatches must cite `chunk-N` / `AC-n` when any plan in `.opencode/plans/*.md` has a `## Decomposition` block                                                                                                                                                         |
-| Read horizon           | Warns at 8 whole-file `read` calls per session, blocks at 15 (prefer grep/glob)                                                                                                                                                                                                   |
-| Marker parsing         | `GATE:` / `VERDICT:` markers are parsed from task results and child-session text, deduped per task; marker-less outputs from marker-contracted agents (test-runner/reviewer/plan-reviewer) are journaled                                                                          |
-| Trace                  | JSONL journal of dispatches, gate transitions, verdicts, blocked calls, bash commands, errors                                                                                                                                                                                     |
-| Decoding clamps        | executor/test-runner/debugger temperature ≤ 0.2; reviewer and plan-reviewer temperature = 0                                                                                                                                                                                       |
-| Compaction             | Injects a "preserve verbatim" instruction for markers and findings                                                                                                                                                                                                                |
-
-A new user prompt resets the session's gate state. Gate state survives
-restarts via journal replay (last 2000 lines of `GATE: PASS` entries).
+| Gate                   | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Plan-approval gate     | `executor` subagent dispatches are blocked until this task's plan-reviewer recorded `VERDICT: APPROVE` (when any plan exists in `.opencode/plans/*.md`), or the task has a human approval — a prompt-channel `PLAN APPROVED:` in the user's prompt, a prompt-channel `USER WAIVER:` waiver, or a permission-prompt reply (`always`/`once`/`reject`); plan-content changes invalidate approvals issued against the previous plans-dir signature (replayed approvals are accepted once, then stamped). See [Waivers and approvals](#waivers-and-approvals)                                                            |
+| Reviewer dispatch gate | `reviewer` subagent dispatches are blocked until a test-runner result in the session recorded a `GATE: PASS` _verified_ by the current task's bash/shell executions — a matching exit-0 test command under the default `gateEvidence:enforce`; `flag` flips on trust (still stamped), `off` never stamps — or the user's prompt carries a prompt-channel `USER WAIVER:` waiver (a `USER WAIVER:` in an agent-composed dispatch prompt unlocks nothing; see [Waivers and approvals](#waivers-and-approvals))                                                                                                         |
+| Reviewer round cap     | Max 2 `reviewer` dispatches per task, regardless of gate state; a prompt-channel `USER WAIVER:` waiver bypasses the cap and does not count toward it (a `USER WAIVER:` in a dispatch prompt does not; see [Waivers and approvals](#waivers-and-approvals))                                                                                                                                                                                                                                                                                                                                                          |
+| Decomposition gate     | `executor` dispatches must cite `chunk-N` / `AC-n` when any plan in `.opencode/plans/*.md` has a `## Decomposition` block                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Read horizon           | Warns at 8 whole-file `read` calls per session, blocks at 15 (prefer grep/glob)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Tool-call policy gate  | `bash`/`shell` commands and `write`/`edit` target paths are matched in `execute.before` against a configurable denylist and blocked with `BLOCKED by turnstile:` under `toolPolicy.mode: enforce`; `shadow` journals the would-block without throwing (adoption path), `off` is a silent no-op. Default `bashDeny` blocks the git-protective operations in [`src/policy.ts`](src/policy.ts) (worktree, branch `switch`/`checkout`, `merge`, `gh pr create or merge`); `pathDeny` defaults empty so ordinary editing is never blocked until configured. `session_move` is journaled as telemetry only, never blocked |
+| Commit-lint            | `bash`/`shell` `git commit -m '<subject>'` messages are validated as conventional commits when `gitGates.commitMessages` is on (default): a non-conventional subject throws `BLOCKED by turnstile:` (journaled `reason:"invalid-commit-message"`) under `gitGates.mode: enforce`; `shadow` journals only, `off` is a no-op. An uninspectable form (`-F`/`-t`/`--edit`/interactive; `--amend -m` is inspectable) is blocked under `enforce` (`reason:"commit-message-uninspectable"`) — pass the subject with `git commit -m <subject>`                                                                              |
+| Landing gate           | `git push` without a reviewer `VERDICT: APPROVE` for the current task is `BLOCKED by turnstile:` (journaled `reason:"no-landing-approval"`) under `gitGates.mode: enforce`; `shadow` journals only, `off` is a no-op. Approval comes only from a reviewer delivery `VERDICT: APPROVE` (streamed text is inert); `gh pr create or merge` stays denied by the default `bashDeny` list, and every `git push` is journaled as landing telemetry; a repeat push under `enforce` escalates to a human ask — the repeat push is the decision point                                                                         |
+| Marker parsing         | `GATE:` / `VERDICT:` markers are parsed from task results and child-session text, deduped per task; marker-less outputs from marker-contracted agents (test-runner/reviewer/plan-reviewer) are journaled                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Trace                  | JSONL journal of dispatches, gate transitions, verdicts, blocked calls, bash commands, errors; `setup` heartbeat per session (plugin version, config digest, hook count), stream-death errors, unresolvable-agent dispatch errors                                                                                                                                                                                                                                                                                                                                                                                   |
+| Decoding clamps        | executor/test-runner/debugger temperature ≤ 0.2; reviewer and plan-reviewer temperature = 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Compaction             | Injects a "preserve verbatim" instruction for markers and findings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+A new user prompt resets the session's gate state. Replayed gate state
+survives a restart and the next user prompt (the resume prompt), then
+reverts: every later prompt starts a clean gate cycle. Replay reads the
+last 2000 lines of the journal, spanning the current file and its previous
+rotated generation (`GATE: PASS` and plan `VERDICT: APPROVE`
+entries).
 
 ## How it fits the ecosystem
 
@@ -75,7 +85,8 @@ are visible in this repo's tests:
 - Verifiable state. `GATE:` and `VERDICT:` markers are parsed from
   child session text (`src/markers.ts`), stored per parent session
   (`src/state.ts`), and replayed from the JSONL journal on restart, so
-  gate state survives sessions and reloads rather than living in a
+  replayed gate state survives a restart and the next user prompt, then
+  every later prompt starts a clean gate cycle rather than living in a
   prompt.
 - Failure posture. Hooks fail open: an internal error is journaled and
   the call proceeds. The only refusals are deliberate
@@ -101,17 +112,20 @@ ways to use it; pick one, and do not combine the plugin-array path with
 the CLI install.
 
 1. **Zero-config enforcement (plugin only).** Add the package to your
-   OpenCode config's plugin array and restart. turnstile loads and
-   enforces its gates, but neither the pipeline agent definitions nor the
-   AGENTS.md contract block are installed:
+   OpenCode config's plugin array and restart. turnstile loads and enforces
+   its gates, injecting the orchestrator policy into the primary session at
+   runtime (see [Policy injection](#policy-injection)) — nothing is written to
+   any instructions file, and the pipeline agent definitions are not installed
+   by this option alone:
 
    ```json
    { "plugins": ["opencode-turnstile"] }
    ```
 
-2. **Full install via the CLI.** `npx opencode-turnstile init` installs
-   the plugin, the pipeline agent definitions, and the managed contract
-   block in `~/.config/opencode/AGENTS.md` (see
+2. **Full install via the CLI.** `npx opencode-turnstile init` installs the
+   plugin and the pipeline agent definitions; the orchestrator policy is
+   injected at runtime by the plugin, so no contract block is written to
+   `~/.config/opencode/AGENTS.md` (see
    [From a clone](#from-a-clone) below for the same commands run from
    a clone).
 
@@ -124,9 +138,9 @@ the CLI install.
 Turnstile has **no** npm lifecycle hook (`postinstall`, etc.). Installing
 `opencode-turnstile` as a dependency never writes to
 `~/.config/opencode`; it only makes the gates available through the
-plugin array. Everything else (agent definitions, the AGENTS.md contract
-block) happens only when you run an explicit command. This is deliberate:
-writes to your config directory are opt-in, not automatic.
+plugin array. Everything else (the agent definitions) happens only when you
+run an explicit command. This is deliberate: writes to your config directory
+are opt-in, not automatic.
 
 ### Modes
 
@@ -156,16 +170,21 @@ The plugin updates with your dependency manager (`npm upgrade
 opencode-turnstile`, or your registry's equivalent). Re-run `check` to see
 whether anything is outdated or drifted, then `init` to re-sync only what
 changed: `npx opencode-turnstile init --copy` for package installs,
-`npm run init -- --copy` from a clone. The AGENTS.md contract block is
-re-synced the same way, keeping only the managed block in step.
+`npm run init -- --copy` from a clone. The injected orchestrator policy
+travels with the plugin, so re-syncing the plugin re-supplies it — there is
+no separate contract block to re-sync.
 
 ### Uninstall
 
 `npx opencode-turnstile uninstall` reverses the install: it removes
-ledger-owned copies and repo-owned symlinks and unmerges the managed
-contract block from AGENTS.md. It is idempotent and ownership-aware:
+ledger-owned copies and repo-owned symlinks and stops injecting the
+orchestrator policy. It is idempotent and ownership-aware:
 files it never installed (untracked files, symlinks pointing outside the
-repo) are left alone, and a second run is a clean no-op.
+repo) are left alone, and a second run is a clean no-op. Injected policy is
+gone the moment the plugin is unloaded; a legacy contract block once written
+by hand into `~/.config/opencode/AGENTS.md` is not owned by turnstile and is
+removed separately — see
+[Migrating a legacy AGENTS.md block](#migrating-a-legacy-agentsmd-block).
 
 ### From a clone
 
@@ -295,9 +314,10 @@ Paste the output into `~/.config/opencode/opencode.json` (see the
 [Set the agents' models](#set-the-agents-models) section).
 `opencode-turnstile init -- --print-model-config` routes the same flags
 through `scripts/install.mjs` and adds nothing of its own: `install.mjs`
-recognizes `--print-model-config` and prints before writing, while the router
-still idempotently installs the contract block in
-`~/.config/opencode/AGENTS.md` in the same run.
+recognizes `--print-model-config` and prints before writing, and the router
+skips the agents install step entirely in that case — so the whole command
+writes nothing (no ledger, no links, no agents, no injected policy). Plain
+`init` still installs everything as usual.
 
 ### Customizing the pipeline agents
 
@@ -353,69 +373,115 @@ Shared caveats:
 - Symlinks point at the clone's absolute path. Do not move, rename, or
   delete the checkout; if you relocate it, re-run `npm run init`.
 - `npm run install:check` reports drift between the manifest and what is
-  actually installed; local `npm run ci` gates on it. GitHub CI runs
-  `npm run ci:host`, the same chain without the install check, because a
-  runner has no installs to check. Verify a copy install with
+  actually installed. There is no `install:agents:check`: the orchestrator
+  policy is injected from code (`src/policy.ts`), not a manifest-managed
+  template, so nothing to verify there — `npm run ci:installed` is now just
+  `install:check`. These install checks must run after `npm run init` on a
+  machine with artifacts installed — a fresh clone has nothing to check. The
+  host chain (`npm run ci` = `npm run ci:host`) covers lint, format:check,
+  typecheck, check:markers, and test without the install checks. GitHub CI
+  runs `npm run ci:host`, the host chain only, because a runner has no
+  installs to check. Verify a copy install with
   `npm run install:check -- --copy`.
 
-### Install the AGENTS.md contracts
-
-Turnstile enforces what your instructions file declares. Install the
-matching contract block into your global AGENTS.md:
+### Policy injection
+
+Turnstile does not read orchestrator policy from a file at install time —
+it makes that policy available by injecting it at runtime. When the plugin is
+loaded, `src/setup.ts` prepends the orchestrator policy paragraph from
+`src/policy.ts` to the primary session's first `task` (or `subagent`) result
+delivery, once per task, via the `tool.hook("execute.after")` handler — the
+same hook the plugin already uses to rewrite tool output reaching the model.
+The source of truth is code shipped with the plugin, so a fresh install can
+never lose it, and it follows the plugin through updates and
+uninstall–reinstall cycles.
+
+- **Fail-open.** The injection is fully guarded with an inner try/catch; on
+  failure it journals a `type:"policy"` entry with `injected:false` and
+  proceeds — a broken injection never blocks a tool call.
+- **Per-task idempotency.** A `GateState.policyInjected` flag (cleared on
+  each new prompt, so the block re-injects per task) means the policy is
+  prepended exactly once per task, not once per turn.
+- **Marker placeholders.** The injected paragraph quotes the gate/verdict
+  markers with `<n>` placeholders (e.g. `GATE: PASS tests=<n> passed=<n>
+failed=<n>`, `VERDICT: APPROVE crit=<n> high=<n> med=<n> low=<n>`) rather
+  than concrete digits, and never the pipe-joined `PASS|FAIL` form. The
+  plugin parses markers from _any_ session text, so a fully concrete example
+  echoed back by the model could flip a gate; the placeholder form stays
+  unparseable while remaining human-readable.
+- **Per-agent instructions** are not injected by the plugin: they live in
+  each `agents/<name>.md` installed alongside the plugin.
+
+With the plugin **off**, none of this prose is present anywhere — there is no
+AGENTS.md block to fall back on. That is the deliberate tradeoff: loss-proof
+by construction while the plugin loads, and a known, documented gap when it
+does not.
+
+### Migrating a legacy AGENTS.md block
+
+If a previous turnstile install once wrote a managed contract block into
+`~/.config/opencode/AGENTS.md`, that block is now orphaned: the plugin no
+longer reads or manages it, and it will coexist with the injected policy
+(duplicate prose until removed). There is deliberately no installer to remove
+it — turnstile no longer owns that file, so it never rewrites it. Delete the
+sentinel-delimited block by hand, once:
 
 ```sh
-node scripts/install-agents.mjs          # or: npm run install:agents
+# ~/.config/opencode/AGENTS.md — delete the section between the
+# `<!-- turnstile:start -->` and `<!-- turnstile:end -->` sentinels, then save
 ```
 
-- Default target: `~/.config/opencode/AGENTS.md` (override with `--file`).
-- The block is delimited by `<!-- turnstile:start -->` …
-  `<!-- turnstile:end -->` sentinels; re-running updates only that block
-  and preserves all surrounding personal content.
-- Legacy targets are adopted automatically. If the file already contains
-  pipeline-gates content _without_ sentinels (e.g. an install from before
-  the block was managed), the installer classifies the existing section:
-  equivalent to the template, it wraps the section in sentinels without
-  changing its content; differing from the template, it backs the file up
-  to `<name>.bak.<timestamp>` and replaces the section with the current
-  block. Pass `--no-adopt` to refuse both and print reconciliation
-  instructions instead.
-- The installer refuses (exit 1, no write) only when a target is
-  ambiguous (more than one turnstile section) or corrupted (a start
-  sentinel without an end sentinel); reconcile those by hand.
-- `--check` reports the outcome without writing: OK, or the adoption
-  decision (would-adopt-equivalent / would-replace / drift), exiting 0
-  only for OK. Useful in CI or dotfiles setup.
-- Agent definitions and the plugin itself are installed separately via
-  `npm run init` (symlinks, for development) or
-  `npm run init -- --copy` (see the Install section above).
-
-Alternatively, in an OpenCode session, invoke the bundled
-`turnstile-setup` skill, which runs the installer and verifies marker
-sync. The skill ships in the package and installs to
-`~/.config/opencode/skills/turnstile-setup/SKILL.md`; the template
-source lives at `templates/global-AGENTS.md`.
+After that, the injected policy is the single source of orchestrator policy
+for the session.
 
 ## Configuration
 
 Defaults live in code (`src/config.ts`); override via
 `~/.config/opencode/turnstile.json`, environment variables, or both.
+
+**Quick start: copy the example config** — [`examples/turnstile.example.json`](examples/turnstile.example.json)
+to `~/.config/opencode/turnstile.json` and edit from there. Every key in it
+is optional and matches the code defaults; delete any key to fall back to the
+default. One key is deliberately omitted from the example:
+
+- `metricsDir`: computed at load time (`$XDG_DATA_HOME/opencode/metrics`,
+  fallback `~/.local/share/opencode/metrics`); if you set it yourself it must
+  be an absolute path (`~` is not expanded)
+
+The example also carries `gateMarker` / `verdictMarker` verbatim so you can
+see the format; leave them alone unless you are intentionally changing
+the marker syntax (the shipped subagent definitions emit the canonical
+markers).
+
 Precedence: defaults < config file < env. The plugin reads config once, at
 setup; restart sessions to apply. Invalid keys are ignored and journaled
 (fail-open); a malformed config file never breaks the host.
 
-| Key                                                                                                     | Default                                                                       | Meaning                                                           |
-| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `metricsDir`                                                                                            | `$XDG_DATA_HOME/opencode/metrics`, fallback `~/.local/share/opencode/metrics` | directory for both telemetry files                                |
-| `journalMaxBytes`                                                                                       | 5242880                                                                       | rotate a journal file past this size                              |
-| `journalMaxGenerations`                                                                                 | 5                                                                             | rotated generations kept per journal                              |
-| `maxReviewerRounds`                                                                                     | 2                                                                             | reviewer dispatches per task without `GATE: PASS`                 |
-| `readWarn` / `readBlock`                                                                                | 8 / 15                                                                        | whole-file read horizon                                           |
-| `waiverMarker`                                                                                          | `USER WAIVER:`                                                                | literal waiver marker                                             |
-| `plansDir`                                                                                              | `.opencode/plans`                                                             | executor decomposition scan directory                             |
-| `trace`                                                                                                 | `true`                                                                        | write the human-readable trace file (JSONL journal always writes) |
-| `agents.reviewer` / `agents.planReviewer` / `agents.executor` / `agents.testRunner` / `agents.debugger` | `reviewer` / `plan-reviewer` / `executor` / `test-runner` / `debugger`        | agent names recognized in dispatches                              |
-| `agents.bareOutput`                                                                                     | `["test-runner", "reviewer", "plan-reviewer"]`                                | agents whose marker-less output is a violation                    |
-| `gateMarker` / `verdictMarker`                                                                          | canonical regex sources                                                       | marker patterns, compiled with `gm`                               |
+| Key                                                                                                     | Default                                                                        | Meaning                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metricsDir`                                                                                            | `$XDG_DATA_HOME/opencode/metrics`, fallback `~/.local/share/opencode/metrics`  | directory for both telemetry files                                                                                                          |
+| `journalMaxBytes`                                                                                       | 5242880                                                                        | rotate a journal file past this size                                                                                                        |
+| `journalMaxGenerations`                                                                                 | 5                                                                              | rotated generations kept per journal                                                                                                        |
+| `maxReviewerRounds`                                                                                     | 2                                                                              | reviewer dispatches per task, regardless of gate state (waived dispatches exempt)                                                           |
+| `maxSessions`                                                                                           | 64                                                                             | LRU cap on tracked sessions (gate state, child→parent edges, verdicts); registered live parents are never evicted                           |
+| `readWarn` / `readBlock`                                                                                | 8 / 15                                                                         | whole-file read horizon                                                                                                                     |
+| `waiverMarker`                                                                                          | `USER WAIVER:`                                                                 | literal waiver marker                                                                                                                       |
+| `approvalMarker`                                                                                        | `PLAN APPROVED:`                                                               | literal prompt-channel plan-approval marker                                                                                                 |
+| `plansDir`                                                                                              | `.opencode/plans`                                                              | executor decomposition scan directory                                                                                                       |
+| `trace`                                                                                                 | `true`                                                                         | write the human-readable trace file (JSONL journal always writes)                                                                           |
+| `agents.reviewer` / `agents.planReviewer` / `agents.executor` / `agents.testRunner` / `agents.debugger` | `reviewer` / `plan-reviewer` / `executor` / `test-runner` / `debugger`         | agent names recognized in dispatches                                                                                                        |
+| `agents.bareOutput`                                                                                     | `["test-runner", "reviewer", "plan-reviewer"]`                                 | agents whose marker-less output is a violation                                                                                              |
+| `gateMarker` / `verdictMarker`                                                                          | canonical regex sources                                                        | marker patterns, compiled with `gm`                                                                                                         |
+| `gateEvidence`                                                                                          | `enforce`                                                                      | `enforce` requires a correlating exit-0 test command to flip the gate; `flag` flips on trust (stamps `verified`); `off` journals without it |
+| `evidencePattern`                                                                                       | a npm/pnpm/yarn/bun/deno/node `--test`/pytest/`make test`/go/cargo pattern     | regex matched (case-insensitively) against bash/shell commands; user-overridable for non-JS toolchains (e.g. Ruby/`rspec`)                  |
+| `toolPolicy.mode`                                                                                       | `enforce`                                                                      | `enforce` blocks matching commands/paths; `shadow` journals would-blocks without throwing (adoption path); `off` is a silent no-op          |
+| `toolPolicy.bashDeny`                                                                                   | the git-protective defaults (worktree, branch switch/checkout, merge, `gh pr`) | case-insensitive regex sources matched against `bash`/`shell` commands; an invalid source is dropped and journaled                          |
+| `toolPolicy.pathDeny`                                                                                   | `[]` (empty)                                                                   | case-insensitive regex sources matched against `write`/`edit` target paths; a dropped source is journaled                                   |
+| `toolPolicy.observeSessionMove`                                                                         | `true`                                                                         | journal `session_move` dispatches as telemetry (never blocks)                                                                               |
+| `gitGates.mode`                                                                                         | `shadow`                                                                       | `shadow` would-block without throwing; `enforce` blocks invalid commits and unapproved pushes (opt-in), `off` is a silent no-op             |
+| `gitGates.commitMessages`                                                                               | `true`                                                                         | validate `git commit -m` subjects as conventional commits; `shadow` journals, `enforce` blocks, `off` is a no-op                            |
+| `gitGates.commitFormat`                                                                                 | a conventional-commits regex source                                            | conventional-commits regex source (compiled `^...$`) matched against each subject; a bad source is dropped and journaled                    |
+| `gitGates.landingGate`                                                                                  | `true`                                                                         | gate `git push` on this task reviewer `VERDICT: APPROVE`; `shadow` journals, `enforce` blocks then escalates, `off` is a no-op              |
 
 Environment variables (override the file):
 
@@ -426,7 +492,7 @@ Environment variables (override the file):
 ## Markers
 
 Subagents must emit these as the first line of their output. These examples
-are the canonical syntax; CI asserts the parser in `turnstile.ts` accepts
+are the canonical syntax; CI asserts the parser in `src/markers.ts` accepts
 exactly them.
 
 ```
@@ -437,44 +503,142 @@ VERDICT: APPROVE crit=0 high=0 med=2 low=1
 VERDICT: BLOCK crit=1 high=0 med=0 low=2
 ```
 
-Waiver marker (must appear in the reviewer dispatch prompt, verbatim):
+Waiver and approval markers (must appear in the user's prompt, verbatim — a dispatch prompt that merely contains the marker unlocks nothing; see [Waivers and approvals](#waivers-and-approvals)):
 
 ```
 USER WAIVER: <the user's words>
+PLAN APPROVED: <the user's words>
 ```
 
+## Waivers and approvals
+
+Turnstile reads a waiver or a human plan approval only from the user's OWN
+prompt — the plugin observes it at prompt admission, never from an agent's
+dispatch prompt. This is the core of issue #34: a marker inside an
+agent-composed prompt must never unlock a gate.
+
+- **Prompt-channel waiver.** Put the literal marker `USER WAIVER:` in the text
+  of your prompt to waive the plan gate and the reviewer gate for the task.
+  The waiver is provenance-checked: it must come from the user prompt, and a
+  dispatch prompt that merely contains `USER WAIVER:` unlocks nothing.
+- **Prompt-channel approval.** Put `PLAN APPROVED:` in your prompt to approve
+  the plan the same way a plan-reviewer `VERDICT: APPROVE` would; it sets the
+  plan verdict and records human provenance, and replays across restart
+  exactly like a reviewer verdict.
+- **Permission-prompt escalation.** When no approval holds, the first
+  executor dispatch escalates the plan gate to the human through OpenCode's
+  permission surface: `permission.evaluate` forces an `ask` that names the
+  plan file and its head. The human replies — `always` approves for the rest
+  of the task, `once` grants a single dispatch, and `reject` keeps the gate
+  red (that single reply is consumed).
+
+Do not create, paste, or relay a `USER WAIVER:` / `PLAN APPROVED:` marker to
+open a gate — only the user's own prompt carries a real waiver or approval.
+
 ## What turnstile is not
 
 Turnstile is a speed bump and an audit trail, not a security boundary.
 
-- Any text matching the gate marker, including a marker an agent
-  hallucinated or copied from documentation, flips `hasGatePass`. An agent
-  that wants a green gate can emit `GATE: PASS tests=1 passed=1 failed=0`
-  without running anything.
-- `USER WAIVER:` as a substring anywhere in a dispatch prompt unlocks the
-  reviewer gate. A prompt-injected waiver is indistinguishable from a real
-  one.
+- Any text matching the gate marker — including a marker an agent
+  hallucinated or copied from documentation — is journaled `verified:false`
+  under the default `gateEvidence:enforce` mode and does not flip
+  `hasGatePass` unless the current task's bash/shell executions contain a
+  matching exit-0 test command (plausibility checked against
+  `evidencePattern`). An agent that wants a green gate can no longer emit
+  `GATE: PASS tests=1 passed=1 failed=0` without running anything — but
+  `gateEvidence:flag` reverts to the historical flip-on-trust semantics
+  (still stamped `verified:false`), and `gateEvidence:off` journals without
+  the field at all.
+- A `GATE: PASS` is only as trustworthy as the journal: an attacker who can
+  write or replay the metrics directory can craft a `verified:true` entry,
+  and `flag`/`off` make a fabricated marker trust-lossless. Tests that run
+  outside the observable bash/shell surface (external CI, a differently
+  named execution tool) leave enforce mode with no evidence to verify
+  against — operators in that situation use `flag`/`off` at the cost of the
+  guarantee. The journal records what was _claimed_, never proof.
+- The dispatch-prompt waiver-forgery vector is closed: a `USER WAIVER:` (or
+  `PLAN APPROVED:`) substring inside an agent-composed dispatch prompt
+  unlocks nothing — turnstile reads waivers and approvals only from the
+  user's prompt at admission. The residual trust stance is unchanged: the
+  journal is still the record of what was _claimed_ (an attacker who can
+  write or replay the metrics directory can still craft entries), so the
+  journal is treated as sensitive data (see SECURITY.md).
 - `scripts/check-markers.mjs` guards against accidental drift between the
   parser and documented markers; it cannot guard against forgery, because
   the markers are plain prose by design.
+- The `bash`/`shell`/`write`/`edit` denylist is a deterrent, not a sandbox: it
+  matches strings, so `bash -c "$X"`, script files, `eval` indirection, and
+  values sourced from the environment still bypass it. A block names the matched
+  _rule_ (never the raw command, per the redaction contract); a dropped or
+  invalid regex _source_ means the operation it guarded is now **allowed**
+  (documented so a config typo weakens the policy visibly in the journal rather
+  than silently). The git rules are global-option tolerant, so `git -C dir
+checkout main` is caught as well as `git checkout main`, and the checkout guard
+  allows the file-restore form `git [global options] checkout [<ref>] -- <path>`
+  while blocking `git [global options] checkout <branch>` and `-b`/`-C`; but two
+  gaps remain by design. `git` **aliases** (e.g. `git co main`, `git cm -m x`)
+  are not matched, because a rule names `git` plus a literal subcommand only; and
+  the wider base can _over-match_ — e.g. `git commit -m "… merge …"` trips the
+  `merge` rule. `session_move` never blocks.
+- MCP tools and other tool names not named in `execute.before` (`task`,
+  `subagent`, `read`, `bash`, `shell`, `write`, `edit`, `session_move`) remain
+  unguarded. Governing them is a follow-on, not part of this policy layer.
 
 Use OpenCode's permission and sandboxing mechanisms against hostile agents.
 Treat turnstile's journal as the record of what was _claimed_, and treat the
 journal itself as sensitive data (see SECURITY.md).
 
+### Adopting the tool-call policy (shadow first)
+
+The default `toolPolicy.mode: enforce` blocks the git-protective operations the
+policy already demands, so it is safe to adopt immediately. To tune it with zero
+risk of breaking work, boot one session in `toolPolicy.mode: shadow` first:
+would-block commands and paths are journaled with `"reason":"tool-policy"` and
+`mode:"shadow"` but never throw. Grep the journal for that reason, review the
+rules that fired, adjust `toolPolicy.bashDeny`/`pathDeny` (each rule is
+case-insensitive), then flip to `enforce`. Restart sessions to apply config —
+it is read once at setup.
+The same shadow-first adoption applies to `gitGates` (default `mode: shadow`):
+under `shadow` an invalid commit message or an unapproved `git push` is journaled
+(`"reason":"invalid-commit-message"` / `"reason":"no-landing-approval"`) without
+throwing, so boot one session in `shadow`, review the journal, then flip to
+`enforce` when you are ready to start blocking.
+
 ## Files and journals
 
 - Journals live outside the repo in `~/.local/share/opencode/metrics/`:
   - `turnstile.jsonl`: full JSONL trace; rotates at 5 MB, keeps 5
     generations
   - `gate-events.jsonl`: human-readable
-    `YYYY-MM-DD HH:MM | agent | event | detail` lines (suppressed entirely
-    by `trace: false`)
+    `YYYY-MM-DD HH:MM | agent | event | detail` lines, with an optional
+    trailing ` | <sessionID>` segment when the trace line is wired to a
+    session (the first four segments are unchanged when it is absent);
+    suppressed entirely by `trace: false`
 - Retention is bounded: 2 files × (1 current + 5 generations) × 5 MB ≈
   ~30 MB per journal, worst case ~60 MB total.
 - `.opencode/plans/*.md` containing `## Decomposition` are load-bearing:
   their presence activates the executor chunk-citation gate.
 
+## Status
+
+`opencode-turnstile status` reports turnstile gate and plan state per parent
+session, read from the journal, as a human-readable table by default or JSON
+with `--json`:
+
+```
+opencode-turnstile status
+opencode-turnstile status --json
+```
+
+It is read-only: it never writes to the journal or config. Per session it
+replays the same gate/plan last-wins rules the runtime uses (a trailing
+`GATE: FAIL` keeps the gate red; an enforce-mode `verified:false` PASS never
+flips), plus last markers, waiver events (with channel), and dispatch/block/
+permission counts. The journal reflects the last prompt-cycle; in-memory state
+can be fresher (a session that has prompted since is newer than the journal
+records), so treat status as the durable state of the previous cycle rather
+than a live snapshot.
+
 ## Behavior contract
 
 - Fail-open by design. Every hook body is guarded; internal errors are

package/agents/debugger.md

@@ -2,8 +2,9 @@
 description: Investigates failures, identifies root causes, implements targeted fixes, and verifies the result.
 mode: subagent
 # Runaway-loop backstop for the Horizon rule below: near the cap OpenCode
-# drops tools and asks for a summary. Tune to your workflow.
-steps: 50
+# drops tools and asks for a summary. Tuned 2026-10-14: 150 capped once on the
+# #34/#35 fix rounds; 200 fits a diagnose-fix-verify loop with full CI.
+steps: 200
 ---
 
 You are a debugging specialist.

package/agents/executor.md

@@ -2,8 +2,13 @@
 description: Implements an approved plan, validates changes, and fixes test failures
 mode: subagent
 # Runaway-loop backstop for the Horizon rule below: near the cap OpenCode
-# drops tools and asks for a summary. Tune to your workflow.
-steps: 50
+# drops tools and asks for a summary. Tuned 2026-10-12: 50 repeatedly cut off
+# executor-sized chunks mid-implementation (issue #51 needed 3 continuations);
+# 150 keeps the backstop while fitting a real chunk (tests + docs + CI + commit).
+# Tuned 2026-10-14: 150 still capped mid-chunk three times on the #34/#35 work
+# (coverage hunts + full CI loops are the cost driver); 200 fits a chunk
+# including one coverage-debug iteration.
+steps: 200
 ---
 
 You are the implementation agent.