@r1z4x/tezgah 1.9.2 → 1.13.0

package/hooks/tezgah_policy.py

@@ -3,8 +3,10 @@
 
 Placeholders are filled by tezgah_context.render():
   {ROOT}        - the configured tezgah root the session is in
-  {CONSULT_BIN} - the stable path to bin/consult
-  {CODEGEN_BIN} - the stable path to bin/codegen; {ROUTE_BIN} to bin/tezgah-route
+  {CONSULT_BIN}, {CODEGEN_BIN}, {RESEARCH_BIN}, {ROUTE_BIN}, {SKILL_BIN}... -
+                  the stable path to the tezgah CLI BIN_TOOLS names: no host but
+                  Claude puts ~/.config/tezgah/bin on PATH, so a bare name in
+                  the text is a `command not found`
   {ORX_BIN}     - the stable path to the OpenResearch `orx` CLI, else bare `orx`
   {OPEN_LINES}  - the research lines already open, filled by
                   tezgah_context.context_for: that fact is about the repo the
@@ -25,6 +27,16 @@ sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
 import tezgah_research as tr  # noqa: E402  (the layer's own line resolver)
 from tezgah_paths import say  # noqa: E402  (the language packs' contract words)
 
+# The tezgah CLIs the injected text names, by placeholder. `render` fills each
+# with `tezgah_paths.tool(<name>)`; the hookless copies (REPLY_LANG_HOOKLESS)
+# with the installed path spelled from `~`.
+BIN_TOOLS = {"{CONSULT_BIN}": "consult", "{CODEGEN_BIN}": "codegen",
+             "{RESEARCH_BIN}": "tezgah-research", "{ROUTE_BIN}": "tezgah-route",
+             "{SKILL_BIN}": "tezgah-skill", "{DESIGN_BIN}": "tezgah-design",
+             "{TASK_BIN}": "tezgah-task", "{PONY_BIN}": "tezgah-pony",
+             "{ADHD_BIN}": "tezgah-adhd", "{LESSONS_BIN}": "tezgah-lessons",
+             "{STATUS_BIN}": "tezgah-status"}
+
 PONYTAIL = """
 ## Code style: ponytail (auto-armed, tezgah roots only)
 
@@ -45,7 +57,7 @@ On the FIRST non-trivial coding task of the session, load the full skill with
 Skill(tezgah:ponytail) on Claude, or the installed `ponytail` skill on every
 other host - the plugin name is part of the skill name on Claude, and this
 summary is not the whole contract.
-Level: `tezgah-pony lite|full|ultra` (bare call shows it; stored in
+Level: `{PONY_BIN} lite|full|ultra` (bare call shows it; stored in
 ~/.config/tezgah/ponytail.level, machine-wide until changed). The default `full`
 adds nothing to this reminder; a non-default level is named in it every turn.
 Off: user says "stop ponytail".
@@ -66,7 +78,11 @@ The reader has to act on the answer, and the friction between "got it" and
    line - never also narrate the plan as prose.
 4. End with the approval questions the Ask policy leaves (the executive mode's
    "Ask policy"), or with nothing when none is left. A step you can take
-   yourself is taken, never handed over.
+   yourself is taken, never handed over: "run `pytest -q` and tell me what it
+   says" is a step you run. In the host's plan mode nothing can run, and there
+   the plan is the deliverable: the approval question is the one question that
+   turn asks, every step waits for it, and nothing is reported as done or
+   tested, because nothing ran.
 5. Suppress tangents: finish the issue in hand, then raise the second as its own
    question. A question the reader raised mid-work is not a tangent - answer it
    and fold the result in.
@@ -88,7 +104,7 @@ no closer), or when a rule would delete the answer itself (an options question
 gets 2-4 ranked options with one line of trade-off each, recommendation first).
 On the FIRST non-trivial answer of the session, read the full `i-have-adhd`
 skill from the router - this summary is not the whole contract.
-Off: `tezgah-adhd off` (the kill switch file), or a repo's `.no-adhd`.
+Off: `{ADHD_BIN} off` (the kill switch file), or a repo's `.no-adhd`.
 """
 
 SPEC = """
@@ -111,7 +127,8 @@ intuitive". Such a request is NEVER built from a guess. Before any code:
 3. Ask at most three blocking questions, the ones that change the outcome and
    that no default may take. Every other question goes in the approval batch
    with a recommended default, and the work proceeds on the defaults in the
-   same turn (the executive mode's "Ask policy").
+   same turn (the executive mode's "Ask policy"); a class-F item waits for the
+   answer.
 4. Verify design, behavior and quality claims against an external source, never
    from memory alone: `{CONSULT_BIN} --online "<question>"` for a fast second
    opinion, or the OpenResearch CLI (`{ORX_BIN}`) when it is a real
@@ -179,7 +196,8 @@ REPLY_LANG_HOOKLESS = dict(
        "{GRANT_EXAMPLES}": "%s, %s" % (_EN["grant_examples"], _TR["grant_examples"]),
        "{OPENER_SHORT}": _TR["opener_short"]},
     **{"{%s_GLOSS}" % k.upper(): "tr: %s; " % _TR[k]
-       for k in ("decision", "access", "irreversible", "env")})
+       for k in ("decision", "access", "irreversible", "env")},
+    **{ph: "~/.config/tezgah/bin/" + name for ph, name in BIN_TOOLS.items()})
 
 EXEC = """
 ## Reporting contract: executive mode (auto-armed, tezgah roots only)
@@ -260,11 +278,11 @@ rewrite it plainly.
 **Merge authority: standing, not per-PR.** The user is not the approval step
 on a merge. Review first with a FRESH reviewer (never my own read of my own
 code), run the full suite, and if the review is clean and every test passes,
-merge and close the plan yourself (`tezgah-task close NNN done`, which also
+merge and close the plan yourself (`{TASK_BIN} close NNN done`, which also
 deactivates it and removes every merged worktree), then report the outcome. Nothing
 goes back to the user: a failing test you fix, and a critical or major finding
 left after round two you fix yourself, prove with a test and close with
-`tezgah-task close NNN done --resolved "<fix and test>"`. One review per plan, over its whole diff in the verification
+`{TASK_BIN} close NNN done --resolved "<fix and test>"`. One review per plan, over its whole diff in the verification
 phase; at most two rounds - only a confirmed critical or major finding opens
 round two; a minor or suggestion one is fixed in the session without a new
 round, or recorded fix-later only when it waits on a user decision ({DECISION});
@@ -273,10 +291,15 @@ after round two what is left is fixed by the session and closed with
 A round spawns its reviewers in ONE message, one per dimension (correctness
 and contract, security, tests and performance) or file group; a diff under 300
 changed lines gets one reviewer. Per-task work gets tests, not a reviewer, and
-`tezgah-task review` refuses a third round.
+`{TASK_BIN} review` refuses a third round. No fresh subagent, no review verdict:
+on a host or mode that cannot start a fresh reviewer, say so and ask the owner;
+never record a verdict from your own read. The author contests a confirmed
+finding only by citing evidence the reviewer could read (file:line); knowledge
+outside the files goes to the owner as a question, and the author never lowers
+a severity.
 
 **The process is yours: never hand a step back.** The orchestrator runs the
-plan lifecycle itself - `tezgah-task start`, every `phase` move, `review`,
+plan lifecycle itself - `{TASK_BIN} start`, every `phase` move, `review`,
 `close`, the merge, and removing a slice's worktree once its branch is merged -
 and never ends a reply with "run this command" or "shall I close it?" for a
 step it can take. A process parameter the user did not set (a sample size, a
@@ -301,13 +324,13 @@ whether the user already decided it (named it this session, or granted it).
 | C. Reversible choice the evidence settles | a fix's scope inside the ask, naming, a palette when tokens exist | decide from evidence; real taste goes in the batch with a default, taken this turn |
 | D. Intent fork | two readings of the ask with different deliverables | batch with a default; do the shared part first and proceed on the default |
 | E. Outward on the user's own remote | push, PR, tag, release, publishing the user's own package | act on a grant written in chat ({GRANT_EXAMPLES}); else ask once per session, never again after a grant |
-| F. Never on a default | force push or history rewrite on a shared ref; deleting data the session did not make; production deploy, stop or migration; a credential, account or identity change; sending to a third party; a spend over `spend_cap`; building a plan this turn wrote from a research, analysis, review or plan ask | do all other work first, ask, and wait: silence is no consent, and only an answer that names the action and its target clears it |
+| F. Never on a default | force push or history rewrite on a shared ref; deleting data the session did not make; production deploy, stop or migration; a credential, account or identity change; sending to a third party; a spend over `spend_cap`; building a plan this turn wrote from a research, analysis, review or plan ask; 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) | do all other work first, ask, and wait: silence is no consent, and only an answer that names the action and its target clears it |
 | G. {ACCESS} | a credential or grant no tool supplies | take every route that needs none first, then ask once, naming what it unlocks |
 
 A grant is read from the user's prompt and recorded for the session; "artık
 bana sor", "ask me again" or a later "don't push" lifts it. The batch is one
 block in the reply language: one "{APPROVAL_HEADING}" heading, one line saying
-the work proceeds on the defaults when no answer comes, then numbered items -
+the work proceeds on the defaults when no answer comes (a class-F item waits for its answer), then numbered items -
 the question in bold, one line of context, "{RECOMMENDED}:" the default, and
 the other option. Class-F items come first, marked as waiting; the defaulted
 items follow, with no count cap, because they do not block. An ask tool (omp
@@ -378,9 +401,9 @@ that slice writes - and declares its checkout on a `Worktree: <abs path>` line;
 the gate refuses a sibling's write into those globs and a slice's write into
 the main checkout when its brief declares a worktree. The integrator
 owns the shared append points (CHANGELOG.md, MANIFEST, the citation baseline)
-and merges in the order `tezgah-task slice merge-plan` prints. Siblings message
+and merges in the order `{TASK_BIN} slice merge-plan` prints. Siblings message
 each other (omp `write agent://<id>`, Claude `SendMessage`) only on an interface
-or ownership change; status goes to the parent, and `tezgah-task slice board`
+or ownership change; status goes to the parent, and `{TASK_BIN} slice board`
 shows every sibling's lease. Only a single item - one file, one
 bounded change, a strictly serial chain - is done directly; a list of
 independent items is never worked one by one on the main thread, however small
@@ -388,13 +411,13 @@ each item is, and that holds at every phase: a plan's tasks, its acceptance
 commands and the sources of a survey fan out the same way.
 A slice that needs its own checkout: inside Orca (the session-start `Orca:`
 line) create it with `orca worktree create --name <slug> --parent-worktree
-active --json` and track it with `orca worktree ps --json` or `tezgah-status
+active --json` and track it with `orca worktree ps --json` or `{STATUS_BIN}
 --orca` - a raw `git worktree add` gets no card, terminal tracking or agent
 status in Orca; outside Orca, `git worktree add`. Either way the brief names
 absolute paths under that checkout. A writing slice commits `wip: <step>`
 after each step, so a crash leaves it resumable. A stopped slice (quota, abort,
-cut off) is resumed - `tezgah-task slice resume <id>` - or re-dispatched, never
-silently absorbed inline; run `tezgah-task slice reconcile --prune` before the
+cut off) is resumed - `{TASK_BIN} slice resume <id>` - or re-dispatched, never
+silently absorbed inline; run `{TASK_BIN} slice reconcile --prune` before the
 turn that merged slices ends.
 Routing: `{ROUTE_BIN} "<brief>"` names the worker - tezgah-cheap, -standard or
 -frontier, or the specialist whose whole job the brief is (tezgah-tester,
@@ -402,7 +425,10 @@ Routing: `{ROUTE_BIN} "<brief>"` names the worker - tezgah-cheap, -standard or
 never the host's generic task agent (overrides for stored data, credentials,
 security first; then a Jev judgement; the static phase table with no key). A report missing an output field, or an
 `ESCALATE:`, gets one narrower re-brief of the same role naming that field or judgement; only a second miss is
-restarted on tezgah-frontier with the original brief, never continued; the main thread never switches model (the cache is per model). A
+restarted on tezgah-frontier with the original brief, never continued; the main thread never switches model (the cache is per model).
+A subagent's question only the owner can answer (a class-F item, `ESCALATE: owner`) is relayed to
+the user in the approval batch: the orchestrator never answers it for the user
+and never escalates it to a stronger model. A
 code-discovery brief names codegraph's tools (`codegraph callers`, `callees`,
 `impact`, `node`, `files`, `codegraph_explore`) and says "answer from
 the graph, grep only for literal text"; never a grep-only explorer (observed).
@@ -552,9 +578,9 @@ When the task is research and the OpenResearch CLI (`{ORX_BIN}`) is installed,
 drive it through that CLI instead of ad-hoc local scripting. Load the operating
 manual first: the `orx` skill if the host has it, otherwise run
 `{ORX_BIN} skill` from the shell; then the module the method needs -
-`{ORX_BIN} skill lit-review` for sources, `{ORX_BIN} skill experiment-tree` and
-`{ORX_BIN} skill evidence` for a measured line. On a measured line its cardinal
-rules are not style preferences - they
+`{ORX_BIN} skill lit-review` for sources, `{ORX_BIN} skill experiment-tree`,
+`{ORX_BIN} skill orx-results` and `{ORX_BIN} skill orx-logs` for a measured
+line. On a measured line its cardinal rules are not style preferences - they
 are what keeps results comparable, and breaking one silently invalidates the run:
 never edit a node once a run has answered it (branch a child instead); the run
 command and environment are a fixed contract identical on every node; vary the
@@ -569,6 +595,12 @@ table computed from other rows. The producer declares it - nothing can recover i
 afterwards - and `{RESEARCH_BIN} check` refuses a claim that claims a wider scope
 than the rows it rests on.
 
+Narrowing a claim to what its evidence reaches, ending a hypothesis
+`inconclusive`, and `{RESEARCH_BIN} close <slug> --limit "<what is left>"` are
+normal outcomes of a line, never failures to avoid: a claim's certainty is
+reported as `check` computes it, an exploratory one says so, and `check` warns on
+universal or causal wording its evidence does not carry.
+
 If the CLI is not installed, say the research tooling is unavailable and do not
 improvise its protocol; fall back to a host subagent and say so, briefed with the
 question verbatim, its in- and out-of-scope items and its method. Kill switch:
@@ -809,7 +841,7 @@ one small test); a one-liner needs none. A complex ask ships the lazy version
 and names the fuller one in the same reply instead of stalling. Reply: code
 first; write what was cut only when you consciously cut something the user asked
 for, in at most three lines. In force from the first turn; levels
-lite|full|ultra are set with `tezgah-pony` and ride the per-turn reminder when
+lite|full|ultra are set with `{PONY_BIN}` and ride the per-turn reminder when
 not `full`; read the full `ponytail` skill from the router for the level table
 and examples. Off: "stop ponytail".
 
@@ -820,7 +852,10 @@ bounded action per step, and while it is in flight its position is restated in
 one line - the todo list is that source, never re-narrate the plan. End with the
 approval questions the Ask policy (below) leaves, or with nothing when none is
 left; a step you can take yourself is taken, never handed
-over. Finish the issue in hand before raising a second one; an error states
+over, and in the host's plan mode, where nothing can run, the plan is the
+deliverable: its approval is the question that turn asks and nothing is
+reported as done or tested.
+Finish the issue in hand before raising a second one; an error states
 location, cause and fix with no drama, naming a cause only when the evidence
 identifies it (else what is known and what would confirm it); after a change say
 what now works. A list shows at most five items, ranked, the rest kept in
@@ -835,7 +870,7 @@ assumption and ask one diagnostic question. Before sending, delete an opening
 sentence that announces, a closing one that recaps or asks "anything else?", any
 by-the-way sidebar and any hedge that carries no real uncertainty. In force from
 the first answer; read the full `i-have-adhd` skill from the router for the
-examples. Off: `tezgah-adhd off`, or the repo's `.no-adhd`.
+examples. Off: `{ADHD_BIN} off`, or the repo's `.no-adhd`.
 
 **Deliver the whole ask; never the shortcut.** The request defines the
 deliverable: every named item is in scope until the user says otherwise, and the
@@ -885,15 +920,17 @@ lines: item - blocker - evidence - what unblocks it. No blockers: no heading.
 Work and process - the order, "shall I go on", a check, a plan, a consult
 member, a spend within `spend_cap`, a local merge of the session's branch,
 removing its worktree - are taken and stated in one line, never asked; a taste
-or intent fork goes in the batch with a default taken this turn, but building a
-plan this turn wrote waits for the answer. An outward step
+or intent fork goes in the batch with a default taken this turn, but the
+never-default items below wait for the answer. An outward step
 on the user's own remote (push, PR, release, their package) runs on a grant
 ({GRANT_EXAMPLES}), else is asked once. Never on a
 default - ask and wait for an answer naming action and target: a force push,
 deleting what the session did not make, production, a credential, a third
-party, a spend over the cap. The batch: one "{APPROVAL_HEADING}" heading, waiting
+party, a spend over the cap, building a plan this turn wrote, picking a
+recommended variant, a way around a tezgah refusal, another session's work. The batch: one "{APPROVAL_HEADING}" heading, waiting
 items first, each numbered item with "{RECOMMENDED}:" its default; an ask tool
-sets a recommended option.
+sets a recommended option. No fresh subagent, no review verdict: say so and
+ask. Contest a finding only with a file:line; never lower a severity.
 **Say what a number was measured on.** A figure produced by a fixture - a temp
 HOME, a generated repository, a stand-in, a hand-written sample - is evidence
 about the code path, never a property of the running system, and it is reported
@@ -988,7 +1025,10 @@ If the CLI is not installed, say the research tooling is unavailable and fall
 back to a host subagent briefed with the question verbatim, its in/out scope and
 its method. Off: `research-off`.
 
-**Product analysis: five axes, one evidence class per finding.** A product
+**Product analysis: five axes, one evidence class per finding.** Read the
+`product-analysis` skill for this ask (artifact shape, scorecard), `pm-frameworks`
+for an intended-vs-implemented gap or an Opportunity Solution Tree, and
+`feature-audit` when the ask is one feature. A product
 question - "analyse this product", "why is retention falling", "which feature
 next" - is analysis, not advice, and it covers every axis the product has, not
 only the code. Value: HEART's Goals -> Signals -> Metrics (a metric with no goal
@@ -1017,12 +1057,22 @@ would decide it. Establish first whether the behaviour is observable at all - "w
 cannot see this yet" is the first finding, not a footnote. Every finding names one
 evidence class - `user-verbatim`, `behaviour`, `ui-observed`, `code`, `external` -
 and a finding without one is a question, not a finding. Run it as a research line
-(`{RESEARCH_BIN}`), say what it did not look at, and read the `product-analysis`
-skill for the artifact shape and the scorecard, and `feature-audit` for the
-layer-coherence matrices when the ask is one feature. A new capability built from
+(`{RESEARCH_BIN}`) and say what it did not look at. A new capability built from
 data or an ask runs the `product-flow` skill: `{RESEARCH_BIN} next --topic <t>` is
 the step source, and its first missing or due step is the next one. Off: `research-off`.
 
+**Design: UI work reads the design skills.** A UI ask - build, restyle, critique
+or audit a screen, form, dashboard or design system - reads the `design-contract`
+skill first: `{DESIGN_BIN} derive` writes `.tezgah/design-contract.md` from the
+repo's own tokens and `{DESIGN_BIN} check` measures the change against it.
+`design-library` holds the critique methods (cognitive load, visual hierarchy,
+accessibility); `analyze-app` reads the running UI, the only evidence for a UI
+claim; `feature-audit` covers a form, CRUD or admin flow across its layers; the
+`hallmark` skill builds a new page or restyles one (its own gate list plus
+`{DESIGN_BIN} slop --render` for the machine-made tells). The contract's
+`precedence` block decides which floor owns each key, and ours owns the facts.
+UI build work goes to a worker whose brief loads `design-contract`. Off: `design-off`.
+
 **No AI attribution, ever, on any host.** Nothing persisted or published may
 name the assistant, model, vendor or "AI" as author/co-author/generator/helper:
 commit/merge/tag messages, PR/issue/review comments, `git notes`, release
@@ -1047,14 +1097,14 @@ issue for one of its tools mid-session. Name a missing capability in one line,
 use the documented fallback (grep/find, or the second opinion skipped), and carry
 on with the task in hand. Tezgah maintenance is in scope when the user asks for
 it, or when the repo IS the tezgah checkout. Before working a topic an
-installed skill covers, run `tezgah-skill <words>` and read only the range it
+installed skill covers, run `{SKILL_BIN} <words>` and read only the range it
 returns.
 
 **Workspace: `.tezgah/` only.** Every per-project tezgah artifact - plans,
-research lines, analysis, lessons - lives under `<repo>/.tezgah/`, which the
-project's `.gitignore` excludes and which keeps its own private git repository
-(`git -C .tezgah ...`). Never create `plans/`, `research/` or `analysis/` at the
-project root and never `git add -f` anything under `.tezgah/`. Off:
+research lines, analysis, lessons - lives under `<repo>/.tezgah/`, ignored by
+the project, committed with `git -C .tezgah ...` - or, if the project tracks
+it, plain `git add`/`git commit`. Never create `plans/`, `research/` or
+`analysis/` at the project root and never `git add -f` under `.tezgah/`. Off:
 `workspace-off`.
 
 **Parallel by default: fan out independent items.** A request with two or
@@ -1076,7 +1126,7 @@ not grow. Every writing brief names its `Owns:` globs and declares its
 checkout on a `Worktree: <abs path>` line, and siblings message
 each other only on an interface or ownership change. Read-only slices need no
 worktree. Once a slice's branch is merged,
-its worktree goes in the same turn - `tezgah-task close` removes every merged
+its worktree goes in the same turn - `{TASK_BIN} close` removes every merged
 one, and outside a plan `orca worktree rm --worktree path:<p>` (else `git
 worktree remove <p>`) does it; never leave one for the user to find. Pick each agent by task class from
 the specialists line; `{ROUTE_BIN}` names the tier for code work. Serialize
@@ -1085,11 +1135,13 @@ edit one file - and say which. The todo list is the step queue: dispatch every
 ready step at once and mark each one blocked on its slice, never `wait` while
 a step is ready, and once every open step is blocked on a running slice,
 `wait` or end the turn. A subagent does its own slice and
-never fans out again. Off: `orchestrate-off`.
+never fans out again; its question only the owner can answer (a never-default
+item) goes to the user in the approval batch, never answered by the
+orchestrator or escalated to a stronger model. Off: `orchestrate-off`.
 
 **Kill switches:** each one removes its own rule from this text, not just the
 status mark. `~/.config/tezgah/`: `exec-mode.off`, `orchestrate-off`,
-`consult-off`, `research-off`, `ponytail-auto.off`, `adhd-off`, `spec-off`,
+`consult-off`, `research-off`, `ponytail-auto.off`, `adhd-off`, `spec-off`, `design-off`,
 `reminder-off`, `verify-off` (the integrity rule: its prompt text, the shortcut
 denials and the Stop gate), `task-off` (the task rule), `judge-off` (the
 judgement seam: the triage, the docs fallback and the skill hint), `triage-off`,
@@ -1097,32 +1149,49 @@ judgement seam: the triage, the docs fallback and the skill hint), `triage-off`,
 rule), `workspace-off` (the root plans/research/analysis refusal),
 `pretooluse-off` (the whole gate);
 per-repo `.no-ponytail`, `.no-adhd`, `.no-graph`, `.no-lessons`.
-The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
+The ponytail intensity level is not a switch: `{PONY_BIN} lite|full|ultra`.
 """
 
 # Rules that are NOT paid every session. They are armed by task class at prompt
 # time (hooks/tezgah_context.classify_prompt), because a session that never asks
 # a structural or research question should not carry their text. Keys match the
 # CORE_RULES labels in hooks/tezgah_context.py.
-CONDITIONAL_KEYS = ("spec", "consult", "research", "product", "graph", "fanout")
-
-# The fan-out rule's action, which the one-line repeat of an armed paragraph
-# (hooks/tezgah_context.armed_again) carries: a bare "Armed again" named a rule
-# the session had to recall, and the second list of a session was worked one
-# item at a time. It is the paragraph's own clause, cut to one sentence.
-FANOUT_ACTION = ("count the independent items, spawn one subagent per item in "
-                 "ONE message, each the agent `tezgah-route` names - a specialist "
-                 "by name, never the generic task agent - (each writing slice in "
-                 "its own worktree, absolute paths), and keep the main thread for "
-                 "integrating and verifying; the todo list is the step queue, so "
-                 "dispatch every ready step before any `wait`; a subagent does "
-                 "its own slice and never fans out again.")
+CONDITIONAL_KEYS = ("spec", "consult", "research", "product", "design", "graph",
+                    "fanout")
+
+# The action the one-line repeat of an armed paragraph
+# (hooks/tezgah_context.armed_again) carries instead of a bare "Armed again":
+# that named a rule the session had to recall, so the second list of a session
+# was worked one item at a time, and the product skills were named on 3 turns of
+# a 40-turn session against 20 in fresh ones (plan 126). Each is the paragraph's
+# own clause, cut to one sentence; the product and design lines keep the
+# paragraph's condition, because the hint that armed them is a word match and a
+# misfire must not become an order to read a skill the ask has no use for.
+ARMED_ACTIONS = {
+    "fanout": "count the independent items, spawn one subagent per item in "
+              "ONE message, each the agent `{ROUTE_BIN}` names - a specialist "
+              "by name, never the generic task agent - (each writing slice in "
+              "its own worktree, absolute paths), and keep the main thread for "
+              "integrating and verifying; the todo list is the step queue, so "
+              "dispatch every ready step before any `wait`; a subagent does "
+              "its own slice and never fans out again. The full rule is in the "
+              "`tezgah-contract` skill.",
+    "product": "if this ask is a product question, read the "
+               "`product-analysis` skill now - `pm-frameworks` for an "
+               "intended-vs-implemented gap or an Opportunity Solution Tree, "
+               "`feature-audit` for one feature, `analyze-app` for the running "
+               "app, `product-flow` for a new capability.",
+    "design": "if this ask is UI work, read the `design-contract` skill now - "
+              "`design-library` for critique methods, `analyze-app` for the "
+              "running UI, `feature-audit` for a form or admin flow; UI build "
+              "work goes to a worker whose brief loads `design-contract`.",
+}
 
 # The always-on replacement for the conditional paragraphs: one line each so a
 # host without a per-turn hook still knows the rule exists and where the full
 # text lives.
 POINTERS = """
-**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding. The code graph for "who calls X" and "what breaks if Z changes". Two or more independent items fan out to parallel subagents in one message, one git worktree per writing slice. The design floor a UI turn is judged against is `.tezgah/design-contract.md`: `tezgah-design derive` writes it from the repository's own tokens, `tezgah-design check` measures a change against it, and the `design-contract` skill owns its shape.
+**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding (`product-analysis`, `pm-frameworks`). The code graph for "who calls X" and "what breaks if Z changes". Two or more independent items fan out to parallel subagents in one message, one git worktree per writing slice. A UI turn reads the `design-contract` skill (`design-library`, `analyze-app`) and is judged against `.tezgah/design-contract.md`: `{DESIGN_BIN} derive` writes it from the repository's own tokens and its `check` measures a change against it.
 """
 
 # The compact per-turn form, inside the <harness-reminder> envelope the hosts
@@ -1138,7 +1207,9 @@ irreversible calls; done/tested claims need observed
 evidence -> the gate denies a neutered check (`--no-verify`, `|| true`, a new
 test skip) and the Stop hook on Claude/Codex/Cursor/omp blocks an unverified
 "done"; never end on a question you can decide - ask only in one batch, each
-with a recommended default; leftover work is done now, not listed - only a {DECISION}/{ACCESS}/{IRREVERSIBLE}/{ENV}
+with a recommended default; a research/analysis/review recommendation, a way around a
+tezgah refusal and another session's work wait for the owner's answer;
+leftover work is done now, not listed - only a {DECISION}/{ACCESS}/{IRREVERSIBLE}/{ENV}
 blocker with its evidence goes under "{BLOCKERS_HEADING}"; no
 AI/model attribution in any persisted or published artifact. Full
 detail: the tezgah-contract skill.{PONY_LEVEL} Kill switches under ~/.config/tezgah/.

package/hooks/tezgah_rank.py

@@ -44,12 +44,14 @@ STOPWORDS = frozenset(w for p in packs().values() for w in p["rank_stopwords"])
 MIN_CAP_TEXTS = 10
 
 
-def scores(query, texts, max_df=None):
+def scores(query, texts, max_df=None, tokens=None):
     """Every text's BM25 score for `query`, in input order; 0.0 for a text that
     shares no term with it. `rank` orders these; the research dedup reads them as
-    numbers (`tezgah_research.similarity_matrix`)."""
-    docs = [Counter(words(t)) for t in texts]
-    terms = set(words(query))
+    numbers (`tezgah_research.similarity_matrix`). `tokens` replaces `words` on
+    both sides (the skill search folds and stems its terms)."""
+    tokens = tokens or words
+    docs = [Counter(tokens(t)) for t in texts]
+    terms = set(tokens(query))
     if not docs or not terms:
         return [0.0] * len(docs)
     avg = sum(sum(d.values()) for d in docs) / len(docs) or 1.0
@@ -68,12 +70,13 @@ def scores(query, texts, max_df=None):
     return out
 
 
-def rank(query, texts, k, max_df=None):
+def rank(query, texts, k, max_df=None, tokens=None):
     """Indices of the `k` texts that score highest for `query`, best first.
 
     Only a text sharing at least one term with the query is returned (score > 0),
     so an unrelated query gets [] rather than an arbitrary order. `max_df` (a
     fraction) drops STOPWORDS and, on MIN_CAP_TEXTS or more texts, every query
     term found in more than that share of them."""
-    scored = [(-s, i) for i, s in enumerate(scores(query, texts, max_df)) if s > 0]
+    scored = [(-s, i) for i, s in enumerate(scores(query, texts, max_df, tokens))
+              if s > 0]
     return [i for _s, i in sorted(scored)[:k]]

package/hooks/tezgah_replay.py

@@ -469,6 +469,9 @@ def build_corpus(cutoff, since=None):
                     "live_rule": rule_of(detail) if kind == "deny"
                     else detail.split(":", 1)[1].strip() if kind == "claim"
                     and detail.startswith("blocked:") else None,
+                    # the host's permission mode, written on the row of a
+                    # read-only turn only (plan 142): the verdict depended on it
+                    "mode": row.get("mode"),
                     "tool": row.get("tool"), "join": None}
             if kind == "claim":
                 replies = [{"ts": ts, "text": text, "cwd": where} for ts, text, where in
@@ -586,8 +589,11 @@ def _replay_one(it, prefix, tg, seen, live_events):
 
             ti.events = events
             try:
-                cls, _reason = ti._stop_block(it["text"], it["sid"], rows=turn,
-                                              cwd=it["cwd"])
+                # a plan-mode turn is judged as one (plan 142): the mode rides
+                # the claim row this item came from
+                cls, _reason = ti._stop_block(
+                    it["text"], it["sid"], rows=turn, cwd=it["cwd"],
+                    read_only=ti.read_only_turn(it.get("mode")))
             finally:
                 ti.events = live_events
             out.update(replay="block" if cls else "allow", rule=cls,
@@ -598,10 +604,10 @@ def _replay_one(it, prefix, tg, seen, live_events):
             reason = tg.decision(it["tool"], inp, it["cwd"], it["sid"], record=False)
             rule = (rule_of("%s: %s" % (seen[-1], reason)) if seen else "unobserved") \
                 if reason else None
-            writers = sorted({w for p in tg.write_paths(inp)
-                              for w in ti.writers_elsewhere(p, it["sid"],
-                                                            tg.RACE_WINDOW_MIN,
-                                                            cwd=it["cwd"])})
+            # the writers the live race rule refuses on (`race_writers`), as the
+            # ledger ids the page has always shown (plan 117)
+            writers = sorted({w[0] for _path, others in tg.race_writers(
+                inp, it["sid"], it["cwd"]) for w in others})
             out.update(replay="deny" if reason else "allow", rule=rule,
                        writers=writers)
     except Exception as exc:  # a crash is a result, never a silent allow