@r1z4x/tezgah 1.0.0

package/docs/contract.md

@@ -0,0 +1,416 @@
+# Contract: what a session is told, and how a rule is disarmed
+
+The rule layer of tezgah: the text a session receives, the order it arrives in,
+the file each piece is written from, and the switch that takes one out. Read it
+when you add or edit a rule, when you need to know whether a session was really
+told something, or when a session behaves as if a rule were missing. The
+user-facing side of the same contract is [README.md](../README.md); the words
+used here are defined once in [glossary.md](glossary.md); which host gets which
+surface is [hosts.md](hosts.md).
+
+Every string is a module constant in `hooks/tezgah_policy.py`, so that every
+host says the same thing (`hooks/tezgah_policy.py:14-15`); path placeholders
+(`{ROOT}`, `{CONSULT_BIN}`, `{ORX_BIN}`, …) are filled at injection time by
+`render()` (`hooks/tezgah_context.py::render`).
+
+## The five surfaces
+
+| Surface | Text | Paid |
+|---|---|---|
+| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the five conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
+| conditional paragraph | one of the five keyed by `CONDITIONAL_KEYS` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) | in full on the first turn of a session whose prompt matches its task class; a later match pays one line (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns (`hooks/tezgah_context.py::ARMED_RESURFACE`) bring the full text back |
+| per-turn reminder | `PROMPT_REMINDER` (`hooks/tezgah_policy.py::PROMPT_REMINDER`) | every user prompt |
+| skill suggestion | one `<skill_relevance>` line naming at most one installed skill, written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`); off unless `skill-suggest-on` is armed | only on a turn the judgement answers with a skill |
+| on-demand full contract | the long-form blocks of `hooks/tezgah_policy.py` (`EXEC`, `CONSULT`, `RESEARCH`, …), shipped hand-kept as `skills/tezgah-contract/SKILL.md` | only when the session loads that skill |
+
+The skill suggestion is the one surface a judgement writes rather than a constant.
+The roster reaches a session as an index of host-truncated one-liners, so which
+entry to look at first is the turn's own weak spot; one batched judgement request
+answers it - TypeSafe, or the OpenRouter fallback when no TypeSafe key resolves
+(`credential()`, `hooks/tezgah_judge.py::credential`) - a Choice across the installed
+skill names plus `none`, and one Noul
+asking whether the turn wants a skill at all - and the winner is appended after
+the armed paragraphs as a hint to look at first, never as an instruction to load
+(`hooks/tezgah_skill_pick.py:41-75` is the whole configuration, wired into
+`context_for` at `hooks/tezgah_context.py::context_for`). Measured cost of the line
+itself: 305-317 characters, about 78 tokens of prompt. Measured cost of the
+judgement: one call per unanswered prompt, 909-915 input tokens, 0.77-0.81 s,
+$0.000038 at $0.042/1M on three live judgements. It is OFF UNLESS ARMED -
+`skill-suggest-on` in `~/.config/tezgah`, the same place the kill switches live -
+because a labelled set of 28 prompts through an independent chooser was measured
+at 0 of 20 wrong with no hint at all, so the line's benefit on this 13-skill
+roster is unproven while its cost is measured; arming it is a decision the user
+makes, and an unarmed install asks nothing. It changes nothing else - no
+credential, a `none` answer, a slash command, a failed or stalled call, or the
+absence of the arming file appends no bytes at all, and the same prompt in one
+session is never paid for twice (`tests/test_skill_pick.py`). The host's own
+roster text is left untouched: that is what a session matches on and what its
+prefix cache covers, which is the whole reason the upstream recipe keeps it.
+
+`context_for(event, …)` is the one dispatcher (`hooks/tezgah_context.py::context_for`):
+`session_start`/`post_compact` build core plus live state, `user_prompt` builds
+the reminder, whatever was armed and any skill hint, `subagent_start` builds a short brief
+(`hooks/tezgah_context.py::context_for`). Outside every configured root it returns `None`
+(`hooks/tezgah_context.py::context_for`). A host whose static always-on file already
+carries the core passes `with_core=False` so the session does not pay for the
+contract twice (`hooks/tezgah_context.py::context_for`); a delegated agent gets
+`subagent_core()`, which keeps every always-on label and its opening sentence -
+two where the operative clause is the second, counted by `BRIEF_SENTENCES`
+(`hooks/tezgah_context.py::BRIEF_SENTENCES`) and cut from CORE's own text - and
+carries the two always-on blocks that are not labelled rules - the on-demand
+pointer line and the kill-switch list - in its header, because its header claims
+every rule is in force and a delegate that cannot name a switch cannot tell its
+caller how to disarm one (`hooks/tezgah_context.py::subagent_core`).
+
+One block on those two events is not a standing rule but the live turn state.
+`session_start` and `post_compact` also build `resume_state`: a plan's
+`## State` and `## Next`, the branch's last three commits, the newest
+`verify_ok`/`verify_fail` the session ledger holds, and the files the last turn
+changed. The plan named is the one the checked-out `plan/...` branch owns, and
+when the checkout owns none the lowest-id open plan is offered as what it is -
+`open plan NNN (not this branch)` - because another plan's Next read as the
+active one would invent a task. It is what a session that compacts, or resumes the next morning, would
+otherwise lose - the contract, the plans and the lessons arrive, but not what the
+turn was doing. It is written as a state of the world and never as an order. Each
+part is silent when its fact is unknown and the block is left out whole when
+every part is empty. On Claude it reaches the model through SessionStart, which
+fires again as `SessionStart:compact` after a compaction and delivers its
+`additionalContext`. It does NOT go out on PostCompact: a real compaction on
+Claude Code 2.1.283 showed the host rejecting a PostCompact envelope
+("Hook JSON output validation failed - hookSpecificOutput.hookEventName:
+expected one of ...") and printing the raw JSON into the transcript as a failed
+hook, so `hooks/projects-auto-init.py` builds the block on that event - which is
+where the compaction is recorded - and prints nothing.
+
+The same event is where a compaction is recorded rather than only answered. When
+the host hands the PostCompact payload a summary - Claude's `compact_summary`,
+the text the model is about to receive - the shared funnel writes one ledger row
+holding the summary's length, a 12-hex digest of it, the host's `trigger`
+(`manual` or `auto`) and how many of the constraint lines tezgah injects (the
+pointer line, the active plan's line when the repo keeps an open plan, and each
+constraint the user issued this session) the summary still carries, out of how
+many were injected. The text itself is
+never stored: the summary is the whole conversation by proxy and the ledger is a
+redacted channel, so a row must not be readable as prose. The count is a report
+and never a refusal - a compaction that dropped a rule is a finding to report,
+not a turn to block - and `tezgah-status --counters` folds the rows into
+`compactions`, `compact_chars` and `compact_constraint_rate`
+([evidence.md](evidence.md#the-kinds-by-what-reads-them)).
+
+A user constraint is the clause a prompt states it in: "don't touch
+hooks.json", "ask before pushing", "README'ye dokunma", "bana sormadan push
+etme". A closed set of imperative shapes matches it (`CONSTRAINT_SHAPES`,
+`hooks/tezgah_context.py::CONSTRAINT_SHAPES`, read by `user_constraints`,
+`hooks/tezgah_context.py::user_constraints`). The turn stamp keeps the clause
+from the shape to its sentence's end, redacted and cut to 120 characters, and
+never the prompt. It keeps the five newest. A shape that starts inside quotes,
+inline code, a fenced block or a `>` line does not count. A quoted object after
+a plain "don't touch" does. The recogniser skips a prompt over 12,000
+characters (`CONSTRAINT_PROMPT_MAX`, `hooks/tezgah_context.py::CONSTRAINT_PROMPT_MAX`).
+Pasted material is not the user's constraint. `post_compact` and `session_start`
+restate the clauses as one block
+(`pinned_block`, `hooks/tezgah_context.py::pinned_block`). The compaction count
+looks for each clause's object phrase, the words a paraphrasing summary keeps
+(`constraint_needle`, `hooks/tezgah_context.py::constraint_needle`). The shapes are
+precise rather than complete. `tests/constraint-fixtures.md` lists the real
+prompts the shapes ran on, the misses and the known false positives.
+
+One per-turn line is not a rule but a check on the turn's own evidence. When the
+ledger says every check that passed in this session ran in a scratch or stand-in
+path - `/tmp/`, `/var/folders/`, `$TMPDIR`, or a path segment naming a
+`fixture`/`fake`/`stub`/`sample`/`demo` (`SCRATCH_PATH`,
+`hooks/tezgah_integrity.py::SCRATCH_PATH`; `scratch_evidence`,
+`hooks/tezgah_integrity.py::scratch_evidence`) - the turn is told the command and the
+rule: evidence from a scratch path is evidence about the code path, so a claim
+about the running system needs a check that ran against it (`SCRATCH_REMINDER`,
+`hooks/tezgah_context.py::SCRATCH_REMINDER`, appended at `hooks/tezgah_context.py::context_for`).
+It is a reminder and not a block because whether a scratch script exercises the
+real system is not decidable from the command; one passing check against a real
+path makes the reader answer `None`, so a session that also ran the real thing is
+never told this; and a ledger with no such row costs no bytes. `verify-off` drops
+it with the integrity rule it restates.
+
+The on-demand contract also carries detail the core has no budget for. One is
+the review rule: a change with an executable oracle - a checker, a gate rule, a
+parser - is reviewed by four direction-led reviewers whose every claim is built
+as a fixture and run before it counts, a tentative default measured on two
+research lines with a written flip; everything else keeps one fresh reviewer
+(`skills/tezgah-contract/SKILL.md:503-527`).
+
+## Composition order of the always-on core
+
+Paragraphs are concatenated in the order they appear in `CORE` and identified by
+the bold label each starts with (`CORE_RULES`, `hooks/tezgah_context.py::CORE_RULES`).
+That order, with the line each label sits on in `hooks/tezgah_policy.py`:
+`**{REPLY_LANG}, BLUF.**` :637, `**Ponytail (minimal code).**` :645, `**Output shape:
+ADHD-friendly.**` :656, `**Deliver the whole ask; never the shortcut.**` :670,
+`**Integrity: evidence, or "doğrulanmadı".**` :684, `**Loop discipline.**` :700,
+`**Spec before building.**` :709 *(conditional)*, `**Lessons ledger: stop
+repeating mistakes.**` :723, `**Code discovery: graph first.**` :731
+*(conditional)*, `**Consult before irreversible.**` :740 *(conditional)*,
+`**Research: route it to OpenResearch.**` :756 *(conditional)*, `**Product
+analysis: five axes, one evidence class per finding.**` :772 *(conditional)*,
+`**No AI attribution, ever, on any host.**` :805, `**Identifiers and messages
+stay English.**` :815, `**Session scope: the user's repo, not tezgah.**` :821,
+`**Kill switches:**` :837. The first label renders as `**Turkish, BLUF.**` under
+the default `reply_lang`.
+
+`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the five
+conditional paragraphs and appends `POINTERS` (`hooks/tezgah_policy.py::POINTERS`):
+one line each saying the rule exists and where its full text lives — spec-first,
+a second opinion, OpenResearch routing, product analysis, the code graph, and the
+per-repo design contract `bin/tezgah-design` checks a UI change against (the one
+pointer with no conditional paragraph behind it, because the Stop rule's `no
+ui_ok` class is what asks for the check). That is
+what a host with no prompt-time hook writes into a static file: opencode's
+`~/.config/tezgah/opencode-contract.md` (`bin/tezgah-setup::OPENCODE_CONTRACT`) and omp's
+managed `RULES.md` (`bin/tezgah-setup::STATIC_RULES`). Claude gets it from the
+managed block in `~/.claude/CLAUDE.md` (its global memory file, and the reason
+its session-start hook drops the core: `TEZGAH_CORE_IN_FILE`) and from
+`output-styles/tezgah.md` where a build loads plugin output styles
+(`output-styles/tezgah.md:11-12`); Codex gets it from the managed block in its
+global instructions file; Cursor receives the same core from its session-start
+hook (`hosts/cursor/hook.py:5`, `hosts/cursor/hook.py::dispatch`). `core_for()`
+(`hooks/tezgah_context.py::core_for`) is that text with the kill-switch filtering
+applied, and it also returns the names of the switches that fired.
+
+## What each always-on rule is for
+
+- **Turkish, BLUF.** Every user-facing reply is Turkish even when the prompt is English, outcome first; code, commits, docs and subagent prompts stay English. That is the default. `reply_lang` in `~/.config/tezgah/config.json` picks another: `tr`, `en` or `any`. `tezgah-setup --install --reply-lang` sets it, and the label follows it. The value is the switch. The Stop rule checks the language only under `tr`: under `en` and `any` it judges none.
+- **Ponytail (minimal code).** Take the laziest rung that holds (YAGNI → reuse → stdlib → platform → installed dependency → one line), never simplify away validation, error handling or security. A non-default level rides the reminder (`hooks/tezgah_context.py::_pony_level_line`).
+- **Output shape: ADHD-friendly.** The action or answer is the first line, multi-step work is a numbered list whose position is restated, an estimate is in concrete units. Two upstream rules were rewritten rather than imported verbatim because they collided with rules already in force: the state restatement points at the todo list instead of duplicating it, and a time estimate can no longer be read as a measurement.
+- **Deliver the whole ask; never the shortcut.** The request is a floor: no cheaper stand-in, no silent scope cut, no token gesture reported as done.
+- **Integrity: evidence, or "doğrulanmadı".** A done/tested claim holds only if the check ran in this session and its output was seen; the mechanical half is enforced by [gate.md](gate.md).
+- **Loop discipline.** Never repeat an identical failing command; three attempts is the ceiling, then report what is still unknown.
+- **Lessons ledger: stop repeating mistakes.** `.tezgah/lessons.md` lines are standing constraints; the recent ones are injected at session start, and up to three older ones a prompt shares words with ride that turn, each once per session when the host sends a session id (a compaction resets that, because the compacted context no longer holds them; without an id every matching turn carries them). Write a line rule first, `<rule> - <incident>` (`LESSON_SEPARATOR`, `hooks/tezgah_context.py::LESSON_SEPARATOR`). The session block counts the shown lines that do not open with their rule. A line ending `|| enforced_by: <rule|test>` leaves both blocks while that gate rule or test is on (`hooks/tezgah_lessons.py::lines`). That one reader serves the context, the gate and the CLI. It cuts that clause, a `|| check: ...` clause and an `@<sha> <path>` stamp off each line (`hooks/tezgah_lessons.py::parse`). None of them changes the key, the per-turn digest, the cut or the ranking. The gate records a line written after untrusted text in the same turn as a `lesson_tainted` row ([evidence.md](evidence.md)). That line still rides both blocks, behind a per-line data label (`hooks/tezgah_context.py::LESSON_TAINTED`). ADR 010 makes it a row, never a refusal. `bin/tezgah-lessons` proposes rewrites, merges and retirements, and never writes the file.
+- **No AI attribution, ever, on any host.** Nothing persisted or published may name a model, vendor or "AI" as author, co-author, generator or helper; one already in pushed history is reported.
+- **Identifiers and messages stay English.** A branch, a plan slug, a commit subject, a PR or issue title is in the repository - often a public one - from the moment it exists, so the gate refuses one that is not English - any non-ASCII letter, or a Turkish word from a curated list - and names the English to write instead (`hooks/tezgah_policy.py::CORE`, [gate.md](gate.md#language-an-identifier-or-message-that-is-not-english)). The word list behind it is a heuristic, not a language detector, and the rule says so where it refuses.
+- **Session scope: the user's repo, not tezgah.** The session never maintains tezgah itself; a missing capability is one line plus the documented fallback.
+- **Kill switches.** The switch list itself, so a session can tell the user how to disarm a rule it is asked to ignore; pinned against the shipped skill by `tests/test_skills.py::SkillStandards`.
+
+## Which mechanism enforces each always-on rule
+
+`tezgah-status --enforcers` prints one row per always-on rule. A row names the
+gate rules (`gate:`) and Stop classes (`stop:`) that refuse on the rule. It
+also names the shape flags (`flag:`) that only record it, or says `none`. The
+rows come from the bold heads of `CORE`. The links come from the code
+(`bin/tezgah-docs::enforcer_links`). An enforcer links to a rule when its name
+is the rule's `CORE_RULES` key. It also links when a switch guards it and that
+switch's branch of `hooks/tezgah_context.py::switches` drops the rule's
+paragraph. A Stop class with no switch of its own rides the Stop hook's
+`verify-off`. The code cannot state four links, so
+`bin/tezgah-docs::HAND_LINKS` writes them. They are `explorer` for graph-first,
+`retry` for loop discipline, `placating opener` for the Deliver rule, and the
+shape flags for the output-shape rule. The report also lists the enforcers tied
+to no always-on rule, such as `task`, `secret` and `plan`.
+
+Each enforcer shows its guards in brackets: the switches and environment
+conditions of the `if` tests around it (`bin/tezgah-docs::_guarded_returns`).
+The switch a whole hook reads first, `pretooluse-off` or the Stop hook's
+`verify-off`, is not shown. A row's status is one of four:
+
+- `enforced`: at least one refusing enforcer stays armed while the rule's text
+  is in force.
+- `partial`: every refusing enforcer has a guard that can remove it while the
+  text stays, or the table below names a part nothing covers.
+- `records`: only shape flags, which refuse nothing.
+- `prose-only`: no enforcer at all.
+
+The table below records why a rule is prose-only, and which part of a partial
+rule no enforcer covers. `bin/tezgah-docs --citations` and
+`tests/test_enforcers.py` fail on a prose-only or records-only rule with no
+row, and on a row naming no rule. A coverage row exists only where someone
+reviewed the gap, so `enforced` says a refusal exists, not that it covers every
+sentence of the rule.
+
+| rule | decision |
+|---|---|
+| exec | Only the reply language is refused, and only under `reply_lang` `tr`. Answer-first (BLUF) has no mechanism. |
+| fidelity | Only the placating opener is refused, and only while the output-shape switches are on. Delivering the whole ask has no mechanism. |
+| loop | Only an identical repeat is refused, under `verify-off`. Re-running a check that already passed is not refused. |
+| ponytail | no decision |
+| spec | no decision |
+| lessons | Owner decision ADR 010 (2026-10-05): a tainted lesson costs a row, never a refusal. |
+| consult | The owner removed the consent rule on 2026-09-26 ([gate.md](gate.md#what-the-gate-deliberately-does-not-catch)). The per-turn reminder carries the clause instead. |
+| research | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. |
+| product | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. The product rule is the research route. |
+| scope | no decision |
+
+## Arming the conditional paragraphs, and the per-turn reminder
+
+`PROMPT_HINTS` (`hooks/tezgah_context.py::PROMPT_HINTS`) is one compiled pattern per key
+— `spec`, `consult`, `research`, `product`, `graph` — and `classify_prompt()` returns the keys
+a prompt matches (`hooks/tezgah_context.py::classify_prompt`). On that turn only, the
+matching paragraphs are appended after the reminder
+(`hooks/tezgah_context.py::context_for`); a session that never asks such a question
+pays the one-line pointer instead. The patterns carry Turkish stems because the
+user writes Turkish, and a plain prompt arms nothing. The same prompt arms the
+same rules on every host (`tests/test_context.py::ArmingConformance.test_all_hosts_arm_the_same_rules`) and each advisory
+rule keeps a pointer line in the always-on text (`tests/test_context.py::ArmingConformance.test_every_advisory_rule_has_an_always_on_pointer`).
+
+`PROMPT_REMINDER` is the compact restatement of the invariants. It stays
+inside the `<harness-reminder>` envelope the hosts and
+tests look for (`hooks/tezgah_policy.py::PROMPT_REMINDER`), with its `{PONY_LEVEL}` slot naming a non-default ponytail level
+(`hooks/tezgah_context.py::_pony_level_line`). It names three conditional rules
+nowhere: spec, graph and research reach a turn through their armed paragraph.
+Consult keeps its short clause. A terse irreversible ask ("push it to main")
+arms no paragraph, and no gate enforces the rule. The session-start text ends with the pointer
+telling the model to load `tezgah-contract` for the deep detail
+(`hooks/tezgah_context.py::context_for`), whose two appendixes apply only on a machine
+missing the code graph or every consult option (`hooks/tezgah_policy.py::NO_GRAPH`, `hooks/tezgah_policy.py::NO_CONSULT`).
+
+## How a rule is disarmed
+
+A kill switch removes the rule's text, not just a status mark
+(`hooks/tezgah_context.py::core_split`). `off()` checks `~/.config/tezgah` and the
+legacy `~/.claude` (`hooks/tezgah_paths.py::OFF_DIRS`, `hooks/tezgah_paths.py::off`); the drop itself
+happens in `core_split()`.
+
+The session latches a switch (`hooks/tezgah_paths.py::latch`). A hook that knows
+its session binds the session's ledger first
+(`hooks/tezgah_integrity.py::bind_session`). From then on `off()` ignores a
+switch file whose ctime or mtime is newer than the ledger's first row. The agent
+under the rules writes files too. Without the latch, a switch it made mid-session
+would disarm the rule that judges it. The check reads ctime: `touch -t` sets
+mtime back, and nothing sets ctime back. A switch made mid-session counts in that session in
+three cases:
+
+- the user's prompt names it as a word (`verify-off`). `note_turn` writes an
+  `authorized` row, and the switch counts from that turn on. While a tool call
+  is in flight it writes none, and marks the turn row `inflight`
+  (`hooks/tezgah_integrity.py::_in_flight`). A host hands its prompt hook a
+  prompt between calls. An unanswered call older than ten minutes no longer
+  counts, since a host writes no answer for a call the user interrupted.
+- it is the stand-down `tezgah-setup --uninstall --full` writes into
+  `pretooluse-off` (`hooks/tezgah_paths.py::STAND_DOWN`).
+- it appeared within the first row's second, because the row's `ts` holds whole
+  seconds.
+
+Otherwise a switch made mid-session counts from the next session on. A CLI and
+a hook with no session id bind nothing and read the file alone, as before. The
+opencode plugin answers the same way (`off(name, sessionID)`). A prompt match is
+a keyword match, not intent: "don't touch `verify-off`" names the switch too.
+
+| Switch file | Rule it removes | Where the drop is implemented |
+|---|---|---|
+| `exec-mode.off` | `**{REPLY_LANG}, BLUF.**` | `hooks/tezgah_context.py::switches` |
+| `ponytail-auto.off` | `**Ponytail (minimal code).**` | `hooks/tezgah_context.py::switches` |
+| `adhd-off` | `**Output shape: ADHD-friendly.**` | `hooks/tezgah_context.py::switches` |
+| `spec-off` | `**Spec before building.**` | `hooks/tezgah_context.py::switches` |
+| `verify-off` | `**Integrity: evidence…**`, and the per-turn evidence-scope line with it | `hooks/tezgah_context.py::switches`, `hooks/tezgah_context.py::context_for` |
+| `consult-off` | `**Consult before irreversible.**` | `hooks/tezgah_context.py::switches` |
+| `research-off` | `**Research: route it to OpenResearch.**` | `hooks/tezgah_context.py::switches` |
+| `orchestrate-off` | the orchestration section of the on-demand skill (there is no core paragraph) | `hooks/tezgah_context.py::switches` disables it, `hooks/tezgah_context.py::context_for` injects "Orchestration is off", and the skill-ignore note is `hooks/tezgah_context.py::context_for` |
+| `reminder-off` | the per-turn reminder | `hooks/tezgah_context.py::context_for` returns `None` |
+| `judge-off` | the judgement seam: the snapshot triage, the docs page fallback and the skill hint | `hooks/tezgah_judge.py::available` — `available()` is asked before any call, so an armed switch makes no request at all |
+| `triage-off` | the snapshot triage alone (`bin/tezgah-triage`), leaving the docs fallback and the skill hint armed | `bin/tezgah-triage::off_reason` — `off_reason()` answers this switch before the seam's, so the analyze-app loop reads the tree instead of paying for a judgement |
+| `docs-judge-off` | the docs page fallback alone (`bin/tezgah-docs`), leaving the triage and the skill hint armed | `bin/tezgah-docs::off` — `off()` answers this switch first, so a query the index cannot place is ranked by shared words instead (`ranked`), and exits 1 only when no page shares one |
+| `lang-off` | `**Identifiers and messages stay English.**` | `hooks/tezgah_context.py::switches` drops the paragraph; the gate's own check reads the same switch (`hooks/tezgah_gate.py::decision`) |
+| `pretooluse-off` | the gate's denials, not a rule | [gate.md](gate.md) |
+| `.no-ponytail` | `**Ponytail (minimal code).**` | `hooks/tezgah_context.py::switches` |
+| `.no-adhd` | `**Output shape: ADHD-friendly.**` | `hooks/tezgah_context.py::switches` |
+| `.no-graph` | `**Code discovery: graph first.**` | `hooks/tezgah_context.py::switches` |
+| `.no-lessons` | `**Lessons ledger: stop repeating mistakes.**` | `hooks/tezgah_context.py::switches`, and neither the session's lessons block (`hooks/tezgah_context.py::lessons`) nor the per-turn one (`relevant_lessons`) is injected |
+
+The last four are per-repo [marks](glossary.md#per-repo-mark), read by
+`repo_marks()`, walking up to the enclosing [root](glossary.md#root)
+(`hooks/tezgah_context.py::repo_marks`). Every switch that fired is named back to the
+session at start (`hooks/tezgah_context.py::context_for`) and per turn (`hooks/tezgah_context.py::context_for`), with the instruction to
+ignore the matching section in `tezgah-contract` — that skill is loaded
+separately and would otherwise re-arm the rule. `tezgah-adhd off` writes the same
+channel as the file (`bin/tezgah-adhd::SWITCH`); the ponytail *level* is not a switch.
+
+`**Deliver the whole ask**`, the sycophancy ban and the attribution ban are
+invariants: no switch touches them, and `tests/test_context.py::KillSwitchEnforcement.test_fidelity_and_the_sycophancy_ban_are_invariants` asserts
+they survive every other switch being off.
+
+## Adding a rule
+
+1. Write the full text as a constant in `hooks/tezgah_policy.py`.
+2. If not every session should pay it, add the key to `CONDITIONAL_KEYS`
+   (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`), a pattern to `PROMPT_HINTS`
+   (`hooks/tezgah_context.py::PROMPT_HINTS`) and a line to `POINTERS`
+   (`hooks/tezgah_policy.py::POINTERS`); the two halves are asserted together
+   (`tests/test_context.py::ArmingConformance`).
+3. Put the paragraph in `CORE` with its bold label and add the `(key, label)`
+   pair to `CORE_RULES` (`hooks/tezgah_context.py::CORE_RULES`). The label is the
+   contract: `core_split()` matches paragraphs by it and `subagent_core()` builds
+   the brief from it, so a label edit fails loudly instead of silently dropping
+   a rule.
+4. If the rule names a kill switch, add the drop to `core_split()` and list the
+   switch in the `**Kill switches:**` paragraph (`hooks/tezgah_policy.py::CORE`).
+5. Mirror the full text into `skills/tezgah-contract/SKILL.md`, and regenerate
+   `output-styles/tezgah.md` from a fresh Python process when the paragraph is
+   always-on — a warm interpreter serves a stale `CORE`.
+6. Last step, the tests that pin it: add the label to `KillSwitchEnforcement`
+   (`tests/test_context.py::KillSwitchEnforcement`) and, for a conditional rule, to the
+   `ArmingConformance` label map (`tests/test_context.py::ArmingConformance`); then run the mirror pair —
+   `OutputStyleMirrorsCore.test_body_is_the_always_on_core`
+   (`tests/test_context.py::OutputStyleMirrorsCore`) and
+   `ContractParity.test_every_rule_and_heading_in_the_contract_reaches_the_skill`
+   (`tests/test_setup.py::ContractParity.test_every_rule_and_heading_in_the_contract_reaches_the_skill`).
+
+## The two copies that must stay in step
+
+| Copy A | Copy B | Test that fails when only one changed |
+|---|---|---|
+| `CORE`, via `always_on_core()` | `output-styles/tezgah.md` (Claude's hookless duplicate) | `tests/test_context.py::OutputStyleMirrorsCore` |
+| the long-form blocks of `hooks/tezgah_policy.py` (`EXEC`, `CONSULT`, …) | `skills/tezgah-contract/SKILL.md` | `tests/test_setup.py::ContractParity` |
+
+Drift between the source and what a host reads is caught on the rendered side:
+`~/.config/tezgah/contract.sha256` holds one `<sha>  <path>` line per rendered
+artifact (the managed blocks of `CLAUDE.md`, `AGENTS.md`, `RULES.md`, and
+opencode's contract and skill routers), and `--report` compares each artifact's
+bytes with a fresh render. That notices that the text a session gets changed;
+`ContractParity` is what notices that only one of the pair above changed, which
+is the drift that actually happens (`tests/test_setup.py::ContractParity`).
+`tezgah-setup --refresh` re-renders every armed host's artifact, not only
+opencode's, and drops the paragraph of any global kill switch that is on
+(`refresh_contract`, `bin/tezgah-setup::refresh_contract`).
+
+The skill may hold more than the contract. Two rules live only in the skill
+today. The graph rule says an empty caller list is not proof that a change is
+safe. The gate section adds evidence adequacy: a check counts only if it can
+fail on the claim it backs. `ContractParity` reads one way, from the
+contract to the skill, so these extra rules pass it. The generated reviewer
+brief carries the same caller-list floor (`hooks/tezgah_agents.py`), and
+`tests/test_agents.py` asserts it on every host.
+
+## When the injected text grows too large
+
+Each event has a byte budget: `session_start` and `post_compact` 12000,
+`user_prompt` 6000, `subagent_start` 5500, anything else 12000
+(`hooks/tezgah_context.py::CONTEXT_BUDGET`). The rationale and the measured
+sizes sit beside it. A fixture repo builds 10066 B at `session_start` and about
+5150 B at `subagent_start`. A `user_prompt` that arms all five conditional rules
+for the first time builds 7503 B. That is over its budget on purpose: an armed paragraph
+is never dropped, and every later match in the session pays one line. The
+budget is a byte count, not a token estimate.
+
+Over budget, `budgeted()` gives up blocks in `DROP_ORDER`, lowest value
+first — the text another surface already carries (project knowledge, the
+sibling-checkout line, lessons), the skill hint (a suggestion, never an
+instruction), the per-turn relevant lessons and the plan table first, then the tooling-availability lines and the live graph
+glance, then the resume state (it outlives those because it is the only one that
+says what this session was doing, and it still yields to a rule), then the
+evidence-scope warning, the task phase, the delta, and the skill pointer last
+(`hooks/tezgah_context.py::DROP_ORDER`). Any key absent from that tuple is
+never dropped: the core, the reminder, the armed paragraphs and the user's pinned
+constraints are the rules, and
+a budget able to spend them would turn bloat into rule loss. The note naming what
+went is appended after the count, so the sentence explaining the trim cannot force
+another one, and it says so when what remains is still over the limit
+(`_drop_note`, `hooks/tezgah_context.py::_drop_note`); the drop is logged to `~/.cache/tezgah/context-drops.log`, truncated
+to its last 200 lines (`hooks/tezgah_context.py::log_drop`). Its row says
+`kind=omitted`. One block shrinks before it goes. The per-turn relevant lessons
+keep their first lesson (`SHRINK`, `hooks/tezgah_context.py::SHRINK`), a row that says
+`kind=truncated`. The budget drops them only when that still does not fit. The
+session remembers only the lessons a turn still shows.
+
+## Source of truth
+
+- `hooks/tezgah_policy.py` — `CORE`, `CONDITIONAL_KEYS`, `POINTERS`, `PROMPT_REMINDER`, and the long-form blocks they are built from
+- `hooks/tezgah_context.py` — `CORE_RULES`, `PROMPT_HINTS`, `classify_prompt`, `core_split`, `core_for`, `always_on_core`, `subagent_core`, `BRIEF_SENTENCES`, `armed_again`, `ARMED_RESURFACE`, `user_constraints`, `constraint_lines`, `context_for`, `repo_marks`, `CONTEXT_BUDGET`, `DROP_ORDER`, `budgeted`, `log_drop`
+- `hooks/tezgah_paths.py` — `OFF_DIRS`, `off()`, the ponytail level path; `bin/tezgah-setup` — `install_common`, `opencode_contract`, `refresh_contract`, the omp `RULES.md` writer, `--refresh`; `bin/tezgah-adhd` — the CLI that writes the `adhd-off` switch
+- `skills/tezgah-contract/SKILL.md` — the on-demand full contract; `output-styles/tezgah.md` — Claude's always-on duplicate of the core
+- `tests/test_context.py`, `tests/test_setup.py`, `tests/test_skills.py` — the label, kill-switch, budget and mirror tests

package/docs/environment.md

@@ -0,0 +1,141 @@
+# Environment variables
+
+Every environment variable tezgah reads, in one table per concern: what reads it,
+what it defaults to, and what setting it changes. For someone pinning an install
+in CI, repointing an endpoint in a test, or wondering why a hook ignores the
+Python on PATH. A variable not on this page is not read by tezgah; one read by a
+host and only passed through (such as `HOME` or `PATH`) is left out.
+
+Nothing loads a `.env` file: a variable reaches tezgah only through the
+environment of the process that started it - the shell, the host, or the host's
+hook runner. A hook's environment is fixed when the host starts it, so a change
+takes effect in the next session, not the running one.
+
+The per-flag installer reference is in [operations](operations.md#installer-flags);
+the kill switches are files, not variables, and live in
+[contract](contract.md).
+
+## Install, upgrade and packaging
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_PREFIX` | `packaging/install.sh:26`, `packaging/upgrade.sh`, `packaging/install.ps1`, `bin/tezgah-setup::default_prefix` | `$XDG_DATA_HOME/tezgah`, else `%LOCALAPPDATA%\tezgah` on Windows, else `~/.local/share/tezgah` | Where the artifact install unpacks its versions and the `current` link; `tezgah-setup` treats it as the install prefix. |
+| `TEZGAH_VERSION` | `packaging/install.sh`, `packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh:70` | the newest GitHub release; `build.sh` falls back to `VERSION`/the CHANGELOG | The version to install, or the version `build.sh` stamps when `--version` is not given. |
+| `TEZGAH_REPO` | `packaging/install.sh:12`, `packaging/upgrade.sh`, `packaging/install.ps1` | `r1z4x/tezgah` | The GitHub repository releases are fetched from. |
+| `TEZGAH_UPDATE_URL` | `hooks/tezgah_update.py` | `https://github.com/<TEZGAH_REPO>/releases/latest` | Where the daily release check reads the newest tag: from the redirect, or from a JSON body's `tag_name`. Tests point it at a `file://` fixture. |
+| `TEZGAH_UPDATE_CHECK` | `hooks/tezgah_update.py` | unset | `0` turns off the update chip and the daily check. The test suite sets it, so no test reaches the network. |
+| `TEZGAH_DIST` | `packaging/upgrade.sh:74`, `packaging/install.ps1` | unset: the release URL | A directory holding `tezgah-<V>.tar.gz` and its `.sha256` (what `build.sh --out` writes) used instead of the release download; CI exercises the real fetch-verify-unpack path with it. |
+| `TEZGAH_GH` | `packaging/upgrade.sh` | `gh` on PATH | The `gh` that checks the tarball's build provenance (`gh attestation verify`). A path that does not exist reads as no `gh`: the upgrade prints `provenance not checked` and goes on. Tests point it at a stand-in. |
+| `TEZGAH_NO_DEPS` | `bin/tezgah-setup::main` | unset | Any value but empty or `0` is `--no-deps`: the optional tools (codegraph, orx, host CLIs) are not installed. |
+| `TEZGAH_NO_SYMLINK` | `bin/tezgah-setup::symlinks_refused` | unset | Any value but empty or `0` writes the copy layout a machine without symlinks gets, on a machine that has them. |
+| `TEZGAH_PYTHON` | `hooks/tezgah_paths.py::python_cmd`, `bin/tezgah.js`, `bin/tezgah-dsh.cmd`, `hooks/hooks.json`, `hosts/*/hooks.json`, `hosts/omp/tezgah-hook.ts.in`, `hosts/opencode/plugins/tezgah.js`, `packaging/build.sh` | this process's interpreter, then `python3`/`python`/`py` on PATH | The interpreter every host hook and the npm shim start; pin it when the right Python is not first on PATH. |
+
+## Where tezgah and the hosts keep state
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_ROOTS` | `hooks/tezgah_paths.py::roots`, `bin/tezgah-setup`, `hosts/opencode/plugins/tezgah.js` | `roots` in `~/.config/tezgah/config.json`, else `~/Projects` | The directories tezgah is armed over, `os.pathsep`-separated (`;` on Windows, the opencode plugin included); it outranks the config file. |
+| `XDG_CONFIG_HOME` | `hooks/tezgah_paths.py::CONFIG_DIR`, `bin/tezgah-doctor`, `bin/tezgah-dsh.cmd`, `hosts/opencode/plugins/tezgah.js` | `~/.config` | Parent of tezgah's config dir (kill switches, `bin/` links, config) and of opencode's. |
+| `XDG_DATA_HOME` | `bin/tezgah-setup::default_prefix`, `packaging/install.sh`, `packaging/upgrade.sh` | `~/.local/share` | Parent of the default install prefix. |
+| `XDG_CACHE_HOME` | `hooks/tezgah_apps.py::ARTIFACTS` | `~/.cache` | Parent of the app-analysis artifact dir. |
+| `TEZGAH_DEBUG` | `hooks/tezgah_guard.py` | unset | `1` makes every hook process append one line to `<cache>/debug.log` (host, script, each guarded call's outcome or exception class, elapsed ms; no prompt or tool text), created 0600 and swept by `tezgah-doctor --clean`. Off, it costs one environment read. |
+| `TEZGAH_FALLBACK_CACHE` | `hooks/tezgah_paths.py::fallback_cache` | `<tempdir>/tezgah` | The cache a sandboxed hook writes when its normal cache dir is denied; a test knob. |
+| `TEZGAH_ARTIFACTS` | `hooks/tezgah_apps.py::ARTIFACTS` | `$XDG_CACHE_HOME/tezgah/apps` | Where `analyze-app` screenshots, traces and tree dumps land. |
+| `TEZGAH_NO_EXCLUDE` | `hooks/tezgah_agents.py::ensure_exclude` | unset | `1` stops tezgah adding its generated-agent dirs to the repository's `.git/info/exclude`. |
+| `CODEX_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | `~/.codex` | The Codex home tezgah installs into and checks; the same variable Codex itself reads. |
+| `DSH_HOME` | `hooks/tezgah_paths.py::HOST_DIRS`, `bin/tezgah-dsh`, `bin/tezgah-dsh.cmd` | `~/.dsh` | The dsh home tezgah installs into, and where `tezgah-dsh` looks for the CLI. |
+| `TEZGAH_OPENCODE_DATA` | `bin/tezgah-setup::OPENCODE_DATA`, `bin/tezgah-doctor` | `~/.local/share/opencode` | opencode's data dir: its session database for `tezgah-doctor` and the installer. |
+
+## Which binary runs
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_CODEGRAPH_BIN` | `hooks/tezgah_paths.py::codegraph_bin` | the config file, then `codegraph` on PATH | The codegraph executable the index and the graph marks use. |
+| `TEZGAH_ORX_BIN` | `hooks/tezgah_paths.py::orx_bin` | `orx` on PATH | The OpenResearch CLI the research rule routes to. |
+| `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table and consult's session-model lookup run. |
+| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`); the test suite points it at a path that does not exist. |
+| `TEZGAH_DSH_BIN` | `bin/tezgah-setup::reconcile_json_servers` | the profile-local entry, then `bin/tezgah-dsh`, then npx | How the installer invokes the dsh CLI. |
+| `TEZGAH_INDEX_BIN` | `bin/tezgah-dsh:19`, `bin/tezgah-dsh.cmd` | `~/.config/tezgah/bin/tezgah-index` | The index worker `tezgah-dsh` warms before it starts dsh. |
+| `TEZGAH_STATUS_BIN` | `hosts/dsh/statusline/lib/index.js:24`, `hosts/opencode/tui/tezgah-tui.tsx` | `~/.config/tezgah/bin/tezgah-status` | The status renderer the dsh status line and the opencode TUI call. |
+| `TEZGAH_CONSULT_CLIS` | `hooks/tezgah_paths.py::consult_options` | unset: every agent CLI on PATH counts | Comma list of the agent CLIs that may count as consult members (empty: none); pins the answer in tests and CI. |
+
+## Index worker
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_INDEX_TIMEOUT` | `hooks/tezgah_index.py::RUN_TIMEOUT` | `600` (seconds) | How long one index attempt may run before its process group is killed. Must be a number. |
+| `TEZGAH_INDEX_RETRIES` | `hooks/tezgah_index.py::RETRIES` | `5` | Attempts the detached index worker makes. Must be an integer. |
+| `TEZGAH_INDEX_RETRY_DELAY` | `hooks/tezgah_index.py::DELAY` | `3` (seconds) | The pause between attempts. Must be a number. |
+
+## Model credentials and endpoints
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first credential; omp also reads it for its own judge. |
+| `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, and omp's `any` family. |
+| `DEEPSEEK_API_KEY`, `INCEPTION_API_KEY` | `bin/consult`, `bin/codegen`, `hooks/tezgah_replay.py::label_model` | `~/.config/deepseek/key`, `~/.config/inception/key` | The `deepseek` and `inception` providers of consult and codegen; `DEEPSEEK_API_KEY` alone is also the replay sheet's `--provider deepseek` rater. |
+| `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic` or `zai` model family, so the model table can pick a row omp will run. |
+| `TEZGAH_TYPESAFE_URL` | `hooks/tezgah_judge.py::endpoint` | `https://api.typesafe.ai/v1/systemone` | Repoints the seam's TypeSafe endpoint (tests). Plain `http` is refused unless the host is this machine; a cross-host redirect is refused. |
+| `TEZGAH_OPENROUTER_URL` | `hooks/tezgah_judge.py::openrouter_url` | OpenRouter's chat-completions URL | Repoints the seam's chat fallback (tests). Plain `http` is refused unless the host is this machine. |
+| `TEZGAH_DEEPSEEK_URL` | `hooks/tezgah_replay.py::_deepseek` | `https://api.deepseek.com/chat/completions` | Repoints the replay sheet's `--provider deepseek` rater (tests). Plain `http` is refused unless the host is this machine. |
+| `TEZGAH_JUDGE_MODEL` | `hooks/tezgah_judge.py::fallback_model` | the cheap `any` row of the models table | The model the seam's chat fallback asks. |
+
+## consult and codegen
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `CONSULT_URL` | `bin/consult::endpoint` | the provider's URL | Repoints every HTTP member. Plain `http` is refused unless the host is this machine (failure class `plain-http`); the bearer token is dropped on a redirect to another host. |
+| `CONSULT_MODELS` | `bin/consult::defaults` | the provider's default list | Comma list of `openrouter` models for the panel. |
+| `CONSULT_JUDGE` | `bin/consult::main` | the recorded referee, else an available member outside the panel | The member that referees, after `--judge`. With none outside the panel a panel member referees and the run prints a note. |
+| `CONSULT_SEED` | `bin/consult::referee_packet` | unset (a fresh shuffle) | Fixes the shuffled order of the anonymised answers the referee reads (tests). |
+| `CONSULT_SESSION_MODEL` | `bin/consult::session_model` | omp's own record of the session model, read only on omp (`OMPCODE`) | The model this session runs on, so the panel skips it. |
+| `OMPCODE`, `CLAUDECODE` | `bin/consult::own_cli` | set by the host | Names the calling host's own CLI, so consult does not ask the session to second-guess itself (omp sets both; `OMPCODE` wins). `OMPCODE` is also what lets consult read omp's session model. |
+| `CODEGEN_URL` | `bin/codegen::ask` | the provider's URL | Repoints codegen's endpoint. Plain `http` is refused unless the host is this machine (`127.0.0.1`, `localhost`); a redirect to another host is refused. |
+| `CODEGEN_MODEL` | `bin/codegen::MODEL` | the cheap `any` row of the models table | The model codegen drafts with. |
+
+## Status line
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `NO_COLOR` | `hooks/tezgah_context.py::color_default`, `hosts/omp/tezgah-hook.ts.in` | unset | Any value renders the status line without ANSI colour. |
+| `TEZGAH_STATUS_COLOR` | `hooks/tezgah_context.py::color_default`, `hosts/omp/tezgah-hook.ts.in` | unset | `0` is the same opt-out as `NO_COLOR`, for tezgah alone. |
+| `TEZGAH_STATUS_ANIMATE` | `hosts/omp/tezgah-hook.ts.in:65` | unset (animated) | `0` keeps omp's status colours and drops the motion. |
+| `TEZGAH_STATUS_HOST` | `statusline.py::HOST` | `claude` | `cursor` renders for Cursor (the same as `--cursor`). |
+| `TEZGAH_STATUS_LEGEND` | `statusline.py:127` | unset | `1` prints the mark legend under the line. |
+
+## Set by tezgah or the host, not by a user
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_SESSION` | `bin/tezgah-status::main`, `bin/tezgah-docs`, `bin/tezgah-route`, `bin/tezgah-triage`, `hosts/omp/tezgah-hook.ts.in` | unset; the omp hook exports it to its shells | The session id `tezgah-docs`, `tezgah-route` and `tezgah-triage` write their ledger rows under, and the id `tezgah-status` lights its "used" marks from when none is passed. |
+| `TEZGAH_CORE_IN_FILE` | `hooks/projects-auto-init.py::core_is_in_a_file`, `hooks/hooks.json` | unset | `1` (set by the Claude plugin's hook rows) drops the core rules from the injection when the host's static file really carries the tezgah block; a file without it falls back to the hook. |
+| `TEZGAH_NESTED` | `hooks/tezgah_integrity.py::_shape_block`, `bin/consult` | unset | Set by consult on the agent CLIs it runs: that session's Stop rule does not fire. |
+| `TEZGAH_CALL_OUTCOME` | `hooks/projects-posttooluse.py::main`, `hosts/dsh/hooks.json` | unset | `none` (dsh's Task rows) records the call's outcome as unknown instead of as a pass. |
+| `CLAUDE_PROJECT_DIR` | `hooks/projects-auto-init.py::main` | the process cwd | The project dir when the hook payload carries no `cwd`. |
+| `PLAYWRIGHT_BROWSERS_PATH`, `LOCALAPPDATA` | `hooks/tezgah_apps.py::_browser_caches`, `bin/tezgah-setup::default_prefix` (`LOCALAPPDATA` only) | Playwright's own cache dirs | Where `analyze-app` looks for an installed browser before it reports one missing; on Windows `LOCALAPPDATA` is also the parent of the default install prefix. |
+
+## Test knob
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_E2E_STRICT` | `tests/e2e_*.py`, `.github/workflows/ci.yml` | unset (a missing prerequisite is a SKIP) | `1` turns an end-to-end script's SKIP into a FAIL; CI sets it. |
+
+## Debugging
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_DEBUG` | `hooks/tezgah_guard.py` | unset (off) | Any value but empty or `0` makes every hook process append one line to `<cache>/debug.log` (created 0600): `<epoch> host=<codex\|cursor\|omp\|claude/dsh> script=<entry script> calls=<core fn>:<answer\|none\|ExceptionClass>,... ms=<elapsed>`. `answer` means the core returned something (a deny reason, a context block, a block decision). No prompt or tool text is written. Off, it costs one environment read. `tezgah-doctor --clean` removes the file once it has gone untouched for `--retention-days` (default 30). |
+
+## Source of truth
+
+`hooks/tezgah_paths.py`, `hooks/tezgah_judge.py`, `hooks/tezgah_models.py`,
+`hooks/tezgah_index.py`, `hooks/tezgah_apps.py`, `hooks/tezgah_agents.py`,
+`hooks/tezgah_context.py`, `hooks/tezgah_integrity.py`,
+`hooks/projects-auto-init.py`, `hooks/projects-posttooluse.py`, `statusline.py`,
+`bin/tezgah-setup`, `bin/consult`, `bin/codegen`, `bin/tezgah-status`,
+`bin/tezgah-doctor`, `bin/tezgah-dsh`, `bin/tezgah.js`, `packaging/install.sh`,
+`packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh`,
+`hosts/omp/tezgah-hook.ts.in`, `hosts/opencode/plugins/tezgah.js`,
+`hosts/dsh/statusline/lib/index.js`. The list was taken by searching the shipped
+code for `os.environ`, `getenv`, `process.env`, `$env:` and `${...}` reads; re-run
+that search after adding a variable and add its row here.