@r1z4x/tezgah 1.11.0 → 1.14.0

package/bin/tezgah-status

@@ -117,7 +117,8 @@ import sys
 HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, os.path.join(HERE, "hooks"))
 from tezgah_context import (  # noqa: E402
-    LEGEND, color_default, health_segments, render_line, skill_fitness)
+    LEGEND, TOOL_USE_MEASURES, color_default, health_segments, render_line,
+    skill_fitness)
 
 # How many rows of the tool histogram the plain report prints. The count is on
 # the line and `--json` carries every row, so a reader can always see what was
@@ -432,6 +433,15 @@ def main():
     if "--help" in flags:
         sys.stdout.write(__doc__.strip() + "\n")
         return 0
+    # the two skill-read marks are measures too; a typo here blanked every mark
+    measures = TOOL_USE_MEASURES | {"pony", "adhd"}
+    named = {n for f in flags if f.startswith("--observable=")
+             for n in f.split("=", 1)[1].split(",") if n}
+    if named - measures:
+        sys.stderr.write("tezgah-status: unknown measure(s) in --observable: %s "
+                         "(known: %s)\n" % (", ".join(sorted(named - measures)),
+                                             ", ".join(sorted(measures))))
+        return 2
     if "--legend" in flags:
         sys.stdout.write(LEGEND)
         return 0

package/bin/tezgah-task

@@ -6,7 +6,7 @@
   tezgah-task allow GLOB ... | --any-path --why REASON         replace the allowlist, recording why
   tezgah-task stop                                            deactivate (clear phase)
   tezgah-task status [--json]                                 the active task, then every open plan: progress, what it waits on, what can run at once
-  tezgah-task review <NNN|path> <reviewer> approve|changes    record a fresh review's verdict
+  tezgah-task review <NNN|path> <reviewer> approve|changes [--no-slice WHY]  record a fresh review's verdict; approve needs the reviewer's slice record, or WHY it has none
   tezgah-task close <NNN|path> done|discarded [--resolved TEXT] move a plan to .tezgah/plans/done, deactivate it, remove merged worktrees
   tezgah-task tick <NNN|path> <n> [--undo]                   tick (or untick) Acceptance item n, counted from 1
   tezgah-task note <NNN|path> state|next "<text>"            replace the body of `## State` (the newest one) or `## Next`
@@ -1082,7 +1082,7 @@ def budget_spent(path, ident):
             % (path, REVIEW_ROUNDS, ident, say()["decision"], ident))
 
 
-def unfinished_review(root, reviewer, plan="", since=0):
+def unfinished_review(root, reviewer, plan="", since=0, no_slice="", ran_since=0):
     """The refusal of an `approve` while a slice journal record whose id or agent
     is `reviewer` is open, stopped or stale: a review slice that died on a
     provider limit had its approve recorded anyway, and a NameError it would have
@@ -1097,7 +1097,11 @@ def unfinished_review(root, reviewer, plan="", since=0):
     `tt.open_slice`) counts too. Under TEZGAH_SESSION only this session's
     records and unowned ones count, by id, agent or name alike: another
     session's review is not this approve's. The refusal names the exact id,
-    which `slice resume` and `slice done` take from any session."""
+    which `slice resume` and `slice done` take from any session. No finished
+    record changed at or after `ran_since` refuses too: a requested reviewer with
+    no status did not run, and a plan-readiness review before the checkpoint, an
+    earlier round's review or a `resumed` record with no re-run is not this
+    review - unless `no_slice` says why the reviewer ran outside the journal."""
     from tezgah_paths import off
     if off("slices-off"):
         return []
@@ -1113,21 +1117,42 @@ def unfinished_review(root, reviewer, plan="", since=0):
             return rec["plan"] == plan
         return (_stamp(rec.get("updated")) or 0) >= since
 
-    return ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
-            "slice resume %s` and wait for that run; if the review was finished "
-            "another way, record it with `tezgah-task slice done %s` - an approve "
-            "from a review that did not finish reads nothing"
-            % (rec["id"], rec.get("status"),
-               (" (%s)" % rec["failure"]) if rec.get("failure") else "",
-               rec["id"], rec["id"])
-            for rec in tt.slices(root)
-            if rec.get("status") in ("open", "stopped", "stale")
-            and named(rec) and ours(rec)]
+    found = [rec for rec in tt.slices(root) if named(rec) and ours(rec)]
+    refusals = ["review slice %s is %s%s: let it finish, or resume it with `tezgah-task "
+                "slice resume %s` and wait for that run; if the review was finished "
+                "another way, record it with `tezgah-task slice done %s` - an approve "
+                "from a review that did not finish reads nothing"
+                % (rec["id"], rec.get("status"),
+                   (" (%s)" % rec["failure"]) if rec.get("failure") else "",
+                   rec["id"], rec["id"])
+                for rec in found if rec.get("status") in ("open", "stopped", "stale")]
+    ran = [rec for rec in found if rec.get("status") == "done"
+           and (_stamp(rec.get("updated")) or 0) >= ran_since]
+    if not ran and not refusals and not no_slice:
+        # a requested reviewer with no finished record since the work is a
+        # review that did not run
+        refusals.append(
+            "no finished review slice names %s for this plan since its work began: "
+            "a reviewer with no record did not run, and a readiness review, an "
+            "earlier round or a resumed record is not this review. Spawn the fresh "
+            "reviewer and approve once its slice is done; a host that keeps no "
+            "slice journal records why with "
+            "`--no-slice \"<why: the reviewer ran outside the slice journal>\"`"
+            % reviewer)
+    return refusals
 
 
 def cmd_review(args):
+    no_slice = ""
+    if "--no-slice" in args:
+        i = args.index("--no-slice")
+        no_slice = " ".join((args[i + 1:i + 2] or [""])[0].split())
+        args = args[:i] + args[i + 2:]
+        if not no_slice:
+            return misuse("--no-slice takes why the reviewer ran outside the slice journal")
     if len(args) != 3 or args[2] not in VERDICTS:
-        return misuse("review takes <NNN|path> <reviewer> %s" % "|".join(VERDICTS))
+        return misuse("review takes <NNN|path> <reviewer> %s [--no-slice WHY]"
+                      % "|".join(VERDICTS))
     path, problem = open_plan(args[0])
     if problem:
         return problems([problem])
@@ -1144,9 +1169,21 @@ def cmd_review(args):
         mark = (fields.get("checkpoint") or "").split()
         since = (git_out(root, "log", "-1", "--format=%ct", mark[-1])
                  if mark and mark[-1] != tt.CHECKPOINT_PENDING else None)
+        since = int(since) if (since or "").isdigit() else 0
+        # this round's review finished after the first commit of the work it
+        # reads: past the checkpoint in round one (a plan-readiness review ran
+        # before it), past the commit round one read in round two (round one's
+        # reviewer finished before it); with no such commit, after the base itself
         ident = fields.get("id") or os.path.basename(path).split("-")[0]
-        bad = unfinished_review(root, args[1], ident,
-                                int(since) if (since or "").isdigit() else 0)
+        base = fields.get("reviewed_sha") or (
+            mark[-1] if mark and mark[-1] != tt.CHECKPOINT_PENDING else "")
+        first = ""
+        if base:
+            after = (git_out(tt.plan_holders(root).get(ident) or root, "log",
+                             "--reverse", "--format=%ct", base + "..HEAD") or "").split()
+            first = after[0] if after else git_out(root, "log", "-1", "--format=%ct", base)
+        ran_since = max(since, int(first) if (first or "").isdigit() else 0)
+        bad = unfinished_review(root, args[1], ident, since, no_slice, ran_since)
         if bad:
             return problems(bad)
     # a plan held by its own worktree is built on that branch: its HEAD is the
@@ -1154,7 +1191,8 @@ def cmd_review(args):
     ident = fields.get("id") or os.path.basename(path).split("-")[0]
     where = tt.plan_holders(root).get(ident) or root
     sha = (git_out(where, "rev-parse", "HEAD") or "")[:12]
-    record = {"review": "%s %s %s" % (args[1], args[2], today()),
+    record = {"review": "%s %s %s%s" % (args[1], args[2], today(),
+                                        " no-slice: " + no_slice if no_slice else ""),
               "review_round": str(int(prior) + 1 if prior.isdigit() else 1),
               "updated": today()}
     if sha:
@@ -2010,6 +2048,9 @@ def main(argv):
         print(__doc__, file=sys.stderr)
         return 2
     cmd, rest = argv[1], argv[2:]
+    if cmd in ("-h", "--help"):
+        print(__doc__.strip())
+        return 0
     if writes_a_record(cmd, rest):
         mark = owner_mark(repo_root(os.getcwd()))
         if mark:

package/bin/tezgah.js

@@ -2,7 +2,7 @@
 // bin/tezgah.js - npm's bin entry: finds a Python interpreter and execs
 // bin/tezgah-setup with every argument passed through. npm resolves this
 // symlink to the global prefix, so process.argv[1] is the shim, not the target.
-const { spawn } = require("child_process");
+const { spawn, spawnSync } = require("child_process");
 const { existsSync } = require("fs");
 const os = require("os");
 const path = require("path");
@@ -18,9 +18,12 @@ const candidates = process.env.TEZGAH_PYTHON
   ? [process.env.TEZGAH_PYTHON]
   : ["python3", "python3.12", "python3.11", "python3.10", "python"];
 
+// Probed exactly as it is spawned below - no shell - so a value the probe
+// accepts is one spawn can start (`TEZGAH_PYTHON="python3 -S"` passed a shell
+// probe, then died in spawn with a stack trace).
 const py = candidates.find(c => {
-  try { require("child_process").execSync(c + " -c ''", { stdio: "ignore" }); return true; }
-  catch (_) { return false; }
+  const probe = spawnSync(c, ["-c", ""], { stdio: "ignore" });
+  return !probe.error && probe.status === 0;
 });
 
 if (!py) {
@@ -29,6 +32,10 @@ if (!py) {
 }
 
 const child = spawn(py, [setup, ...process.argv.slice(2)], { stdio: "inherit" });
+child.on("error", err => {
+  process.stderr.write("tezgah: cannot start " + py + ": " + err.message + "\n");
+  process.exit(1);
+});
 // A child killed by a signal reports code null, and process.exit(null) is exit
 // 0: an installer killed mid-run read as a success (audit L-10, ENV-06). The
 // shell convention 128 + signal number carries the failure out instead.

package/commands/adhd.md

@@ -12,7 +12,7 @@ adhd="$HOME/.config/tezgah/bin/tezgah-adhd"
 
 - No argument: run it bare, which prints `on` or `off`.
 - `off`: disarms the rule everywhere on this machine.
-- `on`: arms it again (`off` is the default).
+- `on`: arms it again (`on` is the default).
 - Anything else: the CLI exits 2 with the usage on stderr - show that to the
   user and stop.
 

package/docs/README.md

@@ -7,7 +7,8 @@ tool to someone deciding whether to install it; `AGENTS.md` says how to check a
 change; these pages explain how the thing actually works, so a session does not
 have to re-derive it by reading 55 Python files. Every page is written for one
 reader with one question in mind, and every non-obvious claim in it carries a
-citation you can open: `path::symbol` into Python code, `path:line` elsewhere.
+citation you can open: `path::symbol` into Python, JavaScript and TypeScript
+code, `path:line` elsewhere.
 
 ## Start here
 
@@ -55,26 +56,36 @@ citation you can open: `path::symbol` into Python code, `path:line` elsewhere.
   belong on a page: delete it rather than soften it.
 - Code in a Python file is cited by symbol: `path::name` for a top-level def,
   class or assignment, `path::Class.method` or `path::outer.inner` for a nested
-  one (`hooks/tezgah_gate.py::decision`). It carries no line number, so an edit
+  one (`hooks/tezgah_gate.py::decision`). A page cites a JavaScript or
+  TypeScript file's top-level `const`, `let`, `function` or `class` the same way
+  (`hosts/opencode/plugins/tezgah.js::noteBegan`). It carries no line number, so an edit
   that moves code above or inside the symbol moves no citation. The sentence says
   which part of the symbol it means. Everything else stays `path:line`: a
-  JavaScript, TypeScript, JSON, YAML or Markdown target, module-level code outside
-  every def and class, and a range across several symbols. Never name a symbol
+  JSON, YAML, shell or Markdown target, code outside every top-level symbol, and a
+  range across several symbols. Never name a symbol
   that does not contain what the sentence cites.
 - `bin/tezgah-docs --citations` checks both forms. It reads every page under `docs/`
   and the comments and docstrings of the Python code. A string literal, such as a
   fixture or a captured output, is data and is not read. A symbol citation is
-  resolved against the AST of the file it names. It fails when that file defines
+  resolved against the AST of the Python file it names, or the top-level
+  declarations of a JavaScript or TypeScript one. It fails when that file defines
   no such name. A name without a dot may also name the one method of that name
   in a class. That is how a test pin names its test. A def local to a function
   never stands in for it. A `path:line` with a symbol named
   before it, or right after it in parentheses, must point inside that symbol's
-  body. A bare file name means the one code file of that name. The suite also
+  body. A bare file name means the one code file of that name, else the file of
+  that name at the repository root. A path under the private `.tezgah/` is never
+  judged, because a CI checkout has no copy of it. A comma list reads every range in it. A bare
+  range, `(8-9)`, `(14,34-38)` or an unquoted :8-9, is read against the path cited
+  before it in the same sentence or table row. One that starts at 0 or runs
+  backwards is a value, not lines. The audit flags a cited range past the end of
+  its file, and one over blank lines only, with or without a symbol beside it. In a shell script, a name beside the range must be on its
+  lines. The suite also
   checks that a cited file exists and that a cited line is inside it
   (`tests/test_docs.py`). Whether a line still *shows the thing the sentence names*
   is a judgement, not a regex. So a `path:line` with no symbol beside it is left
-  unjudged rather than guessed at. So is a `path:N` the pattern cannot read
-  (unquoted, or a comma list), but it is counted.
+  unjudged rather than guessed at. So is an unquoted `path:N` the pattern cannot
+  read, but it is counted.
   On this tree, 2026-10-06: 996 judged (995 of them symbol citations), 577 not
   judgeable, 85 of those unreadable.
   The unjudged count is a ratchet. `docs/citations-baseline.json` holds each file's

package/docs/architecture.md

@@ -222,8 +222,8 @@ So tezgah never creates a `.tezgah`, `.cursor`, `.opencode` or graph index insid
   line armed (`hooks/tezgah_guard.py::safe`, `hooks/projects-pretooluse.py::main`).
   A host that cannot call the core in process gets the same rule in its own
   language: opencode's plugin runs every awaited core CLI through one `collect`
-  helper with a 10 s deadline (`SPAWN_DEADLINE_MS`,
-  `hosts/opencode/plugins/tezgah.js:108-178`). Both fail open, because a core
+  helper with a 10 s deadline (`hosts/opencode/plugins/tezgah.js::SPAWN_DEADLINE_MS`,
+  `hosts/opencode/plugins/tezgah.js::collect`). Both fail open, because a core
   that has crashed has refused nothing.
 - **The root boundary.** Every hook is inert outside a configured root:
   a linked `git worktree` counts as inside when its main checkout is, read from

package/docs/citations-baseline.json

@@ -6,43 +6,37 @@
     "unjudged": 1
   },
   "docs/architecture.md": {
-    "unjudged": 25
+    "unjudged": 23
   },
   "docs/contract.md": {
-    "unjudged": 5
+    "unjudged": 3
   },
   "docs/environment.md": {
-    "unjudged": 8
+    "unjudged": 4
   },
   "docs/evidence.md": {
-    "unjudged": 18
-  },
-  "docs/feature-audit.md": {
-    "unjudged": 2
+    "unjudged": 14
   },
   "docs/gate.md": {
-    "unjudged": 29
+    "unjudged": 10
   },
   "docs/glossary.md": {
-    "unjudged": 12
+    "unjudged": 9
   },
   "docs/hosts.md": {
-    "unjudged": 62
+    "unjudged": 15
   },
   "docs/layers.md": {
-    "unjudged": 14
+    "unjudged": 7
   },
   "docs/operations.md": {
-    "unjudged": 21
+    "unjudged": 4
   },
   "docs/skills.md": {
-    "unjudged": 9
-  },
-  "docs/status-line.md": {
-    "unjudged": 9
+    "unjudged": 6
   },
   "docs/testing.md": {
-    "unjudged": 41
+    "unjudged": 21
   },
   "hooks/tezgah_gate.py": {
     "unjudged": 1

package/docs/clarity-baseline.json

@@ -1,6 +1,6 @@
 {
   "CHANGELOG.md": {
-    "long_sentences": 0,
+    "long_sentences": 1,
     "passive": 2,
     "replace_words": 0,
     "semicolons": 0
@@ -25,12 +25,12 @@
   },
   "docs/environment.md": {
     "long_sentences": 3,
-    "passive": 2,
+    "passive": 1,
     "replace_words": 0,
-    "semicolons": 3
+    "semicolons": 2
   },
   "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,
@@ -91,7 +97,7 @@
   },
   "docs/skills.md": {
     "long_sentences": 35,
-    "passive": 18,
+    "passive": 17,
     "replace_words": 0,
     "semicolons": 16
   },

package/docs/contract.md

@@ -88,7 +88,7 @@ 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.
+`judge-off` leaves it on, and `reminder-off` leaves it on too: that switch drops only the reminder line.
 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.
@@ -208,27 +208,31 @@ default, measured on two research lines with a written flip
 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`).
+`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.**` :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
+That order, read from `hooks/tezgah_policy.py::CORE` (the labels are the
+anchors, so an edit above one moves nothing here):
+`**{REPLY_LANG}, BLUF.**`, `**Ponytail (minimal code).**`, `**Output shape:
+ADHD-friendly.**`, `**Deliver the whole ask; never the shortcut.**`,
+`**Integrity: evidence, or a named blocker.**`, `**Loop discipline.**`,
+`**Spec before building.**` *(conditional)*, `**Lessons ledger: stop
+repeating mistakes.**`, `**Code discovery: graph first.**`
+*(conditional)*, `**Consult before irreversible.**` *(conditional)*,
+`**Research: route it to OpenResearch.**` *(conditional)*, `**Product
+analysis: five axes, one evidence class per finding.**` *(conditional)*,
+`**Design: UI work reads the design skills.**` *(conditional)*,
+`**No AI attribution, ever, on any host.**`, `**Identifiers and messages
+stay English.**`, `**Session scope: the user's repo, not tezgah.**`,
+``**Workspace: `.tezgah/` only.**``, `**Parallel by default: fan out
+independent items.**` *(conditional)*,
+`**Kill switches:**`. The first label renders as `**Turkish, BLUF.**` under
 `language` `tr`.
 
 `always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the seven
@@ -256,7 +260,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.
@@ -416,9 +420,12 @@ with no transcript pays nothing.
 ## 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()`.
+(`hooks/tezgah_context.py::core_split`). `off()` checks tezgah's config dir and
+the legacy `~/.claude` (`hooks/tezgah_paths.py::OFF_DIRS`, `hooks/tezgah_paths.py::off`).
+The config dir is `~/.config/tezgah`, or `$XDG_CONFIG_HOME/tezgah` when
+`XDG_CONFIG_HOME` is set (`hooks/tezgah_paths.py::CONFIG_DIR`). The core and the
+per-turn reminder name the same dir (`hooks/tezgah_policy.py::SWITCH_DIR`). 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
@@ -435,8 +442,8 @@ three cases:
   (`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 is the stand-down a full `tezgah-setup --uninstall` (one covering every
+  armed host) 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.
 
@@ -445,6 +452,18 @@ 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.
 
+A subagent session is no next session. When the payload names the session that
+spawned it (`parent`), the hook binds the parent's ledger too
+(`hooks/tezgah_integrity.py::bind_session`). The subagent then latches on the
+earlier of its own and its parent's first row. A switch the parent made
+mid-session does not count in a subagent it spawns afterwards. A switch the
+user's prompt to the parent named counts there too. The subagent's own prompt
+is its parent's brief and authorizes nothing. The omp and Amp bridges send
+`parent` on a subagent's events. The opencode plugin keeps the parent opencode
+names on the child's `session.created` (`hosts/opencode/plugins/tezgah.js::PARENTS`)
+and hands it to the core it asks (`bin/tezgah-gate`). The parent always comes
+from the host, never from a ledger row an agent could write.
+
 | Switch file | Rule it removes | Where the drop is implemented |
 |---|---|---|
 | `exec-mode.off` | `**{REPLY_LANG}, BLUF.**` | `hooks/tezgah_context.py::switches` |
@@ -454,27 +473,43 @@ a keyword match, not intent: "don't touch `verify-off`" names the switch too.
 | `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` |
+| `research-off` | `**Research: route it to OpenResearch.**` and `**Product analysis: five axes, one evidence class per finding.**` | `hooks/tezgah_context.py::switches` |
 | `orchestrate-off` | `**Parallel by default: fan out independent items.**`, and the orchestration section of the on-demand skill | `hooks/tezgah_context.py::switches` drops the paragraph, `hooks/tezgah_context.py::context_for` injects "Orchestration is off" and drops the specialists line, 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` |
+| `reminder-off` | the per-turn reminder line alone; the armed paragraphs, the gate notice, the off-note and the other per-turn parts stay | `hooks/tezgah_context.py::context_for` leaves the `reminder` part out |
 | `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`) |
+| `workspace-off` | ``**Workspace: `.tezgah/` only.**``, and the gate's refusal of a root `plans/`, `research/` or `analysis/` write | `hooks/tezgah_context.py::switches` drops the paragraph, and the gate reads the same switch (`hooks/tezgah_gate.py::DENY_RULES`, [gate.md](gate.md#workspace-tezgah-state-outside-tezgah)) |
+| `task-off` | the gate's task rule: the active plan's phase, its path allowlist, the plan record and a shell write | `hooks/tezgah_gate.py::decision` ([gate.md](gate.md#task-the-active-plans-phase-and-path-allowlist)) |
 | `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 |
+| `.no-plan-gate` | the gate's plan rule in that repository: a turn's third product file on a branch no plan binds | `hooks/tezgah_gate.py::plan_reason` ([gate.md](gate.md#plan-a-turns-third-product-file-on-a-branch-no-plan-binds)) |
+| `.no-taste` | the opt-in taste capture in that repository | `hooks/tezgah_taste.py::MARK` ([operations](operations.md#opt-in-taste-capture-learn-apply)) |
 
-The last four are per-repo [marks](glossary.md#per-repo-mark), read by
+The last six 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
+session at start (`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
+separately and would otherwise re-arm the rule — and in Claude's static `tezgah`
+output style, which no switch re-renders. The per-turn note names the switches
+again and the output style alone. Both notes are the budget's `offnote` block.
+A turn over its byte budget drops it like the other droppable blocks
+([the budget](#when-the-injected-text-grows-too-large)), so "per turn" holds
+while the turn fits. `tezgah-adhd off` writes the same
 channel as the file (`bin/tezgah-adhd::SWITCH`); the ponytail *level* is not a switch.
 
+`off()` and `armed()` also read five feature switches, not rule switches.
+ADR 007 leaves them unclassified (`hooks/tezgah_paths.py::SWITCHES`): `agents-off`, `update-check-off`, `slices-off`, `taste-on`, `skill-suggest-on`.
+
+One environment variable disarms a refusal too: `TEZGAH_REPO_RULE=0` skips a
+repository's own `.tezgah/gate.py` (`hooks/tezgah_gate.py::REPO_RULE_VALVE`;
+[gate.md](gate.md#a-repositorys-own-rule), [environment](environment.md)).
+
 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
@@ -542,8 +577,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` 16000,
-`user_prompt` 7000, `subagent_start` 5800, anything else 13000
+Each event has a byte budget: `session_start` and `post_compact` 16200,
+`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
@@ -551,8 +586,9 @@ builds 9842 B before the ponytail and ADHD rules went inline and 10884 B after
 113 B. The healthy fixture with a lesson and a plan then built 12059 B. At the
 old 12000 B budget it lost its lessons and sibling checkouts to pay for core
 rules, so the budget moved to 13000 B. The residual rule (plan 080) added
-1473 B to the core and 151 B to the reminder, so the always-on band is
-11972 B (`tests/test_setup.py`). At 13000 B the healthy fixture gave up its
+1473 B to the core and 151 B to the reminder, so the always-on band reached
+11972 B. `tests/test_setup.py::VersionPrefixIsNotContract` pins today's band.
+At 13000 B the healthy fixture gave up its
 lessons, plans and steer blocks. At 6000 B the busiest prompt turn gave up its
 active-task line. The session budgets moved to 14500 B, the prompt budget to 6500 B.
 The Ask policy (plan 086, S3) added 913 B to the core. At 14500 B the healthy
@@ -560,7 +596,10 @@ fixture then gave up a lessons, plans or knowledge block. The session budgets mo
 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).
+block given up. The prompt budget moved to 7000 B (2026-10-22). A longer
+subagent pointer (plan 136) moved `subagent_start` to 6100 B. The output-shape
+paragraph's plan-mode clause (plan 142, +168 B) put the worktree fixture's
+`session_start` over 16000 B again. The session budgets moved to 16200 B.
 `SkillRulesInForceAtSessionStart` (`tests/test_context.py`) pins the rules
 themselves, not the size. A
 `user_prompt` that arms all seven conditional rules
@@ -575,7 +614,17 @@ table first, then the Orca line, the tooling-availability lines and the live gra
 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`).
+delta, and the skill pointer last (`hooks/tezgah_context.py::DROP_ORDER`). The
+whole tuple, in this order:
+
+```
+knowledge worktrees lessons lessons_turn taste plans subagents steer orca
+consult research research_broken graph offnote orchestrate index resume
+slices context scratch skill task delta pointer
+```
+
+`offnote` is the note naming the kill switches that fired, so a turn over budget
+can lose it before the index line.
 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