@r1z4x/tezgah 1.0.0 → 1.1.0

package/bin/tezgah-skill

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""tezgah-skill [-k N] [--json] [--root DIR] QUERY... - find the skill section
+that answers a topic.
+
+The roster a session meets is hundreds of one-line names, so the skill that
+holds the answer is a guess unless something searches the bodies. This is that
+search: every installed skill root on the machine (the plugin's own, omp's user
+and custom-directories corpora, Claude/Codex/Agents/opencode), indexed by
+heading, ranked by the same BM25 the per-turn lessons block uses. Each hit is a
+section, not a file:
+
+  skill://attack-jwt:26-122  /abs/SKILL.md  JWT Token Attack
+
+The `skill://<name>:<start>-<end>` address is what omp's read tool resolves
+(line selectors included); the absolute path is for the hosts that have no
+skill:// transport, and is also the tiebreaker where two roots hold different
+skills under one name (the search reports the first root's copy, omp's own
+precedence order - it does not resolve the collision for you).
+
+--root DIR adds a directory to the discovered roots (a project's vendored
+skills); --json prints the machine shape. Exit 0 hits, 1 none, 2 usage.
+"""
+import argparse
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+import tezgah_skill_pick as sp  # noqa: E402
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="tezgah-skill", description=__doc__.splitlines()[0])
+    parser.add_argument("query", nargs="+", help="the topic to search for")
+    parser.add_argument("-k", type=int, default=5, metavar="N",
+                        help="sections to print (default 5)")
+    parser.add_argument("--root", action="append", default=[], metavar="DIR",
+                        help="an extra skills directory to index (repeatable)")
+    parser.add_argument("--json", action="store_true",
+                        help="print [{skill, uri, path, title, start, end}]")
+    args = parser.parse_args(argv)
+    query = " ".join(args.query)
+    hits = sp.search(query, k=max(1, args.k),
+                     roots=(sp.skill_roots(args.root) if args.root else None))
+    if args.json:
+        print(json.dumps([{"skill": h[0],
+                           "uri": "skill://%s:%d-%d" % (h[0], h[3], h[4]),
+                           "path": h[1], "title": h[2],
+                           "start": h[3], "end": h[4]} for h in hits], indent=1))
+    else:
+        for skill, path, title, start, end in hits:
+            print("skill://%s:%d-%d\t%s\t%s" % (skill, start, end, path, title))
+    return 0 if hits else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/tezgah-skill.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""tezgah-skill [-k N] [--json] [--root DIR] QUERY... - find the skill section
+that answers a topic.
+
+The roster a session meets is hundreds of one-line names, so the skill that
+holds the answer is a guess unless something searches the bodies. This is that
+search: every installed skill root on the machine (the plugin's own, omp's user
+and custom-directories corpora, Claude/Codex/Agents/opencode), indexed by
+heading, ranked by the same BM25 the per-turn lessons block uses. Each hit is a
+section, not a file:
+
+  skill://attack-jwt:26-122  /abs/SKILL.md  JWT Token Attack
+
+The `skill://<name>:<start>-<end>` address is what omp's read tool resolves
+(line selectors included); the absolute path is for the hosts that have no
+skill:// transport, and is also the tiebreaker where two roots hold different
+skills under one name (the search reports the first root's copy, omp's own
+precedence order - it does not resolve the collision for you).
+
+--root DIR adds a directory to the discovered roots (a project's vendored
+skills); --json prints the machine shape. Exit 0 hits, 1 none, 2 usage.
+"""
+import argparse
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+import tezgah_skill_pick as sp  # noqa: E402
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="tezgah-skill", description=__doc__.splitlines()[0])
+    parser.add_argument("query", nargs="+", help="the topic to search for")
+    parser.add_argument("-k", type=int, default=5, metavar="N",
+                        help="sections to print (default 5)")
+    parser.add_argument("--root", action="append", default=[], metavar="DIR",
+                        help="an extra skills directory to index (repeatable)")
+    parser.add_argument("--json", action="store_true",
+                        help="print [{skill, uri, path, title, start, end}]")
+    args = parser.parse_args(argv)
+    query = " ".join(args.query)
+    hits = sp.search(query, k=max(1, args.k),
+                     roots=(sp.skill_roots(args.root) if args.root else None))
+    if args.json:
+        print(json.dumps([{"skill": h[0],
+                           "uri": "skill://%s:%d-%d" % (h[0], h[3], h[4]),
+                           "path": h[1], "title": h[2],
+                           "start": h[3], "end": h[4]} for h in hits], indent=1))
+    else:
+        for skill, path, title, start, end in hits:
+            print("skill://%s:%d-%d\t%s\t%s" % (skill, start, end, path, title))
+    return 0 if hits else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/tezgah-status

@@ -62,7 +62,17 @@ their status line; this CLI is how every host (and a human) gets it:
                            records, prose-only) and the record from
                            docs/contract.md. A report, not a gate: it always
                            exits 0. `--json` prints the rows.
+  tezgah-status --judge    what the judgement seam used last: the provider and
+                           model that answered, and why it was not the session's
+                           own CLI when it was not, or the refusal and the
+                           failures that left no judgement. `--json` prints it.
   tezgah-status --legend   explain the marks
+  tezgah-status --orca [PATH]
+                           this repository's checkouts as Orca sees them: each
+                           one Orca tracks with its card status, live terminal
+                           count and agent states (`orca worktree ps`), and each
+                           git worktree Orca does not list. Exits 0 when Orca is
+                           absent or down and says so. `--json` prints the fold.
   tezgah-status --observable=consult,research,graph,orch
                            the measures this surface can see; a measure outside
                            the set renders as dim "no state" instead of claiming
@@ -200,6 +210,37 @@ def print_enforcers(as_json):
         print("unrecorded: %s" % failure)
 
 
+def print_orca(cwd, as_json):
+    """`--orca`: this repository's git checkouts against Orca's listing. A
+    checkout Orca does not list has no card, terminal tracking or agent status
+    in Orca: create the next one with `orca worktree create`, or show the
+    existing ones with `orca repo set --external-worktree-visibility show`."""
+    import tezgah_orca
+    from tezgah_paths import worktrees
+    if not tezgah_orca.cli():
+        print("orca CLI not found: nothing to track")
+        return 0
+    found = tezgah_orca.checkouts(worktrees(cwd) or [cwd])
+    if found is None:
+        print("orca runtime did not answer `orca worktree ps --json` "
+              "(start it with `orca open`)")
+        return 0
+    if as_json:
+        print(json.dumps(found))
+        return 0
+    print("Orca tracks %d checkout(s) of this repository:" % len(found["tracked"]))
+    for w in found["tracked"]:
+        print("  %s  [%s/%s] %d terminal(s) agents: %s" % (
+            w["path"], w["card"] or "-", w["status"] or "-", w["terminals"],
+            ", ".join(w["agents"]) or "-"))
+    if found["untracked"]:
+        print("not listed by Orca (raw `git worktree`; no card, terminals or "
+              "agent status there): %d" % len(found["untracked"]))
+        for path in found["untracked"]:
+            print("  %s" % path)
+    return 0
+
+
 def main():
     # `--` ends the options: what follows is PATH and SESSION_ID even when it
     # starts with a dash. The dsh route and the MCP tool hand caller-chosen
@@ -219,7 +260,7 @@ def main():
     pos = [a for a in args if not a.startswith("--")] + rest
     known = {"--legend", "--json", "--color", "--no-color", "--counters",
              "--all", "--trend", "--skill-fitness", "--failure-shapes",
-             "--rule-yield", "--enforcers", "--help"}
+             "--rule-yield", "--enforcers", "--orca", "--judge", "--help"}
     unknown = sorted(f for f in flags
                      if f not in known and not f.startswith("--observable="))
     if unknown:
@@ -252,6 +293,23 @@ def main():
         sys.stderr.write("tezgah-status: %s only means something with "
                          "--counters\n" % modifier)
         return 2
+    if "--judge" in flags:
+        import tezgah_judge as tj
+        last = tj.last_use()
+        if "--json" in flags:
+            print(json.dumps(last, sort_keys=True))
+        elif not last:
+            print("judge: no judgement recorded")
+        elif last.get("provider"):
+            print("judge: %s answered with %s/%s (fallback=%s)%s" % (
+                last.get("at"), last["provider"], last.get("model"),
+                last.get("policy"), "; not the session: " + last["fallback"]
+                if last.get("fallback") else ""))
+        else:
+            print("judge: %s no judgement (fallback=%s): %s; failed: %s" % (
+                last.get("at"), last.get("policy"),
+                last.get("refused") or "every provider failed", last.get("failed")))
+        return 0
     if "--skill-fitness" in flags:
         fit = skill_fitness()
         if "--json" in flags:
@@ -362,6 +420,9 @@ def main():
     if "--enforcers" in flags:
         print_enforcers("--json" in flags)
         return 0
+    if "--orca" in flags:
+        return print_orca(os.path.realpath(pos[0] if pos else os.getcwd()),
+                          "--json" in flags)
     cwd = os.path.realpath(pos[0] if pos else os.getcwd())
     session = pos[1] if len(pos) > 1 else os.environ.get("TEZGAH_SESSION")
     spec = next((f.split("=", 1)[1] for f in flags

package/bin/tezgah-triage

@@ -90,9 +90,11 @@ MEASURED = ("100% of the control lines at a 94% read on a reproduced 356-line "
             "screen")
 CUT = 96
 USAGE = "tezgah-triage --select FILE --task TEXT | --states FILE [--component TEXT]"
-NO_CREDENTIAL = ("no credential (TYPESAFE_API_KEY or ~/.config/typesafe/key, or "
-                 "the OpenRouter fallback's OPENROUTER_API_KEY or "
-                 "~/.config/openrouter/key), or the judge-off switch is on")
+NO_CREDENTIAL = ("no judge: no session CLI (omp or claude, from OMPCODE/CLAUDECODE), "
+                 "and no third party the `fallback` setting allows (TYPESAFE_API_KEY "
+                 "or ~/.config/typesafe/key, or the OpenRouter fallback's "
+                 "OPENROUTER_API_KEY or ~/.config/openrouter/key), or the judge-off "
+                 "switch is on")
 TRIAGE_OFF = "the triage-off switch is on"
 FAILED = ("the call failed - a timeout, a refusal, or a reply that is not the "
           "documented shape")

package/docs/README.md

@@ -36,6 +36,7 @@ citation you can open: `path::symbol` into Python code, `path:line` elsewhere.
 | Which model runs which subagent, and how does `tezgah-route` pick one? | [models](models.md) |
 | Where does a research line live, and what does `tezgah-research check` refuse? | [research](research.md) |
 | What does each host get, and what can it observe? | [hosts](hosts.md) |
+| Inside Orca, who owns worktrees and terminals, and which checkouts does Orca track? | [orca](orca.md) |
 | Which skills ship, and how does one reach a host? | [skills](skills.md) |
 | How is one feature audited across its layers, and what does a capability change need to carry? | [feature-audit](feature-audit.md) |
 | How do I check a change, and how do I test it? | [testing](testing.md) |

package/docs/architecture.md

@@ -93,6 +93,7 @@ One session, in order. Each step names the file that handles the event on Claude
    the graph index status and the detached index spawn (`hooks/tezgah_context.py::context_for`),
    the open plans, the sibling checkouts of a `git worktree` with their open plan
    and research line counts (`sibling_line`, `hooks/tezgah_context.py::sibling_line`),
+   inside Orca the `Orca:` line ([orca](orca.md), `hooks/tezgah_orca.py::context_line`),
    the lessons ledger, and the active kill switches. The CORE is
    dropped when the host's own file already carries it (`TEZGAH_CORE_IN_FILE`,
    declared by that manifest row: `~/.claude/CLAUDE.md` on Claude). Outside a
@@ -110,9 +111,11 @@ One session, in order. Each step names the file that handles the event on Claude
    session block's last five, see
    [operations.md](operations.md#opt-in-embedding-relevance); each once per
    session, remembered in the turn stamp and forgotten at a compaction),
-   and the stale-index notice (`hooks/tezgah_context.py::index_notice`).
+   and the stale-index notice, which also starts the incremental re-index
+   (`hooks/tezgah_context.py::index_notice`).
 3. **PreToolUse** — `hooks/projects-pretooluse.py::main` calls `decision` and emits
-   the deny envelope (`hooks/projects-pretooluse.py::main`). The gate is the same
+   the deny envelope, or, for a code-symbol search it lets through, the graph line
+   as `additionalContext` (`hooks/tezgah_gate.py::graph_advice`). The gate is the same
    object on every host: `hosts/omp/hook.py::handle`, `hosts/codex/hook.py::gate_reason`.
 4. **PostToolUse** — `hooks/projects-posttooluse.py::main` writes the evidence row
    through `note_tool` (`hooks/projects-posttooluse.py::main`), records the used

package/docs/citations-baseline.json

@@ -42,7 +42,7 @@
     "unjudged": 9
   },
   "docs/testing.md": {
-    "unjudged": 42
+    "unjudged": 41
   },
   "hooks/tezgah_gate.py": {
     "unjudged": 1

package/docs/clarity-baseline.json

@@ -18,10 +18,10 @@
     "semicolons": 9
   },
   "docs/contract.md": {
-    "long_sentences": 40,
+    "long_sentences": 43,
     "passive": 26,
     "replace_words": 0,
-    "semicolons": 30
+    "semicolons": 31
   },
   "docs/environment.md": {
     "long_sentences": 3,
@@ -45,7 +45,7 @@
     "long_sentences": 67,
     "passive": 32,
     "replace_words": 1,
-    "semicolons": 46
+    "semicolons": 45
   },
   "docs/glossary.md": {
     "long_sentences": 51,
@@ -60,10 +60,10 @@
     "semicolons": 18
   },
   "docs/judge.md": {
-    "long_sentences": 28,
+    "long_sentences": 23,
     "passive": 15,
     "replace_words": 0,
-    "semicolons": 17
+    "semicolons": 14
   },
   "docs/layers.md": {
     "long_sentences": 20,
@@ -90,10 +90,10 @@
     "semicolons": 77
   },
   "docs/skills.md": {
-    "long_sentences": 31,
-    "passive": 16,
+    "long_sentences": 36,
+    "passive": 18,
     "replace_words": 0,
-    "semicolons": 14
+    "semicolons": 16
   },
   "docs/status-line.md": {
     "long_sentences": 44,
@@ -111,6 +111,6 @@
     "long_sentences": 9,
     "passive": 7,
     "replace_words": 1,
-    "semicolons": 12
+    "semicolons": 11
   }
 }

package/docs/contract.md

@@ -17,12 +17,24 @@ host says the same thing (`hooks/tezgah_policy.py:14-15`); path placeholders
 
 | Surface | Text | Paid |
 |---|---|---|
-| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the five conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
-| conditional paragraph | one of the five keyed by `CONDITIONAL_KEYS` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) | in full on the first turn of a session whose prompt matches its task class; a later match pays one line (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns (`hooks/tezgah_context.py::ARMED_RESURFACE`) bring the full text back |
+| always-on core | `CORE` (`hooks/tezgah_policy.py::CORE`) minus the six conditional paragraphs, plus the pointer line | once per session: `session_start` and `post_compact` |
+| conditional paragraph | one of the six keyed by `CONDITIONAL_KEYS` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) | in full on the first turn of a session whose prompt matches its task class; a later match pays one line (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns (`hooks/tezgah_context.py::ARMED_RESURFACE`) bring the full text back |
 | per-turn reminder | `PROMPT_REMINDER` (`hooks/tezgah_policy.py::PROMPT_REMINDER`) | every user prompt |
-| skill suggestion | one `<skill_relevance>` line naming at most one installed skill, written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`); off unless `skill-suggest-on` is armed | only on a turn the judgement answers with a skill |
+| skill suggestion | one `<skill_relevance>` line naming at most one installed skill and the SECTION of it that matches the turn (`skill://<name>:<start>-<end>` plus the absolute path), written by `suggest` (`hooks/tezgah_skill_pick.py::suggest`) when `skill-suggest-on` is armed, else by the model-free section search (`hooks/tezgah_skill_pick.py::section_hint`), default on | only on a turn the judgement answers with a skill, or whose prompt one section covers (each section once per session) |
 | on-demand full contract | the long-form blocks of `hooks/tezgah_policy.py` (`EXEC`, `CONSULT`, `RESEARCH`, …), shipped hand-kept as `skills/tezgah-contract/SKILL.md` | only when the session loads that skill |
 
+Two paragraphs of the core are complete statements of their rule, not
+summaries the session must upgrade: **Ponytail** and **Output shape:
+ADHD-friendly** carry every operative clause of their skills (the runnable-check
+rule, the lazy-version-and-question reply, the evidence-gated cause, the
+three-still-broken stop, the pre-send delete pass) from the first turn of every
+session, because "on the first non-trivial task, read the full skill" armed a
+rule only when the model chose to load it. What the skills still hold is the
+level table, the reasoning and the worked examples (`skills/ponytail/SKILL.md`,
+`skills/i-have-adhd/SKILL.md`), and the pointer says so. The kill switches drop
+the paragraphs whole (`ponytail-auto.off`/`.no-ponytail`, `adhd-off`/`.no-adhd`),
+rules and all.
+
 The skill suggestion is the one surface a judgement writes rather than a constant.
 The roster reaches a session as an index of host-truncated one-liners, so which
 entry to look at first is the turn's own weak spot; one batched judgement request
@@ -33,8 +45,10 @@ asking whether the turn wants a skill at all - and the winner is appended after
 the armed paragraphs as a hint to look at first, never as an instruction to load
 (`hooks/tezgah_skill_pick.py:41-75` is the whole configuration, wired into
 `context_for` at `hooks/tezgah_context.py::context_for`). Measured cost of the line
-itself: 305-317 characters, about 78 tokens of prompt. Measured cost of the
-judgement: one call per unanswered prompt, 909-915 input tokens, 0.77-0.81 s,
+itself: 455-523 characters, about 115-130 tokens of prompt (the section address
+added ~150 characters over the name-only line; `bin/tezgah-skill` is the same
+ranking without the call). Measured cost of the judgement: one call per
+unanswered prompt, 909-915 input tokens, 0.77-0.81 s,
 $0.000038 at $0.042/1M on three live judgements. It is OFF UNLESS ARMED -
 `skill-suggest-on` in `~/.config/tezgah`, the same place the kill switches live -
 because a labelled set of 28 prompts through an independent chooser was measured
@@ -47,6 +61,19 @@ session is never paid for twice (`tests/test_skill_pick.py`). The host's own
 roster text is left untouched: that is what a session matches on and what its
 prefix cache covers, which is the whole reason the upstream recipe keeps it.
 
+When the judgement gives no line, the local section search may write one. It
+uses no model and is on by default (`hooks/tezgah_skill_pick.py::section_hint`,
+[skills](skills.md)). Its SQLite index lives in the tezgah cache dir and
+rebuilds only when a SKILL.md's stat moves. The line needs a top section that
+carries 60% of the prompt's distinct content terms, and at least three. It
+names each section once per session and drops the absolute path on omp, whose
+read tool resolves `skill://`. Measured on this machine: 6-15 ms warm, and
+1.36 s for the one cold rebuild over 7 502 sections. The line costs 196-239
+bytes on omp and 245-320 elsewhere. It is not a judgement, so `judge-off` leaves it on,
+and `reminder-off` drops it with the per-turn text. The always-on core also
+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.
+
 `context_for(event, …)` is the one dispatcher (`hooks/tezgah_context.py::context_for`):
 `session_start`/`post_compact` build core plus live state, `user_prompt` builds
 the reminder, whatever was armed and any skill hint, `subagent_start` builds a short brief
@@ -142,23 +169,26 @@ research lines with a written flip; everything else keeps one fresh reviewer
 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.**` :637, `**Ponytail (minimal code).**` :645, `**Output shape:
-ADHD-friendly.**` :656, `**Deliver the whole ask; never the shortcut.**` :670,
-`**Integrity: evidence, or "doğrulanmadı".**` :684, `**Loop discipline.**` :700,
-`**Spec before building.**` :709 *(conditional)*, `**Lessons ledger: stop
-repeating mistakes.**` :723, `**Code discovery: graph first.**` :731
-*(conditional)*, `**Consult before irreversible.**` :740 *(conditional)*,
-`**Research: route it to OpenResearch.**` :756 *(conditional)*, `**Product
-analysis: five axes, one evidence class per finding.**` :772 *(conditional)*,
-`**No AI attribution, ever, on any host.**` :805, `**Identifiers and messages
-stay English.**` :815, `**Session scope: the user's repo, not tezgah.**` :821,
-`**Kill switches:**` :837. The first label renders as `**Turkish, BLUF.**` under
+`**{REPLY_LANG}, BLUF.**` :649, `**Ponytail (minimal code).**` :657, `**Output shape:
+ADHD-friendly.**` :668, `**Deliver the whole ask; never the shortcut.**` :682,
+`**Integrity: evidence, or "doğrulanmadı".**` :696, `**Loop discipline.**` :713,
+`**Spec before building.**` :722 *(conditional)*, `**Lessons ledger: stop
+repeating mistakes.**` :736, `**Code discovery: graph first.**` :744
+*(conditional)*, `**Consult before irreversible.**` :753 *(conditional)*,
+`**Research: route it to OpenResearch.**` :769 *(conditional)*, `**Product
+analysis: five axes, one evidence class per finding.**` :785 *(conditional)*,
+`**No AI attribution, ever, on any host.**` :818, `**Identifiers and messages
+stay English.**` :828, `**Session scope: the user's repo, not tezgah.**` :834,
+``**Workspace: `.tezgah/` only.**`` :843, `**Parallel by default: fan out
+independent items.**` :850 *(conditional)*,
+`**Kill switches:**` :865. The first label renders as `**Turkish, BLUF.**` under
 the default `reply_lang`.
 
-`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the five
+`always_on_core()` (`hooks/tezgah_context.py::always_on_core`) drops the six
 conditional paragraphs and appends `POINTERS` (`hooks/tezgah_policy.py::POINTERS`):
 one line each saying the rule exists and where its full text lives — spec-first,
-a second opinion, OpenResearch routing, product analysis, the code graph, and the
+a second opinion, OpenResearch routing, product analysis, the code graph, parallel
+fan-out, and the
 per-repo design contract `bin/tezgah-design` checks a UI change against (the one
 pointer with no conditional paragraph behind it, because the Stop rule's `no
 ui_ok` class is what asks for the check). That is
@@ -234,13 +264,17 @@ sentence of the rule.
 | consult | The owner removed the consent rule on 2026-09-26 ([gate.md](gate.md#what-the-gate-deliberately-does-not-catch)). The per-turn reminder carries the clause instead. |
 | research | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. |
 | product | Owner decision ADR 010 (2026-10-05): no new research rule until plan 062 reports. The product rule is the research route. |
+| fanout | A refusal cannot see a serial run that should have been parallel: nothing is called that a gate could deny. The prompt-shape arming (`hooks/tezgah_context.py::PROMPT_HINTS`) and the generated specialists line are the mechanism. |
 | scope | no decision |
 
 ## Arming the conditional paragraphs, and the per-turn reminder
 
 `PROMPT_HINTS` (`hooks/tezgah_context.py::PROMPT_HINTS`) is one compiled pattern per key
-— `spec`, `consult`, `research`, `product`, `graph` — and `classify_prompt()` returns the keys
-a prompt matches (`hooks/tezgah_context.py::classify_prompt`). On that turn only, the
+— `spec`, `consult`, `research`, `product`, `graph`, `fanout` — and `classify_prompt()` returns the keys
+a prompt matches (`hooks/tezgah_context.py::classify_prompt`). `fanout` arms on the
+shape of the request, not a word. Two or more list entries on their own lines
+arm it, and so does an explicit subagent, parallel or worktree ask. The owner
+no longer has to say "do it with subagents, in parallel". On that turn only, the
 matching paragraphs are appended after the reminder
 (`hooks/tezgah_context.py::context_for`); a session that never asks such a question
 pays the one-line pointer instead. The patterns carry Turkish stems because the
@@ -300,7 +334,7 @@ a keyword match, not intent: "don't touch `verify-off`" names the switch too.
 | `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` |
-| `orchestrate-off` | the orchestration section of the on-demand skill (there is no core paragraph) | `hooks/tezgah_context.py::switches` disables it, `hooks/tezgah_context.py::context_for` injects "Orchestration is off", and the skill-ignore note is `hooks/tezgah_context.py::context_for` |
+| `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` |
 | `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 |
@@ -378,11 +412,19 @@ 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` 12000,
-`user_prompt` 6000, `subagent_start` 5500, anything else 12000
+Each event has a byte budget: `session_start` and `post_compact` 13000,
+`user_prompt` 6000, `subagent_start` 5500, anything else 13000
 (`hooks/tezgah_context.py::CONTEXT_BUDGET`). The rationale and the measured
-sizes sit beside it. A fixture repo builds 10066 B at `session_start` and about
-5150 B at `subagent_start`. A `user_prompt` that arms all five conditional rules
+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
+(+1042 B). The fan-out pointer adds 112 B and the `tezgah-skill` sentence
+113 B, so the always-on band is 10499 B (`tests/test_setup.py`). 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 subagent brief and the reminder stay the same size.
+`SkillRulesInForceAtSessionStart` (`tests/test_context.py`) pins the rules
+themselves, not the size. A
+`user_prompt` that arms all five conditional rules
 for the first time builds 7503 B. That is over its budget on purpose: an armed paragraph
 is never dropped, and every later match in the session pays one line. The
 budget is a byte count, not a token estimate.
@@ -390,7 +432,7 @@ budget is a byte count, not a token estimate.
 Over budget, `budgeted()` gives up blocks in `DROP_ORDER`, lowest value
 first — the text another surface already carries (project knowledge, the
 sibling-checkout line, lessons), the skill hint (a suggestion, never an
-instruction), the per-turn relevant lessons and the plan table first, then the tooling-availability lines and the live graph
+instruction), the per-turn relevant lessons and the plan table first, then the Orca line, the tooling-availability lines and the live graph
 glance, then the resume state (it outlives those because it is the only one that
 says what this session was doing, and it still yields to a rule), then the
 evidence-scope warning, the task phase, the delta, and the skill pointer last

package/docs/environment.md

@@ -44,6 +44,7 @@ the kill switches are files, not variables, and live in
 | `TEZGAH_NO_EXCLUDE` | `hooks/tezgah_agents.py::ensure_exclude` | unset | `1` stops tezgah adding its generated-agent dirs to the repository's `.git/info/exclude`. |
 | `CODEX_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | `~/.codex` | The Codex home tezgah installs into and checks; the same variable Codex itself reads. |
 | `DSH_HOME` | `hooks/tezgah_paths.py::HOST_DIRS`, `bin/tezgah-dsh`, `bin/tezgah-dsh.cmd` | `~/.dsh` | The dsh home tezgah installs into, and where `tezgah-dsh` looks for the CLI. |
+| `ORCA_WORKTREE_ID`, `ORCA_TERMINAL_HANDLE`, `ORCA_PANE_KEY`, `TERM_PROGRAM=Orca` | `hooks/tezgah_orca.py::session` | unset | Exported by an Orca terminal. Any one marks the session as inside Orca: the session-start block gains the `Orca:` line and `tezgah-setup --status` an `orca:` line ([orca](orca.md)). tezgah never writes them. |
 | `TEZGAH_OPENCODE_DATA` | `bin/tezgah-setup::OPENCODE_DATA`, `bin/tezgah-doctor` | `~/.local/share/opencode` | opencode's data dir: its session database for `tezgah-doctor` and the installer. |
 
 ## Which binary runs
@@ -52,8 +53,9 @@ the kill switches are files, not variables, and live in
 |---|---|---|---|
 | `TEZGAH_CODEGRAPH_BIN` | `hooks/tezgah_paths.py::codegraph_bin` | the config file, then `codegraph` on PATH | The codegraph executable the index and the graph marks use. |
 | `TEZGAH_ORX_BIN` | `hooks/tezgah_paths.py::orx_bin` | `orx` on PATH | The OpenResearch CLI the research rule routes to. |
-| `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table and consult's session-model lookup run. |
-| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`); the test suite points it at a path that does not exist. |
+| `TEZGAH_ORCA_BIN` | `hooks/tezgah_orca.py::cli` | `ORCA_CLI_COMMAND`, then `$ORCA_CLI_BIN_DIR/orca`, then `orca` on PATH (`orca-ide` on Linux outside Orca), then the macOS app's CLI | The Orca CLI `tezgah-status --orca` and `tezgah-setup --status` ask. A missing path is no CLI, never a fallback: the test suite points it at one. |
+| `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table, consult's session-model lookup and the judgement seam's session call run; tests point it at a stand-in. |
+| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`) and the judgement seam asks in a Claude Code session; the test suite points it at a path that does not exist, or at a stand-in. |
 | `TEZGAH_DSH_BIN` | `bin/tezgah-setup::reconcile_json_servers` | the profile-local entry, then `bin/tezgah-dsh`, then npx | How the installer invokes the dsh CLI. |
 | `TEZGAH_INDEX_BIN` | `bin/tezgah-dsh:19`, `bin/tezgah-dsh.cmd` | `~/.config/tezgah/bin/tezgah-index` | The index worker `tezgah-dsh` warms before it starts dsh. |
 | `TEZGAH_STATUS_BIN` | `hosts/dsh/statusline/lib/index.js:24`, `hosts/opencode/tui/tezgah-tui.tsx` | `~/.config/tezgah/bin/tezgah-status` | The status renderer the dsh status line and the opencode TUI call. |
@@ -71,7 +73,8 @@ the kill switches are files, not variables, and live in
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first credential; omp also reads it for its own judge. |
+| `OMPCODE`, `CLAUDECODE` | `hooks/tezgah_paths.py::session_cli`, `bin/consult`, `hooks/tezgah_models.py::worker_model` | set by the host | Name the host session: the judgement seam asks that host's CLI first (`OMPCODE` wins, omp sets both). The test suite unsets both. |
+| `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first third-party credential, used as `fallback` in `config.json` allows ([judge](judge.md)); omp also reads it for its own judge. |
 | `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, and omp's `any` family. |
 | `DEEPSEEK_API_KEY`, `INCEPTION_API_KEY` | `bin/consult`, `bin/codegen`, `hooks/tezgah_replay.py::label_model` | `~/.config/deepseek/key`, `~/.config/inception/key` | The `deepseek` and `inception` providers of consult and codegen; `DEEPSEEK_API_KEY` alone is also the replay sheet's `--provider deepseek` rater. |
 | `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic` or `zai` model family, so the model table can pick a row omp will run. |

package/docs/evidence.md

@@ -313,6 +313,13 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    has only its words as the trigger. There a claim word inside a question or under a negation in
    its own clause is no claim (`asserted_claims`). Examples: "testler geçti mi?", "is it done?",
    "not tested yet", "tamamlandı değil". "Tamamlandı, push edeyim mi?" still claims.
+   A prose edit is no step and no change (`hooks/tezgah_integrity.py::_prose_edit`,
+   `hooks/tezgah_integrity.py::_work_row`). Such an `edit` row has a real `target` ending in
+   `.md`, `.markdown`, `.rst` or `.adoc`. It owes no check and does not stale a pass. An agent
+   instruction file is not prose: `SKILL.md`, `AGENTS.md`, `CLAUDE.md` and anything under
+   `skills/`, `prompts/`, `agents/`, `commands/` or a host directory stay a change. A reply that
+   claims a test ran ("tested", "tüm testler geçti") still needs a pass after a prose-only turn.
+   A comment-only edit to code is still a change: the row carries no text to tell it apart.
 10. **no external read** — the reply states the state of a system tezgah does not own — a registry,
    a release, a tag, a formula, a CI run — and no read of that system ran in the same turn
    (`hooks/tezgah_integrity.py::_external_claim`, over `EXTERNAL_SYSTEM`/`EXTERNAL_STATE`

package/docs/gate.md

@@ -244,13 +244,19 @@ failures. Under `verify-off` (`hooks/tezgah_gate.py::decision`).
 Trigger: the same call has been attempted more than `RETRY_CEILING = 3` times in the session, whatever those attempts returned (`hooks/tezgah_gate.py::RETRY_CEILING`, `retry_reason`
 `hooks/tezgah_gate.py::retry_reason`). Told: an unchanged repeat is not a retry (`hooks/tezgah_gate.py::loop_reason`). Standing. Under `verify-off` (`hooks/tezgah_gate.py::decision`). Both guards read only the ledger tail.
 
-### Nudge — the first identifier-shaped search of a session
-
-Trigger: a `Grep` whose pattern, or a `grep`/`rg` argument (`hooks/tezgah_gate.py::BASH_SEARCH`), matches `IDENT` (`^[A-Za-z_][A-Za-z0-9_]{2,}$`, `hooks/tezgah_gate.py::IDENT`), in a repo whose
-codegraph index exists (`<repo>/.codegraph/codegraph.db`; `searched_identifier`
-`hooks/tezgah_gate.py::searched_identifier`). Told: the runnable command built from the denied search (`codegraph explore <X>`, `codegraph callers <X>`, `codegraph impact <X>`), and that an omp subagent uses this CLI because omp's MCP device refuses concurrent writes
-(`hooks/tezgah_gate.py::nudge_reason`).
+### Nudge — the first code-symbol search of a session, then a line beside every later one
+
+Trigger: a search for a code symbol, in a repo whose codegraph index exists (`<repo>/.codegraph/codegraph.db`) and that has no `.no-graph` (`hooks/tezgah_gate.py::index_slug`).
+A code symbol has an inner underscore or a lower-to-upper step, or sits in a `def x` or `x\(` pattern (`hooks/tezgah_gate.py::symbol_in`).
+A plain word such as `TODO` is literal text and never matches.
+The search is the pattern of a `grep`, `search` or `ast_grep` tool, a term of omp's `find`, or a `grep`/`rg` argument (`hooks/tezgah_gate.py::searched_symbol`, `hooks/tezgah_gate.py::BASH_SEARCH`).
+omp's bridge sends `find`, `search` and `ast_grep` to the gate, because omp's own prompt sends code discovery to `find` first (`hosts/omp/tezgah-hook.ts.in`).
+Told: the host's graph tool (`hooks/tezgah_gate.py::graph_tool`) and the runnable command built from the denied search (`codegraph explore <X>`, `codegraph callers <X>`, `codegraph impact <X>`).
+An omp subagent uses this CLI, because omp's MCP device refuses concurrent writes (`hooks/tezgah_gate.py::nudge_reason`).
 Once-only: the mark in `cache_dir()/nudged/<sha1(session)[:16]>` is written *before* the refusal, so re-issuing the search passes (`hooks/tezgah_gate.py::first_nudge`). opencode's `oncePerSession` writes the same name (`hooks/tezgah_gate.py::nudge_mark`).
+After that, every later symbol search passes with one line naming the graph tool, while the index stamp equals HEAD (`hooks/tezgah_gate.py::graph_advice`).
+Claude reads the line as PreToolUse `additionalContext` (`hooks/projects-pretooluse.py`), and omp reads it with the call's `tool_result` (`hosts/omp/tezgah-hook.ts.in`).
+Codex and Cursor read it with their PostToolUse result (`hosts/codex/hook.py`, `hosts/cursor/hook.py`).
 
 ### Drift — a long turn loses the rules it started with
 
@@ -395,7 +401,7 @@ rule's triggers are the classes `_stop_block` returns, the four `_shape_block` a
 ## Source of truth
 
 - `hooks/tezgah_gate.py` — `hooks/tezgah_gate.py::decision`; every rule constant and refusal text `hooks/tezgah_gate.py:162-2157`; `attribution`/`attribution_edit` `hooks/tezgah_gate.py::attribution`, `hooks/tezgah_gate.py::attribution_edit`; `explored`
-  `hooks/tezgah_gate.py::explored`; `hooks/tezgah_gate.py::searched_identifier`, `hooks/tezgah_gate.py::index_slug`, `hooks/tezgah_gate.py::first_nudge`, `hooks/tezgah_gate.py::nudge_reason`; `hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`,
+  `hooks/tezgah_gate.py::explored`; `hooks/tezgah_gate.py::searched_symbol`, `hooks/tezgah_gate.py::index_slug`, `hooks/tezgah_gate.py::first_nudge`, `hooks/tezgah_gate.py::nudge_reason`, `hooks/tezgah_gate.py::graph_advice`; `hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`,
   `hooks/tezgah_gate.py::RETRY_CEILING`, `hooks/tezgah_gate.py::retry_reason`; `hooks/tezgah_gate.py::secret_command`, `hooks/tezgah_gate.py::race_reason`,
   `hooks/tezgah_gate.py::drift_reason`, `hooks/tezgah_gate.py::effectful`, `hooks/tezgah_gate.py::_deny`; the plan rule's own section `hooks/tezgah_gate.py:1391-1588` — `hooks/tezgah_gate.py::plan_reason`, `hooks/tezgah_gate.py::_branch`, `hooks/tezgah_gate.py::_checkout`, `hooks/tezgah_gate.py::_product`, `hooks/tezgah_gate.py::PLAN_DENY`; `hooks/tezgah_gate.py::write_paths`, `hooks/tezgah_gate.py::shell_target`, `hooks/tezgah_gate.py::SHELL_AS_WRITE`; the `capture` call `hooks/tezgah_gate.py::decision` (a write tool's target, and a shell write's)
 - `hooks/projects-pretooluse.py` — the Claude and dsh envelope; `hooks/tezgah_paths.py` — `off`, `root_for`, `cache_dir`

package/docs/glossary.md

@@ -86,7 +86,7 @@ One measured row of always-on context the installer reports in bytes: the core c
 `output-styles/tezgah.md`, a by-hand duplicate of `always_on_core()` kept for the host path that is hookless, which a test holds to the generator (`tests/test_context.py::OutputStyleMirrorsCore`). Not generated: an edit to [CORE](#core) must be carried into it by hand - a lesson the local `.tezgah/lessons.md` ledger holds; that file is untracked by design, so it carries no `path:line` here.
 
 ### nudge
-The one-time hint that sends a first identifier-shaped search to the code graph, `first_nudge()` consuming a per-session mark before the grep is denied (`hooks/tezgah_gate.py::first_nudge`) with the text naming the graph tools (`nudge_reason()`, `hooks/tezgah_gate.py::nudge_reason`). Not a deny: it is spent by being delivered, and the identical call passes on the retry.
+The one-time hint that sends a first code-symbol search to the code graph, `first_nudge()` consuming a per-session mark before the grep is denied (`hooks/tezgah_gate.py::first_nudge`) with the text naming the graph tools (`nudge_reason()`, `hooks/tezgah_gate.py::nudge_reason`). Not a deny: it is spent by being delivered, and the identical call passes on the retry. Every later symbol search gets a non-blocking line naming the graph tool (`hooks/tezgah_gate.py::graph_advice`).
 
 ### observable measure
 A used-mark a surface is able to see at all, so it can say "armed, not used yet" without inventing it: `health_segments(observable=...)` (`hooks/tezgah_context.py::health_segments`) with the five tool-use measures in `TOOL_USE_MEASURES` (`hooks/tezgah_context.py::TOOL_USE_MEASURES`), a measure outside the set rendering as `info` rather than `ready`. Which host can see a skill read is [hosts](hosts.md)'s.