@r1z4x/tezgah 1.0.0 → 1.2.0

package/docs/research.md

@@ -65,7 +65,7 @@ nothing recorded the ask and `close --limit` accepted any string.
 `state.json` `rules` is the line's format version. `init` writes `RULES`, the
 newest set (`hooks/tezgah_research.py::RULES`). Each set keeps its own gate. Rules 2
 are the standards rules. Rules 3 add the ask contract. Rules 4 add the protocol
-sections below. A bump never weakens an older set.
+sections below. Rules 5 add the scope lock. A bump never weakens an older set.
 
 A `rules` above `RULES` means a later tezgah wrote the line. `check` then reports
 one error that names both numbers and reads nothing else. The writers refuse the
@@ -110,14 +110,49 @@ it. The rules come from the gortex/SoL-Pi adoption's ideas 3 and 4 and from the
 layer audit's P2 probe (`_check_protocol_sections`, `_token_claim_problem`).
 Older lines keep the word rule.
 
+## Scope lock (rules 5)
+
+The owner reported on 2026-10-07 that research turned every question into
+metrics. It also grew past the ask, stayed shallow, and drifted off topic. The
+rule text pushed each of these. The injected rule sent every research task to
+orx's experiment tree. The skill locked a metric at bootstrap. `check` refused a
+line past `bootstrap` without one. An analysis owed three compared variants. The
+ideation moves had no fence. Rules 5 lock a line to its question:
+
+- `init --in "<covered>" --out "<left alone>"` (repeatable) write `state.json`
+  `scope`. The in-scope items are `S1`, `S2`, ... in order. `--method
+  qualitative|measured` writes `method`. `scope_problems`
+  (`hooks/tezgah_research.py::scope_problems`) names an empty `scope.in`, an
+  empty `scope.out` and a missing method. `check` refuses them past `bootstrap`
+  and warns at it.
+- A claim's `trace` names the in-scope item it answers (`S<n>` or the item's
+  text). `claim_problems` and `_check_claims` both call `trace_problem`
+  (`hooks/tezgah_research.py::trace_problem`). The writer and the checker refuse
+  the same off-topic claim.
+- A `qualitative` line owes no metric. `_check_evaluation`
+  (`hooks/tezgah_research.py::_check_evaluation`) skips it. `_check_scope`
+  refuses one that records `results.jsonl`. A measured question says `measured`
+  and locks its evaluation first.
+- An `analysis` deliverable owes no variants (`deliverable_problems` takes the
+  line's rules). A design, plan or code still does. Older lines keep three.
+
+The session reads the same lock in the research rule
+(`hooks/tezgah_policy.py::RESEARCH` and the paragraph `**Research: route it to
+OpenResearch.**`). Restate the question verbatim. Name what is in and out of
+scope. Drop a finding that answers nothing asked. Pick the method from the
+question. Answer a plain factual question in the reply from primary sources, with
+no line. Cite each finding's source with a confidence. The host-subagent fallback
+gets the question, its scope and its method in its brief. The research skill's
+"Scope and method" section is the long form.
+
 ## One line, one directory
 
 | Path | Holds |
 |---|---|
-| `state.json` | the question, the phase (`bootstrap`/`inner`/`outer`/`concluded`), the direction, the locked evaluation and its optional second gate (`capability_tolerance`, `counter_metric`), the session events (`PHASES`, `hooks/tezgah_research.py::PHASES`), `rules` (the rule set `init` opened it under, `RULES`), `deliverable` (`kind`, `path`, `ask`, `min_variants`), `supersedes` for a new version of an older line, and `closed` once `close` records a deliberate limit. The phase is the author's declaration; `derived_phase` (`hooks/tezgah_research.py::derived_phase`) reads the *other* authority beside it from the line's own artifacts, and the checker names the two disagreeing |
+| `state.json` | the question, the phase (`bootstrap`/`inner`/`outer`/`concluded`), the direction, `method` and `scope` (rules 5, see "Scope lock"), the locked evaluation and its optional second gate (`capability_tolerance`, `counter_metric`), the session events (`PHASES`, `hooks/tezgah_research.py::PHASES`), `rules` (the rule set `init` opened it under, `RULES`), `deliverable` (`kind`, `path`, `ask`, `min_variants`), `supersedes` for a new version of an older line, and `closed` once `close` records a deliberate limit. The phase is the author's declaration; `derived_phase` (`hooks/tezgah_research.py::derived_phase`) reads the *other* authority beside it from the line's own artifacts, and the checker names the two disagreeing |
 | `log.md` | the decision log, newest last: one line per decision, experiment, dead end or pivot, with the evidence that drove it |
 | `findings.md` | the four sections every line answers, named by `FINDINGS_SECTIONS` (`hooks/tezgah_research.py::FINDINGS_SECTIONS`) |
-| `claims.jsonl` | one JSON object per row: `statement`, `falsification`, `proof`, `provenance`, `status`, `kind`, `scope` (what the claim's numbers were measured on, which may not be wider than the rows it rests on), and `supersedes` when the row replaces an earlier claim |
+| `claims.jsonl` | one JSON object per row: `statement`, `falsification`, `proof`, `provenance`, `status`, `kind`, `trace` (the in-scope item, rules 5), `scope` (what the claim's numbers were measured on, which may not be wider than the rows it rests on), and `supersedes` when the row replaces an earlier claim |
 | `predictions.jsonl` | one JSON object per row: `commit` (a 40-character sha the row is bound to), `claim` (an id the line holds, or empty when the prediction stands alone), `metric`, `value_before`, `value_after`, `falsifier`, `components` (the keys of the components the change touches, read from `hooks/tezgah_components.py`), and `granted_by` when a human granted what the frozen paths below forbid |
 | `experiments/<hypothesis>/protocol.md` | what the change is, what it predicts, what result would falsify it, why - committed before the run |
 | `experiments/<hypothesis>/results.jsonl` | the rows the run produced, one JSON object per non-blank line, each carrying a non-empty `source` and, once declared, a `scope` of `real`, `fixture` or `derived`, and - when that scope is `fixture` - a `fixture` description of what was generated |

package/docs/skills.md

@@ -83,6 +83,66 @@ directory that host reads, and the host lists `name` + `description` itself -
 which is why the installer counts that metadata as an always-on cost
 (`bin/tezgah-setup::context_budget`).
 
+## Searching skills, and reading part of one
+
+A session meets the roster as names (omp's list runs to hundreds once a
+`skills.customDirectories` corpus is mounted - 284 on this machine), and no host
+searches bodies by topic. `bin/tezgah-skill` does: it indexes every installed
+skill root - the checkout's, omp's user and custom-directories corpora,
+Claude's, `~/.agents`, Codex's, opencode's - into heading-delimited sections
+(`hooks/tezgah_skill_pick.py::sections`) and ranks them for a query with the
+lessons ledger's BM25 (`hooks/tezgah_rank.py::rank`, heading weighted over
+body). Each hit is a section:
+
+    tezgah-skill "jwt alg none"
+    skill://attack-jwt:26-122  /Users/.../attack-jwt/SKILL.md  JWT Token Attack
+
+The `skill://<name>:<start>-<end>` address is a range omp's read tool resolves
+(line selectors are part of the `read` contract; `skill://<name>/<file>` reads a
+neighbour file, and `/skill:<name>` injects the whole body - a command, not a
+range). The absolute path beside it is for hosts without a `skill://`
+transport, and both are printed because a name that differs between roots keeps
+only omp's precedence - the search reports the first root's copy rather than
+resolving the collision. Measured on this machine: 7 roots, 10 482 sections,
+2.3-2.6 s cold. Fenced code is not indexed as headings, so a `# comment`
+inside a block never masquerades as a section title.
+
+The per-turn hint reuses the same ranking: when the armed judgement names a
+skill (`skill-suggest-on`, [contract](contract.md)), the appended line points at
+the matching SECTION of that skill - `Start at skill://ponytail:38-61` plus the
+path - so the session opens the part that answers the turn instead of a name it
+must skim (`hooks/tezgah_skill_pick.py::section_of`, pinned by
+`tests/test_skill_pick.py::OmpHintPath` through omp's own dispatch). The search
+CLI is local and unarmed: it costs nothing until it is run, and the judgement
+stays opt-in exactly as before.
+
+The always-on Session scope paragraph sends every session to it. Run
+`tezgah-skill <words>` before working a topic a skill covers, then read only
+the returned range (`hooks/tezgah_policy.py::CORE`). The installer links the
+CLI into `~/.config/tezgah/bin` beside the other tezgah commands.
+
+On a turn the judgement does not answer, the same search runs on its own,
+default on and with no model (`hooks/tezgah_skill_pick.py::section_hint`). It
+keeps its index as SQLite in the tezgah cache dir (`skill-search.sqlite`). It
+rebuilds that index only when a SKILL.md's mtime or size moves
+(`hooks/tezgah_skill_pick.py::_open_index`). A prompt reads its own terms'
+postings and the length column, never the corpus.
+
+The hook then appends one line, `A local skill search matched this request:
+skill://<name>:<start>-<end>`, with the section title. Every host but omp also
+gets the absolute path. The top section must carry 60% of the prompt's
+distinct content terms that any skill contains, and at least three
+(`hooks/tezgah_skill_pick.py::HINT_COVER`, `HINT_MIN_TERMS`). Each section
+appears once per session.
+
+Measured on this machine on 2026-10-07: 7 502 sections and a 9.5 MB index. The
+one cold rebuild took 1.36 s, and a warm prompt takes 6-15 ms. On a turn it
+fires the line costs 196-239 bytes on omp and 245-320 elsewhere. It is not a
+judgement, so `judge-off` leaves it on. `reminder-off` drops it with the rest
+of the per-turn text (`tests/test_skill_search.py::LocalHint`,
+`OmpPromptPath`).
+
+
 ## How a skill reaches a host
 
 `SKILLS` in `bin/tezgah-setup::SKILLS` is the shipped list, and it is the single
@@ -127,6 +187,17 @@ it (`tests/test_skills.py::SkillStandards`).
 | `ai-research` | The vendored 98-skill library for AI/ML machinery - training and serving a model, benchmarks, interpretability, retrieval pipelines; read one entry, never the tree. |
 | `rl-env` | The vendored FineEnvs skill set for authoring an RL environment from a description - OpenEnv, OpenReward/ORS, Verifiers and NeMo Gym, plus the orchestrator that ports one description across all four; read one entry, never the tree. |
 
+The generated specialists load skills first (`hooks/tezgah_agents.py::SPECIALISTS`).
+`tezgah-agents --list` prints the roster with tiers.
+
+| Specialist | Skills it loads |
+|---|---|
+| `tezgah-docs` | `no-ai-slop` |
+| `tezgah-ui` | `analyze-app`, `design-contract`, `design-library`, `feature-audit` |
+| `tezgah-researcher` | `research`, `ai-research` |
+| `tezgah-security` | the host's `wstg-*`, `attack-*`, `ci-assessment` and `llm-security` skills, which tezgah does not ship |
+| `tezgah-tester` | none |
+
 ## Vendored material
 
 `NOTICE` records every third-party skill and its terms: it opens by saying the
@@ -229,6 +300,9 @@ unlisted directory, and fails on a body that pairs 44x44 with Level AA again.
   its index and its three trap cases
 - `skills/rl-env/SOURCE` - the vendored FineEnvs environment-authoring set, its
   upstream revision and the per-file sha256
+- `bin/tezgah-skill` - the section search CLI over every installed skill root;
+  `hooks/tezgah_skill_pick.py` - `sections`, `search`, `skill_roots`,
+  `section_of`, the hint that carries the address
 - `hooks/tezgah_policy.py` - the always-on rule text and the Claude skill name
 - `tests/test_setup.py`, `tests/test_skills.py` - the router-line, name
   resolution, frontmatter, collision and skill-standard tests

package/docs/status-line.md

@@ -105,7 +105,8 @@ must use it": a missing key or binary reads the same red as a kill switch
 (`consult_options()`, `orx_bin()`, `have_judge_key()`: `hooks/tezgah_paths.py::consult_options`,
 `hooks/tezgah_paths.py::orx_bin`, `hooks/tezgah_paths.py::have_judge_key`). `judge` is the seam
 behind `bin/tezgah-triage`, `bin/tezgah-docs` and the skill picker
-([judge](judge.md)), and its credential is the seam's own two channels, never
+([judge](judge.md)). Its credential is the session's own CLI, else a third-party
+key `fallback` allows, never
 omp's login store. `graph` and `orch` are the two switch-only marks: nothing at
 arming time asks whether their toolchain is on the machine, because neither rule
 leaves the text when it is missing - the graph-first rule ships whether or not
@@ -229,6 +230,7 @@ tezgah-status /path/to/repo <id> --counters  # the evidence ledger's counters
 tezgah-status --legend                       # what each mark means
 tezgah-status --rule-yield                   # live gate rules that stopped firing
 tezgah-status --enforcers                    # what enforces each always-on rule
+tezgah-status --judge                        # what the judge used last, and why
 ```
 
 The session id is the second positional argument or `TEZGAH_SESSION`; without it

package/docs/testing.md

@@ -26,7 +26,7 @@ request (`CONTRIBUTING.md:15-20`).
 `ruff` is not vendored: install it as a uv tool, run `uvx ruff check .` without
 installing it, or use the version CI installs from `requirements-dev.txt:3`
 (`ruff==0.16.7`). There is no other linter and no type checker
-(`AGENTS.md:44-45`).
+(`AGENTS.md:51-52`).
 
 The clarity ratchet, `bin/tezgah-docs --clarity`, counts four prose rules per
 file in `docs/*.md` and `CHANGELOG.md`. The rules are sentences over 25 words,
@@ -41,7 +41,7 @@ baseline on the next run. Only `--clarity --update` raises it.
 A pin is a claim about what ran, not a guarantee about what will. This repository
 has two, and both are about the language rather than about dependencies: the
 floor `py310` (`pyproject.toml:5`) and the CI matrix that proves it
-(`.github/workflows/ci.yml:24`). There is no dependency lockfile to pin
+(`.github/workflows/ci.yml:114`). There is no dependency lockfile to pin
 because there is no package: tezgah is a set of scripts run in place, and no
 `[project]` or build system is declared (`pyproject.toml:1-2`). The only
 third-party tool the checks name is ruff, at a version in
@@ -57,30 +57,42 @@ conclude from either.
 
 ## Continuous integration
 
-`.github/workflows/ci.yml` runs on every push and pull request. `release.yml`
-calls it (`ci.yml:8`) as its `ci` job, so npm and brew publish only after CI
-passed on the release commit. It runs five jobs. No matrix
-cancels its other legs when one fails (`fail-fast: false`).
-
-- `test` (`ci.yml:15-43`) on Python 3.10, 3.12, 3.13 and 3.14. 3.10 is the
-  floor the project supports. The byte-compile step exercises it rather than
-  asserts it. It byte-compiles, runs the suite with `-v`, lints with
-  ruff from `requirements-dev.txt` (`ci.yml:37`), audits the docs citations and
-  runs `TEZGAH_E2E_STRICT=1 python3 tests/e2e_plan_flow.py`.
-- `test-sharded` (`ci.yml:48-69`) on Python 3.10 and 3.14 with node 22 (the
-  first line that loads the omp `.ts` hook without a flag):
-  `python3 tests/impacted.py --all`. It is a shadow that started 2026-10-05.
-  After four weeks it replaces the four-version `test` matrix only if it missed
-  no failure that matrix caught.
-- `apps-e2e` (`ci.yml:71-88`) on Python 3.12 and node 20: one step,
+`.github/workflows/ci.yml` runs on a push to `main` and on a pull request, so
+a branch commit runs once, through its pull request, not twice. A tag push does
+not start it. `release.yml` calls it (`ci.yml:13`) as its `ci` job, so npm and
+brew publish only after CI passed on the release commit. A newer push to the
+same ref cancels the run it replaces, except on a release (`concurrency`). Every
+job has a `timeout-minutes`, so a hung test cannot hold a runner for six hours.
+No matrix cancels its other legs when one fails (`fail-fast: false`).
+
+- `changes` diffs against the commit the push replaced or the
+  pull request's base. A change only under `docs/`, `assets/`, a root `*.md`
+  page or the GitHub templates is prose: it runs `docs` and nothing else. An
+  empty diff, a base it cannot read, a release or a manual run runs everything.
+- `docs`, prose only: the citations audit and
+  `tests/impacted.py --ref <base>`, which maps a docs page to the docs modules.
+- `test` (`ci.yml:100`) on Python 3.10 and 3.14, the floor and the ceiling.
+  It byte-compiles, lints with ruff from `requirements-dev.txt` (pip cached),
+  audits the docs citations and runs `TEZGAH_E2E_STRICT=1 python3
+  tests/e2e_plan_flow.py`. On `main` it also runs the serial suite with `-v`.
+  A pull request skips that step, and so does a release, which passes the
+  `release` input and runs one 3.10 leg.
+- `test-sharded` (`ci.yml:145`) on Python 3.10 and 3.14 with node 22 (the
+  first line that loads the omp `.ts` hook without a flag). On `main` and a
+  release it runs `python3 tests/impacted.py --all`. On a pull request it runs
+  `--ref <base>`: the modules the change maps to, and the whole suite when the
+  map does not know a path. It is a shadow that started 2026-10-05. After four
+  weeks it replaces the serial `test` step only if it missed no failure that
+  step caught.
+- `apps-e2e` (`ci.yml:178`) on Python 3.12 and node 20: one step,
   `TEZGAH_E2E_STRICT=1 python3 tests/e2e_analyze_wiring.py`. It completes the
   app-MCP handshake only - no browser, no device - so it stays deterministic;
   strict mode makes a server that cannot start a failure rather than a skip, so
   a broken wire cannot hide behind a skip (`e2e_analyze_wiring.py:4-12`).
-- `artifact-install` (`ci.yml:90-128`) on Python 3.10 and 3.12: builds the
+- `artifact-install` (`ci.yml:200`) on Python 3.10 and 3.12: builds the
   tarball, installs from it under a temp prefix, and runs the artifact smoke on
   the installed tree instead of the checkout.
-- `artifact-install-windows` (`ci.yml:130-214`) on `windows-latest`: the same
+- `artifact-install-windows` (`ci.yml:243`) on `windows-latest`: the same
   build, install and smoke through `packaging/install.ps1` - the twin a Windows
   user runs - so it is the only place the Windows claim is proven. It then runs
   the opencode plugin's path tests natively, `tezgah update --dry-run`, the
@@ -233,7 +245,7 @@ a browser or a device) or to a `_probe_*.py` helper the tests call.
 - **No network.** Loopback stubs only, as above.
 - **Two e2e scripts stay opt-in and local**: `e2e_analyze_web.py` and
   `e2e_analyze_mobile.py`, behind `TEZGAH_E2E_APPS=1`, with the wiring handshake
-  as their CI substitute (`AGENTS.md:108-114`).
+  as their CI substitute (`AGENTS.md:119-125`).
 
 ## Adding a test
 

package/docs/vision.md

@@ -51,14 +51,18 @@ change that would silently run nothing.
 
 ## Model routing
 
-Every omp agent gets a **cross-family fallback chain** (`hooks/tezgah_models.py::_chain`, over `hooks/tezgah_models.py::funded_families`): the mode's family first,
-then every other family this machine holds a credential for. One pin per agent
-made one provider's 429 every subagent's failure, because the account is shared
-with the main thread (measured: 24 of 26 post-routing 429s hit a subagent's first
-request, all on one Opus account; four reviews and three implementation agents
-died on it in one day). A family whose credential cannot be detected is left out
-of the chain, never guessed in. The main thread's own model, and the provider-keyed
-chains, stay the user's settings - tezgah writes only the keys it owns.
+Every omp agent gets a **fallback chain** (`hooks/tezgah_models.py::_chain`, over
+`hooks/tezgah_models.py::funded_families`). The mode's family goes first. By
+default the rest is the same vendor's model through another funded provider, such
+as Opus through OpenRouter on an Anthropic session. `fallback: any` in
+`config.json` adds every other funded family, and `none` keeps the first entry
+alone. One pin per agent made one provider's 429 every subagent's failure, because
+the account is shared with the main thread (measured: 24 of 26 post-routing 429s hit
+a subagent's first request, all on one Opus account). A chain that left the vendor
+ran an Opus session's subagents on GPT and GLM, so that step is opt-in. A family
+whose credential cannot be detected is left out of the chain, never guessed in. The
+main thread's own model, and the provider-keyed chains, stay the user's settings.
+tezgah writes only the keys it owns.
 
 What tezgah cannot fix from inside: a provider that stalls on a very large
 context (`OpenAI completions stream stalled`, five minutes without an event on a

package/hooks/projects-posttooluse.py

@@ -26,6 +26,7 @@ try:
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, note_tool, ran_nothing, report_bytes, untrusted_source)
     from tezgah_paths import root_for  # noqa: E402
+    from tezgah_taste import write_note  # noqa: E402
     from tezgah_untrusted import marks  # noqa: E402
 except Exception as exc:
     import_failed(exc)
@@ -139,6 +140,12 @@ def main():
          # empty-run contract (tezgah_integrity.EMPTY_RUN)
          empty_run=ran_nothing(result),
          agent=agent)
+    # the opt-in taste note: the learnings in scope for the first write to this
+    # file type in the session (hooks/tezgah_taste.write_note), beside the
+    # provenance line rather than instead of it
+    if event == "PostToolUse" and not failed:
+        notice = "\n".join(t for t in (notice, safe(session_id, write_note, session_id,
+                                                     inp, cwd, tool)) if t)
     if notice:
         json.dump({"hookSpecificOutput": {
             "hookEventName": event,

package/hooks/projects-pretooluse.py

@@ -2,8 +2,9 @@
 """Claude Code PreToolUse hook (matcher Agent|Task|Grep|Bash), inert outside roots.
 
 Claude's envelope around the shared gate (hooks/tezgah_gate.py): refuse the
-grep-only explorer subagent, and nudge the first identifier-shaped search of a
-session toward the code graph. Later searches pass.
+grep-only explorer subagent, and nudge the first code-symbol search of a
+session toward the code graph. Later symbol searches pass with the graph named
+beside them (`additionalContext`, which Claude reads with the tool result).
 """
 import json
 import os
@@ -12,11 +13,17 @@ import sys
 sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
 from tezgah_guard import import_failed, safe  # noqa: E402
 try:
-    from tezgah_gate import decision  # noqa: E402
+    from tezgah_gate import decision, graph_advice  # noqa: E402
 except Exception as exc:
     import_failed(exc)
 
 
+def verdict(tool, inp, cwd, session_id, agent):
+    """(deny reason, graph line): the line only for a call the gate lets through."""
+    reason = decision(tool, inp, cwd, session_id, agent=agent)
+    return reason, None if reason else graph_advice(tool, inp, cwd, "claude")
+
+
 def main():
     try:
         p = json.load(sys.stdin)
@@ -27,14 +34,19 @@ def main():
     inp = p.get("tool_input") or {}
     # `agent_id` is set only when the call comes from a subagent (Claude's hook
     # reference, common input fields): the repeat ceilings key on it
-    reason = safe(p.get("session_id"), decision, tool, inp, cwd,
-                  p.get("session_id"), agent=p.get("agent_id"))
+    reason, advice = safe(p.get("session_id"), verdict, tool, inp, cwd,
+                          p.get("session_id"), p.get("agent_id")) or (None, None)
     if reason:
         json.dump({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
             "permissionDecisionReason": reason,
         }}, sys.stdout)
+    elif advice:
+        json.dump({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": advice,
+        }}, sys.stdout)
 
 
 main()

package/hooks/tezgah_agents.py

@@ -79,7 +79,12 @@ EMPTY_IS_NOT_PROOF = (
 STEER = (("mechanical edit (tier from `tezgah-route`)", "tezgah-cheap"),
          ("bounded code or tests", "tezgah-standard"),
          ("design, invariants, unknown-cause debugging", "tezgah-frontier"),
-         ("review of a diff", "tezgah-reviewer"))
+         ("review of a diff", "tezgah-reviewer"),
+         ("running the impacted checks", "tezgah-tester"),
+         ("docs and path:line citations", "tezgah-docs"),
+         ("security review", "tezgah-security"),
+         ("running-app UI or design analysis", "tezgah-ui"),
+         ("a research line", "tezgah-researcher"))
 
 
 def manifest_sha():
@@ -235,6 +240,104 @@ def _worker_body(tier):
     return body
 
 
+# The specialists beside the tier workers: name -> (what it does, the skills it
+# loads first, its tools, the role text). The tier is not here: it is
+# tezgah_models.AGENT_SLOT, the row every host's model line is rendered from, so
+# the description cannot name one tier while the frontmatter runs another.
+# A skill is shipped under skills/ unless HOST_SKILLS names it: those are the
+# security families a host installs on its own, which tezgah does not ship.
+HOST_SKILLS = ("wstg-*", "attack-*", "ci-assessment", "llm-security")
+SPECIALISTS = {
+    "tezgah-tester": (
+        "Runs only the checks a change reaches and reports them verbatim: the "
+        "repo's impacted-test runner or the tests that import the changed "
+        "files, never the full suite unless the brief asks.",
+        (), "shell to run checks; no source or test edits",
+        "Take the changed files from the brief or `git diff --name-only`. Run\n"
+        "the repository's own impacted-test runner if it has one (for example\n"
+        "`python3 tests/impacted.py --run <files>`), else the test files that\n"
+        "import the changed modules. Keep each check last on its line with its\n"
+        "output in a file, then read the file in a separate call: never pipe a\n"
+        "check into tail or grep, never `|| true`, never `--no-verify`, never a\n"
+        "new skip. Set the shell timeout above 300 s for a long run. Report each\n"
+        "check as passed or failed with its counts and the exact failure text.\n"
+        "Never edit source or test files; a fix belongs to the caller."),
+    "tezgah-docs": (
+        "Writes and repairs docs pages and their `path:line` / `path::symbol` "
+        "citations after a code change, under the repo's own docs checks.",
+        ("no-ai-slop",), "read, edit and write docs; shell for the docs checks",
+        "Edit only documentation files the brief names. Cite code as\n"
+        "`path::symbol`; when a code change shifted a `path:line` citation,\n"
+        "re-anchor it by whole token (`:87` must never rewrite `:870`), map each\n"
+        "changed line to its replacement block, and run the repo's citation and\n"
+        "clarity checks (`bin/tezgah-docs --citations`, `--clarity` where they\n"
+        "exist) until they report zero. Plain sentences, one fact each."),
+    "tezgah-security": (
+        "Read-only security review of a change or surface: injection, authn/authz, "
+        "secrets, SSRF, deserialisation, supply chain; every finding with a "
+        "concrete exploit path and file:line.",
+        HOST_SKILLS, "read-only; shell only for read-only git and the codegraph CLI",
+        "Pick the skills that match the class under test: `wstg-injection`,\n"
+        "`wstg-auth-session`, `wstg-logic-client-api`, `wstg-recon-config`,\n"
+        "the matching `attack-*` entry (attack-ssrf, attack-jwt, ...),\n"
+        "`ci-assessment` for pipelines, `llm-security` for prompt handling.\n"
+        "Trace each untrusted input to its sink. Classify every candidate as\n"
+        "confirmed (exploit path + file:line), refuted (the guard that stops it)\n"
+        "or unverified. Never write, never run an exploit against a live system,\n"
+        "never print a secret you find - name its location only."),
+    "tezgah-ui": (
+        "Inspects a running web or mobile app and judges it against the design "
+        "floor: component x state coverage, layout, contrast and WCAG 2.2, with "
+        "the screen it read as evidence.",
+        ("analyze-app", "design-contract", "design-library", "feature-audit"),
+        "shell and browser/device tools; no source edits",
+        "Read the running app, never only its source: a UI claim inferred from\n"
+        "code is not evidence. Measure against `.tezgah/design-contract.md` when\n"
+        "it exists (`tezgah-design check`). Every finding names the screen,\n"
+        "breakpoint and state it came from and a 0-4 severity. Report findings;\n"
+        "do not edit source files."),
+    "tezgah-researcher": (
+        "Runs one research line through OpenResearch: hypotheses, experiments, "
+        "literature, a report - the protocol frozen before the run.",
+        ("research", "ai-research"),
+        "shell for `orx` and `tezgah-research`; writes only under .tezgah/research",
+        "Load the OpenResearch manual first (`orx skill`) and follow its\n"
+        "experiment-tree rules. Work inside the one line the brief names; never\n"
+        "open a second line while one is open (`tezgah-research status`). Freeze\n"
+        "the protocol and the criteria before any run; a correction after a run\n"
+        "goes in `amendments.md`. Run `tezgah-research check` before reporting.\n"
+        "If `orx` is not installed, say so and stop."),
+}
+
+
+def _specialist_desc(name):
+    what, skills, tools, _role = SPECIALISTS[name]
+    named = ", ".join(s + (" (host-installed)" if s in HOST_SKILLS else "")
+                      for s in skills)
+    return "%s Skills: %s. Tier: %s (tezgah-route). Tools: %s." % (
+        what, named or "none", tm.AGENT_SLOT[name], tools)
+
+
+def _specialist_body(name):
+    _what, skills, _tools, role = SPECIALISTS[name]
+
+    def body(_host):
+        load = ("Load these skills before anything else, those this host has: "
+                "%s.\n" % ", ".join("`%s`" % s for s in skills)) if skills else ""
+        return ("You are %s, a specialist on the %s model tier. Do exactly the\n"
+                "brief: stay inside the files and paths it names (absolute paths\n"
+                "under the worktree it gives, never the main checkout), and\n"
+                "report what you did and what each command printed, verbatim.\n"
+                "%s%s\nIf the brief cannot be met as written, say so and stop.\n"
+                "Never spawn subagents." % (name, tm.AGENT_SLOT[name], load, role))
+    return body
+
+
+def _specialist(name, readonly=False):
+    return (name, _specialist_desc(name), lambda infra: True,
+            _specialist_body(name), readonly)
+
+
 # name, description, capability gate, body(host), read-only?
 ROLES = (
     ("tezgah-reviewer",
@@ -257,6 +360,11 @@ ROLES = (
      "unknown-cause debugging and hard-to-reverse changes on the strongest model "
      "tier; also where an ESCALATE from a cheaper worker is restarted.",
      lambda infra: True, _worker_body("frontier"), False),
+    _specialist("tezgah-tester"),
+    _specialist("tezgah-docs"),
+    _specialist("tezgah-security", readonly=True),
+    _specialist("tezgah-ui"),
+    _specialist("tezgah-researcher"),
 )
 
 # The roles gated on the code graph, which a repo's `.no-graph` turns off.
@@ -264,25 +372,38 @@ GRAPH_ROLES = ("tezgah-reviewer",)
 # Every agent name tezgah ever generated: the live roles, the orchestrator and
 # the retired roles. omp's files carry no MARKER, so this list - not the
 # `tezgah-` prefix - is what makes a file there tezgah's to sweep.
-RETIRED_ROLES = ("tezgah-explorer", "tezgah-verifier", "tezgah-researcher")
+# tezgah-researcher was retired and came back as the OpenResearch specialist.
+RETIRED_ROLES = ("tezgah-explorer", "tezgah-verifier")
 OWNED_NAMES = tuple(r[0] for r in ROLES) + ("tezgah-orchestrator",) + RETIRED_ROLES
 
 ORCH_DESC = ("Route work in this repo to the generated tezgah-* subagents. The "
-             "main thread decides and verifies; delegate bounded, well-specified "
-             "work and never let a subagent orchestrate another.")
+             "main thread decides and verifies; two or more independent items "
+             "fan out to parallel subagents in one message, one git worktree per "
+             "writing slice, and no subagent orchestrates another.")
 
 
 def _orch_body(names):
     listed = ", ".join(names) if names else "(none active yet)"
     return (
         "You are the tezgah orchestrator for this repository. You decide and\n"
-        "verify; you delegate bounded, well-specified work and read the evidence\n"
-        "back. Available specialists: %s.\n\n"
+        "verify; you delegate execution and read the evidence back. Available\n"
+        "specialists: %s.\n\n"
+        "Fan out by default: when the request or your todo list holds two or more\n"
+        "independent items, spawn one subagent per item in ONE message. Give\n"
+        "every writing slice its own branch and checkout - `orca worktree create\n"
+        "--name <slug> --parent-worktree active --json` when the session runs\n"
+        "inside Orca, else `git worktree add -b <branch> <absolute path>` - and\n"
+        "brief it with absolute paths under that checkout only, never the main\n"
+        "checkout. Serialize only a real\n"
+        "dependency, and never wait idle while independent work remains; you\n"
+        "integrate the branches and run the checks once on the merged tree.\n\n"
         "Route reviews to tezgah-reviewer, with the changed files and symbols in\n"
-        "the brief: where it has no shell it cannot run `git diff` itself. Brief a\n"
-        "code-discovery task to a tier worker with the codegraph tools; a second\n"
-        "opinion (`consult`) and research (`orx`) stay with the main thread. Other\n"
-        "work goes to the tier worker\n"
+        "the brief: where it has no shell it cannot run `git diff` itself. Checks\n"
+        "go to tezgah-tester, docs and citations to tezgah-docs, a security review\n"
+        "to tezgah-security, a running app to tezgah-ui, a research line to\n"
+        "tezgah-researcher. Brief a code-discovery task to a tier worker with the\n"
+        "codegraph tools; a second opinion (`consult`) stays with the main\n"
+        "thread. Other work goes to the tier worker\n"
         "`tezgah-route \"<brief>\"` names (tezgah-cheap, tezgah-standard,\n"
         "tezgah-frontier); an ESCALATE answer is restarted on tezgah-frontier with\n"
         "the same brief. Never delegate a task a specialist is not\n"
@@ -407,10 +528,11 @@ def omp_user_agents(root="~"):
     names = [r[0] for r in active]
     if not names:
         return {}
+    # A role that writes gets every tool the session has; a read-only one gets
+    # the read tools plus the shell its body bounds to read-only commands.
     out = {name + ".md": render_md_omp(
-        name, desc, body("omp"),
-        **({"tools": None} if name[len("tezgah-"):] in tm.TIERS else {}))
-           for name, desc, _cap, body, _readonly in active}
+        name, desc, body("omp"), **({} if readonly else {"tools": None}))
+           for name, desc, _cap, body, readonly in active}
     out["tezgah-orchestrator.md"] = render_md_omp(
         "tezgah-orchestrator", ORCH_DESC, _orch_body(names),
         tools=("read", "grep", "glob", "bash", "task"))

package/hooks/tezgah_components.py

@@ -114,6 +114,9 @@ COMPONENTS = [
     {"key": "workspace", "label": "workspace",
      "files": ["hooks/tezgah_policy.py", "hooks/tezgah_gate.py"],
      "switch": "workspace-off", "editable": False, "revert": "git"},
+    {"key": "fanout", "label": "fanout",
+     "files": ["hooks/tezgah_policy.py", "hooks/tezgah_agents.py"],
+     "switch": "orchestrate-off", "editable": True, "revert": "git"},
     {"key": "skills", "label": "skills",
      "files": ["skills/"],
      "switch": "none", "editable": True, "revert": "git"},