@r1z4x/tezgah 1.0.0 → 1.2.0

package/hooks/tezgah_orca.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Orca: is this session inside it, which CLI drives it, and what it tracks.
+
+Orca (an IDE for agent sessions) owns worktrees, terminals, its embedded browser
+and artifacts, and it exports its own markers into every terminal it starts.
+tezgah reads those markers - never writes them - so a session in Orca is told to
+create a checkout with `orca worktree create` rather than a raw `git worktree
+add` Orca does not list, and `tezgah-status --orca` shows which of a repo's
+checkouts Orca tracks. Stdlib only; detection forks nothing, so the session-start
+line costs no process. docs/orca.md is the page.
+"""
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+# The markers an Orca terminal exports (observed in Orca 1.4.221's env). Any one
+# is enough; TERM_PROGRAM=Orca covers a shell that dropped the ORCA_* set.
+MARKERS = ("ORCA_WORKTREE_ID", "ORCA_TERMINAL_HANDLE", "ORCA_PANE_KEY")
+MAC_APP_CLI = "/Applications/Orca.app/Contents/Resources/bin/orca"
+# The file Orca leaves in each per-account codex home it hands out as CODEX_HOME.
+MANAGED_HOME = ".orca-managed-home"
+
+
+def session(env=None):
+    """{worktree, terminal, version} when this process runs in an Orca terminal,
+    else None. `worktree` is the path half of ORCA_WORKTREE_ID
+    (`<repoId>::<path>`)."""
+    env = os.environ if env is None else env
+    if not any(env.get(k) for k in MARKERS) and env.get("TERM_PROGRAM") != "Orca":
+        return None
+    return {"worktree": env.get("ORCA_WORKTREE_ID", "").partition("::")[2],
+            "terminal": env.get("ORCA_TERMINAL_HANDLE", ""),
+            "version": env.get("ORCA_APP_VERSION", "")}
+
+
+def cli(env=None, platform=None):
+    """The argv prefix that runs Orca's CLI, or None. The order is the orca-cli
+    skill's: Orca's own ORCA_CLI_COMMAND (WSL), then its exported bin dir, then
+    PATH. On Linux outside an Orca terminal a bare `orca` is the GNOME screen
+    reader, so only `orca-ide` counts there. TEZGAH_ORCA_BIN pins one binary
+    (tests): a missing one is None, never a fallback to the real app."""
+    env = os.environ if env is None else env
+    platform = platform or sys.platform
+    pinned = env.get("TEZGAH_ORCA_BIN")
+    if pinned:
+        return [pinned] if os.access(pinned, os.X_OK) else None
+    if env.get("ORCA_CLI_COMMAND"):
+        return shlex.split(env["ORCA_CLI_COMMAND"])
+    bindir = env.get("ORCA_CLI_BIN_DIR")
+    if bindir and os.access(os.path.join(bindir, "orca"), os.X_OK):
+        return [os.path.join(bindir, "orca")]
+    path = env.get("PATH", os.defpath)
+    name = ("orca-ide" if platform.startswith("linux") and not session(env)
+            else "orca")
+    found = shutil.which(name, path=path)
+    if found:
+        return [found]
+    if platform == "darwin" and os.access(MAC_APP_CLI, os.X_OK):
+        return [MAC_APP_CLI]
+    return None
+
+
+def run(args, timeout=10):
+    """`orca <args> --json`'s `result`, or None when there is no CLI, the
+    runtime is down or the answer is not `ok`."""
+    argv = cli()
+    if not argv:
+        return None
+    try:
+        proc = subprocess.run(argv + list(args) + ["--json"], capture_output=True,
+                              text=True, timeout=timeout)
+        data = json.loads(proc.stdout)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    return data.get("result") if isinstance(data, dict) and data.get("ok") else None
+
+
+def checkouts(paths):
+    """Orca's view of a repository's git checkouts (`paths`, real paths):
+    {"tracked": [row per checkout Orca lists], "untracked": [path Orca does not
+    list]}, or None when the runtime cannot answer. Read from `orca worktree ps`,
+    the one call that carries terminals and agent states together."""
+    ps = run(["worktree", "ps", "--limit", "1000"])
+    if ps is None:
+        return None
+    wanted = set(paths)
+    tracked = {}
+    for row in ps.get("worktrees") or []:
+        path = os.path.realpath(row.get("path") or "")
+        if path in wanted:
+            tracked[path] = {
+                "path": path, "name": row.get("displayName") or "",
+                "card": row.get("workspaceStatus") or "",
+                "status": row.get("status") or "",
+                "terminals": row.get("liveTerminalCount") or 0,
+                "agents": ["%s:%s" % (a.get("agentType"), a.get("state"))
+                           for a in row.get("agents") or []]}
+    return {"tracked": [tracked[p] for p in paths if p in tracked],
+            "untracked": [p for p in paths if p not in tracked]}
+
+
+def context_line(env=None):
+    """The session-start line for a session inside Orca, or "" outside it."""
+    here = session(env)
+    if not here:
+        return ""
+    where = here["worktree"] or "unknown"
+    return ("Orca: this session runs in an Orca terminal (worktree `%s`); Orca "
+            "owns worktrees, terminals, its embedded browser and artifacts here. "
+            "A parallel slice that needs its own checkout gets one from `orca "
+            "worktree create --name <slug> --parent-worktree active --json` (add "
+            "`--agent <cli> --prompt <brief>` to start its worker there), not "
+            "`git worktree add`, which Orca does not list. A long job runs in "
+            "`orca terminal create --worktree <selector> --command <cmd> --json`, "
+            "not a background shell. Track with `orca worktree ps --json` and "
+            "`tezgah-status --orca`; mark checkpoints with `orca worktree set "
+            "--worktree active --comment <text>`. Full guide: `orca skills get "
+            "orca-cli`." % where)
+
+
+def summary(codex_home):
+    """One `orca:` line for `tezgah-setup --status`: app/runtime, whether this
+    shell is in an Orca terminal, and whose codex home CODEX_HOME names; ""
+    when Orca is neither installed nor around this shell."""
+    argv, here = cli(), session()
+    if not argv and not here:
+        return ""
+    runtime = ((run(["status"]) or {}).get("runtime") or {}) if argv else {}
+    parts = ["orca: %s" % (
+        "runtime %s reachable" % runtime.get("appVersion", "")
+        if runtime.get("reachable") else
+        "CLI %s, runtime not reachable (`orca open`)" % argv[-1] if argv else
+        "no orca CLI found")]
+    parts.append("this shell runs in an Orca terminal (worktree %s)"
+                 % (here["worktree"] or "unknown") if here
+                 else "this shell is not an Orca terminal")
+    if os.path.isfile(os.path.join(codex_home, MANAGED_HOME)):
+        parts.append("CODEX_HOME %s is an Orca-managed codex home: tezgah adds "
+                     "its hook groups beside Orca's and leaves Orca's entries "
+                     "and env alone" % codex_home)
+    return "; ".join(parts)

package/hooks/tezgah_paths.py

@@ -497,18 +497,23 @@ def have_typesafe_key():
 
 
 def have_judge_key():
-    """True when tezgah's own judgement seam resolves a credential: the env var
-    it reads, else its key file - and, when neither resolves, the OpenRouter
-    fallback's own two channels (`OPENROUTER_API_KEY`, `~/.config/openrouter/key`),
-    which are the channels `hooks/tezgah_judge.py`'s `credential()` picks
-    between. This is what `bin/tezgah-triage`, `bin/tezgah-docs` and the skill
-    picker spend. Never omp's login store: the seam does not open it.
+    """True when tezgah's own judgement seam can ask anyone: the session's own
+    CLI (`session_cli()`), else - when the `fallback` setting lets a third party
+    answer - the TypeSafe env var or key file, then the OpenRouter fallback's own
+    two channels (`OPENROUTER_API_KEY`, `~/.config/openrouter/key`), which are
+    the channels `hooks/tezgah_judge.py`'s `providers()` picks between. This is
+    what `bin/tezgah-triage`, `bin/tezgah-docs` and the skill picker spend. Never
+    omp's login store: the seam does not open it.
 
     Kept next to `have_typesafe_key()` because the two are asked together and a
     report that showed one answer under both questions was wrong in both
     directions - a key file alone (seam works, omp does not) and a login-store
     record alone (omp works, seam does not). A blank file is not a credential
     here either, so this stays in step with the seam's own `strip() or None`."""
+    if session_cli():
+        return True
+    if fallback_policy() == "none":
+        return False
     for env, home in (("TYPESAFE_API_KEY", ".config/typesafe/key"),
                       ("OPENROUTER_API_KEY", ".config/openrouter/key")):
         if os.environ.get(env, "").strip():
@@ -522,6 +527,35 @@ def have_judge_key():
     return False
 
 
+# How far a model call may leave the session's own vendor (config.json
+# `fallback`). `vendor`, the default: the session's own model first, and a
+# fallback only to the same vendor's model (a subagent chain may reach Opus
+# through OpenRouter; the judge has no such route, so it falls back to nobody
+# while the session CLI exists, and to a third party only when there is no
+# session CLI at all). `any`: a cross-vendor fallback is allowed after the
+# session's own model fails. `none`: no provider but the session's, ever.
+FALLBACKS = ("vendor", "any", "none")
+
+
+def fallback_policy():
+    """The configured `fallback` value, `vendor` when unset or unknown."""
+    cfg = config()
+    value = cfg.get("fallback") if isinstance(cfg, dict) else None
+    return value if value in FALLBACKS else "vendor"
+
+
+def session_cli():
+    """`omp` or `claude` - the CLI of the host this process runs under, when it
+    is installed - else None. omp sets CLAUDECODE too, so OMPCODE is read first,
+    and an omp session whose binary is missing is None rather than Claude: the
+    session's credential is omp's, not whatever `claude` is logged in as."""
+    if os.environ.get("OMPCODE"):
+        return "omp" if omp_bin() else None
+    if os.environ.get("CLAUDECODE"):
+        return "claude" if claude_bin() else None
+    return None
+
+
 def orx_bin():
     """The OpenResearch `orx` executable, or None when it is not installed.
 

package/hooks/tezgah_policy.py

@@ -273,13 +273,25 @@ discovery, review, impact analysis (research goes to OpenResearch - see the
 Research section - with a host subagent only as the fallback when `orx` is
 absent). Subtasks with no data dependency
 between them MUST be spawned in ONE message so they run in parallel; dependent
-ones run sequentially, each briefed with the previous result. Fan out only when
+ones run sequentially, each briefed with the previous result. Fanning out is the
+default, not a favour the user has to ask for: two or more independent items -
+a list, several files or areas, todo entries that share nothing - go to one
+subagent each, and every writing slice gets its own branch and checkout (see
+below), never the main checkout. The
+orchestrator is the main thread itself: it does not wait idle on a slice while
+independent work remains. Fan out only when
 the subtasks share no mutable file and no interface: if two of them would edit
 the same file, or one's answer decides the other's, keep them in one context or
 sequence them. The shared artifact is the coordination channel, not chatter -
 naming a lead coordinates nothing by itself. If the work
 cannot be split - one file, one bounded change, a strictly serial chain - do it
 directly. Never spawn a subagent whose briefing is bigger than the work.
+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
+--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.
 Routing: `{ROUTE_BIN} "<brief>"` names the worker - tezgah-cheap, -standard or
 -frontier (overrides for stored data, credentials, security first; then a Jev
 judgement; the static phase table with no key). A worker that answers
@@ -400,12 +412,30 @@ experiments/variants, or producing a research artifact (report, figure, dataset)
 It is NOT "where is X defined" or "who calls Y" - that is code discovery and
 stays on the codegraph index.
 
+**Lock the line to the question asked.** Restate the user's question verbatim as
+the line's scope (`--ask`) and name what is in it and what is out (`--in`,
+`--out`: state.json `scope`). Every finding answers an in-scope item - a claim's
+`trace` names its `S<n>`, and `{RESEARCH_BIN} check` refuses one that names none -
+and a finding that answers nothing asked is dropped, not reported as a bonus. Do
+not widen the question, add sub-questions or chase an adjacent topic; a tangent
+worth having is one line under Open questions for the user to pick. The question
+picks the method, not the tooling: a qualitative, conceptual or reference question
+is a source review (`--method qualitative`: no metric, no experiment), and a
+metric, a locked evaluation and the experiment tree belong only to a question
+whose answer is a measurement (`--method measured`). A plain factual or reference
+question gets no line at all: answer it in the reply from primary sources. Depth
+is the primary source read, not more breadth - the spec, the paper, the code, the
+vendor's own documentation - each finding citing the source it rests on and
+stating its confidence (high, medium or low, and why); a summary of summaries is
+not an answer.
+
 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 named modules (`{ORX_BIN} skill experiment-tree`, `{ORX_BIN} skill lit-review`,
-`{ORX_BIN} skill evidence`, ...). Its cardinal rules are not style preferences - they
+`{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
 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
@@ -420,7 +450,8 @@ afterwards - and `{RESEARCH_BIN} check` refuses a claim that claims a wider scop
 than the rows it rests on.
 
 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. Kill switch:
+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:
 `research-off`.
 
 Keep the line auditable in the repository, not in your head:
@@ -437,11 +468,13 @@ into a refusal. A report owes an independent review (`reviewer` is not the
 construct and conclusion validity threats, whatever `phase` says. `state.json`
 `deliverable` names what the line delivers and lists the ask's items, each
 answered in the report, a decision or a claim `trace`, or written `A<n> not
-delivered: <reason>`. A design, plan or analysis is produced as >= 3 variants in
+delivered: <reason>`. A design or plan the user will choose between is produced
+as >= 3 variants in
 `decisions/<id>/` - `criteria.json` committed before any cell, `variants.jsonl`
 (V0 the status quo), cells appended by `{RESEARCH_BIN} compare`, `decision.md`
 naming the chosen id, each rejected id with the criterion that ruled it out, and a
-`flip:` condition; a new version of a line is opened `init --supersedes <old>` and
+`flip:` condition (an analysis answers its question once); a new version of a
+line is opened `init --supersedes <old>` and
 carries the old one as a variant. Code or config variants are sibling orx nodes
 under one head node. Literature is found with `{ORX_BIN} discover` and read with
 `{ORX_BIN} paper`; an agent's summary is indexed as `agent-report` and never alone
@@ -602,7 +635,7 @@ prefers shell tools; that preference does NOT cover definitions, callers, or
 blast radius - those go to the graph. The graph answers from a parsed call
 graph, so it beats text search on renames, dynamic dispatch and cross-file
 callers. On Claude a PreToolUse hook denies the Explore subagent here and nudges
-the first identifier-shaped Grep per session toward the graph. The MCP tool's
+the first code-symbol search per session toward the graph. The MCP tool's
 schema is deferred: on the FIRST code-discovery step of the session load it -
 ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore")
 (the plain name on a checkout's own server, the `plugin_tezgah_` one on a plugin
@@ -645,27 +678,40 @@ it - no apology theater, no self-justifying phrasing.
 **Ponytail (minimal code).** Laziest solution that works: YAGNI -> reuse an
 existing helper -> stdlib -> native platform feature -> installed dependency ->
 one line -> minimum code. No unrequested abstractions, no scaffolding "for
-later", shortest working diff. Trace the problem fully before climbing; never
-simplify away validation, error handling, security or anything requested. Bug
-fix = root cause where all callers route through. A deliberate corner cut gets
-a `ponytail:` comment naming the ceiling. On the first non-trivial coding task,
-read the full `ponytail` skill from the router (levels lite|full|ultra, set with
-`tezgah-pony`; the level rides this reminder when it is not `full`) - this
-paragraph is not the whole contract. Off: "stop ponytail".
+later", deletion over addition, fewest files, shortest working diff. Trace the
+problem fully before climbing; never simplify away validation, error handling,
+security, accessibility or anything requested, and build the full version
+without re-arguing when the user insists. Bug fix = root cause where all
+callers route through. A deliberate corner cut gets a `ponytail:` comment
+naming the ceiling. Non-trivial logic leaves ONE runnable check (an assert
+self-check or 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, then at most three lines - what was skipped, when to add it.
+In force from the first turn; levels lite|full|ultra are set with `tezgah-pony`
+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".
 
 **Output shape: ADHD-friendly.** The answer or the next action is on the first
-line, prose after it. Multi-step work is a numbered list, one 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 one concrete next step.
-Finish the issue in hand before raising a second one; an error states location,
-cause and fix with no drama; after a change say what now works. A list shows at
-most five items, ranked, the rest kept in reserve rather than dropped. An
+line - a command, path, snippet or the decision itself, never context or the
+question restated - prose after it. Multi-step work is a numbered list, one
+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 one
+concrete next step. 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 reserve rather than dropped - presentation only, never the analysis. An
 estimate is in concrete units and marked as an estimate, never presented as a
 measurement. No preamble, no recap, no closer, and a question the reader raises
-mid-work is answered rather than deferred as the second issue. On the FIRST
-non-trivial answer of the session, read the full `i-have-adhd` skill from the
-router - this paragraph is not the whole contract. Off: `tezgah-adhd off`, or
-the repo's `.no-adhd`.
+mid-work is answered rather than deferred as the second issue. Break the shape
+only where it would delete the answer: an explanation runs as long as it needs,
+with headers; an options question gets two to four ranked options,
+recommendation first; after three "still broken" turns, name the suspect
+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`.
 
 **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
@@ -756,19 +802,30 @@ Off: `consult-off`.
 
 **Research: route it to OpenResearch.** When a task is research - a literature
 or reference review, forming and testing hypotheses, running or comparing
-experiments, producing a research artifact - drive it through the OpenResearch
-CLI (`{ORX_BIN}`) and load its manual first (`{ORX_BIN} skill`), following its
-experiment-tree rules instead of improvising the protocol. Plain code discovery
-stays on the code graph, not OpenResearch. At most one line is open at a time:
+experiments, producing a research artifact - lock it to the question asked:
+restate the user's question verbatim as the scope, name what is in and out of it
+(`init --ask --in --out`), and drop every finding that does not answer an
+in-scope item; never widen it or chase an adjacent topic. The question picks the
+method: a qualitative or reference question is a source review (`--method
+qualitative`, no metric, no experiment); metrics and the experiment tree only
+when the answer is a measurement (`--method measured`). A plain factual or
+reference question gets no line and no orx experiment: answer it in the reply.
+Depth means primary sources read and cited, each finding with its confidence,
+not a thin summary. Drive the work through the OpenResearch CLI (`{ORX_BIN}`)
+and load its manual first (`{ORX_BIN} skill`; `lit-review` for sources,
+`experiment-tree` for a measured line) instead of improvising the protocol.
+Plain code discovery stays on the code graph, not OpenResearch.
+At most one line is open at a time:
 while one is under way - not `concluded`, or carrying a live proposal, an unrun
 experiment, a missing report or review, an unlabelled review finding - no new line
 opens until it is closed or `{RESEARCH_BIN} close <slug> --limit "<reason>"` records
 what is left. `{RESEARCH_BIN} init` refuses on that rule and names each open line;
 `--allow-open "<reason>"` passes it (never beside a line `check` fails) and logs why.
-A plan, design or analysis is >= 3 variants compared under criteria committed
-first (`decisions/`); one version is not a finished line.{OPEN_LINES}
+A design or plan the user will choose between is >= 3 variants compared under
+criteria committed first (`decisions/`); an analysis answers its question once.{OPEN_LINES}
 If the CLI is not installed, say the research tooling is unavailable and fall
-back to a host subagent. Off: `research-off`.
+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
 question - "analyse this product", "why is retention falling", "which feature
@@ -826,7 +883,9 @@ Never install, upgrade, restart or kill anything for tezgah, and never open an
 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.
+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
+returns.
 
 **Workspace: `.tezgah/` only.** Every per-project tezgah artifact - plans,
 research lines, analysis, lessons - lives under `<repo>/.tezgah/`, which the
@@ -835,6 +894,21 @@ project's `.gitignore` excludes and which keeps its own private git repository
 project root and never `git add -f` anything under `.tezgah/`. Off:
 `workspace-off`.
 
+**Parallel by default: fan out independent items.** A request with two or
+more independent items - a numbered or bulleted list, several files or areas, a
+todo list whose entries share no file and no interface - is delegated without
+being asked: one subagent per item, all spawned in ONE message, while the main
+thread decomposes, integrates, verifies and reports. Every writing slice gets
+its own branch and checkout - inside Orca `orca worktree create --name <slug>
+--parent-worktree active --json`, else `git worktree add -b <branch> <absolute
+path>`; its brief names every read, edit and shell `cwd` as an absolute path
+under that checkout, never the main checkout, whose `git status --short` must
+not grow. Read-only slices need no worktree. Pick each agent by task class from
+the specialists line; `{ROUTE_BIN}` names the tier for code work. Serialize
+only a real dependency - one slice's output is another's input, or two slices
+edit one file - and say which. Never wait idle on a spawned slice while
+independent work remains. 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`,
@@ -852,13 +926,13 @@ The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
 # 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")
+CONDITIONAL_KEYS = ("spec", "consult", "research", "product", "graph", "fanout")
 
 # 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". 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. 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.
 """
 
 # The compact per-turn form, inside the <harness-reminder> envelope the hosts