@r1z4x/tezgah 1.9.2 → 1.11.0

package/bin/tezgah-task

@@ -122,7 +122,10 @@ history) is printed as `not judged` and the exit is 1. `review ... approve`
 is refused while a record whose id or agent is that reviewer is not done.
 
 Exit codes: 0 ok, 1 a refusal or a problem - one `FAIL <what>` line per problem,
-with nothing written - 2 misuse.
+with nothing written - 2 misuse. In a repository whose `tezgah.owner` says
+`tasks: off` (or `harness: excluded`) every command above that writes a record
+is refused, and the read-only ones still answer
+(`bin/tezgah-task::owner_mark`).
 """
 import glob
 import json
@@ -136,7 +139,12 @@ import time
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 import tezgah_task as tt  # noqa: E402
-from tezgah_paths import project_top, say, work_tree  # noqa: E402
+from tezgah_paths import config, ocr_bin, omp_bin, project_top, say, work_tree  # noqa: E402
+
+# Mirrors hooks/tezgah_gate.py::PLAN_TRUNKS: the gate reads these as unplanned
+# whatever a plan declares, so `start --branch` refuses them (plan 113). Not
+# imported: the gate hook pulls in every rule module for this one tuple.
+PLAN_TRUNKS = ("main", "master")
 
 
 def repo_root(path):
@@ -152,6 +160,43 @@ def repo_root(path):
     return os.path.realpath(path)
 
 
+# Commands that write a plan's record. A repository that carries `tezgah.owner`
+# saying `tasks: off` (or `harness: excluded`) keeps its records to itself: the
+# phase would arm nothing there - `tezgah_task._phased` answers no task
+# (`hooks/tezgah_paths.py::tasks_disabled`) - so writing one would report
+# success for a guard that never fired. `writes_a_record` reads both tuples, and
+# the read-only commands are untouched.
+RECORD_COMMANDS = ("start", "phase", "allow", "stop", "review", "close",
+                   "tick", "note", "spike", "unmet")
+# The journal's own writers, and `sweep`, which clears an orphan `phase:` and
+# closes the slices of the worktrees it prunes. The rest of `slice` only reads
+# (stats, board, merge-plan), and so does `status`.
+SLICE_WRITERS = ("open", "done", "stop", "reconcile", "resume")
+
+
+def writes_a_record(cmd, rest):
+    """True when this invocation writes the task machine's records: the plan
+    file, the slice journal, or the phases and slices `sweep` clears. The
+    readers write none, so a repository that is not this harness's still answers
+    them (`status`, `slice stats`, `slice board`, `slice merge-plan`)."""
+    if cmd in RECORD_COMMANDS:
+        return True
+    if cmd == "slice":
+        return bool(rest) and rest[0] in SLICE_WRITERS
+    return cmd == "sweep"
+
+
+def owner_mark(root):
+    """Why this repository's records are not this machine's to write, else
+    None. Through `tasks_disabled`, so the CLI and the gate read one answer."""
+    from tezgah_paths import OWNER_MARKER, tasks_disabled
+    if not tasks_disabled(root):
+        return None
+    return ("%s says `tasks: off` in %s: its records are the repository's own, so "
+            "this machine writes none there - edit them directly"
+            % (root, os.path.join(root, OWNER_MARKER)))
+
+
 def misuse(message):
     """Misuse exits 2, so a caller can tell it from a record that refuses."""
     print("tezgah-task: %s" % message, file=sys.stderr)
@@ -434,6 +479,139 @@ MERGE_CHECKS = (
      "python3 skills/plan-add/render_table.py --acceptance --strict"),
 )
 
+# OCR's texts vendored with tezgah (plan 125): the review prompt each per-group
+# reviewer reads as an appendix, the filter prompt the refuter pass follows
+OCR_PROMPTS = os.path.join(HERE, "third_party", "open-code-review", "prompts")
+
+
+def ocr_json(ocr, args):
+    """One `ocr delegate ... --format json` answer as a dict, or the reason it
+    is not one: a non-zero exit, a timeout, output that is not a JSON object."""
+    try:
+        out = subprocess.run([ocr, "delegate"] + args, capture_output=True,
+                             text=True, timeout=30,
+                             env=dict(os.environ, OCR_NO_UPDATE="1"))
+    except subprocess.TimeoutExpired:
+        return "`ocr delegate %s` timed out after 30 s" % args[0]
+    except OSError as exc:
+        return "`ocr delegate %s` did not start: %s" % (args[0], exc)
+    if out.returncode:
+        return "`ocr delegate %s` exited %d" % (args[0], out.returncode)
+    try:
+        data = json.loads(out.stdout)
+    except ValueError:
+        data = None
+    return data if isinstance(data, dict) else \
+        "`ocr delegate %s` printed no JSON object" % args[0]
+
+
+def ocr_spec(where, base):
+    """OCR's deterministic review spec for `base..HEAD`: (preview, rule groups,
+    the rule command), the reason it is skipped, or None without `ocr` or with
+    the `ocr` feature not enabled (`tezgah-setup --enable ocr`) - the step is
+    then today's."""
+    ocr = ocr_bin()
+    if ocr is None or "ocr" not in (config().get("features") or []):
+        return None
+    if base == "<base>":
+        return "no diff base to preview"
+    preview = ocr_json(ocr, ["preview", "--format", "json", "--from", base,
+                             "--to", "HEAD", "--repo", where])
+    if isinstance(preview, str):
+        return preview
+    # the JSON shape this reader was written against (OCR 375f64c / 1.13.2)
+    if preview.get("schema_version") != "1":
+        return "`ocr delegate preview` schema_version %r is not \"1\"" % (
+            preview.get("schema_version"),)
+    files = preview.get("reviewable_files")
+    excluded = preview.get("excluded_files", [])
+    if not isinstance(files, list) or not isinstance(excluded, list):
+        return "`ocr delegate preview` JSON has no file lists"
+    # a row with no string path is dropped here, so neither the rule argv nor
+    # the printed list can meet a None
+    files = [f for f in files if isinstance(f, dict) and isinstance(f.get("path"), str)]
+    preview["reviewable_files"] = files
+    paths = [f["path"] for f in files]
+    groups = []
+    # `--` ends OCR's options, so a changed file named like a flag stays a path
+    rule_cmd = [ocr, "delegate", "rule", "--format", "json", "--repo", where, "--"] + paths
+    if paths:
+        rule = ocr_json(ocr, rule_cmd[2:])
+        if isinstance(rule, str):
+            return rule
+        if rule.get("schema_version") != "1":
+            return "`ocr delegate rule` schema_version %r is not \"1\"" % (
+                rule.get("schema_version"),)
+        groups = rule.get("groups")
+        if not isinstance(groups, list):
+            return "`ocr delegate rule` JSON has no groups"
+    return preview, groups, rule_cmd
+
+
+def print_ocr_spec(where, base):
+    """Step 2's OCR lines: the reviewable files, the exclusions (still in scope),
+    one reviewer per rule group, the refuter pass and the quote check. Prints
+    nothing without `ocr`, one `OCR spec skipped:` line when it fails."""
+    spec = ocr_spec(where, base)
+    if spec is None:
+        return
+    if isinstance(spec, str):
+        print("     OCR spec skipped: %s" % spec)
+        return
+    preview, groups, rule_cmd = spec
+    paths = [f.get("path") for f in preview["reviewable_files"] if isinstance(f, dict)]
+    print("     OCR review spec (`ocr delegate`; its output is input to the "
+          "review, never a verdict):")
+    print("     - reviewable files (%d): %s" % (len(paths), ", ".join(paths) or "none"))
+    out = ["%s (%s)" % (f.get("path"), f.get("exclude_reason", "no reason"))
+           for f in preview.get("excluded_files", []) if isinstance(f, dict)]
+    print("     - excluded by OCR, NOT covered by OCR rules but still in the "
+          "reviewer's scope (tests and docs stay in scope; one more "
+          "tezgah-reviewer reads them over the dimensions above): %s"
+          % (", ".join(out) or "none"))
+    if groups:
+        # OCR's own bundling below its LLM-grouping threshold (task_template.json
+        # GROUPING_MIN_FILES 4, GROUPING_BUNDLE_LINE_THRESHOLD 200): fewer than 4
+        # files are one bundle under 200 changed lines, else one file each.
+        churn = sum(n for f in preview["reviewable_files"]
+                    for n in (f.get("insertions"), f.get("deletions"))
+                    if isinstance(n, int) and not isinstance(n, bool))
+        if len(paths) < 4 and churn < 200:
+            who = ("one tezgah-reviewer for the whole small change set (%d files, "
+                   "%d changed lines), its brief carrying every group's rule text"
+                   % (len(paths), churn))
+        elif len(paths) < 4:
+            who = "one tezgah-reviewer per file, in ONE message"
+        else:
+            who = "one tezgah-reviewer per rule group below, in ONE message"
+        print("     - instead of one reviewer per dimension, spawn %s: a brief "
+              "carries its group's rule text verbatim (`groups[].rule` of `%s`) "
+              "and names %s as an appendix to read; each reviewer accounts for "
+              "every file it owns as reviewed or skipped-with-reason"
+              % (who, shlex.join(rule_cmd),
+                 os.path.join(OCR_PROMPTS, "main_task_system.md")))
+        for g in groups:
+            if isinstance(g, dict):
+                print("       - rule group %s: source %s, pattern %s, files %s"
+                      % (g.get("group_id"), g.get("source"), g.get("pattern"),
+                         ", ".join(g.get("files") or []) or "none"))
+    else:
+        print("     - no OCR rule group: the dimension fan-out above stands")
+    print("     - refuter pass: after merging the findings, one fresh "
+          "tezgah-reviewer reads %s as its instructions and removes only "
+          "findings the diff proves wrong"
+          % os.path.join(OCR_PROMPTS, "review_filter_task_system.md"))
+    print("     - quote check: `tezgah-review-quote --repo %s --from %s "
+          "FINDINGS.json` over the merged findings (a JSON list of path, quote, "
+          "start_line, end_line); an `unlocated` finding goes back to its "
+          "reviewer" % (shlex.quote(where), base))
+    # V4, omp only: OCR's own loop on omp's model; candidates, never findings
+    if os.environ.get("OMPCODE") and omp_bin():
+        print("     - omp: `tezgah-ocr-review --repo %s --from %s --to HEAD "
+              "--output OCR.json` runs OCR's own review on omp's model; hand its "
+              "comments to the reviewers as candidates to confirm or refute, "
+              "never as findings" % (shlex.quote(where), base))
+
 
 def verification_steps(text, path):
     """What the verification phase requires before the plan is done: the plan's
@@ -510,6 +688,7 @@ def verification_steps(text, path):
               "without a new round, or recorded fix-later under ## State only "
               "when it waits on a user decision (%s), and the verdict is "
               "`approve`" % say()["decision"])
+        print_ocr_spec(where, base)
     print("  3. record its verdict: `tezgah-task review %s <reviewer> approve|changes`"
           " (records the reviewed sha);"
           " `tezgah-task close %s done` refuses without an approve" % (ident, ident))
@@ -552,6 +731,11 @@ def cmd_start(args):
             if i + 1 >= len(rest) or rest[i + 1].startswith("--"):
                 return misuse("--branch needs the branch name to bind the plan to")
             branch = rest[i + 1]
+            if branch in PLAN_TRUNKS:
+                return misuse("--branch %s: a trunk (%s) never binds a plan - the gate "
+                              "reads every PLAN_TRUNKS name as unplanned; bind a "
+                              "plan/NNN-slug branch instead"
+                              % (branch, ", ".join(PLAN_TRUNKS)))
             i += 2
             continue
         if rest[i] == ANY_PATH:
@@ -619,7 +803,19 @@ def cmd_start(args):
     bad = write_fields(path, **fields)
     if bad:
         return problems(bad)
-    return show(path)
+    shown = show(path)
+    top = repo_root(os.getcwd())
+    if main_root(top) != top:
+        # a worktree bound to a plan gets its graph now, seeded from the main
+        # checkout's (plan 118); an index that cannot start costs the line, never
+        # the start the record already holds
+        try:
+            from tezgah_context import autoindex, under
+            if under(top):
+                print("graph: %s" % autoindex(top))
+        except Exception:
+            pass
+    return shown
 
 
 def cmd_phase(args):
@@ -1814,6 +2010,10 @@ def main(argv):
         print(__doc__, file=sys.stderr)
         return 2
     cmd, rest = argv[1], argv[2:]
+    if writes_a_record(cmd, rest):
+        mark = owner_mark(repo_root(os.getcwd()))
+        if mark:
+            return problems([mark])
     if cmd == "start":
         return cmd_start(rest)
     if cmd == "phase":

package/commands/adhd.md

@@ -1,4 +1,4 @@
-Run `tezgah-adhd $ARGUMENTS` and report the one line it prints.
+Run `~/.config/tezgah/bin/tezgah-adhd $ARGUMENTS` and report the one line it prints.
 
 The installed CLI owns the state: it writes or removes
 `~/.config/tezgah/adhd-off`, the kill switch that drops the act-on-it rule from
@@ -6,7 +6,7 @@ the text every host injects. Never create or delete that file by hand, and never
 edit any other rule's switch from here.
 
 ```sh
-adhd=$(command -v tezgah-adhd || echo "$HOME/.config/tezgah/bin/tezgah-adhd")
+adhd="$HOME/.config/tezgah/bin/tezgah-adhd"
 "$adhd" $ARGUMENTS
 ```
 

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,7 +21,7 @@
     "unjudged": 2
   },
   "docs/gate.md": {
-    "unjudged": 39
+    "unjudged": 29
   },
   "docs/glossary.md": {
     "unjudged": 12
@@ -36,7 +36,7 @@
     "unjudged": 21
   },
   "docs/skills.md": {
-    "unjudged": 7
+    "unjudged": 9
   },
   "docs/status-line.md": {
     "unjudged": 9

package/docs/clarity-baseline.json

@@ -18,7 +18,7 @@
     "semicolons": 9
   },
   "docs/contract.md": {
-    "long_sentences": 42,
+    "long_sentences": 41,
     "passive": 25,
     "replace_words": 0,
     "semicolons": 29
@@ -90,7 +90,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,40 @@ 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`).
 
 ## 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
@@ -338,12 +359,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 +379,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 +451,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 +475,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 +542,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` 5800, 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 +558,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

@@ -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,6 +117,7 @@ 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`. |