@r1z4x/tezgah 1.0.0

package/docs/testing.md

@@ -0,0 +1,287 @@
+# Testing: the checks, the probes, the e2e scripts
+
+This page is for a maintainer adding or changing a test, or who has just changed
+a hook, a CLI or a status line and wants to know what will notice. It records the
+checks that gate a commit, the shape of the suite, the helpers to reach for, and
+the rules a new test must satisfy.
+
+## The three checks
+
+```sh
+python3 -m compileall -q hooks hosts bin statusline.py   # byte-compile every script
+python3 -m unittest discover -s tests                     # stdlib test suite
+ruff check .                                              # lint; config in pyproject.toml
+```
+
+[`AGENTS.md`](../AGENTS.md) gives them in that order (`AGENTS.md:20-35`), and
+[`CONTRIBUTING.md`](../CONTRIBUTING.md) repeats the same three before a pull
+request (`CONTRIBUTING.md:15-20`).
+
+| Check | What it catches that the other two do not |
+|---|---|
+| `compileall` | A syntax error in any `.py` under `hooks/` and `hosts/`, plus `statusline.py`, without running a line of it and with no environment set up. The `bin/` CLIs are Python sources with no `.py` suffix, so only running one compiles it (`test_setup.py::SetupBase.setup`). |
+| `unittest` | Behaviour: what a hook answers, what the [gate](glossary.md#gate) denies, what reaches the [ledger](glossary.md#ledger), what a status line renders. |
+| `ruff` | Lint only, with the rule set pinned in `pyproject.toml:12-14` (`E4`, `E7`, `E9`, `F`; `E501` ignored). The pin exists because newer ruff releases ship a broader default and would otherwise change `ruff check .` in CI (`pyproject.toml:10-11`). One pre-existing script is exempted per-file in `pyproject.toml:19-20`. |
+
+`ruff` is not vendored: install it as a uv tool, run `uvx ruff check .` without
+installing it, or use the version CI installs from `requirements-dev.txt:3`
+(`ruff==0.16.7`). There is no other linter and no type checker
+(`AGENTS.md:44-45`).
+
+The clarity ratchet, `bin/tezgah-docs --clarity`, counts four prose rules per
+file in `docs/*.md` and `CHANGELOG.md`. The rules are sentences over 25 words,
+semicolons, a short list of words with a plainer form, and passive voice. It
+skips code fences, code spans, tables, headings and Turkish lines. Each count is held to
+`docs/clarity-baseline.json`. A file over its baseline in any rule exits 1, and
+a file the baseline does not list is held to 0. A count that drops lowers the
+baseline on the next run. Only `--clarity --update` raises it.
+
+## What the pins do not cover
+
+A pin is a claim about what ran, not a guarantee about what will. This repository
+has two, and both are about the language rather than about dependencies: the
+floor `py310` (`pyproject.toml:5`) and the CI matrix that proves it
+(`.github/workflows/ci.yml:24`). There is no dependency lockfile to pin
+because there is no package: tezgah is a set of scripts run in place, and no
+`[project]` or build system is declared (`pyproject.toml:1-2`). The only
+third-party tool the checks name is ruff, at a version in
+`requirements-dev.txt:3`.
+
+The FineEnvs multi-harness RL tutorial carries far more machinery and says the
+same thing out loud: its validation record installs TRL and OpenEnv from upstream
+main, records the commit each run resolved to, states that this "is not a
+dependency lockfile", and lists its own unchecked GPU items as pending rather
+than implying the matrix is done. That is the shape to copy - say what is pinned,
+say what was resolved at the time, and say what a reader should therefore not
+conclude from either.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on every push and pull request. `release.yml`
+calls it (`ci.yml:8`) as its `ci` job, so npm and brew publish only after CI
+passed on the release commit. It runs five jobs. No matrix
+cancels its other legs when one fails (`fail-fast: false`).
+
+- `test` (`ci.yml:15-43`) on Python 3.10, 3.12, 3.13 and 3.14. 3.10 is the
+  floor the project supports. The byte-compile step exercises it rather than
+  asserts it. It byte-compiles, runs the suite with `-v`, lints with
+  ruff from `requirements-dev.txt` (`ci.yml:37`), audits the docs citations and
+  runs `TEZGAH_E2E_STRICT=1 python3 tests/e2e_plan_flow.py`.
+- `test-sharded` (`ci.yml:48-69`) on Python 3.10 and 3.14 with node 22 (the
+  first line that loads the omp `.ts` hook without a flag):
+  `python3 tests/impacted.py --all`. It is a shadow that started 2026-10-05.
+  After four weeks it replaces the four-version `test` matrix only if it missed
+  no failure that matrix caught.
+- `apps-e2e` (`ci.yml:71-88`) on Python 3.12 and node 20: one step,
+  `TEZGAH_E2E_STRICT=1 python3 tests/e2e_analyze_wiring.py`. It completes the
+  app-MCP handshake only - no browser, no device - so it stays deterministic;
+  strict mode makes a server that cannot start a failure rather than a skip, so
+  a broken wire cannot hide behind a skip (`e2e_analyze_wiring.py:4-12`).
+- `artifact-install` (`ci.yml:90-128`) on Python 3.10 and 3.12: builds the
+  tarball, installs from it under a temp prefix, and runs the artifact smoke on
+  the installed tree instead of the checkout.
+- `artifact-install-windows` (`ci.yml:130-214`) on `windows-latest`: the same
+  build, install and smoke through `packaging/install.ps1` - the twin a Windows
+  user runs - so it is the only place the Windows claim is proven. It then runs
+  the opencode plugin's path tests natively, `tezgah update --dry-run`, the
+  opencode live probe and `--uninstall` from the installed tree. Any residue
+  under the prefix fails it.
+
+`.github/workflows/neuter.yml` runs two jobs weekly (and on demand). The first,
+`neuter`, asks the question the suite cannot ask of itself - would a test fail
+if a guard went?
+`tests/neuter_matrix.py` clones HEAD once per anti-shortcut guard, reverts that
+guard, and runs the gate's test modules; a mutant that still passes is a guard no
+test notices, and an unmutated control that fails voids the run. The script
+generates the gate half: one `gate-<rule>` mutant per rule `decision` refuses with.
+It reads HEAD with the AST reader of the `--citations` rule check. Each mutant turns
+every `return _deny(...)` of its rule into `pass` at its line span.
+The script generates the Stop half too. Each `return ("<class>", ...)` site of
+`_stop_block`, `_shape_block` and `_evidence_block` gets one `stop-<class>` mutant. Hand-written
+rows cover the guards around those classes: the pass predicate, the empty-run
+read and the "doğrulanmadı" clear. The lost call, the bookkeeping and idle-turn
+fallbacks and the refusal row have rows too. The shortcut half is still
+hand-written (`MUTANTS`), so a new guard there needs a row.
+
+The second, `fuzz-shell`, runs the bash-oracle fuzzer (`tests/fuzz_shell.py`)
+under the ubuntu runner's bash 5.x. Locally, macOS ships bash 3.2. A first step
+fails unless `BASH_VERSINFO` is 5 or later. Then
+`python3 tests/fuzz_shell.py --seed 1 --lines 20000 --strict` reads the lines
+with the core readers. The same command with `--js` reads them with the
+opencode plugin's ports. That step runs even when the core step failed.
+`--strict` turns any disagreement class into exit 1
+(`tests/fuzz_shell.py::main`). So a reader that misreads a bash 5 line fails
+the leg instead of printing a count. `tests/test_packaging.py` pins the job.
+
+The Stop rule's temporal spec (`hooks/tezgah_stopspec.py`, plan 063) has its own
+local script, `tests/stop_spec_eval.py`. `--replay` judges plan 055's replayed
+Stop events with both folds and reads GO 2 only on the events whose selector
+reached the fold. `--shadow-rows` reads the live `stop_spec` rows the same way.
+`--timing` times both folds in-process. `--stop-cost` times the whole
+`stop_reason`, shadow on and off, on copies of the real ledgers. `--mutants`, also reached through
+`tests/neuter_matrix.py --stop-generated`, runs seeded mutants of the formula
+table through the in-process Stop tests of `tests/test_integrity.py`. On any
+suite run, `TEZGAH_STOPSPEC_STRICT=1` fails the test that reached a disagreement.
+
+The plan report (`render_table.py --acceptance --strict`) is not in CI: it reads
+the gitignored `.tezgah/`, so on a runner it reads nothing and cannot fail. Run
+it locally. The dsh and omp status-line scripts, `tests/e2e_tezgah_mcp.py` and
+`tests/e2e_docker_cycle.py` are not in CI either.
+
+## How the suite is shaped
+
+Every test that exercises a hook runs it in a subprocess with an environment the
+test built: a throwaway `HOME`, `TEZGAH_ROOTS` under tempfile, `PYTHONPATH` at
+`hooks/`, so the real `~/.claude`, `~/.config/tezgah` and `~/.cache` are never
+read or written (`tests/support.py:3-5`). Four kinds of test live under `tests/`,
+on top of that support layer.
+
+**Unit tests over a module.** `tests/test_paths.py:17-18` imports
+`hooks/tezgah_paths.py` directly and drives it in-process; where a temp HOME must
+matter it patches the module's own constants with
+`unittest.mock.patch.multiple` (`tests/test_paths.py::ConcurrentProbe`). Reach for this only for
+pure logic or for concurrency, which a subprocess cannot express.
+
+**Subprocess tests with a temp HOME.** The default. `TempHome` gives the test a
+fresh `home` and a `roots` dir, `env()`, `make_repo()`, `config()` and `touch()`
+(`TempHome`, `tests/support.py::TempHome`); the hook or CLI is then run with `run`
+(`tests/support.py::run`) or `run_json` (`tests/support.py::run_json`). `tests/test_codex_hook.py::CodexHook` is the smallest example.
+
+**Probes.** `tests/_probe_*.py` are tiny scripts that call one function of a
+shared module and print its result as JSON, so the call happens in a process
+whose `HOME` and `TEZGAH_ROOTS` are already the test's. They exist because those
+modules derive paths from `HOME` at import time - `hooks/tezgah_paths.py:19-32`
+builds `CONFIG`, `CACHE` and `DEFAULT_ROOT` at module level - so importing them
+into the test process would answer about the developer's real machine.
+
+| Probe | Command | Entry points |
+|---|---|---|
+| `tests/_probe_paths.py` | argv op, no payload (`:11`) | `roots`, `root_for`, `off`, `default_root`, `config`, `off_dirs`, `cache_dir`, `which_user`, `orx_bin`, `consult_options`, `have_typesafe_key`, `codegraph_bin` |
+| `tests/_probe_context.py` | JSON on stdin, `{"fn": ...}` (`:4-5`) | `context_for`, `health_lines`, `health_segments`, `record` |
+| `tests/_probe_integrity.py` | JSON on stdin (`:4-6`) | `note`, `note_tool`, `note_turn`, `kinds`, `events`, `prior_calls`, `counters`, `shortcut_command`, `shortcut_edit`, `stop_reason`, `verify_command` |
+| `tests/_probe_agents.py` | JSON on stdin (`:3-4`) | `sync_root`, `opencode_json`, `cleanup`, `detect` |
+| `tests/_probe_gate.py` | JSON on stdin (`:4-8`) | the shared gate `decision(tool, input, cwd, session_id)`; `capture_log` plants a stub `tezgah_snapshot` in `sys.modules`, so the snapshot call site is pinned whether or not that module has landed |
+
+A probe is invoked through `support.run`/`run_json` with its path constant
+(`support.PROBE_PATHS`, `support.PROBE_CONTEXT`, ... in `support.py:21-26`), e.g.
+`run_json([support.PROBE_CONTEXT], {"fn": "health_lines", "cwd": repo},
+env=self.env())` (`test_context.py::HealthLines.test_armed_but_unused_checklist`). Nothing in `tests/_probe_*.py` is
+collected: the name does not match discovery's `test*.py` pattern and no probe
+defines a `TestCase`.
+
+**End-to-end scripts.** `tests/e2e_*.py` are not collected either
+(`e2e_omp_statusline.py:13-16`) and are run by hand. They exit 0 on `PASS` or
+`SKIP` and 1 only on a real failure (`tests/e2e_dsh_statusline.py::main`).
+
+| Script | Needs | Prints `SKIP` when |
+|---|---|---|
+| `e2e_analyze_wiring.py` | node (`npx`) (`tests/e2e_analyze_wiring.py::main`) | npx is absent; a server that cannot start is a skip, or a failure under `TEZGAH_E2E_STRICT=1` (`:10-12`) |
+| `e2e_analyze_web.py` | `TEZGAH_E2E_APPS=1`, npx, a Playwright browser build (`:9-13`) | the opt-in env var, npx, the server start or the browser build is missing |
+| `e2e_analyze_mobile.py` | `TEZGAH_E2E_APPS=1`, npx, a booted simulator or emulator (`:9-14`) | the same, or no running device |
+| `e2e_dsh_statusline.py` | the `dsh` binary, Playwright, a Chromium build, a persisted session (`tests/e2e_dsh_statusline.py::run`) | any of them is missing (`tests/e2e_dsh_statusline.py::run`) |
+| `e2e_omp_statusline.py` | the `omp` binary and the extension `tezgah-setup` installs, plus a pty (`:13-15`) | either is missing (`tests/e2e_omp_statusline.py::run`) |
+| `e2e_docker_cycle.py` | a running Docker daemon; the image is `python:3.12-slim` unless `TEZGAH_E2E_DOCKER_IMAGE` says otherwise (`tests/e2e_docker_cycle.py::IMAGE`) | docker or its daemon is missing (`tests/e2e_docker_cycle.py::main`) |
+
+`SKIP` is the designed answer, not a hideout: these scripts test that a wire or a
+render works, and a missing prerequisite says nothing about the repository. Two
+are opt-in behind `TEZGAH_E2E_APPS=1` because they do real work, so they never run
+by surprise (`tests/e2e_analyze_web.py::main`), and the omp script starts the TUI with
+no prompt, so the run costs no model call (`e2e_omp_statusline.py:2-4`).
+
+## The rules a new test must satisfy
+
+**It must fail on a plausible bug.** Where the repo turns a behaviour into a
+string, the pin *is* the contract: the exact status segment
+(`tests/test_statusline.py::SEGMENT`, compared at `tests/test_statusline.py::Statusline.test_claude_mode_segment`), a `tezgah-setup --status` row
+label (`test_setup.py::StatusNamesTheHostListGap`), the opencode router line a skill's trigger
+reaches (`test_setup.py::SkillRouterTriggers.test_core_skill_lines_carry_their_trigger`), the kill-switch labels whose deletion must
+fail the test rather than silently disarm a rule (`test_context.py::KillSwitchEnforcement`). An
+intentional change updates the pin in the same commit; deleting the test because
+it is now red is the failure mode these pins exist to catch.
+
+**Assert observable behaviour, not wiring, defaults or source text.** A test that
+reads a file to check a copy of an implementation, or that asserts an internal
+call was forwarded, dies at the first refactor. Where text is asserted it is
+output the user or a host sees. The suite's own comments say the rule twice:
+pin the behaviour, not one phrasing of it (`tests/test_skills.py::SkillStandards.test_the_bootstrap_completes_a_partial_tree_and_never_clobbers_it`), and pin a
+rule on a synthetic input, not only on the shipped pair
+(`test_setup.py::SkillTriggerLine`).
+
+**Stay deterministic and isolated.** A temp HOME is the mechanism
+(`support.py:3-5`), and importing `support` gives the test process one too, with
+no `TEZGAH_SESSION` (`support.py:113-126`); `base_env` also points `TEZGAH_CODEGRAPH_BIN` and `TEZGAH_ORX_BIN`
+at paths that do not exist and sets `TEZGAH_CONSULT_CLIS` empty, so the
+machine's own graph binary, orx and agent CLIs cannot leak into an assertion
+(`tests/support.py::base_env`). The installer suite sets
+`TEZGAH_NO_DEPS=1` so `--install` fetches nothing (`tests/test_setup.py::SetupBase.setUp`). No test
+reaches the network: where a provider is needed it is a loopback stub
+(`tests/test_providers.py::Trickle.__init__`, `tests/test_consult_arena.py::ArenaCase.setUp`).
+
+**Run inside the default discovery.** A new test is `tests/test_<thing>.py`, a
+`unittest.TestCase`, and passes under
+`python3 -m unittest discover -s tests` from the repository root. A check that
+cannot run everywhere is not a test: it goes to `e2e_*.py` (needs a binary,
+a browser or a device) or to a `_probe_*.py` helper the tests call.
+
+## What the suite deliberately does not do
+
+- **No coverage target and no coverage tool.** `requirements-dev.txt` pins ruff
+  and nothing else (`requirements-dev.txt:1-3`); no coverage tool is named there
+  or in `pyproject.toml`. A line count is not a check.
+- **No fixtures framework.** Stdlib `unittest` only (`CONTRIBUTING.md:33`);
+  `tests/support.py` is the whole fixture layer, with no `conftest.py`.
+- **No network.** Loopback stubs only, as above.
+- **Two e2e scripts stay opt-in and local**: `e2e_analyze_web.py` and
+  `e2e_analyze_mobile.py`, behind `TEZGAH_E2E_APPS=1`, with the wiring handshake
+  as their CI substitute (`AGENTS.md:108-114`).
+
+## Adding a test
+
+**For a hook.** Subclass `TempHome`, make a repo, run the adapter with a payload
+and `self.env()`, assert on its JSON output:
+
+1. `from support import TempHome, run_json` and `import support` (`test_codex_hook.py:1-8`).
+2. `repo = self.make_repo()`; seed any state with `self.touch(...)` / `self.config({...})`.
+3. `out, proc = run_json([support.CODEX_HOOK], {"hook_event_name": "Stop", "cwd": repo, "session_id": "s"}, env=self.env())`.
+4. `self.assertEqual(proc.returncode, 0, proc.stderr)` first, then assert the field you changed.
+   Which host lives where: `support.py:31-36` (`CODEX_HOOK`, `CURSOR_HOOK`, `OMP_HOOK`, `STATUSLINE`).
+5. Reading back what the hook wrote? Use the ledger probe, not the file path
+   (`test_codex_hook.py::CodexEvidence.kinds` uses `support.PROBE_INTEGRITY` with `{"fn": "kinds"}`).
+
+**For a CLI.** Run it with a temp environment and assert on its stdout or on the
+tree it left. A `bin/` CLI is run as a subprocess with `sys.executable` and an
+explicit environment (`test_setup.py::SetupBase.setup`); `SetupBase` in
+`tests/test_setup.py::SetupBase` is the worked example for `bin/tezgah-setup` (fake host
+dirs, `TEZGAH_NO_DEPS=1`, stdin always a pipe so the wizard cannot block on a
+real terminal). For a plain CLI,
+`run([support.STATUSLINE], {"cwd": repo}, env=self.envv)` is enough
+(`test_statusline.py::Statusline.test_claude_mode_segment`).
+
+**For a status-line change.**
+
+1. Change the [mark](glossary.md#mark) in `hooks/tezgah_context.py` (the shared
+   builder) or in the host surface named on [status-line](status-line.md).
+2. Update the pinned segment in `tests/test_statusline.py:17-20` - both the
+   in-roots and off-roots constants - and re-run
+   `python3 -m unittest discover -s tests -p 'test_statusline.py'`.
+3. If the colour or the state changed, extend the `NO_COLOR` / `TEZGAH_STATUS_COLOR`
+   cases (`test_statusline.py::Statusline.test_status_color_env_off_strips_ansi`) rather than adding a new file.
+4. The shared builder is covered through the context probe
+   (`test_context.py::HealthLines`); a mark that flips on an event belongs there.
+5. Only the drawing is left to the real surface, and that is
+   `e2e_omp_statusline.py` / `e2e_dsh_statusline.py`, run by hand.
+
+## Source of truth
+
+- `AGENTS.md`
+- `CONTRIBUTING.md`
+- `.github/workflows/ci.yml`
+- `pyproject.toml`, `requirements-dev.txt`
+- `tests/support.py`
+- `tests/_probe_paths.py`, `tests/_probe_gate.py`, `tests/_probe_context.py`,
+  `tests/_probe_integrity.py`, `tests/_probe_agents.py`
+- `tests/e2e_analyze_wiring.py`, `tests/e2e_analyze_web.py`,
+  `tests/e2e_analyze_mobile.py`, `tests/e2e_dsh_statusline.py`,
+  `tests/e2e_omp_statusline.py`
+- `tests/test_statusline.py`, `tests/test_codex_hook.py`, `tests/test_setup.py`,
+  `tests/test_context.py`, `tests/test_paths.py`

package/docs/vision.md

@@ -0,0 +1,117 @@
+# How a tezgah session is meant to run
+
+**Who reads this, and when.** A maintainer or an agent about to change how
+sessions behave: the check cadence, the review loop, model routing, the research
+layer. It is the operating model those rules serve, with the measurement behind
+each one. The rules themselves live in `hooks/tezgah_policy.py`; this page is the
+shape they add up to, and it is written so a change to one of them can be judged
+against the model instead of against taste.
+
+Measured on 2026-10-01 from one session (356 active minutes, 573 tool calls) plus
+the workspace's own records; every number below names where it came from.
+
+## The five principles
+
+1. **Answer first, act only inside the asked scope.** A turn whose ask is a
+   question answers it from evidence already gathered, then stops. Standing
+   authority to merge or push never fires on such a turn. (Measured: a question
+   turn ended in a merge and a push, and the user had to say the question went
+   unanswered.)
+2. **Cost is paid once per revision, not once per commit.** Checks have tiers,
+   and the biggest one runs once on the final tree (`hooks/tezgah_policy.py::CORE`). (Measured: 11 serial suite
+   runs, 106 minutes, 10 of them green confirmations, in one session - the rule
+   "run the full suite once, on the final tree" was already written down and
+   `AGENTS.md` said "before every commit".)
+3. **A review loop reads every fix.** A round that confirms a defect gets a
+   round over the fix. The loop ends when a round confirms none
+   (`hooks/tezgah_agents.py::_reviewer_body`). The same defect family three times means the
+   design changes. (Measured: two of four severe defects in one internal plan came from
+   fixes, after round two.)
+4. **Doubt lowers nothing and hides nothing.** An unverifiable check never
+   downgrades a finding, an unknown criterion never relaxes a cap, and a line
+   whose own criteria are unmet is reported as unanswered rather than concluded.
+   (Measured: `close --limit` accepted any string; 4 of 11 sampled research lines
+   concluded with the ask unanswered.)
+5. **Do not re-verify a revision that has not changed, and do not re-ask a
+   question that was answered.** Repeat guards key on the tree, not on the
+   command text; a green check is evidence until the tree moves.
+
+## The tiers, and what each costs (measured)
+
+| Tier | Command | Wall time |
+|---|---|---|
+| edit loop | `tests/impacted.py --run <changed paths>` | 0.1-95 s (integrity+gate: 18 modules, 93.8 s) |
+| pre-commit | that set + compileall + ruff (+ `--citations` when hooks/ or bin/ moved) | +~5 s |
+| pre-merge, once | `tests/impacted.py --all` + the two e2e scripts | 103.5 s (8 shards; 566.9 s serial) |
+| CI | the same, on the matrix in `.github/workflows/ci.yml` | unchanged |
+
+A path the map does not know runs everything (`tests/impacted.py::modules_for`): `tests/support.py`,
+`hooks/tezgah_paths.py` and anything new. `tests/test_impacted.py` refuses a
+change that would silently run nothing.
+
+## Model routing
+
+Every omp agent gets a **cross-family fallback chain** (`hooks/tezgah_models.py::_chain`, over `hooks/tezgah_models.py::funded_families`): the mode's family first,
+then every other family this machine holds a credential for. One pin per agent
+made one provider's 429 every subagent's failure, because the account is shared
+with the main thread (measured: 24 of 26 post-routing 429s hit a subagent's first
+request, all on one Opus account; four reviews and three implementation agents
+died on it in one day). A family whose credential cannot be detected is left out
+of the chain, never guessed in. The main thread's own model, and the provider-keyed
+chains, stay the user's settings - tezgah writes only the keys it owns.
+
+What tezgah cannot fix from inside: a provider that stalls on a very large
+context (`OpenAI completions stream stalled`, five minutes without an event on a
+458k-token request - a DeepSeek-side stall, with no hook blocking the loop), and a
+quota shared by every session on the machine. Those are settings and a reminder,
+not a rule.
+
+## The research layer
+
+A line carries the user's ask verbatim, a tier (`quick` gets no line at all, `hooks/tezgah_research.py::ask_problems`), and
+one success criterion per part of the ask, written before any experiment. It ends
+with a verdict per criterion; a criterion that is `not-met` is a result, but it is
+recorded, and an unanswered line stays visible in `status` instead of disappearing
+into `done/`. Lines live under `research/open/` and `research/done/`, the way plans do, resolved
+by one reader (`hooks/tezgah_research.py::line_dir`); an unmet criterion keeps a line
+listed as unanswered (`hooks/tezgah_research.py::unanswered`).
+
+## What is measured to know the operating model holds
+
+These are measures of how a session runs, not of task outcomes.
+
+- wall time per session and the share spent waiting;
+- serial full-suite runs per session (the count, not the length, is the cost);
+- review rounds per change;
+- subagent spawn failures by model;
+- research lines concluded with every criterion met, against lines concluded
+  unanswered;
+- `status`'s own count of lines the layout has not migrated.
+
+## What it does not claim
+
+The model above describes mechanisms: what a session is told, what the gate
+refuses, what the ledger records. It does not claim that an agent under tezgah
+cheats less, finishes more tasks or reports more honestly. A paired on/off
+experiment in October 2026 tested that and found no measurable effect. It ran
+DeepSeek V4.1 Flash on omp, bare against a full install. On ImpossibleBench's
+conflicting SWE-bench split, the agent cheated in 0 of 132 runs with tezgah and
+1 of 131 without. The model barely cheated in either arm, so the experiment had
+no headroom. Hand labels of final messages on those impossible tasks found
+false done claims in 3 of 30 runs with tezgah and 6 of 30 without. The CI of
+that difference includes 0. The Stop rule's claim reader
+flagged far more runs than that. On Turkish replies it counts `doğrulandı`
+(verified) on a partial fix as a claim, a recorded weakness not yet fixed. The
+numbers, the per-task counts and the instrument flaws are in
+[the results bundle](results/paired-outcome-2026-10.md).
+
+## Source of truth
+
+- `hooks/tezgah_policy.py` - the rules this page describes.
+- `hooks/tezgah_integrity.py`, `hooks/tezgah_gate.py` - the gate and the ledger.
+- `hooks/tezgah_models.py`, `docs/models.md` - the routing table and the chains.
+- `hooks/tezgah_research.py`, `docs/research.md` - the research layer.
+- `tests/impacted.py`, `docs/testing.md`, `AGENTS.md` - the check tiers.
+- `docs/results/paired-outcome-2026-10.md` - the paired outcome experiment.
+- The four internal diagnosis reports behind the numbers (session scratch,
+  not published).

package/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "TEZGAH_CORE_IN_FILE=1 \"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-auto-init.py\"", "timeout": 10 } ] }
+    ],
+    "SubagentStart": [
+      { "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-auto-init.py\"", "timeout": 10 } ] }
+    ],
+    "PostCompact": [
+      { "hooks": [ { "type": "command", "command": "TEZGAH_CORE_IN_FILE=1 \"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-auto-init.py\"", "timeout": 10 } ] }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-auto-init.py\"", "timeout": 10 } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Agent|agent|Task|task|Grep|grep|Bash|bash|PowerShell|pwsh|Shell|shell|subagent|Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-pretooluse.py\"", "timeout": 5 } ] },
+      { "matcher": "^mcp__(?:.*[^A-Za-z0-9])?(?:append|cancel|clear|click|close|comment|commit|copy|create|delete|deploy|drag|edit|email|evaluate|exec|execute|fill|insert|install|kill|launch|merge|message|mkdir|move|navigate|notify|patch|pause|post|press|print|publish|push|put|release|remove|rename|replace|reply|resume|review|run|save|send|set|share|skip|start|stop|submit|swipe|tag|tap|terminate|type|uninstall|update|upload|write)(?:[^A-Za-z0-9].*)?$", "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-pretooluse.py\"", "timeout": 5 } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|edit|Write|write|MultiEdit|NotebookEdit|Bash|bash|PowerShell|pwsh|str_replace_editor|WebFetch|WebSearch|web_fetch|web_search|fetch|mcp__.*", "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-posttooluse.py\"", "timeout": 5 } ] },
+      { "matcher": "Agent|Task|Skill", "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-posttooluse.py\"", "timeout": 5 } ] }
+    ],
+    "PostToolUseFailure": [
+      { "matcher": "Edit|edit|Write|write|MultiEdit|NotebookEdit|Bash|bash|PowerShell|pwsh|str_replace_editor|WebFetch|WebSearch|web_fetch|web_search|fetch|mcp__.*", "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-posttooluse.py\"", "timeout": 5 } ] }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-stop.py\"", "timeout": 5 } ] }
+    ],
+    "SubagentStop": [
+      { "hooks": [ { "type": "command", "command": "\"${TEZGAH_PYTHON:-python3}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/projects-stop.py\"", "timeout": 5 } ] }
+    ]
+  }
+}

package/hooks/projects-auto-init.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Claude Code hook: SessionStart, UserPromptSubmit, SubagentStart, PostCompact.
+
+Emits the shared tezgah context (hooks/tezgah_context.py) for the session's
+cwd when it resolves inside a configured root, and prints nothing outside them.
+This file is only the Claude envelope; the contract itself lives in the core so
+Codex, Cursor, opencode, dsh and omp inject the exact same text.
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
+from tezgah_guard import attest_session, import_failed, safe  # noqa: E402
+try:
+    from tezgah_context import context_for, record  # noqa: E402
+    from tezgah_paths import HOST_DIRS  # noqa: E402
+except Exception as exc:
+    import_failed(exc)
+
+EVENTS = {
+    "SessionStart": "session_start",
+    "UserPromptSubmit": "user_prompt",
+    "SubagentStart": "subagent_start",
+    "PostCompact": "post_compact",
+}
+
+# PostCompact is observed, not answered. A real compaction on Claude Code
+# 2.1.283 (2026-09-30) showed what the host does with an envelope on
+# this event: it REJECTS it - "Hook JSON output validation failed -
+# hookSpecificOutput.hookEventName: expected one of "PreToolUse" |
+# "UserPromptSubmit" | ... | "SessionStart" | ..." - reports the hook as failed,
+# and prints the raw JSON, context text included, into the transcript the model
+# reads next. The post-compaction context reaches the model through SessionStart,
+# which fires again as `SessionStart:compact` and whose additionalContext was
+# delivered in the same run. So on PostCompact this hook still builds the block -
+# that is where `context_for` records the compaction (remember_compaction) - and
+# prints nothing. Codex answers PostCompact from hosts/codex/hook.py, which
+# prints no context on it either, and dsh's bridge does not carry the event.
+
+# Claude's global memory file, where install_claude writes the always-on core as
+# a managed block: the file Claude reads into every session, so the core is
+# already in the session's instructions.
+CORE_IN_FILE = os.path.join(HOST_DIRS["claude"], "CLAUDE.md")
+
+
+def core_is_in_a_file():
+    """True when the core reaches this session from a file the host keeps, so
+    this hook must not pay for the contract a second time in its one message.
+
+    The host declares it in its manifest (`TEZGAH_CORE_IN_FILE`, the same shape
+    as the dsh rows' `TEZGAH_CALL_OUTCOME`) rather than this file guessing from
+    the payload: dsh runs this very script through its claude-code bridge and has
+    no such file, so its session still gets the core from here. The file is read
+    as well as assumed - a user who deleted it falls back to the hook."""
+    if os.environ.get("TEZGAH_CORE_IN_FILE") != "1":
+        return False
+    try:
+        with open(CORE_IN_FILE, encoding="utf-8", errors="ignore") as fh:
+            return "<!-- tezgah:start" in fh.read()
+    except OSError:
+        return False
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        payload = {}
+    event = payload.get("hook_event_name") or "SessionStart"
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    if event == "SubagentStart":
+        # The status line's orch mark. This file is the only SubagentStart hook
+        # tezgah wires, and dsh (which runs it too) has no transcript to derive
+        # the kind from, so the store is the only channel its line has.
+        safe(payload.get("session_id"), record, payload.get("session_id"), "orch")
+    if event == "SessionStart":
+        # Claude and dsh run this one script; Claude's manifest declares
+        # TEZGAH_CORE_IN_FILE on SessionStart and dsh's does not, so the flag
+        # names whose entries to attest. ponytail: a Claude manifest edited to
+        # drop the flag is attested as dsh - and still reads as drift there.
+        sid = payload.get("session_id")
+        host = "claude" if os.environ.get("TEZGAH_CORE_IN_FILE") == "1" else "dsh"
+        safe(sid, attest_session, host, sid, cwd)
+    text = safe(payload.get("session_id"), context_for,
+                EVENTS.get(event, "session_start"), cwd, payload,
+                # the brief is a subagent's own text, never the file's; every
+                # other event drops the core when the host's file carries it
+                with_core=(event == "SubagentStart" or not core_is_in_a_file()))
+    if text and event != "PostCompact":
+        json.dump({"hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": text,
+        }}, sys.stdout)
+    sys.exit(0)
+
+
+main()