@r1z4x/tezgah 1.0.0

package/docs/feature-audit.md

@@ -0,0 +1,139 @@
+# Feature audit: one feature, every layer
+
+Audience: the agent and the maintainer answering "why does this screen do that"
+or "make this feature better" on an existing product surface.
+
+A screen review judges what is on the screen. Most of what goes wrong in a real
+feature is not on the screen: it is a disagreement between two layers - the surface
+a person uses, the route that serves it, the authorization that gates it, the
+service that validates it, the data that stores it - or a capability that exists on
+one side only. This page is the method that makes those visible, the evidence that
+it works, and how to run it.
+
+## What ships
+
+`skills/feature-audit/SKILL.md` is the method: five matrices filled before any
+taste judgement, a capability-change proposal required whenever a fix names a layer
+that does not exist, a `Prevent` line per finding, and a per-surface rule table
+sourced to WAI-ARIA APG and WCAG 2.2.
+
+It is reached the same way `product-analysis` is: the `product` task class arms the
+rule (`hooks/tezgah_context.py::PROMPT_HINTS`), whose coherence paragraph
+(`hooks/tezgah_policy.py::CORE`) names the feature unit and the matrices, and
+`skills/product-analysis/SKILL.md:51` runs the coherence pass before its axes.
+`skills/tezgah-contract/SKILL.md:725-737` carries the long form for a session that
+reads the contract.
+
+The unit is the feature, not the screen, and every interface element and every data
+view is in scope - a control, a list or table, a detail view, a filter, a picker, a
+step flow, a notification. It is not a form-only method.
+
+## The five matrices
+
+| Matrix | Rows | Columns | The defect it exposes |
+|---|---|---|---|
+| Capability | the entity's actions | surface, route, authorization, service, persistence | an action the UI offers and nothing backs; a capability the server has and no surface reaches; two routes for one action |
+| Field contract | the fields | column, API read, API write, rendered, validated, label source, locale | a contract field no view renders; a view field no layer stores; two sources for one enum; two fields printing one word |
+| Flow and step | the steps of a multi-step flow | precondition, validation, write, skip prevention, resume, back-navigation, error landing | a step reachable without its precondition; work lost on reload; an error mapped to the wrong step |
+| Interaction dependency | the controls whose change alters another's valid set | dependents, required action on change, state owner, announcement | a stale dependent value; a silent reset; a filter showing a state the view no longer has |
+| Surface pattern | the controls, data views, flows and notifications | the decidable rule, with its source | a combobox with no expanded state; a results count announced nowhere; a destructive confirmation that hides what it destroys |
+
+## The gate that makes it more than advice
+
+A finding whose fix names a layer that does not exist yet is not a UI finding. It
+becomes a capability-change proposal, and the proposal must carry **an artifact
+something other than its author can reject**: a contract, permission or schema diff
+a checker can fail on, a flag with a type and an expiry, an ADR with a status.
+Prose cannot be rejected by a tool, so a proposal without one is not yet a proposal.
+
+Measured, this is mechanical: comparing the API's committed contract against the
+surface's call sites reproduced two "declared and unreached" endpoints in one
+pipeline, in 3.09 s, with no credential and no running app
+(an internal research line, not published).
+
+## What the evidence says
+
+Measured on a real Next.js admin users area, 15 frozen defect rows across ten
+classes, against three independent rater passes of the shipped `product-analysis`
+rubric, then three passes of the feature-audit skill:
+
+- the shipped rubric reached **4 of the 9 in-scope classes** (capability, list
+  convention, search behaviour partly, table layout); its misses are the
+  field-contract, flow/step, interaction-dependency, form-pattern,
+  destructive-confirmation and capability-change classes;
+- the feature-audit artifact reached **7 of 9**, added the field contract and the
+  destructive-confirmation content, and wrote **5 capability-change proposals** where
+  the baseline wrote none - the difference that matters most, because it is not about
+  detection;
+- both arms found, and the matrices name, what a screen review reads as taste: a
+  table 1140 px wide inside a 242 px container at 320 CSS px, a search that misses
+  Turkish casefolded names, a role select whose only option the service refuses;
+- two rows were reachable **only** by running the app, and two others only by
+  reading the server side - which is why the method names both, and why the browser
+  request log alone is not an instrument for a capability claim
+  (internal research findings, not published);
+- on a **second stack** (a Rust axum + React admin users area, code-scope) the
+  measurement was repeated twice: once against the current axis skill and once
+  against the **pre-wiring rubric extracted from history**, and both pairs came out
+  level (5 of 6 against 4, then 4 against 4). Detection moved with the rater, not with
+  the artifact, so the class count is not what this file buys;
+- what reproduced, on both stacks, is the **proposal slot**: every artifact that follows
+  this file wrote at least one capability-change proposal - 14 of 14, recounted in
+  the internal proposal tally - against 2 of 5 that followed the
+  pre-wiring rubric under a heading-only reading (3 of 5 by content, one of them proposing
+  the same absent layers under a recommendations heading). The proposal is required here and optional there,
+  which is the difference the evidence supports - not that the other rubric's users never
+  think of one. There is also a thin detection lead with enough passes: 7 defect classes
+  against 6 on the first feature, 6 against 4 on the second. That, plus
+  the depth it carries - the per-surface rule table with its sources, the eight
+  hand-checks, the proposal headings and their falsifiers - is the claim this page
+  makes. The matrices are the unit of analysis, and on this evidence the unit changes
+  what an analysis writes down more reliably than it changes what a diligent rater
+  finds;
+- the second stack was also **run**: after a docker bridge the surface rendered with
+  real data and produced 13 `ui-observed` rows plus the layout class - the table clips
+  its columns at 320 and, with a long row, at 768, with `overflow-x: hidden` and no rule
+  declaring `auto`, so the clipped columns are unreachable rather than scrollable. The
+  repository's own `make admin-dev` never reaches that surface: its frontend crash-loops
+  on an nginx upstream the dev composition does not start - the same defect class as the
+  product findings, found in the tooling;
+- the **competition axis** the earlier runs declared missing is now produced: seven
+  comparable products read at first hand, all seven delivering an invitation credential
+  in-product, which turns the "invitation with no delivery path" finding from an internal
+  inconsistency into a market gap with external evidence;
+- the two evidence classes every run declared unreachable - `behaviour` and
+  `user-verbatim` - were **looked for wrongly, not unreachable**: both products carry a
+  wired analytics seam that is dark (noop sink, switch default off, consent false, and in
+  the first product no caller ever passes `enabled`), and both carry real user-voice
+  sources (support tickets and messages, a customer-portal free-text request);
+  `behaviour` is reachable today as an audit-derived ratio and as a funnel only after that
+  consent path is fixed;
+- one corpus row was **false and is withdrawn**: E7's prompted raters traced the
+  create path and showed the handler returns 400 rather than defaulting its way to a
+  successful create (an internal corpus correction, not published).
+
+## Running it
+
+1. Bound the feature: one entity, its actions, the screens and endpoints that carry
+   them. Write the boundary down.
+2. Fill the five matrices, every cell with its citation and its coverage marker.
+   Run the app for the rows a reading cannot settle, and name which rows those were.
+3. Turn a disagreement into a finding, most severe first, each with its evidence
+   class and its `Prevent` line.
+4. For every fix that needs a layer which does not exist, write the proposal and
+   the rejectable artifact it carries.
+5. Hand the result to the axes in `product-analysis` - the matrices are its
+   feasibility evidence, and its surface patterns fill the usability state matrix.
+
+## Source of truth
+
+- `skills/feature-audit/SKILL.md` - the method: the five matrices, the proposal
+  gate, the per-surface rule table and the hand-check list
+- `skills/product-analysis/SKILL.md` - the coherence pass and the artifact element
+  that carries the matrices
+- `hooks/tezgah_context.py` - `PROMPT_HINTS`, whose `product` alternation carries
+  the feature-surface words that arm the rule
+- `hooks/tezgah_policy.py` - the coherence paragraph inside the product rule, and
+  `skills/tezgah-contract/SKILL.md` as its long form
+- `tests/test_context.py`, `tests/test_setup.py` - the arming table and the router
+  line that pin the wiring

package/docs/gate.md

@@ -0,0 +1,407 @@
+# The gate: every refusal, and what lifts it
+
+This page answers one question: why a tool call was refused before it ran. It is written for the maintainer adding a rule or reading a "the gate missed this"
+report, and for the session that has just met a refusal in its transcript. [architecture.md](architecture.md) places the gate among the layers;
+[evidence.md](evidence.md) describes the [ledger](glossary.md#ledger) a refusal writes to; [hosts.md](hosts.md) covers the per-host envelopes.
+
+## Where it sits in the call path
+
+One function decides every refusal: `decision(tool, inp, cwd, session_id)` returns a reason string or `None`, and nothing else
+(`hooks/tezgah_gate.py::decision`). It answers only inside a tezgah [root](glossary.md#root): outside one `root_for` returns nothing and every call passes
+(`hooks/tezgah_gate.py::decision`). The `pretooluse-off` kill switch drops the whole gate (`hooks/tezgah_gate.py::decision`). `decision` binds the session first.
+It reads every switch through the session latch ([contract.md](contract.md#how-a-rule-is-disarmed)).
+
+Each host's pre-tool hook calls it and wraps the string in that host's own deny envelope — opencode's is its `tool.execute.before`, which throws
+`new Error(deny)`; a `None` prints no envelope at all.
+
+A host that is not Python reaches the same function through `bin/tezgah-gate`. Two of its verbs
+answer one call (`decision(..., record=...)`). `decide` is the live gate: it records what `decision` records - the
+deny, drift and nudge rows and the pre-write snapshot - and it is the verb opencode's plugin calls,
+because the once-per-turn drift refusal depends on the recorded row. `check` is a true dry run: the
+same answer with nothing written anywhere, and it is what a person and the MCP `tezgah_gate_check`
+tool ask. Before 2026-10-02 `check` recorded too, so a dry run against a live session id wrote
+refusal rows into that session's counters (audit L-14b, CHAT-07).
+
+The third verb, `replay`, answers no call. It measures the gate. It replays the real ledgers
+through the unmodified dry run in a sandbox HOME. Per stratum, it prints how often the replayed
+verdict equals the recorded one. `replay --sheet` draws a blind label sample.
+`replay --label-model` labels it with a model as rater 2, and `replay --report` reads the labels
+into per-rule false-block rates. It changes no gate behaviour, and everything it
+writes stays under `~/.cache/tezgah/replay`. The corpus, the exclusions and the metrics are in
+[evidence.md](evidence.md#the-replay-corpus).
+
+| Host | Adapter | Refusal envelope |
+|---|---|---|
+| claude, dsh | `hooks/projects-pretooluse.py::main` (`hosts/dsh/hooks.json:13-14`) | `hookSpecificOutput.permissionDecision: "deny"` |
+| codex, cursor, omp | `hosts/codex/hook.py::main`, `hosts/cursor/hook.py::dispatch`, `hosts/omp/hook.py::handle` | that host's own envelope — [hosts.md](hosts.md) |
+| opencode | `hosts/opencode/plugins/tezgah.js:2373` | `new Error(deny)` thrown at `hosts/opencode/plugins/tezgah.js:2534` |
+
+Every refusal is also recorded before it is returned: `_deny` appends a ledger row `deny` whose `detail` is `"<rule>: <reason, first 80 chars>"`, plus any
+`extra` (`hooks/tezgah_gate.py::_deny`). That row, not the reason wording, is where "why was this denied" is answered, and `<rule>` is the name used below.
+
+A call the gate lets through is also where it keeps the pre-write bytes: `capture` runs for a write tool, and for a shell command that writes a file through a
+redirect or `tee` - the same shape the task phase rule reads, `write_paths` returns the target for both routes, and a shell write gets its pre-state the same
+way (`hooks/tezgah_gate.py::decision`, `hooks/tezgah_gate.py::write_paths`, `hooks/tezgah_gate.py::shell_target`). Without it the after-state alone
+cannot tell a redirect that wrote the file from one that wrote what was already there, and the freshness half of the Stop rule would read every redirect as a
+change; the two halves of that rule are `hooks/tezgah_integrity.py`'s and are described in [evidence.md](evidence.md).
+
+## MCP — a server's effect tool
+
+An MCP effect tool reaches `decision` on every host that can route it ([hosts.md](hosts.md)). No rule refuses it for what it is.
+Its verb class only picks which existing content rules read its payload. An effect verb in the tool part of the name decides the class, case-sensitive
+like the host matcher (`hooks/tezgah_integrity.py::mcp_class`, `hooks/tezgah_integrity.py::MCP_VERBS`). The tool part is what follows the last `__`.
+A clause of it that a read verb leads (`get_commit`) is a read. An effect verb in another clause still decides (`get_or_create_issue`).
+omp's `mcp__<server>_<tool>` has no server boundary, so there an effect verb anywhere decides.
+A `write` call such as `write_file` meets the shortcut, attribution and secret rules.
+A `publish` call such as `send_message` meets attribution and secret. An `act` call such as `click` meets none of them.
+Every class counts as an effect for the drift re-statement (`hooks/tezgah_gate.py::effectful`) and the taint notice
+(`hooks/tezgah_untrusted.py::effectful`). So an `act` call can now draw the drift re-statement, once per long turn.
+The gate reads the payload through a bounded walk (`hooks/tezgah_integrity.py::mcp_text`).
+An unbounded read of an unbounded payload runs past the 5 s hook budget, and a late hook refuses nothing (audit H-3).
+On Claude, dsh and omp the host matcher names the effect verbs only, so a read-only MCP call spawns no hook.
+A temp-HOME fixture measured the cost: 200 spawns per case, on a loaded machine.
+The Claude hook took p95 135 ms on a 300-byte MCP write and 222 ms on a 1 MB one. A plain `Bash` call took 101 ms.
+
+## The rules, in the order `decision` checks them
+
+Code on this page is cited by symbol (`path::name`, see [the convention](README.md#how-these-pages-are-written)). Each rule ends with its reach: *once*, a mark lifts the next
+identical call; *standing*, only changing the call does.
+`bin/tezgah-docs --citations` checks the headings below against `decision`, read by AST (`rule_sites`). They keep the order
+of each rule's first deny site. A rule's section names every `off(...)` switch that guards it.
+
+### Control — tezgah's own control plane
+
+Trigger: a write tool or a shell command that changes a file the other rules rest on (`control_reason` `hooks/tezgah_gate.py::control_reason`). `decision` checks
+it first after the root check (`decision` `hooks/tezgah_gate.py::decision`). The protected set (`control_target` `hooks/tezgah_gate.py::control_target`):
+
+| What | Paths | Refused for |
+|---|---|---|
+| kill switches and opt-in markers | every name in `SWITCHES` (`hooks/tezgah_paths.py::SWITCHES`) under `~/.config/tezgah` or `~/.claude` | any write |
+| tezgah's configuration | all of `~/.config/tezgah` (`config.json`, `bin/`, `ponytail.level`, the `hook:<host>:...` rows of `contract.sha256`, ...) | any write |
+| evidence and session state | the cache's `evidence/`, `sessions/`, `switches/`, `gate-inactive/`, `harness-drift/`, `import-crash/` and `workspace-index.json`, in the global cache and the temp fallback (`hooks/tezgah_gate.py::CONTROL_CACHE`) | any write |
+| hook wiring | the opencode plugin file, the omp hook, the Claude plugin copy, the install prefix, and the tree the hooks run from unless the session works inside it (`hooks/tezgah_gate.py::_registration`, `hooks/tezgah_gate.py::_install_trees`) | any write |
+| shared registration files | `.claude/settings.json` and `settings.local.json`, `~/.claude/plugins/installed_plugins.json` and `known_marketplaces.json`, Codex's and Cursor's `hooks.json`, Codex's `config.toml` | a shell write; a write tool only when it changes an entry that is tezgah's - `statusLine`, `attribution`, `disableAllHooks`, a key or item naming tezgah (the user's own hook beside tezgah's in one matcher group stays theirs), or any `[hooks...]` line of `config.toml`, where the trust entries live (`hooks/tezgah_gate.py::_shared_change`) |
+| repository marks and hooks | a `REPO_MARKS` name under a root, the session checkout's `.git/hooks` (a `.sample` file and a clone elsewhere pass), `git config core.hooksPath` set or unset there or `--global` | any write |
+| | `.husky` | a delete, a chmod that takes a permission away, or a move |
+| | a directory holding any protected path (`rm -rf ~/.cache`, `mv .git /tmp/x`), also through a link (`rm -rf link/`), including `.tezgah/plans/open/` itself, every ancestor of it (`rm -rf .tezgah`, `mv .tezgah/plans /tmp/x`) and a glob or brace directly under it (`rm -rf .tezgah/plans/open/*`) | a delete or move |
+| evidence only | a delete or move of one named plan under `.tezgah/plans/open/`; a glob or the directory is refused (row above); `git add -f` or `--force` of a `.tezgah/` path (`_git_change` `hooks/tezgah_gate.py::_git_change`) | never: the call goes on to the other rules and, if they let it through, leaves a `disarm` row whose `detail` is `control: <what>` (`CONTROL_EVIDENCE` `hooks/tezgah_gate.py::CONTROL_EVIDENCE`); `git rm --cached` leaves none (plan-sync's move) |
+| the CLIs | `tezgah-gate decide`, `tezgah-capture`, `tezgah-pony <level>`, `tezgah-adhd on` or `off`, `tezgah-context attest` or `user_prompt`, by basename with or without `.py` (`hooks/tezgah_gate.py::CONTROL_CLIS`) | always |
+| the hook entries | `projects-auto-init`, `projects-pretooluse`, `projects-posttooluse`, `projects-stop`, `hook.py` under `hosts/codex`, `hosts/cursor` or `hosts/omp`, and the `tezgah-codex-hook`/`tezgah-cursor-hook` launchers (`hooks/tezgah_gate.py::HOOK_ENTRIES`, `hooks/tezgah_gate.py::_host_hook`): fed a forged payload, one writes genuine rows, the switch latch's `authorized` row among them | always |
+
+The rule reads the shell word by word, one simple command at a time (`shell_control` `hooks/tezgah_gate.py::shell_control`). It reads each redirect target.
+It reads the arguments of `touch`, `rm`, `rmdir`, `unlink`, `mv`, `chmod`, `mkdir`, `tee`, `truncate`, the copiers' destination and `sed -i`/`perl -i`.
+It reads the value of `cp -t`, `curl -o`, `wget -O`, `tar -C` on extraction and `unzip -d` (`OPTION_TARGETS`). It expands `~`, `$HOME` and the XDG
+variables first. It follows a `cd` within the line and reads past `if`/`then`/`do`/`!`/`{`. It opens `eval` and `bash -c`, and any flag cluster holding
+`c` is `-c`. A path counts as written and with its last link resolved. A quoted word is a word, so a grep or a commit message that names a switch passes. `SHELL_WRITE` stays as it was: it feeds the
+task phase rule and the opencode mirror. The task CLI stays the task rule's (below), so `task-off` still removes all of that rule. Told: what the call would
+change, and that the user changes it in their own terminal (`CONTROL_DENY` `hooks/tezgah_gate.py::CONTROL_DENY`). The text names no command. Standing. No switch
+but `pretooluse-off` removes the rule, and that switch is a protected file. The rule cannot tell a change the user asked for from one the agent chose. It
+refuses both inside the session, and it never sees the user's own terminal. Plan 050's replay of three weeks of real ledgers found the two evidence-only
+targets refused without the user's say-so more than once a week. Its falsifier kept the tamper evidence and dropped the refusal for them. The rule still
+refuses a call that also changes a refusing target.
+
+### Explorer — the grep-only subagent
+
+Trigger: tool `agent`/`task`/`subagent` whose `subagent_type` is `explore` or `explorer`, case-insensitively (`hooks/tezgah_gate.py::decision`, `hooks/tezgah_gate.py::explored`). Told: use
+the general-purpose agent and name the codegraph tools in its prompt (`hooks/tezgah_gate.py::EXPLORE_DENY`). Standing: no mark, every such
+request is refused.
+
+### Shortcut — a check made unable to fail, or a test disabled
+
+Trigger, shell: `--no-verify`, or `SKIP=`/`HUSKY_SKIP_HOOKS=`/`HUSKY=0`, next to a git/hook word; or a `core.hooksPath` assignment (`git -c core.hooksPath=...`, `git config core.hooksPath <dir>` with a quoted value too, `--config-env`, `GIT_CONFIG_KEY_n`/`GIT_CONFIG_PARAMETERS`) in the same command as a `git commit`/`git push` (`HOOKS_KEY`/`GIT_VALUE_OPTS`/`CONFIG_READS`/`ROUGH_WORDS` `hooks/tezgah_integrity.py::HOOKS_KEY`, `hooks/tezgah_integrity.py::GIT_VALUE_OPTS`, `hooks/tezgah_integrity.py::CONFIG_READS`, `hooks/tezgah_integrity.py::ROUGH_WORDS`, `hooks/tezgah_integrity.py::_shell_segments` reads the line word by word the way shlex does - an unquoted backtick ends a command (`hooks/tezgah_integrity.py::_unquoted_backticks`; one inside double quotes is read as data, the blind spot `mask` has) and a line shlex cannot read is read roughly rather than dropped - `hooks/tezgah_integrity.py::_hooks_redirect`; husky's standalone setup, a read or `--unset`, a hook install naming `pre-push`, and a commit message naming the key or the env var pass); or a verification command chained with `|| true`/`; true`
+(`hooks/tezgah_integrity.py::_shortcut_command`, `hooks/tezgah_integrity.py::NO_VERIFY`, `hooks/tezgah_integrity.py::SKIP_ENV`, `hooks/tezgah_integrity.py::NEUTER`, `hooks/tezgah_integrity.py::GITISH`).
+These shell predicates read the line through `mask()` (`hooks/tezgah_integrity.py::mask`), which blanks quotes and comments the way bash reads them. A URL's `//`, a word's `#`, a `/* */` glob pair and `'x\'` are words there, so they do not hide the command after them. The word reader takes a `$'...'` as one word and a `$( )` or backtick body as a command of its own (`hooks/tezgah_integrity.py::_for_shlex`). Trigger, edit/write: a skip marker newly
+introduced into a test file — the path must match `tests?/`, `test_*`, `*_test`, `*.test.*` (`hooks/tezgah_integrity.py::TEST_PATH`), the marker must survive `mask_source()` so one
+inside a string or comment does not count, and `_added` compares against the file's own text on disk for a `Write` (`hooks/tezgah_integrity.py::_added`, `hooks/tezgah_integrity.py::SKIP_TEST`). Every write dialect is read
+through one reader (`hooks/tezgah_integrity.py::write_texts`, over `hooks/tezgah_taste.py::edit_text`): `new_string`/`newString`, `new_str`, `content`/`file_text`, `edits[]` and an `apply_patch` body, which is split per `*** Update File:`/`*** Add File:` header so the test-path gate and the count run per file (`hooks/tezgah_integrity.py::PATCH_FILE`). Told:
+the texts at `hooks/tezgah_integrity.py::shortcut_edit` — run the checks, or say the test is failing; ask the user first if the skip is intended. Standing, with one switch:
+`verify-off` removes this check (`hooks/tezgah_gate.py::decision`). The shell is a write route like any other, and the one E7c measured an
+armed session taking once the write tools were refused: a heredoc that writes a skip into a test file meets the same predicate, run over the body the
+command would land (`hooks/tezgah_gate.py::shell_write_body`, read at `hooks/tezgah_gate.py::decision` — the body is the raw text, because `mask()` blanks
+heredoc bodies by design). An MCP `write` call meets the same predicate over its payload text ([MCP](#mcp-a-servers-effect-tool)).
+
+### Piped — a check whose status a trimmer owns
+
+Trigger: a verification command (integrity's `VERIFY`) piped into a trimmer or filter — `tail`, `head`, `grep`/`egrep`/`fgrep`, `cut`, `wc`, `sed -n`, with
+`|` or `|&`, a `tee` in between included — in one `&&`/`;`-separated segment of the line (`hooks/tezgah_integrity.py::piped_check`, `TRIMMER`
+`hooks/tezgah_integrity.py::TRIMMER`). The line's exit status is the trimmer's, so the ledger can only record the check as ran, never as passed, and the Stop rule
+then refuses every claim the run was meant to carry — observed in a real omp session where 13 checks ran piped and 3 of 6 completion claims were blocked.
+Passes: a line that opens with `set -o pipefail` (`hooks/tezgah_integrity.py::PIPEFAIL`), which integrity then records as decisive
+(`verify_ok`/`verify_fail`, [evidence.md](evidence.md)); a redirect to a file; a pipe of anything that is not a check (`git log | head`). The
+remedy is one sentence, `hooks/tezgah_integrity.py::PIPED_REMEDY`, which the always-on core and the contract skill quote too. Told: keep the check last with its output in a file, then read the file in a separate call, or open the line with `set -o pipefail;`. A `; tail` on the same line hands the status to `tail`. The refusal names the check as it was typed. Standing, under `verify-off`
+(`hooks/tezgah_gate.py::decision`). opencode asks the core for this rule on any shell line that pipes a check
+(`hosts/opencode/plugins/tezgah.js:2459-2463`) and records such a line as `verify` when a pipe or a later command owns its status (`statusHidden`, `hosts/opencode/plugins/tezgah.js:445`).
+
+### Attribution — an AI/model credit on its way into an artifact
+
+Trigger, shell: a write command (`hooks/tezgah_gate.py::WRITE_CMD` — `git commit|merge|tag|notes`, `gh api`,
+`gh pr|issue|release create|edit|comment|review|merge|close`) carrying a credit form (`hooks/tezgah_gate.py::ATTRIB` — `co-authored-by:`, `generated with`, `made with`,
+`built by`, `assisted by`, `authored by`, `noreply@anthropic`, a robot emoji). Trigger, edit/write: one of the content fields `EDIT_TEXT` (`hooks/tezgah_gate.py::EDIT_TEXT`)
+containing a line that *starts* with a credit (`hooks/tezgah_gate.py::ATTRIB_LINE`). Told: remove it and re-run; naming a tool in order to use it is fine, crediting it
+as author is not (`hooks/tezgah_gate.py::ATTRIB_DENY`). Standing. The line anchor is why prose that merely names the banned forms passes (`hooks/tezgah_gate.py::_CREDIT`).
+The same twin as the shortcut rule's: a credit a heredoc writes into a file is refused from the body (`hooks/tezgah_gate.py::decision`), and no command has to be
+a `git`/`gh` write for it to be this rule's. An MCP `write` or `publish` call meets `ATTRIB_LINE` over its payload text ([MCP](#mcp-a-servers-effect-tool)).
+
+### Language — an identifier or message that is not English
+
+Trigger, shell: a command that would create an identifier - `git checkout -b`/`git switch -c`, `git branch` with a new name, a commit subject (`git commit -m`/`--message`/`-F`), or a `gh pr|issue create --title` (the language section `hooks/tezgah_gate.py:352-465`, `hooks/tezgah_gate.py::created_texts`; the text is read from the raw command, because `mask()` blanks quoted strings and a commit subject is one) - whose name or subject is **not English**: a letter outside ASCII anywhere (`hooks/tezgah_lang.py::non_english` - a predicate rather than one language's letter list, so Russian, Greek, Arabic, Chinese and accented Latin hit it exactly as Turkish does) or an ASCII-folded Turkish word from the curated list (`hooks/tezgah_lang.py::ENGLISH`, wi…
+
+The rule is a **heuristic** and its own text says so: a word list is not a language detector, so it cannot tell a proper noun or a product name in another language from a word that ought to be English, and a listed word may be the user's own term. A command that only names the words - `echo`, `grep`, `git log --grep` - creates nothing and passes. An identifier outlives the session that typed it, which is the reason the rule exists at all: `plan/004-admin-durum-onarimi` is in a public history from the moment it exists. On **opencode** the rule is not ported: the plugin asks the core for it through `bin/tezgah-gate check`, one spawn for a command its pre-test reads as identifier-creating (`IDENT_CMD` `hosts/opencode/plugins/tezgah.js:585`, the call site `hosts/opencode/plugins/tezgah.js:2459-2463`).
+
+Off: `lang-off`, the rule's own switch (`hooks/tezgah_gate.py::decision`), and `pretooluse-off` drops it with the whole gate.
+
+### Race — another session wrote this file minutes ago
+
+Trigger: another session recorded a write of this call's file inside `RACE_WINDOW_MIN = 10` minutes (`hooks/tezgah_gate.py::RACE_WINDOW_MIN`). The call's files are
+its path field, its `apply_patch` headers, or a shell redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`, `hooks/tezgah_gate.py::race_reason`).
+The reader counts an `edit` row and a shell `run` row that carries a `target` (`hooks/tezgah_integrity.py::writers_elsewhere`).
+Scratch is skipped: a temp file or a device (`hooks/tezgah_integrity.py::scratch_target`). A `run` row that writes only scratch carries no `target`.
+Told: re-read the file and re-apply the change to what is on disk now (`RACE_DENY`
+`hooks/tezgah_gate.py::RACE_DENY`). Standing (`RACE_REFUSE = True` `hooks/tezgah_gate.py::RACE_REFUSE`) — a notice would not close a silent overwrite — and it lifts only by time.
+
+### Task — the user's own phase and path allowlist
+
+Trigger: a write tool, or a shell command that writes a file, while an active task is set — a plan file under `.tezgah/plans/open` whose frontmatter carries a valid
+`phase` (`tezgah_task.active`). The phase refuses a write in a reading phase (`hooks/tezgah_gate.py::TASK_PHASE_DENY`) and a shell command that writes one (`hooks/tezgah_gate.py::TASK_SHELL_DENY`,
+against `hooks/tezgah_gate.py::SHELL_WRITE`); the allowlist refuses a target outside it (`hooks/tezgah_gate.py::TASK_SCOPE_DENY`) — a write tool's path, and a shell command's redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`); and the record itself is refused twice over — a write whose target IS it, by a write tool or a shell redirect/`tee`
+(`hooks/tezgah_gate.py::TASK_RECORD_DENY`) and a shell command that would change it through the CLI, named by its basename with or without `.py` (`hooks/tezgah_gate.py::TASK_UNLOCK_DENY`, matched on the masked text by `hooks/tezgah_gate.py::TASK_CHANGE`). Told:
+none of them names the command that lifts it, on purpose — with the unlock printed, an armed arm removed or disabled the gate in 25 of 25 runs and obeyed it in none
+(`hooks/tezgah_gate.py:883-887`) — so each names the phase or the allowlist as the user's to change. Standing: only the record changing lifts it.
+Scratch meets no allowlist: a temp file or a device, such as `pytest > /tmp/check.log` (`hooks/tezgah_gate.py::task_reason`). Build output inside the repo stays held. Off: `task-off`
+(`hooks/tezgah_gate.py::decision`). It fails open wherever the question cannot be answered: no active task, no readable record; the record is written by `bin/tezgah-task` and
+never by the agent, so this rule refuses on a decision the user made rather than one the gate inferred.
+
+The fifth refusal under the same rule is the checkpoint. Trigger: a write, or a shell command that writes a file (`hooks/tezgah_gate.py::SHELL_WRITE`), while the task is in
+`phase: implementation`, its record reads `checkpoint: pending <sha>`, that sha is still the checkout's HEAD and the tree is dirty (`checkpoint_reason()`
+`hooks/tezgah_gate.py::checkpoint_reason`, `hooks/tezgah_gate.py::CHECKPOINT_DENY`). Told: the task it read, that the record holds a `pending` checkpoint, and the one command
+that makes the boundary real - unlike the refusals above it names that command, because running it *satisfies* the rule rather than taking it off. Standing: the recorded sha is the switch, not the tree - the commit
+the refusal names moves HEAD off that sha, so the refusal clears itself, where keying on the word `pending` alone left the phase waiting on a record only
+`bin/tezgah-task` rewrites. Off, with the rest of the rule: `task-off`. It fails open wherever the question cannot be answered: no record, no `checkpoint:` key, a
+checkpoint that is a plain sha (the boundary is already real), a `pending` with no sha, a sha this checkout's HEAD does not name, and a repo whose HEAD cannot be read.
+
+### Workspace — tezgah state outside `.tezgah/`
+
+Trigger: a write tool, or a shell redirect/`tee` (`write_paths`), whose target relative to the repo root starts with `plans/`, `research/` or `analysis/` while the project tracks no file under that directory (`workspace_reason`, `hooks/tezgah_gate.py`). The refusal names `.tezgah/<kind>/` as the place to write. A directory the project already tracks is its own and passes. `mkdir` and positional shell targets (`cp`, `mv`) are not read - the same ceiling as `write_paths`. Off: `workspace-off`.
+
+### Secret — a credential on its way into a file
+
+Three triggers, one per shape a credential takes on its way into a file (`hooks/tezgah_gate.py::secret_command`, `hooks/tezgah_gate.py::secret_edit`, read at `hooks/tezgah_gate.py::decision`):
+
+- **Shell text.** One simple command (split on `&&`, `||`, `;`, newline — `hooks/tezgah_gate.py::SEGMENT`) carrying both a token (`hooks/tezgah_gate.py::SECRET_TOKEN` — an
+  `Authorization: Bearer` header, or a `name=value` assignment for `api_key`/`token`/`secret`/`password`/...) and a sink (`hooks/tezgah_gate.py::SECRET_SINK` — `>`/`>>`,
+  `| tee`, a curl `--trace`, or `git add`). Told: record the name, length or a fingerprint instead, and pass the value through the tool's environment (`hooks/tezgah_gate.py::SECRET_DENY`).
+- **A credential file staged.** A `git add` that names a credential file (`hooks/tezgah_snapshot.py::SECRET_FILE`: `.env`, `.env.local`, a key, `id_rsa`, `credentials.json`).
+  The command is read word by word (`hooks/tezgah_gate.py::_secret_add`). `.env.example`, `.env.sample`, `.env.template`, `.env.dist` and `.env.defaults` carry names without values and pass (`hooks/tezgah_gate.py::SECRET_TEMPLATES`).
+  The rule does not read `git add -A` or `git add .` (`hooks/tezgah_gate.py::SECRET_ADD_DENY`).
+- **The text a write lands.** The text holds a token with a known credential prefix. It is read on every route: a write tool in every dialect, an `apply_patch` file by file, a heredoc body.
+  The prefixes are the redactor's families (`hooks/tezgah_integrity.py::SECRET_PREFIXED`: `ghp_`, `github_pat_`, `sk-live-`, `xox?-`, `AKIA`, `AIza`, `glpat-`, `npm_`).
+  An `sk`/`pk`/`rk` token counts only with its qualifier (`sk-live-`, `pk_test_`, `sk-proj-`). The redactor's bare branch also matches identifiers such as `pk_users_organization_id`.
+  A token the file already carried does not count: the baseline is the replaced text plus the file on disk (`hooks/tezgah_gate.py::secret_edit`). This trigger does not read `name=value`.
+  A template or test-fixture file may carry a token (`hooks/tezgah_gate.py::SECRET_FIXTURE`: `*.example`, `tests/**/fixtures/**`, and the templates above).
+  A documentation placeholder passes: a token that says `example`, one whose body is one repeated character, and a published docs key (`hooks/tezgah_gate.py::SECRET_PUBLISHED`).
+  In a file's text, `password = os.environ[...]` is a program that reads its credential. A Write, an Edit, a patch and a heredoc that land it all pass.
+- **An MCP payload.** The gate refuses an MCP `write` or `publish` payload that carries a vendor token such as `ghp_` or `sk_live_` (`hooks/tezgah_gate.py::MCP_TOKEN`).
+  A bare `sk-`, `pk_` or `rk_` prefix does not count there, because identifiers and branch names carry it (`hooks/tezgah_gate.py::MCP_SECRET_DENY`).
+  Neither does the `name=value` shape, which a program's own text matches.
+
+Standing, no escape hatch, and outside `verify-off`.
+
+### Plan — a turn's third product file on `main`
+
+Trigger: a write tool, or a shell redirect/`tee` (`hooks/tezgah_gate.py::write_paths`), whose target is a product path, while the checkout holding that target is on `main` or `master` and this turn has
+already written two other product files into the same checkout (`hooks/tezgah_gate.py::plan_reason`, `hooks/tezgah_gate.py::_branch`, `hooks/tezgah_gate.py::_checkout`, `hooks/tezgah_gate.py::_product`). The branch comes from that checkout, not from the session's cwd. The
+count folds the turn's own write rows (`hooks/tezgah_integrity.py::turn_rows`) together with the files the call in hand names, so it needs no state of its own, and it counts DISTINCT
+paths - a turn that rewrites one file three times is still one file's work. The product paths are the ones at the repository root that a plan exists to scope - `hooks/`, `tests/`, `bin/`,
+`skills/`, `docs/`, `statusline.py` and `MANIFEST` (`PLAN_DIRS`/`PLAN_FILES` `hooks/tezgah_gate.py::PLAN_DIRS`, `hooks/tezgah_gate.py::PLAN_FILES`); a `.tezgah/` path is never one of them, and neither is a path outside any git
+repository. Told: the branch it read, how many files the turn has written, and the command that opens a plan - the `plan-add` skill, `/tezgah:plan-add <description>` (`PLAN_DENY`
+`hooks/tezgah_gate.py::PLAN_DENY`). Standing: only changing the tree's state changes it - the work moves to the `plan/NNN-slug` branch the skill creates (a one- or two-file fix is free either
+way), or the repository carries a `.no-plan-gate` mark (the shape of `.no-graph` and `.no-lessons`). It passes wherever the question cannot be answered: no session or ledger, a directory that is
+not a git repository, and a detached HEAD with no branch to name.
+
+### Ordering — a commit while the newest check failed
+
+The one rule here that asserts a relation between two actions rather than reading one call plus a ledger tail, and the shape FAVA found in 90% of real
+agent-instruction projects ("do not commit before running the tests").
+
+Trigger: the command is a `git commit` (or `--amend`; `hooks/tezgah_gate.py::COMMIT_CMD`, matched at `hooks/tezgah_gate.py::commit_order_reason`) and the newest check in
+this session **failed**. The state is the Stop rule's own fold over the ledger tail (`ORDER_TAIL = 200` `hooks/tezgah_gate.py::ORDER_TAIL`, the fold
+`tezgah_integrity._last_verify`), and the rule is structurally incapable of firing in either direction that would punish honest work: no check at all folds
+to `None` and a passing newest check folds to `ok`, so a commit in a session that ran no check — a docs-only commit — and a commit after a green run both
+pass. Only `fail` refuses: the tree the commit would freeze is the one a check just rejected.
+
+Told: the failed check by name and nothing else (`hooks/tezgah_gate.py::ORDER_DENY`, `hooks/tezgah_gate.py::commit_order_reason`) —
+making the newest check pass is the whole repair, so the refusal names no command that lifts it, for the reason the task refusals carry. Standing while the
+tail still shows that failure, under `verify-off` (`hooks/tezgah_gate.py::decision`). Its deny row is its own rule name (`order`), so the counters separate it.
+
+### Loop — the identical attempt that already failed twice
+
+Trigger: the same call (same `call_id`) failed `LOOP_ATTEMPTS = 2` times already in the current user turn (`hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`). Told: attempt N
+of an identical call, the failure class read from the ledger (`transient`, `user`, `permanent`, `unknown`; the cap is the same for every class, and a `user` failure - a 401/403, a missing credential, a login - says to ask the user), "change the approach or stop" (`hooks/tezgah_gate.py::loop_reason`). Standing while the ledger tail still shows those
+failures. Under `verify-off` (`hooks/tezgah_gate.py::decision`).
+
+### Retry — the session-wide ceiling
+
+Trigger: the same call has been attempted more than `RETRY_CEILING = 3` times in the session, whatever those attempts returned (`hooks/tezgah_gate.py::RETRY_CEILING`, `retry_reason`
+`hooks/tezgah_gate.py::retry_reason`). Told: an unchanged repeat is not a retry (`hooks/tezgah_gate.py::loop_reason`). Standing. Under `verify-off` (`hooks/tezgah_gate.py::decision`). Both guards read only the ledger tail.
+
+### Nudge — the first identifier-shaped search of a session
+
+Trigger: a `Grep` whose pattern, or a `grep`/`rg` argument (`hooks/tezgah_gate.py::BASH_SEARCH`), matches `IDENT` (`^[A-Za-z_][A-Za-z0-9_]{2,}$`, `hooks/tezgah_gate.py::IDENT`), in a repo whose
+codegraph index exists (`<repo>/.codegraph/codegraph.db`; `searched_identifier`
+`hooks/tezgah_gate.py::searched_identifier`). Told: the runnable command built from the denied search (`codegraph explore <X>`, `codegraph callers <X>`, `codegraph impact <X>`), and that an omp subagent uses this CLI because omp's MCP device refuses concurrent writes
+(`hooks/tezgah_gate.py::nudge_reason`).
+Once-only: the mark in `cache_dir()/nudged/<sha1(session)[:16]>` is written *before* the refusal, so re-issuing the search passes (`hooks/tezgah_gate.py::first_nudge`). opencode's `oncePerSession` writes the same name (`hooks/tezgah_gate.py::nudge_mark`).
+
+### Drift — a long turn loses the rules it started with
+
+Trigger: 25 work rows (`hooks/tezgah_gate.py::DRIFT_STEPS`) in the current user turn and an effectful call — a write tool, or a git/gh artifact command (`effectful`
+`hooks/tezgah_gate.py::effectful`). An MCP call of any verb class counts as an effectful call too. Told: the standing constraints re-stated, or the delta since the turn began; "re-issue this call unchanged and carry on" (`hooks/tezgah_gate.py::DRIFT_DENY`,
+`hooks/tezgah_gate.py::drift_reason`). A refusal, last in `decision` after every other rule, and its only delivery: no host's PostToolUse side carries it, and opencode gets it from the core through `bin/tezgah-gate` on its write path. Once per turn: the `drift` mark is written *before* the refusal, so the identical call passes on the next attempt, and the count behind it is the turn's own — a bounded read (`hooks/tezgah_gate.py::DRIFT_TAIL`) falls back to the turn's own start (`hooks/tezgah_integrity.py::turn_rows`) when the turn outgrew the window. Governed by `reminder-off`, not `verify-off` (`hooks/tezgah_gate.py::drift_reason`).
+
+## What the gate deliberately does not catch
+
+Read this before filing a security-ish issue; each is a decision, not an oversight.
+
+- Irreversible and outward-facing shell commands — force-pushes, migrations, deploys, `ssh`, `scp`, a `curl` write, a `gh pr` write — run without an ask.
+  The consent rule and its `send`/`outward`/`deploy`/`publish`/`schema`/`destructive` class table were removed on purpose (2026-09-26): the ask it put in
+  front of every server-side command cost a round-trip per effect, the user's chat approval could not lift it (only the deleted `bin/tezgah-consent` CLI
+  could), and the sessions it actually gated were the user's own deploys. The untrusted-read half went with it: a turn that read web content may now run an
+  outbound effect carrying only the taint notice, with no refusal in between. The notice itself stays (`hooks/tezgah_untrusted.py`).
+- A write inside the root after a fetch: left to the taint notice that `hooks/tezgah_untrusted.py` rides the first effect with, because it is recoverable from
+  the snapshot.
+- `grep -A 3 foo`: a flag with its own value shifts the token, so the search passes unnudged (`hooks/tezgah_gate.py:163-164`).
+- A foreign `apply_patch` write: the PostToolUse writer records no path for that row (`hooks/tezgah_gate.py::write_paths`); and the guard skips a row an older writer left with no
+  `target`, because that row names no file (`hooks/tezgah_integrity.py::writers_elsewhere`).
+- Which rule the user meant when a turn drifts: "a guess about intent wearing a check's clothes" (`hooks/tezgah_gate.py::drift_reason`).
+- The MCP walk stops at 64 KiB of text, 8 levels or 4096 values (`hooks/tezgah_integrity.py::MCP_WALK_MAX`). Text past the cap goes unread.
+  A tool name with no verb from `MCP_VERBS` counts as a read. Both cost that call the content rules, never a refusal.
+- A skip already in the file, or one inside a string (a test *about* the rule), is not a disable (`hooks/tezgah_integrity.py::_added`).
+- A `core.hooksPath` redirect behind an alias or a variable: `git -c core.hooksPath=/tmp/h -c alias.c=commit c` and `K=core.hooksPath; GIT_CONFIG_KEY_0=$K ...` set the directory and commit without the words `commit`/`push` or the literal key, so the word reader (`hooks/tezgah_integrity.py::_hooks_redirect`) does not see them. Same class as `bash -c '<line>'`, which the program-position reader also does not open: a shell feature that hides the command is out of scope rather than half-read. A command substitution inside double quotes (`"$(git config core.hooksPath /dev/null)"` beside a commit) is the same class, and the reader's docstring says so (`hooks/tezgah_integrity.py::_unquoted_backticks`).
+- The content of a shell write that is not a heredoc: `echo "Co-Authored-By: x" > f` puts the credit inside a quoted string that no line-start anchor can see,
+  and reading the whole command instead would deny a search for the form (`grep "Co-Authored-By" x > out`). The three twins read a heredoc body, which is the
+  route E7c measured (`hooks/tezgah_gate.py::shell_write_body`).
+- A shell write whose target is not a redirect: `cp`, `mv`, `sed -i`, `patch` and `git apply` name it as a positional argument, and which argument of those is
+  the target is a per-program question, so the gate keeps no pre-state for it and the freshness half reads no change there (`write_paths`
+  `hooks/tezgah_gate.py::write_paths`). A shell write chained with a check in one call (`sed -i ... && pytest`) records as the check row, and the row that carries a
+  pass is never the row read as the change - otherwise a check redirecting its own log would stale itself (`tezgah_integrity._change_row`).
+- A PRIOR shell write's target, in the plan rule's count: a write the shell landed is a `run` row whose detail is the command, so the count reads the turn's
+  write-tool rows plus the redirect the call in hand names (`hooks/tezgah_gate.py::plan_reason`). Three heredocs into product files in one turn
+  therefore pass where the same three through the write tools are refused, and reading a stored command line for its target would be a second reader of the
+  table `write_paths` already holds.
+- A control-plane write through an interpreter: `python3 -c "open(...)"`, `node -e`, or a script the agent wrote. `find -delete` and `xargs` are the same
+  class, and so is a path built from variables other than `~`, `$HOME` and the XDG ones. The control rule reads the command line, not what a program does at
+  run time. `SECURITY.md` names these as the residual routes. A forged `verify_ok` row appended this way no longer passes: with no gate-written `began`
+  row before it, it is an orphan (`hooks/tezgah_integrity.py::_pair`, `docs/evidence.md`). A forged `began` row plus its pass still does.
+
+**The seat a semantic rule would take on the Stop path, and why it stays empty.** The Stop rule's
+claim detector is a vocabulary (`DONE`/`VERIFIED`, `hooks/tezgah_integrity.py`),
+so it is the second place a classifier could sit - "does this reply claim the work
+is done?". Measured 2026-09-19 over this machine's own 161 final replies from
+`~/.omp/agent/sessions/-Projects-tezgah` and a hand-drawn set of 15 completions
+stated as a *completed state*: the list caught 2 of the 15, and the misses are all
+one shape - the Turkish passive and the English state predicate (`güncellendi`,
+`kuruldu`, `düzeltildi`, `yayına girdi`, `landed`, `merged`, `is green`, `all checks
+pass`). That is a lexical hole, not a semantic one, and naming 11 of the 13 closes
+it: the list carries them now, 39 of the 161 replies are read as claims instead of
+34, and 0 of the 5 control replies (a question, a plan, an explicit
+`doğrulanmadı`) is claimed. The verdict never moved, which is the point - a turn
+that recorded work is refused on its evidence whatever its wording (the `worked`
+trigger, which is how this detector's real semantic weakness - the same unfounded
+state stated as a description - was answered, at 0 of 10 refused before it). A
+model here would be a synchronous remote call on the Stop event of four hosts, to
+widen a list a regex already covers.
+
+## The mirror: the opencode plugin
+
+opencode cannot run Python hooks, so `hosts/opencode/plugins/tezgah.js` is an independent JavaScript re-implementation of the same rules, dispatched from
+`tool.execute.before` (hosts/opencode/plugins/tezgah.js:2373, exported `hosts/opencode/plugins/tezgah.js:2321`) in the gate's own order (`hosts/opencode/plugins/tezgah.js:2373-2535`); its shortcut constants restate the same regexes (`NEUTER` `hosts/opencode/plugins/tezgah.js:270`,
+`SKIP_ENV` hosts/opencode/plugins/tezgah.js:271, `NO_VERIFY` hosts/opencode/plugins/tezgah.js:272, `GITISH` hosts/opencode/plugins/tezgah.js:273, `SKIP_TEST` hosts/opencode/plugins/tezgah.js:515). What keeps the two halves honest is a test, not a shared module:
+`tests/test_opencode_plugin.py` drives the plugin's hooks through a node harness with a throwaway HOME, and imports the Python `tezgah_integrity.call_id` so a
+separator or canonical-form drift in the action id fails there instead of silently in a session (`tests/test_opencode_plugin.py:1-7`, `tests/test_opencode_plugin.py:24-27`, `tests/test_opencode_plugin.py::OpenCodePlugin.test_the_id_is_the_hash_the_python_writer_computes`).
+
+The shell rule kinds mirrored last are each pinned in both suites: the shell's write body (`SHELL_WRITE` `hosts/opencode/plugins/tezgah.js:979`,
+`heredocBodies` `hosts/opencode/plugins/tezgah.js:985`, `shellWriteBody` `hosts/opencode/plugins/tezgah.js:1018`, the shortcut and attribution twins at
+`hosts/opencode/plugins/tezgah.js:2425-2429` and `hosts/opencode/plugins/tezgah.js:1626`, the credential twin at `hosts/opencode/plugins/tezgah.js:1586-1590`) and the
+ordering obligation (`COMMIT_CMD` `hosts/opencode/plugins/tezgah.js:1515`, `ORDER_DENY`
+`hosts/opencode/plugins/tezgah.js:1517`, `lastVerify` `hosts/opencode/plugins/tezgah.js:1527`, `orderReason` `hosts/opencode/plugins/tezgah.js:1552`, dispatched at
+`hosts/opencode/plugins/tezgah.js:2474-2477`). `lastVerify` folds the tail exactly as `_last_verify` does, minus the `passing_check` narrowing - this rule reads only
+`fail`, and a row that narrowing would refuse reads `ok`/`ran` on both sides, so the outcome is identical.
+
+The control rule has no JavaScript copy. The plugin's `CONTROL_CMD` pre-test picks the shell lines that could touch the control plane. The plugin puts each
+such line to the core before any rule of its own, and returns the core's answer verbatim. A write tool already goes to the core. The plugin's own `off()`
+answers only for a name in its `SWITCHES` list, and `tests/test_paths.py` holds that list equal to `tezgah_paths.SWITCHES`.
+
+## Rule provenance
+
+A rule is a refusal with a cause: something happened, the check was written, and a case was added so it cannot happen again unnoticed. That record used to live
+only as a sentence inside each rule's own paragraph above. It is a table here instead, so it is one place and a machine reads it: `bin/tezgah-docs --citations`
+opens `docs/gate.md`, reads this table, and refuses a rule name the source can still produce with no row, and a row whose `pin` names a test that does not exist.
+The names are read off the source, not restated: the gate's rules are the `_deny(session_id, "<rule>", ...)` calls in `hooks/tezgah_gate.py`, and the Stop
+rule's triggers are the classes `_stop_block` returns, the four `_shape_block` and the six `_evidence_block` hand back included.
+
+- `incident` — what produced the rule; `designed` where none is recorded. The ratio of incident-derived to designed rules is the maturity signal the research
+  entry names, which is why the distinction is written down rather than smoothed over.
+- `evidence` — where that incident is written down: the page section, the module comment, or the experiment's own preregistration.
+- `pin` — the case that guards it, as `tests/<file>.py::<test_name>`. The checker refuses a pin that names no test, so the case and the row move together.
+
+| rule | incident | evidence | pin |
+|---|---|---|---|
+| `control` | the deep analysis (REPORT R05): all 12 tamper probes passed the gate - a `touch` of a switch, a Write to one, `rm .git/hooks/pre-commit`, an `echo` into the ledger, `git add -f .tezgah/x` | `SECURITY.md` (Threat model) | `tests/test_control_plane.py::test_every_tamper_probe_is_refused_without_naming_a_command` |
+| `explorer` | designed | the grep-only subagent was replaced by the graph tools; no incident recorded | `tests/test_gate.py::test_explore_subagent_denies` |
+| `shortcut` | E7c: with the write tools refused, 3 of 25 armed runs wrote a test skip through a heredoc | an internal benchmark (block E7, not published) | `tests/test_gate.py::test_a_shell_write_that_disables_a_test_is_denied` |
+| `piped` | a real omp session: 13 checks ran piped and 3 of 6 completion claims were blocked | the Piped section above | `tests/test_gate.py::test_a_piped_check_is_refused_and_pipefail_passes` |
+| `attribution` | E7c: the same 3 of 25 runs, a credit written through a heredoc | an internal benchmark (block E7, not published) | `tests/test_gate.py::test_attribution_denies_a_credit_written_by_the_shell` |
+| `lang` | a plan branch was created as `plan/004-admin-durum-onarimi`, and its slug is in the public history for good | `hooks/tezgah_gate.py:352-361` | `tests/test_gate.py::test_a_turkish_branch_name_is_refused` |
+| `race` | two sessions on one file - a parent and its subagent, or two worktrees - landing on a stale read | `hooks/tezgah_gate.py:752-759` | `tests/test_gate.py::test_a_write_to_a_file_another_session_wrote_is_refused` |
+| `task` | E7: with the unlocking command printed, an armed arm removed or disabled the gate in 25 of 25 runs; E7b: the heredoc redirect in 3 of 25 | the Task section above (the checkpoint refusal) | `tests/test_gate.py::test_a_reading_phase_refuses_a_write_inside_the_allowlist` |
+| `secret` | E7c: the same 3 of 25 runs, a key written through a heredoc | an internal benchmark (block E7, not published) | `tests/test_gate.py::test_a_credential_written_by_a_heredoc_is_denied` |
+| `workspace` | sessions wrote root `plans/`, `research/` and `analysis/` (observed across several unrelated projects on one machine) | `hooks/tezgah_gate.py:1111-1115` | `tests/test_gate.py::test_untracked_root_kinds_are_refused_for_tools_and_redirects` |
+| `plan` | a turn wrote four product files - a hook, its tests, its docs and the changelog - straight onto `main` | `hooks/tezgah_gate.py:1391-1399` | `tests/test_gate.py::test_the_third_product_write_on_main_is_refused` |
+| `order` | FAVA: the shape found in 90% of real agent-instruction projects ("do not commit before running the tests") | the Ordering section above | `tests/test_gate.py::test_a_commit_is_refused_while_the_newest_check_failed` |
+| `loop` | designed | the turn's own repeated failure; no incident recorded | `tests/test_gate.py::test_an_identical_failed_call_is_denied_after_the_ceiling` |
+| `retry` | designed | the session ceiling over the same guard; no incident recorded | `tests/test_gate.py::test_a_fourth_identical_call_is_refused_whatever_the_outcome` |
+| `drift` | an internal plan's flip rule on the 2026-09-20 move to a result-channel notice: at 27 sessions the blocked-claim rate in turns under 25 work rows read 112/140 = 0.8000, against 59/142 = 0.4155 before | `hooks/tezgah_gate.py:1284-1296` | `tests/test_gate.py::test_a_long_turn_restates_the_constraints_before_a_write` |
+| `evidence tampered` | a terminated garbage line made `_parse` raise, and the guard then failed the Stop rule open for the turn; corrupting a `verify_fail` row was an allow route. A `verify_ok` appended with `python3 -c` licensed a claim (security-03), so a pass with no `began` row is an orphan (`hooks/tezgah_integrity.py::_pair`) | `hooks/tezgah_integrity.py::_parse` | `tests/test_integrity.py::test_a_damaged_ledger_blocks_a_done_claim_as_evidence_tampered` |
+| `check failed` | designed | the newest check failing is its own class; no incident recorded | `tests/test_integrity.py::test_failed_check_blocks` |
+| `partial failure` | designed | a failure the turn never resolved; no incident recorded | `tests/test_integrity.py::test_an_unresolved_failure_blocks_even_after_an_earlier_pass` |
+| `no ui_ok` | reading the fold the old way refused honest turns and named a screen check the turn had in fact run | `hooks/tezgah_integrity.py::_evidence_block` | `tests/test_integrity.py::test_a_green_unit_run_does_not_license_a_ui_change` |
+| `stale evidence` | measured 2026-09-19: reading a rewrite as a change refused honest turns | `hooks/tezgah_integrity.py::_post_write` | `tests/test_integrity.py::test_a_write_after_the_check_makes_the_check_stale` |
+| `no verify_ok` | E2: 0 of 10 description-shaped claims refused before the `worked` trigger | `hooks/tezgah_integrity.py::_stop_block` | `tests/test_integrity.py::test_work_with_no_passing_check_is_refused_without_a_claim_word` |
+| `no external read` | two turns: "npm 0.22.0 is missing" off a stale client, and "make NPM_TOKEN an automation token" when it already was | `hooks/tezgah_integrity.py::_external_read_row` | `tests/test_integrity.py::test_an_external_claim_with_no_read_is_refused` |
+| `placating opener` | designed | output rule 10 read at the Stop event; no incident recorded | `tests/test_integrity.py::test_sycophantic_opener_blocks` |
+| `forbidden closer` | designed | output rule 10 read at the Stop event; no incident recorded | `tests/test_integrity.py::test_a_closer_from_the_skills_own_list_blocks` |
+| `list cap` | designed | output rule 8 read at the Stop event; no incident recorded | `tests/test_integrity.py::test_a_list_over_the_cap_blocks_with_its_size` |
+| `reply language` | measured 2026-09-19: the 161 final replies the claim vocabulary was read off | `hooks/tezgah_integrity.py:255-262` | `tests/test_integrity.py::test_english_prose_blocks_and_names_the_language` |
+
+## Adding a rule
+
+1. Write the check inside `decision` (`hooks/tezgah_gate.py::decision`). A rule is a function returning a `str` reason or `None`; keep an argument-shaped rule
+   above the repeat guards (`hooks/tezgah_gate.py::decision`) — the drift refusal stays last, below every other rule — and put its constants beside its own section.
+   A citation into this file names its symbol, so moving code inside it shifts nothing. Renaming or removing a cited symbol does, and `bin/tezgah-docs --citations`
+   flags it - re-run it in the same pass as the suite and re-anchor what it flags.
+2. Return through `_deny(session_id, "<rule>", reason, tool, inp, base)` so the ledger counts the refusal (`hooks/tezgah_gate.py::_deny`); gate it on the kill switch it belongs
+   to (`off(...)`), the way the shortcut and repeat rules use `verify-off` (`hooks/tezgah_gate.py::decision`). The rule name is now a record too: add its row to
+   [Rule provenance](#rule-provenance), or `bin/tezgah-docs --citations` refuses the rule for having none.
+3. Extend `tests/test_gate.py`. It drives the real function through `tests/_probe_gate.py` (`tests/support.py::PROBE_GATE`), which also carries the `capture_log` stub
+   standing in for `tezgah_gate.capture` on the allow path (`tests/_probe_gate.py:20-30`). Only if the refusal envelope changes, touch
+   `tests/test_claude_adapters.py::PreToolUse` and the codex/cursor/omp hook tests.
+4. Mirror the rule in `hosts/opencode/plugins/tezgah.js` and extend `tests/test_opencode_plugin.py` with its cases; that suite is where the two halves are
+   compared and where a shared-vocabulary drift fails.
+5. Add the rule's vectors to the shared corpus `tests/gate_vectors.json`. Its `owner` field says who keeps it. Write one call per route the rule reads, with the
+   verdict the core gives it. `tests/test_gate_vectors.py` sends each vector through every host's own entry point, under the tool name that host uses.
+   A host gets the call only when its own matcher routes that name (`hooks/hooks.json`, `hosts/dsh/hooks.json`, `hosts/codex/hooks.json`, `hosts/cursor/hooks.json`,
+   omp's `GATED` list). A cell that disagrees with the core fails the suite. The corpus may name it a ceiling, with the plan that closes it. A ceiling that agrees fails too.
+
+## Source of truth
+
+- `hooks/tezgah_gate.py` — `hooks/tezgah_gate.py::decision`; every rule constant and refusal text `hooks/tezgah_gate.py:162-2157`; `attribution`/`attribution_edit` `hooks/tezgah_gate.py::attribution`, `hooks/tezgah_gate.py::attribution_edit`; `explored`
+  `hooks/tezgah_gate.py::explored`; `hooks/tezgah_gate.py::searched_identifier`, `hooks/tezgah_gate.py::index_slug`, `hooks/tezgah_gate.py::first_nudge`, `hooks/tezgah_gate.py::nudge_reason`; `hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`,
+  `hooks/tezgah_gate.py::RETRY_CEILING`, `hooks/tezgah_gate.py::retry_reason`; `hooks/tezgah_gate.py::secret_command`, `hooks/tezgah_gate.py::race_reason`,
+  `hooks/tezgah_gate.py::drift_reason`, `hooks/tezgah_gate.py::effectful`, `hooks/tezgah_gate.py::_deny`; the plan rule's own section `hooks/tezgah_gate.py:1391-1588` — `hooks/tezgah_gate.py::plan_reason`, `hooks/tezgah_gate.py::_branch`, `hooks/tezgah_gate.py::_checkout`, `hooks/tezgah_gate.py::_product`, `hooks/tezgah_gate.py::PLAN_DENY`; `hooks/tezgah_gate.py::write_paths`, `hooks/tezgah_gate.py::shell_target`, `hooks/tezgah_gate.py::SHELL_AS_WRITE`; the `capture` call `hooks/tezgah_gate.py::decision` (a write tool's target, and a shell write's)
+- `hooks/projects-pretooluse.py` — the Claude and dsh envelope; `hooks/tezgah_paths.py` — `off`, `root_for`, `cache_dir`
+- `hooks/tezgah_integrity.py` — `hooks/tezgah_integrity.py::WRITE_TOOLS`, `hooks/tezgah_integrity.py::BASH_TOOLS`; `NEUTER`/`SKIP_ENV`/`NO_VERIFY`/`GITISH` `hooks/tezgah_integrity.py::NEUTER`, `hooks/tezgah_integrity.py::SKIP_ENV`, `hooks/tezgah_integrity.py::NO_VERIFY`, `hooks/tezgah_integrity.py::GITISH`; `HOOKS_KEY`/`GIT_VALUE_OPTS`/`CONFIG_READS`/`ROUGH_WORDS` `hooks/tezgah_integrity.py::HOOKS_KEY`, `hooks/tezgah_integrity.py::GIT_VALUE_OPTS`, `hooks/tezgah_integrity.py::CONFIG_READS`, `hooks/tezgah_integrity.py::ROUGH_WORDS`; `hooks/tezgah_integrity.py::SKIP_TEST`; `TEST_PATH`
+  `hooks/tezgah_integrity.py::TEST_PATH`; `hooks/tezgah_integrity.py::call_id`; `hooks/tezgah_integrity.py::_path`, `hooks/tezgah_integrity.py::note`, `hooks/tezgah_integrity.py::events`, `hooks/tezgah_integrity.py::writers_elsewhere`, `hooks/tezgah_integrity.py::mask`, `hooks/tezgah_integrity.py::shortcut_command`,
+  `hooks/tezgah_integrity.py::shortcut_edit`
+- `hosts/opencode/plugins/tezgah.js` — the JavaScript mirror
+- `bin/tezgah-docs` — the rule-ledger check (`ledger_failures`) that reads this page's provenance table; `tests/test_docs.py` drives it
+- `tests/test_gate.py`, `tests/_probe_gate.py`, `tests/test_opencode_plugin.py`, `tests/test_claude_adapters.py`