@r1z4x/tezgah 1.9.2 → 1.11.0

package/docs/models.md

@@ -22,7 +22,14 @@ generated in every tezgah root because routing needs no capability (`ROLES`,
 `hooks/tezgah_agents.py::ROLES`; their brief, `_worker_body`,
 `hooks/tezgah_agents.py::_worker_body`). So are the five specialists:
 `tezgah-tester`, `tezgah-docs`, `tezgah-security`, `tezgah-ui` and
-`tezgah-researcher` (`hooks/tezgah_agents.py::SPECIALISTS`). A specialist's
+`tezgah-researcher` (`hooks/tezgah_agents.py::SPECIALISTS`). The steering line names the agent per
+task class (`hooks/tezgah_agents.py::STEER`).
+Software design, invariants and unknown-cause debugging go to `tezgah-frontier`.
+A UI, screen or component build or redesign goes to `tezgah-standard`.
+Every tier worker's brief tells a UI build to read the `design-contract` skill, and
+`design-library` for critique (`hooks/tezgah_agents.py::_worker_body`).
+It then derives and checks with `~/.config/tezgah/bin/tezgah-design` before editing.
+Running-app UI or design analysis stays with `tezgah-ui`. A specialist's
 description names its slot from `AGENT_SLOT`. The tier a host shows and the
 model line it runs therefore cannot disagree, and `tezgah-agents --list` prints
 both. A cheaper worker that meets work above its tier answers `ESCALATE: <why>`,
@@ -36,12 +43,22 @@ cheap trajectory on a frontier model was the most expensive option measured
 
 ## The table (snapshot 2026-09-30)
 
-| slot | agents | anthropic | zai (omp's own provider) | openai | any (OpenRouter id) |
-|---|---|---|---|---|
-| cheap | tezgah-cheap, tezgah-tester | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash |
-| explore | omp's bundled `scout` | Opus 5.5 @medium | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | DeepSeek V4.1 Flash |
-| standard | tezgah-standard, tezgah-docs, tezgah-ui | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high |
-| frontier | tezgah-frontier, tezgah-reviewer, tezgah-security, tezgah-researcher | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high |
+| slot | agents | anthropic | zai (omp's own provider) | openai | any (OpenRouter id) | experientiallabs (models.yml provider) |
+|---|---|---|---|---|---|---|
+| cheap | tezgah-cheap, tezgah-tester | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash | DeepSeek V4.1 Flash Uncensored @low |
+| explore | omp's bundled `scout` | Opus 5.5 @medium | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | DeepSeek V4.1 Flash | DeepSeek V4.1 Flash Uncensored @low |
+| standard | tezgah-standard, tezgah-docs, tezgah-ui | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high | DeepSeek V4.1 Flash Uncensored @high |
+| frontier | tezgah-frontier, tezgah-reviewer, tezgah-security, tezgah-researcher | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high | DeepSeek V4.1 Flash Uncensored @high |
+
+The `experientiallabs` column runs omp through the custom provider of the same
+name in `~/.omp/agent/models.yml` (`OMP_AUTH`, `hooks/tezgah_models.py::OMP_AUTH`).
+omp resolves its key from `~/.omp/.env` as `EXPERIMENTALLABS_API_KEY`.
+The gateway's uncensored DeepSeek V4.1 Flash serves efforts none/low/high/max
+only (gateway model metadata, read 2026-10-20). Cheap and explore therefore
+carry `low` where the Anthropic column carries `medium`. The column has no
+`SNAPSHOT` row: `SNAPSHOT` holds OpenRouter ids, and `refresh` compares against
+OpenRouter's list. The provider's prices live in the models.yml `cost` block
+instead.
 
 Why these, briefly. Inside the Anthropic family the lever is effort, not model:
 Opus 5.5 and Sonnet 5.5 read cache at the same $0.20 per 1M tokens, and on
@@ -64,7 +81,7 @@ invoices).
 | Claude Code | anthropic | the agent file's alias and `effort:` (`_model_lines`): an alias follows the provider and keeps the main session's variant, where a full id breaks on Bedrock, Vertex and a gateway (code.claude.com/docs/en/sub-agents) |
 | Codex | openai | `model` and `model_reasoning_effort` in `$CODEX_HOME/agents/*.toml` |
 | opencode | any | a selector `--refresh` found in `opencode models` for the slot's model under any configured provider (`resolve_opencode`); none found, no model line, so the agent inherits. The slot's effort rides the JSON agent config as `reasoningEffort` (opencode.ai/docs/agents) |
-| omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **fallback chain** (`omp_overrides`, `_chain`): the mode's family first, then what `fallback` in `~/.config/tezgah/config.json` allows (`tp.fallback_policy`) over the families this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - `vendor`, the default, keeps only the session vendor's model (`openrouter/anthropic/claude-opus-5.5:<effort>` behind an Anthropic session, `OPENROUTER_ID`), so a 429 never moves an Opus session's subagent onto GPT or GLM; `any` adds every other funded family, rotated per agent; `none` writes the first entry alone - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>` under the same `fallback` rule, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`); a changed `fallback` reaches omp on the next `tezgah-route --refresh` or `tezgah-setup --install` |
+| omp | the saved `--mode` family, else anthropic when the session default is an Anthropic model, `experientiallabs` when it is an `experientiallabs/` selector, `any` otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **fallback chain** (`omp_overrides`, `_chain`): the mode's family first, then what `fallback` in `~/.config/tezgah/config.json` allows (`tp.fallback_policy`) over the families this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - `vendor`, the default, keeps only the session vendor's model (`openrouter/anthropic/claude-opus-5.5:<effort>` behind an Anthropic session, `OPENROUTER_ID`), so a 429 never moves an Opus session's subagent onto GPT or GLM; `any` adds every other funded family, rotated per agent; `none` writes the first entry alone - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>` under the same `fallback` rule, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`); a changed `fallback` reaches omp on the next `tezgah-route --refresh` or `tezgah-setup --install` |
 | dsh | - | none: no model setting was found to write |
 
 The orchestrator agent keeps `model: inherit`: it is the main thread's own agent.
@@ -215,7 +232,7 @@ moved against the snapshot (`SNAPSHOT`, `hooks/tezgah_models.py::SNAPSHOT`;
 re-applies omp's overrides. Scores are not re-read - they need a key - so
 `tezgah-route --check` reports the snapshot's age and exits 1 past 60 days or with
 a flag (`check`, `hooks/tezgah_models.py::check`); that is the moment to re-read
-the leaderboards and edit `SLOTS`. `tezgah-route --mode anthropic|zai|any|openai|auto|off` pins
+the leaderboards and edit `SLOTS`. `tezgah-route --mode anthropic|zai|any|experientiallabs|openai|auto|off` pins
 omp's family instead of following the session default; `off` removes every entry
 and role the table wrote and writes nothing, which is the way back when the
 provider those selectors need has no budget - a measured case, not a
@@ -229,6 +246,11 @@ omp status report carries a row for them.
 login (`OMP_OPENAI`, `hooks/tezgah_models.py::OMP_OPENAI`). Its ids are not the
 Codex host's `openai` column, which omp does not list. The mode is never a
 fallback for the others, and with no `openai-codex` login it writes nothing.
+`experientiallabs` pins the custom models.yml provider of the same name
+(`FAMILY_PREFIX`, `hooks/tezgah_models.py::FAMILY_PREFIX`). The selector is
+`experientiallabs/<model id>`, and omp reads its key from `~/.omp/.env`. The
+mode therefore applies even where that env var is not exported to the shell
+tezgah runs in.
 
 ## Source of truth
 

package/docs/operations.md

@@ -41,7 +41,7 @@ before an install is considered.
 | `update` | `tezgah update [--dry-run]` moves this install to the newest release through the channel it came from, then re-arms the hosts from the new tree. A release prefix goes through `--upgrade`. A Homebrew keg runs `brew upgrade r1z4x/tezgah/tezgah`, an npm tree runs `npm install -g @r1z4x/tezgah@latest`, and a git checkout runs `git pull --ff-only` (`update()`, `hooks/tezgah_update.py`). Before re-arming it prints every tezgah hook entry the new tree adds, removes or changes, per host. Paths compare with the tree root taken out, so a move to the new release's own path is no change. A real change on a terminal waits for a yes; Enter is no. A piped run goes on without asking (decision 12; `hooks/tezgah_update.py::confirm_rearm`). A no exits 1 after the fetch and says what it left. A checkout or an npm package is replaced in place, and the prefix's `current` already points at the new tree, so there the hooks run the new code and only the changed entries wait. A Homebrew keg is new beside the old one, so hooks wired to the old keg's path run the old code until the re-arm (`NOT_REARMED`, `hooks/tezgah_update.py::NOT_REARMED`). |
 | `--version` | Print the plugin version and exit (`bin/tezgah-setup::main`, `hooks/tezgah_context.py::version`). |
 | `--roots R` | Set the roots for this install, `os.pathsep`-separated. Without `--install` it exits 1: `--roots only means something with --install` (`bin/tezgah-setup::main`). |
-| `--hosts H` | Comma-separated subset of `claude,codex,opencode,cursor,dsh,omp`; an unknown name exits 1 before anything is written, and naming hosts switches off the re-detection that follows a tool install (`bin/tezgah-setup::main`, `bin/tezgah-setup::install_all`). |
+| `--hosts H` | Comma-separated subset of `claude,codex,opencode,cursor,dsh,omp`; an unknown name exits 1 before anything is written, and naming hosts switches off the re-detection that follows a tool install (`bin/tezgah-setup::main`, `bin/tezgah-setup::install_all`). `--install --hosts X` adds X to the hosts recorded in `config.json` and keeps the others. |
 | `-h`, `--help` | Usage and the list above (`bin/tezgah-setup::main`). |
 
 A green `--report` says the wiring is on disk; `--report --live` says it ran. What it cannot cover is the host binary itself: it runs the command the host would run, not the host, so a host that refuses to load its own config (a Claude plugin disabled in the UI after the check, a dsh build whose bridge drops the event) still needs a real session to show.
@@ -401,6 +401,19 @@ extension the engine has no parser for and an extensionless script it cannot key
 on at all. The extensionless case is why `bin/*` carries `.py` twins, and the
 report counts a tracked `bin/x` as covered when the index holds `bin/x.py`.
 
+A linked worktree starts with its main checkout's index. Git ignores
+`.codegraph/`, so a new worktree has none. When the main checkout has one, the
+auto-index copies it into the worktree before it starts the worker
+(`hooks/tezgah_context.py::seed_index`, called from
+`hooks/tezgah_context.py::autoindex`). The copy uses sqlite's backup API. The
+worker then runs `codegraph sync`, not `init` (`hooks/tezgah_index.py::command`).
+The database stores repo-relative paths, so the synced copy reads the
+worktree's own files. On this
+repository a sync over the copy took 1 s, and a fresh `init` took 10 s.
+`tezgah-task start` run inside a worktree seeds and starts the index the same
+way (`bin/tezgah-task::cmd_start`). A copy that fails leaves the worktree to
+`init`, as before.
+
 ## Opt-in taste: capture, learn, apply
 
 Taste learns the user's coding preferences from their own corrections. It is
@@ -631,6 +644,96 @@ it costs nothing there. On held-out Turkish phrasings of the docs index,
 meaning alone found the page in the top three for 0.91 with `embed-mrl` and 0.78
 with `embed-m2v`. The fusion found it for 0.75 and 0.74, BM25 for 0.68.
 
+## Opt-in OCR review spec: `ocr`
+
+The `ocr` feature id adds open-code-review (OCR) to a plan's review. It is off by
+default (`"default": False` in `hooks/tezgah_apps.py::REGISTRY`). Turn it on with
+`tezgah-setup --enable ocr`, which runs
+`npm install -g @alibaba-group/open-code-review@1.13.2`, the release whose prompts,
+delegate and rules match the vendored 375f64c texts. The binary is
+found by `ocr_bin()` (`hooks/tezgah_paths.py::ocr_bin`): `TEZGAH_OCR_BIN` first,
+then `ocr` on PATH. The verification step uses it only while `features` in
+config.json lists `ocr`, so an `ocr` installed for other
+work changes nothing. The report prints one `ocr on PATH` row
+(`bin/tezgah-setup::report`). Without `ocr` nothing changes: the verification
+step prints the same lines as before.
+
+With `ocr` installed, round one of the verification step adds an OCR review spec
+(`bin/tezgah-task::print_ocr_spec`). It runs `ocr delegate preview` and
+`ocr delegate rule` over `<base>..HEAD`. Both are deterministic and call no model
+(`bin/tezgah-task::ocr_spec`). The spec is input to the review, never a verdict.
+A failed or timed-out call prints one `OCR spec skipped:` line and the step
+goes on without it (`bin/tezgah-task::ocr_json`).
+
+The spec prints these lines:
+
+- The reviewable files OCR selected.
+- The files OCR excluded, with OCR's reason. OCR excludes tests and `.md` files.
+  They stay in the reviewer's scope: one more tezgah-reviewer reads them over the
+  usual dimensions.
+- The reviewer split, which follows OCR's own bundling thresholds. Under 4 files
+  and under 200 changed lines, one reviewer reads the whole change set. Under 4
+  files, one reviewer reads each file. From 4 files, one reviewer reads each OCR
+  rule group. Each brief carries its group's rule text verbatim and names the
+  vendored `main_task_system.md` as an appendix (`bin/tezgah-task::OCR_PROMPTS`).
+  Without a rule group, the per-dimension fan-out stands.
+- The refuter pass. Once the review merges its findings, one fresh tezgah-reviewer reads
+  the vendored `review_filter_task_system.md` as its instructions. It removes
+  only findings the diff proves wrong.
+- The quote check, `tezgah-review-quote` over the merged findings.
+
+The reviewer brief carries the matching rule
+(`hooks/tezgah_agents.py::_reviewer_body`). A reviewer given an OCR rule group
+accounts for every listed file as reviewed or skipped with a reason. It still
+applies the rest of its brief.
+
+`tezgah-review-quote --from BASE [--to HEAD] FINDINGS.json` places each finding by
+its quoted code (`bin/tezgah-review-quote::main`). Each finding needs `path` and
+`quote`, and may carry the `start_line` it cites. The tool adds a `status`.
+`located` means the quote is in the finding's own file. The match covering the
+cited line wins, else the one new-side match, else the one match. `unlocated`
+with `reason: "ambiguous: N matches"` means several matches and no cited line
+among them. `relocated` means no match in its own file and exactly one in
+another changed file, and `path` moves there. Any other `unlocated` finding goes
+back to its reviewer. A placed finding gets `start_line` and `end_line`, and
+`side: "old"` when the lines are pre-change (`bin/tezgah-review-quote::resolve`).
+It ports OCR's comment positioning from `internal/diff/resolver.go`.
+
+`tezgah-ocr-review [--from REF --to REF | --commit SHA] [--model SELECTOR]
+[--output FILE] [--allow-secrets]` runs OCR's own review loop on omp only. It
+starts one `omp auth-gateway stdio` child (`bin/tezgah-ocr-review::Gateway`).
+OCR then reviews on omp's model with omp's own credentials.
+
+- A loopback HTTP shim forwards OCR's requests to that child
+  (`bin/tezgah-ocr-review::handler`). It accepts `POST /v1/chat/completions` and
+  `GET /v1/models` only, with the per-run bearer token the tool hands OCR.
+  Another local process cannot spend omp's credentials during a run.
+- The tool writes no OCR provider config. OCR runs with a private, empty `HOME`.
+  A `~/.opencodereview/config.json` from standalone OCR use cannot redirect the
+  review.
+- Only the OCR process loses the caller's `OCR_*`, `ANTHROPIC_*` and `OPENAI_*`
+  variables (`bin/tezgah-ocr-review::run`). Git under OCR keeps the user's
+  global config and excludes, so a globally ignored file stays ignored. The omp
+  child keeps the caller's environment, because it needs omp's own credentials.
+- A path that looks like a secret stops the run with exit 3
+  (`bin/tezgah-ocr-review::first_secret`). In workspace mode the check covers
+  tracked, untracked and ignored files. In range or commit mode it covers the
+  tree of the reviewed ref. `--allow-secrets` skips the check. The patterns are
+  OCR's own (`bin/tezgah-ocr-review::SECRET_PATTERNS`).
+- A missing `ocr` or `omp` exits 2. A setup failure of the tool itself exits 4
+  with one line (`bin/tezgah-ocr-review::SetupError`). Three failures count:
+  no git repository, omp cannot start, the gateway never reports ready.
+
+Its findings are candidates for a tezgah-reviewer, never a verdict.
+
+`tezgah-setup` links both CLIs into `~/.config/tezgah/bin`
+(`bin/tezgah-setup::install_common`).
+
+The two OCR prompts live under `third_party/open-code-review/`. Tezgah copies them
+verbatim from alibaba/open-code-review at commit `375f64c`, under the Apache
+License 2.0, with its `LICENSE` beside them. Each prompt has one added first
+line, the modification notice (`third_party/open-code-review/README.md`).
+
 ## Plan records: the lock, `landed`, the close commit
 
 Every `tezgah-task` writer of a plan record holds an exclusive lock on the
@@ -761,6 +864,24 @@ The `~/.config/tezgah/slices-off` switch
 stops the hooks from writing records (`hooks/tezgah_paths.py::UNCLASSIFIED_SWITCHES`).
 A cwd outside a git repository writes nothing either.
 
+## A repository that is not this harness's
+
+Tezgah arms every repository under a root, because `roots()` is the only switch
+that decides. Every other switch is global (`~/.config/tezgah/*.off`) or
+per-feature (`.no-ponytail`, `.no-graph`). A project whose workspace is not this
+harness's says so itself, in a `tezgah.owner` file it commits at its own top:
+
+| Setting | What stops |
+|---|---|
+| `tasks: off` | the plan and task machine: no active task (`hooks/tezgah_task.py::_phased`), so no per-turn phase line and no scope held to a plan, the record rule holds no write to its own plan files (`hooks/tezgah_task.py::phased_record`), and every `tezgah-task` command that writes a record - the plan writers, the slice journal and `sweep` - is refused with the file named (`bin/tezgah-task::writes_a_record`, `bin/tezgah-task::owner_mark`). The scope gate, `bin/run-tool`, research and lessons keep reading the repository |
+| `harness: excluded` | everything: `root_for` answers None, so no contract text is injected, no workspace is set up, no plan, task or lesson record is written, and the gate passes every call (`hooks/tezgah_paths.py::harness_excluded`) |
+| `owner: <name>` | nothing - it names who owns the workspace, for the person reading the diff |
+
+The file comes from the nearest `.git` top at or above the path, so a repository
+cloned inside a marked one answers for itself. A missing or unreadable file, an
+unknown key and a blank value decide nothing
+(`hooks/tezgah_paths.py::owner_marker`).
+
 ## Troubleshooting
 
 | Symptom | First check | Likely cause |
@@ -911,6 +1032,10 @@ page exits 1 with the message it always printed (`available()`,
   spawn parser, reconcile, resume, prune and stats.
 - `hooks/tezgah_paths.py`, `hooks/tezgah_context.py` — the paths and `off()`; the
   marks and the kill-switch filtering.
+- `bin/tezgah-task`, `bin/tezgah-review-quote`, `bin/tezgah-ocr-review`,
+  `third_party/open-code-review/` — the opt-in OCR review spec, the quote check,
+  OCR's own loop on omp, and the vendored prompts. `tests/test_task.py`,
+  `tests/test_review_quote.py` and `tests/test_ocr_review.py` pin them.
 - `RELEASING.md`, `README.md`, `AGENTS.md`, `.gitignore`, `tests/test_setup.py` —
   the version rule, the install and configuration sections, the layer map, what
   stays untracked, and the behaviour these checks pin.