@r1z4x/tezgah 1.9.2 → 1.13.0

package/commands/ponytail.md

@@ -1,12 +1,12 @@
-Run `tezgah-pony $ARGUMENTS` and report the one line it prints.
+Run `~/.config/tezgah/bin/tezgah-pony $ARGUMENTS` and report the one line it prints.
 
 The installed CLI is the source of truth for the level, and it owns the state
 file (`~/.config/tezgah/ponytail.level`) - never edit that file by hand, and do
-not argue for a level: the user's argument is the decision. Resolve the command
-first, because this machine may not have tezgah's bin dir on PATH:
+not argue for a level: the user's argument is the decision. Run the installed path,
+because this machine may not have tezgah's bin dir on PATH:
 
 ```sh
-pony=$(command -v tezgah-pony || echo "$HOME/.config/tezgah/bin/tezgah-pony")
+pony="$HOME/.config/tezgah/bin/tezgah-pony"
 "$pony" $ARGUMENTS
 ```
 

package/docs/architecture.md

@@ -27,7 +27,7 @@ nothing about a host's event names or output envelope.
 | Module | Owns | Point at |
 |---|---|---|
 | `tezgah_context.py` | the one builder of injected text; event normalisation to `session_start`/`user_prompt`/`subagent_start`/`post_compact`; the status segments and the used marks | `hooks/tezgah_context.py:2-7`, `hooks/tezgah_context.py::context_for` |
-| `tezgah_policy.py` | the contract itself, as strings: `CORE`, the conditional paragraphs, the pointer line, the per-turn reminder, and the long-form blocks the on-demand skill mirrors | `hooks/tezgah_policy.py:2-16`, `hooks/tezgah_policy.py::CORE`, `hooks/tezgah_policy.py::CONDITIONAL_KEYS` |
+| `tezgah_policy.py` | the contract itself, as strings: `CORE`, the conditional paragraphs, the pointer line, the per-turn reminder, and the long-form blocks the on-demand skill mirrors | `hooks/tezgah_policy.py:2-18`, `hooks/tezgah_policy.py::CORE`, `hooks/tezgah_policy.py::CONDITIONAL_KEYS` |
 | `tezgah_gate.py` | the tool gate: explorer refusal, the one-time grep nudge, attribution and test-disable denies, loop/retry ceilings | `hooks/tezgah_gate.py:2-91`, `hooks/tezgah_gate.py::decision` |
 | `tezgah_integrity.py` | the evidence ledger, redaction, the anti-shortcut parser and the Stop rule | `hooks/tezgah_integrity.py:2-24`, `hooks/tezgah_integrity.py::note_tool`, `hooks/tezgah_integrity.py::stop_reason` |
 | `tezgah_guard.py` | the one catch around an entry point's call into the core, so a crash costs an envelope rather than a session, and the `crash` ledger row that keeps it countable | `hooks/tezgah_guard.py:2-26`, `hooks/tezgah_guard.py::safe` |
@@ -54,7 +54,7 @@ passes Codex's tool names through a translation table before calling the gate
 the same split in another language: the TypeScript extension is "only the
 bridge" and substitutes the absolute path of
 the Python half (`hosts/omp/tezgah-hook.ts.in:5-7`), whose `handle()` dispatches
-every event (`hosts/omp/hook.py::handle`). Cursor (`hosts/cursor/hook.py:2-40`) and
+every event (`hosts/omp/hook.py::handle`). Cursor (`hosts/cursor/hook.py:2-43`) and
 opencode (`hosts/opencode/plugins/tezgah.js:1-57`) follow the same rule; opencode
 is the one host whose plugin cannot call the core in process, so it shells out
 through `bin/tezgah-context` and `bin/tezgah-capture` instead of copying it

package/docs/citations-baseline.json

@@ -21,13 +21,13 @@
     "unjudged": 2
   },
   "docs/gate.md": {
-    "unjudged": 39
+    "unjudged": 29
   },
   "docs/glossary.md": {
     "unjudged": 12
   },
   "docs/hosts.md": {
-    "unjudged": 62
+    "unjudged": 61
   },
   "docs/layers.md": {
     "unjudged": 14
@@ -36,7 +36,7 @@
     "unjudged": 21
   },
   "docs/skills.md": {
-    "unjudged": 7
+    "unjudged": 9
   },
   "docs/status-line.md": {
     "unjudged": 9

package/docs/clarity-baseline.json

@@ -1,6 +1,6 @@
 {
   "CHANGELOG.md": {
-    "long_sentences": 0,
+    "long_sentences": 1,
     "passive": 2,
     "replace_words": 0,
     "semicolons": 0
@@ -18,7 +18,7 @@
     "semicolons": 9
   },
   "docs/contract.md": {
-    "long_sentences": 42,
+    "long_sentences": 41,
     "passive": 25,
     "replace_words": 0,
     "semicolons": 29
@@ -30,7 +30,7 @@
     "semicolons": 3
   },
   "docs/evidence.md": {
-    "long_sentences": 108,
+    "long_sentences": 112,
     "passive": 55,
     "replace_words": 1,
     "semicolons": 39
@@ -54,7 +54,7 @@
     "semicolons": 14
   },
   "docs/hosts.md": {
-    "long_sentences": 36,
+    "long_sentences": 38,
     "passive": 19,
     "replace_words": 0,
     "semicolons": 18
@@ -83,6 +83,12 @@
     "replace_words": 3,
     "semicolons": 42
   },
+  "docs/orca.md": {
+    "long_sentences": 0,
+    "passive": 0,
+    "replace_words": 0,
+    "semicolons": 0
+  },
   "docs/research.md": {
     "long_sentences": 105,
     "passive": 59,
@@ -90,7 +96,7 @@
     "semicolons": 77
   },
   "docs/skills.md": {
-    "long_sentences": 36,
+    "long_sentences": 35,
     "passive": 18,
     "replace_words": 0,
     "semicolons": 16

package/docs/contract.md

@@ -9,16 +9,24 @@ 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
+host says the same thing (`hooks/tezgah_policy.py:19-20`); path placeholders
 (`{ROOT}`, `{CONSULT_BIN}`, `{ORX_BIN}`, …) are filled at injection time by
 `render()` (`hooks/tezgah_context.py::render`).
+Every tezgah CLI the injected text names is a placeholder in `BIN_TOOLS`
+(`hooks/tezgah_policy.py::BIN_TOOLS`): `{CONSULT_BIN}`, `{CODEGEN_BIN}`,
+`{RESEARCH_BIN}`, `{ROUTE_BIN}`, `{SKILL_BIN}`, `{DESIGN_BIN}`, `{TASK_BIN}`,
+`{PONY_BIN}`, `{ADHD_BIN}` and `{LESSONS_BIN}`.
+`render()` fills each with the installed absolute path, `tezgah_paths.tool(<name>)`.
+A bare `tezgah-pony` in the text failed on a host whose shell PATH lacks
+`~/.config/tezgah/bin`.
+The hookless static copies spell the same path from `~`.
 
 ## The five surfaces
 
 | Surface | Text | Paid |
 |---|---|---|
-| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the six conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
-| conditional paragraph | one of the six 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 |
+| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the seven conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
+| conditional paragraph | one of the seven 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 and the SECTION of it that matches the turn (`skill://<name>:<start>-<end>` plus the absolute path), written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`) when `skill-suggest-on` is armed, else by the model-free section search (`hooks/tezgah_skill_pick.py::section_hint`), default on | only on a turn the judgement answers with a skill, or whose prompt one section covers (each section once per session) |
 | 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 |
@@ -69,10 +77,19 @@ uses no model and is on by default (`hooks/tezgah_skill_pick.py::section_hint`,
 rebuilds only when a SKILL.md's stat moves. The line needs a top section that
 carries 60% of the prompt's distinct content terms, and at least three. It
 names each section once per session and drops the absolute path on omp, whose
-read tool resolves `skill://`. Measured on this machine: 6-15 ms warm, and
-1.36 s for the one cold rebuild over 7 502 sections. The line costs 196-239
-bytes on omp and 245-320 elsewhere. It is not a judgement, so `judge-off` leaves it on,
-and `reminder-off` drops it with the per-turn text. The always-on core also
+read tool resolves `skill://`. On Claude it names the Skill tool's
+`tezgah:<name>`. It also carries the skill's description, which Claude's roster
+cuts for 20 of 21 tezgah skills. For `harness` it names Claude's own
+`workflow-authoring` as the skill it precedes
+(`hooks/tezgah_skill_pick.py::NATIVE_TWIN`). A hint for `i-have-adhd` ends with
+that rule's first-line clause on every host
+(`hooks/tezgah_skill_pick.py::IN_FORCE`). The core states the rule, and replies
+to an adhd ask still opened on a diagnosis. Measured on this
+machine: 6-15 ms warm, and 1.36 s for the one cold rebuild over 7 502 sections.
+The line costs 187-201 bytes on omp, 264-287 on other hosts and 450-483 on
+Claude, plus 231 for the `i-have-adhd` clause. It is not a judgement, so
+`judge-off` leaves it on, and `reminder-off` drops it with the per-turn text.
+The always-on core also
 sends every session to the same search by hand. Run `tezgah-skill <words>`
 before working a topic a skill covers, then read only the returned range.
 
@@ -187,36 +204,43 @@ change with an executable oracle - a checker, a gate rule, a parser - spends the
 same budget. Its round one is four direction-led reviewers, and each claim
 becomes a fixture that runs before it counts. That population is a tentative
 default, measured on two research lines with a written flip
-(`skills/tezgah-contract/SKILL.md:532-563`).
+(`skills/tezgah-contract/SKILL.md:537-568`). With the opt-in `ocr` feature, round
+one also gets an OCR review spec: OCR's file selection, its rule groups and a
+refuter pass. The spec is input to the review, never a verdict
+([operations](operations.md#opt-in-ocr-review-spec-ocr),
+`bin/tezgah-task::print_ocr_spec`). A verdict comes only from a fresh
+reviewer. A host that cannot start one says so and asks the owner. The author
+contests a confirmed finding only with a file:line the reviewer could read. It
+never lowers a severity (`hooks/tezgah_policy.py::EXEC`).
 
 ## 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.**` :713, `**Ponytail (minimal code).**` :722, `**Output shape:
-ADHD-friendly.**` :739, `**Deliver the whole ask; never the shortcut.**` :763,
-`**Integrity: evidence, or a named blocker.**` :778, `**Loop discipline.**` :811,
-`**Spec before building.**` :820 *(conditional)*, `**Lessons ledger: stop
-repeating mistakes.**` :834, `**Code discovery: graph first.**` :842
-*(conditional)*, `**Consult before irreversible.**` :851 *(conditional)*,
-`**Research: route it to OpenResearch.**` :869 *(conditional)*, `**Product
-analysis: five axes, one evidence class per finding.**` :896 *(conditional)*,
-`**No AI attribution, ever, on any host.**` :931, `**Identifiers and messages
-stay English.**` :941, `**Session scope: the user's repo, not tezgah.**` :947,
-``**Workspace: `.tezgah/` only.**`` :958, `**Parallel by default: fan out
-independent items.**` :965 *(conditional)*,
-`**Kill switches:**` :990. The first label renders as `**Turkish, BLUF.**` under
+`**{REPLY_LANG}, BLUF.**` :802, `**Ponytail (minimal code).**` :811, `**Output shape:
+ADHD-friendly.**` :828, `**Deliver the whole ask; never the shortcut.**` :852,
+`**Integrity: evidence, or a named blocker.**` :869, `**Loop discipline.**` :915,
+`**Spec before building.**` :925 *(conditional)*, `**Lessons ledger: stop
+repeating mistakes.**` :939, `**Code discovery: graph first.**` :947
+*(conditional)*, `**Consult before irreversible.**` :956 *(conditional)*,
+`**Research: route it to OpenResearch.**` :974 *(conditional)*, `**Product
+analysis: five axes, one evidence class per finding.**` :1003 *(conditional)*,
+`**Design: UI work reads the design skills.**` :1039 *(conditional)*,
+`**No AI attribution, ever, on any host.**` :1048, `**Identifiers and messages
+stay English.**` :1058, `**Session scope: the user's repo, not tezgah.**` :1064,
+``**Workspace: `.tezgah/` only.**`` :1075, `**Parallel by default: fan out
+independent items.**` :1082 *(conditional)*,
+`**Kill switches:**` :1112. The first label renders as `**Turkish, BLUF.**` under
 `language` `tr`.
 
-`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the six
-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, parallel
-fan-out, 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
+`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the seven
+conditional paragraphs and appends `POINTERS` (`hooks/tezgah_policy.py::POINTERS`).
+That is one line each saying the rule exists and where its full text lives.
+The lines cover spec-first, a second opinion, OpenResearch routing, product analysis
+(`product-analysis`, `pm-frameworks`), the code graph, parallel fan-out and design.
+The design pointer names the `design-contract` skill and the per-repo design
+contract `bin/tezgah-design` checks a UI change against. 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
@@ -235,7 +259,7 @@ applied, and it also returns the names of the switches that fired.
 - **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 a named blocker.** A done/tested claim holds only if the check ran in this session and its output was seen; "unverified" (tr: "doğrulanmadı") follows a check that ran and failed; leftover work is done, or stays as one of four blockers (DECISION, ACCESS, IRREVERSIBLE, ENV; tr: KARAR, YETKİ, GERİ ALINAMAZ, ORTAM) with its evidence. The mechanical half is enforced by [gate.md](gate.md), the residual half by the Stop rule's `residual work` class ([evidence.md](evidence.md)). Its **Ask policy** says what is asked at all. Work and process are never asked. An outward step runs on a grant. A never-default step waits for an answer. Every other question goes in one batch with a recommended default. The Stop rule's `needless ask` class refuses a reply that ends on a question the agent can decide, and the gate warns on an ask-tool question with no default ([gate.md](gate.md#ask-an-ask-tool-question-with-no-recommended-option)).
+- **Integrity: evidence, or a named blocker.** A done/tested claim holds only if the check ran in this session and its output was seen; "unverified" (tr: "doğrulanmadı") follows a check that ran and failed; leftover work is done, or stays as one of four blockers (DECISION, ACCESS, IRREVERSIBLE, ENV; tr: KARAR, YETKİ, GERİ ALINAMAZ, ORTAM) with its evidence. The mechanical half is enforced by [gate.md](gate.md), the residual half by the Stop rule's `residual work` class ([evidence.md](evidence.md)). Its **Ask policy** says what is asked at all. Work and process are never asked. An outward step runs on a grant. A never-default step waits for an answer. Plan 136 added three to that list after a session ran another session's research line under a hidden dir and wrote a `chosen:` variant the owner never picked: choosing a variant or option a research, analysis or review recommends; a way around a tezgah refusal (another folder, a hidden dir, a hatch the owner did not grant); deciding about another session's work (its line, plan or branch). A taste or intent fork still goes in the batch with a default taken this turn; these do not. A subagent's question of that kind is relayed to the user, never answered by the orchestrator or escalated to a stronger model. Every other question goes in one batch with a recommended default. The Stop rule's `needless ask` class refuses a reply that ends on a question the agent can decide, and passes one that asks the owner to pick a variant or to decide one of those steps (`hooks/tezgah_integrity.py::OWNER_CHOICE`); the gate warns on an ask-tool question with no default ([gate.md](gate.md#ask-an-ask-tool-question-with-no-recommended-option)).
 - **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.
@@ -338,12 +362,13 @@ sentence of the rule.
 | 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. |
 | fanout | A refusal cannot see a serial run that should have been parallel: nothing is called that a gate could deny. The prompt-shape arming (`hooks/tezgah_context.py::PROMPT_HINTS`) and the generated specialists line are the mechanism. |
+| design | A refusal cannot see which skill a UI turn read. The prompt arming (`hooks/tezgah_context.py::PROMPT_HINTS`) is the mechanism, and the Stop rule's `no ui_ok` class asks for the design check. |
 | 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`, `fanout` — and `classify_prompt()` returns the keys
+— `spec`, `consult`, `research`, `product`, `design`, `graph`, `fanout` — and `classify_prompt()` returns the keys
 a prompt matches (`hooks/tezgah_context.py::classify_prompt`). It also adds `product`
 for a data ask: a dashboard, a chart or a metric to choose. The check reads each
 clause on its own (`hooks/tezgah_context.py::_data_ask`). A code marker in that
@@ -357,8 +382,15 @@ say "do it with subagents, in parallel". 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. A later match in the same session pays one
-line. The fan-out line still names the action
-(`hooks/tezgah_context.py::armed_again`). The patterns carry Turkish stems because the
+line (`hooks/tezgah_context.py::armed_again`). For `fanout`, `product` and
+`design` that line carries the rule's action from `ARMED_ACTIONS`
+(`hooks/tezgah_policy.py::ARMED_ACTIONS`), not a bare "Armed again".
+The product line names `product-analysis`, `pm-frameworks`, `feature-audit`,
+`analyze-app` and `product-flow`.
+The design line names `design-contract`, `design-library`, `analyze-app` and
+`feature-audit`, and sends UI build work to a worker that loads `design-contract`.
+A bare reminder did not work.
+In one 40-turn session the product skills came up on 3 turns, against 20 in fresh sessions (plan 126). 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`).
@@ -422,6 +454,7 @@ a keyword match, not intent: "don't touch `verify-off`" names the switch too.
 | `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` |
+| `design-off` | `**Design: UI work reads the design skills.**` | `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` |
@@ -445,6 +478,15 @@ 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.
 
+One more file in a repository's own tree is not a rule switch either. A
+`tezgah.owner` at the repository's top says who owns the workspace, and its two
+settings turn seams off rather than dropping a paragraph. `tasks: off` stops the
+plan and task machine there: no active task, no per-turn phase line, and no
+`tezgah-task` command that writes a record
+(`hooks/tezgah_paths.py::tasks_disabled`). The scope gate, research and lessons
+keep reading the repository. `harness: excluded` makes `root_for` answer None,
+so nothing here runs at all (`hooks/tezgah_paths.py::harness_excluded`).
+
 `**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.
@@ -503,8 +545,8 @@ brief carries the same caller-list floor (`hooks/tezgah_agents.py`), and
 
 ## When the injected text grows too large
 
-Each event has a byte budget: `session_start` and `post_compact` 15500,
-`user_prompt` 6500, `subagent_start` 5500, anything else 13000
+Each event has a byte budget: `session_start` and `post_compact` 16000,
+`user_prompt` 7000, `subagent_start` 6100, anything else 13000
 (`hooks/tezgah_context.py::CONTEXT_BUDGET`). The rationale and the measured
 sizes sit beside it. In an empty fixture repo, `session_start` with the core
 builds 9842 B before the ponytail and ADHD rules went inline and 10884 B after
@@ -519,21 +561,27 @@ active-task line. The session budgets moved to 14500 B, the prompt budget to 650
 The Ask policy (plan 086, S3) added 913 B to the core. At 14500 B the healthy
 fixture then gave up a lessons, plans or knowledge block. The session budgets moved to 15500 B.
 The subagent brief stays the same size.
+A research ask arms the Research and Product paragraphs: 6239 B on Claude
+(S4Remeasure p08). At 6500 B the skill hint naming the research skill was the
+block given up. The prompt budget moved to 7000 B (2026-10-22).
 `SkillRulesInForceAtSessionStart` (`tests/test_context.py`) pins the rules
 themselves, not the size. 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
+`user_prompt` that arms all seven conditional rules
+for the first time builds 11979 B. That figure comes from a fixture repo with one lesson and one plan. 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 Orca line, 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
+sibling-checkout line, lessons), the per-turn relevant lessons and the plan
+table first, then the Orca line, the tooling-availability lines and the live graph
+glance, then the index line and 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 skill hint, the task phase, the
+delta, and the skill pointer last (`hooks/tezgah_context.py::DROP_ORDER`).
+The skill hint moved from near the front to after `lessons_turn` and `index`.
+It names the skill this ask needs, and no other block can work that out.
+It was the first block given up in 32 logged live drops (plan 126). 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

package/docs/environment.md

@@ -28,14 +28,14 @@ the kill switches are files, not variables, and live in
 | `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. |
+| `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/amp/tezgah-plugin.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_CONFIG_HOME` | `hooks/tezgah_paths.py::CONFIG_DIR`, `hooks/tezgah_paths.py::AMP_PLUGIN`, `bin/tezgah-doctor`, `bin/tezgah-dsh.cmd`, `hosts/opencode/plugins/tezgah.js` | `~/.config` | Parent of tezgah's config dir (kill switches, `bin/` links, config), of opencode's, and of Amp's system plugin dir (`amp/plugins/tezgah.ts`). |
 | `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. |
@@ -53,6 +53,7 @@ the kill switches are files, not variables, and live in
 |---|---|---|---|
 | `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_OCR_BIN` | `hooks/tezgah_paths.py::ocr_bin` | `ocr` on PATH | The open-code-review CLI the opt-in OCR review spec runs ([operations](operations.md#opt-in-ocr-review-spec-ocr)). |
 | `TEZGAH_ORCA_BIN` | `hooks/tezgah_orca.py::cli` | `ORCA_CLI_COMMAND`, then `$ORCA_CLI_BIN_DIR/orca`, then `orca` on PATH (`orca-ide` on Linux outside Orca), then the macOS app's CLI | The Orca CLI `tezgah-status --orca` and `tezgah-setup --status` ask. A missing path is no CLI, never a fallback: the test suite points it at one. |
 | `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table, consult's session-model lookup and the judgement seam's session call run; tests point it at a stand-in. |
 | `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`) and the judgement seam asks in a Claude Code session; the test suite points it at a path that does not exist, or at a stand-in. |
@@ -116,10 +117,12 @@ the kill switches are files, not variables, and live in
 | `CODEX_THREAD_ID`, `CURSOR_CONVERSATION_ID` | `bin/tezgah-route` | set by Codex and Cursor in their agent shells | The session `tezgah-route` writes its rows under when `TEZGAH_SESSION` is unset. When two of the three name different sessions, an inherited id is present and no row is written. |
 | `CLAUDE_ENV_FILE` | `hooks/projects-auto-init.py::main` | set by Claude Code for SessionStart hooks | The file Claude sources before each Bash call; `export_session` appends `TEZGAH_SESSION` to it. |
 | `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_HOST` | `hooks/tezgah_context.py::context_for`, `hooks/hooks.json` | unset | `claude` (set by the Claude plugin's UserPromptSubmit row; the payload names no host) makes the skill hint name the Skill tool's `tezgah:<name>` beside the path instead of a `skill://` address (`hooks/tezgah_skill_pick.py::_emit`). A host that sends `host` in the payload (omp, opencode) is not read from here. |
 | `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. |
+| `AMP_IGNORE_GUIDANCE_FILES` | `hosts/amp/tezgah-plugin.ts.in` | set by the user for Amp | Amp's own list of guidance files to skip; when it is set the plugin asks for the session brief with the core in it, since `~/.config/amp/AGENTS.md` may be skipped. |
 
 ## Test knob