@r1z4x/tezgah 1.4.0 → 1.5.0

package/docs/operations.md

@@ -435,18 +435,21 @@ builds it (`capture_signals`, `bin/tezgah-taste::capture_signals`). A signal
 holds the prompt, the files written, the agent's edits, and the user's own edit
 between two agent writes. That last one compares the after blob with the next
 write's pre-state, or with the file on disk (`user_diff`,
-`bin/tezgah-taste::user_diff`). `learn` asks TypeSafe for one typed decision per
-signal (`decide`, `bin/tezgah-taste::decide`, [judge](judge.md)). The decision
+`bin/tezgah-taste::user_diff`). `learn` asks the Jev model for one typed decision
+per signal (`decide`, `bin/tezgah-taste::decide`, [judge](judge.md)). Any Jev
+carrier will do: TypeSafe, OpenRouter System One, Cloudflare Workers AI or a
+compatible endpoint. The decision
 names preference, defect or none. It picks one of eleven fixed categories and a
 scope. It also says how the signal relates to each learning held: supports,
-contradicts, narrows or unrelated. When another provider answers, `learn` records
-the decision in the `decisions` table as `unverified` and never applies it. A
+contradicts, narrows or unrelated. When a provider outside the Jev family answers,
+`learn` records the decision in the `decisions` table as `unverified`. It never
+applies it. The report counts the typed decisions under `jev`. A
 defect goes to the `defects` table and never into the ledger.
 
 Armed taste also learns by itself. At session start, `learn` starts in the
 background when new signals arrived since the last start. It starts at most
 once an hour per repository (`learn_later`, `hooks/tezgah_taste.py::learn_later`). It runs
-with `--no-fallback` and only when a TypeSafe key resolves, so it never pays a
+with `--no-fallback` and only when a Jev carrier resolves, so it never pays a
 generative provider for a decision it could not apply. It does not run on
 Windows, which has no ledger lock yet. The stamp is a `taste_learn` row of the
 cache's `tezgah.db`. The log lives under the cache dir, in `taste-learn/`.
@@ -661,7 +664,7 @@ or its optional tools and config, on its own initiative
 
 ## Triage: `tezgah-triage` and the `judge-off` switch
 
-One judgement seam serves five callers, each of them asking TypeSafe a batched
+One judgement seam serves five callers, each of them asking the judge a batched
 question instead of paying an agent to read a page: the analyze-app loop's snapshot
 triage (`bin/tezgah-triage`), `bin/tezgah-docs` for a query its keyword index
 cannot place, and the prompt-path skill hint (`hooks/tezgah_skill_pick.py`), the
@@ -700,7 +703,10 @@ made - no credential, the switch below, or a failed call - and the loop reads th
 tree directly instead.
 
 The state leaves the machine. A judgement sends the state and the questions to
-`api.typesafe.ai` (`ask()`, `hooks/tezgah_judge.py::ask`) - for the triage that is
+the host of whichever provider answers - the session's own CLI (omp, claude,
+opencode, cursor, codex), or the chosen Jev
+carrier's (`api.typesafe.ai`, `openrouter.ai`, `api.cloudflare.com` or a
+`JEV_API_BASE_URL`, see [judge](judge.md)) (`ask()`, `hooks/tezgah_judge.py::ask`) - for the triage that is
 the snapshot's own text, so a screen carrying personal data is read by a third
 party, and for the docs fallback it is the reader's query. Nothing else goes: no
 session id, no workspace path, no credential beyond the bearer header, and the
@@ -710,11 +716,16 @@ request cannot drift. That is why the two shell callers are on-demand - an agent
 asks for a judgement, no gate does - while the skill hint asks only with its own
 marker armed, and why the switch below is the off button for the whole path.
 
-The credential resolves from `TYPESAFE_API_KEY`, else from
-`~/.config/typesafe/key` (`credential()`, `hooks/tezgah_judge.py::credential`), and when
-neither resolves the same questions go to the OpenRouter fallback, whose key rides
-`OPENROUTER_API_KEY` and then `~/.config/openrouter/key`
-(`openrouter_key()`, `hooks/tezgah_judge.py::openrouter_key`). The file is the channel that
+With no session CLI, the third party is the Jev model through one of its carriers.
+TypeSafe's credential resolves from `TYPESAFE_API_KEY`, else from
+`~/.config/typesafe/key`, else from the active omp login (`typesafe_key()`,
+`hooks/tezgah_paths.py::typesafe_key`). `jev` chooses which of the other Jev
+carriers the seam asks - OpenRouter's System One endpoint, Cloudflare Workers AI
+and any System One-compatible URL (`jev_carriers()`,
+`hooks/tezgah_paths.py::jev_carriers`). The OpenRouter chat fallback's key rides
+`OPENROUTER_API_KEY` and then `~/.config/openrouter/key` (`openrouter_key()`,
+`hooks/tezgah_judge.py::openrouter_key`). When no carrier answers, the same
+questions go to that chat fallback. The file is the channel that
 matters on a machine exporting the variable from `~/.zshenv`: a hook or a bin tool
 runs in a non-interactive shell, where that export never ran, so the file is what a
 judgement actually resolves. Cost is input tokens alone - $0.042 per

package/docs/skills.md

@@ -176,7 +176,7 @@ it (`tests/test_skills.py::SkillStandards`).
 | `no-ai-slop` | Edits a draft sharper and more human without losing the voice, or flags slop; fires on a draft review, on a draft in a language other than English, on text that must keep terms, identifiers or unit symbols verbatim, and before publishing English prose tezgah writes itself. |
 | `analyze-app` | Inspects and drives a running web or mobile app from its accessibility / DOM / view tree, its rendered screen (screenshots, blur and grayscale tests, breakpoints) and measurements taken in the page; fires when a task must verify behaviour or read the UI, not just read source. |
 | `plan-add` | Creates a plan under `.tezgah/plans/open/` with its own `allowed_paths:` scope, bootstraps the `.tezgah/plans/` layer if missing, commits it in the private `.tezgah` repository (`git -C .tezgah`, never the project's git); fires on `/tezgah:plan-add`, "track this as a plan". |
-| `plan-status` | Reads every open plan, enriches rows with live PR state from `gh`, rewrites the README table (committed in the private `.tezgah` repository) and recommends the next plan; fires on `/tezgah:plan-status` or "what plans are open". |
+| `plan-status` | Reads every open plan and `tezgah-task status` (each plan's Acceptance boxes ticked, the plans its `after:` waits on, the ready plans that can run at once), enriches rows with live PR state from `gh`, rewrites the README table (committed in the private `.tezgah` repository) and recommends the next plan; fires on `/tezgah:plan-status` or "what plans are open". |
 | `plan-sync` | Closes finished plans whose PR merged or closed through `tezgah-task close`, which moves a plan to `.tezgah/plans/done/` as done only when it records an approving `review:`; commits one message per plan in the private `.tezgah` repository; fires on `/tezgah:plan-sync`, "sync plans". |
 | `research` | Runs an auditable research line - two loops, protocol before run, six-dimension review, provenance; fires when the deliverable is evidence: a lit review, a hypothesis, a benchmark or ablation. |
 | `product-analysis` | Runs a product analysis across five axes - value (HEART), usability (heuristics, the cognitive walkthrough, WCAG 2.2, axe-core, the running app read through `analyze-app` down to component x state, tree and image both), feasibility (a cited `path:line`), competition (a dated teardown) and triage (keep/fix/cut/bet) - with one named evidence class per finding, executed as a research line; fires on a product, feature, retention or roadmap question rather than a code change. |

package/docs/vision.md

@@ -22,11 +22,16 @@ the workspace's own records; every number below names where it came from.
    runs, 106 minutes, 10 of them green confirmations, in one session - the rule
    "run the full suite once, on the final tree" was already written down and
    `AGENTS.md` said "before every commit".)
-3. **A review loop reads every fix.** A round that confirms a defect gets a
-   round over the fix. The loop ends when a round confirms none
-   (`hooks/tezgah_agents.py::_reviewer_body`). The same defect family three times means the
-   design changes. (Measured: two of four severe defects in one internal plan came from
-   fixes, after round two.)
+3. **One review per plan, two rounds, fanned out.** Reviewers read the plan's
+   whole diff once, in its verification phase. Round one spawns them together,
+   one per dimension. Only a confirmed critical or major finding opens round two,
+   and round two reads the fix's delta. After round two the user gets what is
+   left, or the plan lists it as fix-later. `tezgah-task review` refuses a third
+   round (`hooks/tezgah_agents.py::_reviewer_body`, `bin/tezgah-task::cmd_review`).
+   (Measured: the old loop opened a round on any finding and ended only on a
+   clean round. It reviewed one finished plan round after round. In another plan,
+   fixes brought two of four severe defects. So round two reads the fix, and a
+   severe finding left after it blocks.)
 4. **Doubt lowers nothing and hides nothing.** An unverifiable check never
    downgrades a finding, an unknown criterion never relaxes a cap, and a line
    whose own criteria are unmet is reported as unanswered rather than concluded.

package/hooks/tezgah_agents.py

@@ -206,15 +206,22 @@ def _reviewer_body(host):
         "is lowered only by evidence: a check you could not complete never\n"
         "downgrades a confirmed finding - keep its severity and mark it\n"
         "provisional. Disclose the order you read the files in.\n\n"
-        "Scope and budget. Every round that confirms a defect is followed by a\n"
-        "round over that fix's delta; the review ends when a round confirms none.\n"
-        "A later round reads only the delta since the sha the previous round\n"
-        "recorded (`tezgah-task review` prints it): re-reading the whole diff\n"
-        "re-reports what was already triaged. Test results are input, not a task\n"
-        "- read the author's output file; do not run the suite, and run at most one\n"
-        "`-k` test when a specific accusation needs it. The same defect family\n"
-        "confirmed three times is a sign the design needs a pivot, not another\n"
-        "patch.\n\n"
+        "Scope and budget. One review per plan, over its whole diff in the\n"
+        "verification phase; at most two rounds - only a confirmed critical or\n"
+        "major finding opens round two, a minor or suggestion one is recorded\n"
+        "fix-later, and after round two what is left goes to the user or is\n"
+        "recorded fix-later, never a third round. A round may be a fan-out of\n"
+        "reviewers spawned at once, one per dimension (correctness and contract,\n"
+        "security, tests and performance) or per file group: when your brief\n"
+        "names a dimension or files, review only those - a sibling owns the rest.\n"
+        "Round two reads only the delta since the sha round one recorded\n"
+        "(`tezgah-task review` prints it), plus the round-one hunks and direct\n"
+        "callers of the symbols that delta touches, and marks every round-one\n"
+        "finding closed or open: re-reading the whole diff re-reports what was\n"
+        "already triaged. Test results are input, not a task - read the author's\n"
+        "output file; do not run the suite, and run at most one `-k` test when a\n"
+        "specific accusation needs it. The same defect family confirmed in both\n"
+        "rounds is a sign the design needs a pivot, not another patch.\n\n"
         "%s" % (_graph_howto(host), _blast_radius(host), EMPTY_IS_NOT_PROOF,
                 _may_use(host)))
 
@@ -343,7 +350,8 @@ ROLES = (
     ("tezgah-reviewer",
      "Adversarial, read-only review of a diff, branch or PR: derives the blast "
      "radius, checks correctness, contract, security, tests and performance, and "
-     "classifies every finding confirmed/refuted/unverified.",
+     "classifies every finding confirmed/refuted/unverified. One review per plan, "
+     "at most two rounds; spawn one per dimension in one message for a large diff.",
      lambda infra: infra["caps"]["graph"], _reviewer_body, True),
     ("tezgah-cheap",
      "Mechanical, fully specified edits on the cheapest model tier: renames, "
@@ -389,7 +397,10 @@ def _orch_body(names):
         "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"
+        "independent items, count them and spawn one subagent per item in ONE\n"
+        "message - at every phase: a plan's tasks, its acceptance commands and the\n"
+        "sources of a survey are items too, and checks that share no state run as\n"
+        "tool calls in one message, never a queue. 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"

package/hooks/tezgah_context.py

@@ -26,8 +26,9 @@ from tezgah_integrity import (STEP_KINDS, _heredocs, _path as _ledger_path,
                               UNTRUSTED_CHANNEL)
 from tezgah_lessons import (lesson_key, lines as lesson_lines,
                             tainted as tainted_lessons)
-from tezgah_policy import (CONDITIONAL_KEYS, CORE, POINTERS, PROMPT_REMINDER,
-                           REPLY_LANG_TEXT, open_lines_note, pony_level_line)
+from tezgah_policy import (CONDITIONAL_KEYS, CORE, FANOUT_ACTION, POINTERS,
+                           PROMPT_REMINDER, REPLY_LANG_TEXT, open_lines_note,
+                           pony_level_line)
 from tezgah_paths import (CACHE, REPO_MARKS, SWITCHES, ai_research_dir, armed,
                           cache_dir, codegraph_bin, consult_options,
                           ensure_workspace, fallback_cache, have_judge_key, off,
@@ -106,6 +107,21 @@ def _tr_ui_ask(word):
     return (r"(?:\b(?:%s)\w*[^.!?\n]{0,40}\b(?:%s))" % (TR_UI_OBJECTS, word))
 
 
+# The fan-out hint's parts (PROMPT_HINTS["fanout"]). A list item's marker:
+# `1.`, `1)`, `1 -`, `1:`, `a)`, or a `-`/`*`/`+`/`•` bullet, then its text.
+_FAN_ITEM = r"(?:\d+[ \t]*[.):\u2013-]|[a-z]\)|[-*+\u2022])[ \t]+\S"
+# A file a prompt names: a path with a directory, or a name with an extension.
+# Anchored at a token start: unanchored, a long run of word characters made
+# every position a start and the search quadratic (100 KB took minutes).
+_FAN_FILE = (r"(?<![\w./-])[`'\"]?(?:(?:[\w.-]+/)+[\w.-]*\w|"
+             r"\w[\w-]*\.[a-z]{1,4}\b)[`'\"]?")
+# The imperative that opens an English clause and closes a Turkish one.
+_FAN_VERB_EN = (r"(?:fix|add|update|write|remove|delete|rename|move|refactor|"
+                r"document|bump|create|implement|migrate|replace)")
+_FAN_VERB_TR = (r"(?:düzelt|güncelle|ekle|yaz|sil|kaldır|taşı|bitir|tamamla|"
+                r"incele|oluştur|değiştir)")
+
+
 PROMPT_HINTS = (
     ("spec", r"\b(normal (user )?behaviou?r|clean ui|nicer|more intuitive|"
              r"un?professional|polish(ed)?|improve the (ui|ux)|make it (better|"
@@ -340,9 +356,22 @@ PROMPT_HINTS = (
     # had to say "do everything with subagents and in parallel" on every task
     # because nothing armed the fan-out rule from the shape of the request.
     # `parallelize` alone is code work, so only the delegation phrasings count.
-    ("fanout", r"(?ms:^[ \t]*\d+[.)][ \t]+\S.*?^[ \t]*\d+[.)][ \t]+\S)|"
-               r"(?ms:^[ \t]*[-*•][ \t]+\S.*?^[ \t]*[-*•][ \t]+\S)|"
-               r"\b(?:in parallel|paralel\w*|sub-?agents?|alt ?ajan\w*|"
+    # The owner's own shapes armed nothing until 2026-10-09: `1 - `, `1- `,
+    # `1:`, `a)`, `+` items, an inline `1. ... 2. ...`, "subagentlerle", three
+    # files named as one list, "First, ... Second, ...", and three imperative
+    # clauses in one sentence (clause-initial in English, clause-final in
+    # Turkish). A timestamp, a range and a traceback stay out (the corpus).
+    ("fanout", r"(?ms:^[ \t]*" + _FAN_ITEM + r".*?^[ \t]*" + _FAN_ITEM + r")|"
+               r"(?<![\w.])1[ \t]*[.)-][ \t]+\S[^\n]*?(?<![\w.])2[ \t]*[.)-][ \t]+\S|"
+               + _FAN_FILE + r"(?:[ \t]*(?:,[ \t]*(?:(?:and|ve)[ \t]+)?|"
+               r"(?:and|ve|&)[ \t]+)" + _FAN_FILE + r"){2,}|"
+               r"(?s:\bfirst(?:ly)?[,:].*?\bsecond(?:ly)?[,:])|"
+               r"(?s:\bbirinci(?:si)?[,:].*?\bikinci(?:si)?[,:])|"
+               r"(?m:(?:(?:^|[,;]|\band\b)[ \t]*(?:and[ \t]+)?" + _FAN_VERB_EN
+               + r"\b[^\n]*?){3})|"
+               r"(?m:(?:\b" + _FAN_VERB_TR + r"\w{0,4}[ \t]*(?:[,;.]|\bve\b|$)"
+               r"[^\n]*?){3})|"
+               r"\b(?:in parallel|paralel\w*|sub-?agent\w*|alt ?ajan\w*|"
                r"worktrees?|fan[- ]?out|orchestrat\w*|orkestra\w*)\b"),
 )
 
@@ -1094,8 +1123,13 @@ ARMED_RESURFACE = 20
 def armed_again(key):
     """The one line a matching prompt pays for a paragraph this session was
     already shown. The research rule keeps its `{OPEN_LINES}` slot: the open
-    lines are a fact about the repo now, not rule text the session holds."""
+    lines are a fact about the repo now, not rule text the session holds. The
+    fan-out rule keeps its action (`FANOUT_ACTION`): the rule is a thing to do
+    on this turn's list, and a bare reminder that it exists was not done."""
     label = dict(CORE_RULES)[key]
+    if key == "fanout":
+        return ("%s Armed again: %s The full rule is in the `tezgah-contract` "
+                "skill." % (label, FANOUT_ACTION))
     return ("%s Armed again: the full rule was given earlier this session and "
             "is in the `tezgah-contract` skill.%s"
             % (label, "{OPEN_LINES}" if key == "research" else ""))