@r1z4x/tezgah 1.5.1 → 1.7.0

package/docs/research.md

@@ -65,7 +65,9 @@ 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. Rules 5 add the scope lock. A bump never weakens an older set.
+sections below. Rules 5 add the scope lock. Rules 6 add the selection warnings
+("Held-out set, repeats and noise band" below). Rules 7 add the `exploratory`
+method ("Rules 7: exploratory lines" below). 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
@@ -121,7 +123,8 @@ 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`
+  qualitative|measured|exploratory` writes `method` (`exploratory` from rules 7,
+  see "Rules 7: exploratory lines"). `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.
@@ -149,11 +152,14 @@ gets the question, its scope and its method in its brief. The research skill's
 
 | Path | Holds |
 |---|---|
-| `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 |
+| `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`) with its `noise_band`, the optional `held_out` set (rules 6), the `arena` of an exploratory line (`problem`, `budget`, and `evaluator`, `evaluator_sha256`, `metric` for a measurable one - rules 7, see "The arena lock"), 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`, `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 |
+| `ideas.jsonl` | an exploratory line's ideas, one JSON object per row, appended by `idea` (rules 7, see "Three files") |
+| `stages.jsonl` | an exploratory line's stage moves, one row per move, appended by `stage`; an idea's stage is its newest row |
+| `tournament.jsonl` | an exploratory line's judged pairwise matches, appended by `match` |
 | `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 |
 | `experiments/<hypothesis>/analysis.md` | what the rows mean, and which claim they move |
@@ -168,7 +174,9 @@ gets the question, its scope and its method in its brief. The research skill's
 file that exists (`init`, `hooks/tezgah_research.py::init`); `predictions.jsonl` is not
 one of them, because a file that exists without a row is a line that looks like
 it predicted something - it appears with the first `predict` the line records,
-and `check` reads an absent one as no rows rather than as a missing file. A slug
+and `check` reads an absent one as no rows rather than as a missing file. The
+three campaign files work the same way. Each appears with its first `idea`,
+`stage` or `match`. A slug
 is lowercase letters, digits and dashes (`valid_slug`,
 `hooks/tezgah_research.py::valid_slug`), because it is the directory name `check`, `status` and
 `claim` look for.
@@ -238,14 +246,66 @@ through its seal.
 | `tezgah-research source <slug> <hypothesis> --run <orxRunId> [--command "..."] [--scope real\|fixture\|derived] [--fixture "<what was generated>"]` | keeps the receipt: runs `orx logs <runId>`, writes `raw/<runId>.log`, appends the results row `{"source": "orx:<runId>", ...}` and the scope and fixture description the filer states (`source_run`, `hooks/tezgah_research.py::source_run`). A `--scope fixture` filed without `--fixture` still writes the row and prints the field it still owes, so the tool is never the thing that makes its own checker warn silently; a given `--fixture` that is empty is misuse | 0, 1 nothing filed, 2 without orx |
 | `tezgah-research compare <slug> <decision>` | reads one variants x criteria cell from stdin and appends it to `decisions/<decision>/comparison.jsonl` under the lock, or refuses it by the rule `check` applies (`append_comparison` and `comparison_problems`, `hooks/tezgah_research.py`); it notes when `criteria.json` is not committed yet | 0, 1 refused, 2 misuse |
 | `tezgah-research close <slug> --limit "<reason>"` | concludes the line as a deliberate limit, writing the reasons it was still open into `state.json` `closed` and `log.md`, and seals it (`close_line`) | 0, 1 unreadable state, 2 misuse |
+| `tezgah-research verdict <slug> <id> met\|not-met\|unanswerable --evidence "<ref>"` | records one success criterion's verdict and the evidence it rests on in the line's `state.json`, or refuses it with one `FAIL verdict:` line per problem (`verdict_problems`, `hooks/tezgah_research.py::verdict_problems`) | 0, 1 refused or unreadable state, 2 misuse |
+| `tezgah-research conclude <slug>` | concludes a line once every success criterion carries a verdict, seals it and moves it to `done/` (`conclude_line`, `hooks/tezgah_research.py::conclude_line`) | 0, 1 refused, 2 misuse |
+| `tezgah-research migrate-layout` | moves flat `research/<slug>` directories into `open/` or `done/` by each line's state, and is idempotent (`migrate_layout`, `hooks/tezgah_research.py::migrate_layout`) | 0, 2 misuse |
 | `tezgah-research seal <slug> [--history-lost] --ack "<owner decision>"` | seals a line under `done/` that was concluded before seals existed: plainly, as `conclude` would, when every experiment's order still checks; with `--history-lost`, with that verdict for every experiment whose order the lost history left undecidable. Refuses a line with a real order violation, a plain seal on any order finding, and a `history-lost` seal with nothing lost (`retro_seal`, `hooks/tezgah_research.py::retro_seal`) | 0, 1 refused, 2 misuse |
 | `tezgah-research import <checkout> [<slug>] [--allow-open "<reason>"]` | brings a line - or every line this checkout lacks - from another checkout's `.tezgah` repository with its history; an open line arrives beside open ones only with `--allow-open` (`import_line`, `hooks/tezgah_research.py::import_line`) | 0, 1 refused, 2 misuse |
+| `tezgah-research next --topic <t> [--flow f] [--json]` | prints every step of a product flow with its status from the topic's files under `.tezgah/analysis/<topic>/`, then the first missing or due step's skill and command; `--flow` picks `metric-dashboard` (the default) or `feature`, and `--json` prints the same steps as data (`next_steps`, `hooks/tezgah_product.py::next_steps`) | 0, 2 unknown flow or no `--topic` |
+| `tezgah-research init <slug> --ask "<the user's words>" --method exploratory --in "<covered>" --out "<left alone>" --arena "<problem>" --budget "<budget>" [--evaluator <path> --metric "<metric>"]` | opens a rules-7 exploratory line and writes the arena into `state.json` (`arena_record`, `hooks/tezgah_research.py::arena_record`). `--ask`, `--in` and `--out` are required as on any rules-5 line. Without `--arena` or `--budget` it is misuse; `--evaluator` and `--metric` go together; the evaluator has to be a file in the repository; the four flags on any other method are misuse. Its next step says to commit the arena before the first idea | 0, 1 refused over open lines, 2 misuse |
+| `tezgah-research idea <slug>` | reads one idea row from stdin and appends it to `ideas.jsonl` under the lock, or refuses it with one reason per problem (`append_idea`, `hooks/tezgah_research.py::append_idea`) | 0 written, 1 refused, 2 misuse |
+| `tezgah-research stage <slug> <idea> <stage> [--evidence "<ref or JSON>"] [--reason "<why>"]` | appends one stage move to `stages.jsonl` under the lock, or refuses it. `--reason` is the kill's reason, and a `known` prior art needs it for the kill appended with it (`append_stage`, `hooks/tezgah_research.py::append_stage`) | 0 written, 1 refused, 2 misuse |
+| `tezgah-research match <slug>` | reads one judged match from stdin and appends it to `tournament.jsonl` under the lock, or refuses it (`append_match`, `hooks/tezgah_research.py::append_match`) | 0 written, 1 refused, 2 misuse |
+| `tezgah-research board <slug> [--json]` | the campaign as its files show it: arena, rows, torn tails, each idea's stage, score and next action, the ideas tested and the next step; writes nothing (`board_text`, `hooks/tezgah_research.py::board_text`) | 0, 2 misuse |
+| `tezgah-research dedup <slug> [--threshold <(0, 1]>] [--json]` | clusters the `proposed` ideas by statement and prints the `stage ... duplicate` command for each member; names the backend and the threshold's source; writes nothing (`dedup_text`, `hooks/tezgah_research.py::dedup_text`). A `--threshold` outside `(0, 1]` is misuse | 0, 2 misuse |
+| `tezgah-research yield [--json] [--all-lines]` | per operator and per generator family, how many ideas reached each stage, the kill reasons, the board-score-to-pilot correlation and the next campaign's operator weights; writes nothing (`yield_text`, `hooks/tezgah_research.py::yield_text`) | 0, 2 misuse |
 
 Exit code 2 is always misuse, so a caller can tell it from a line that fails the
 checks (`misuse`, `bin/tezgah-research::misuse`). `check` asks nothing at all - no
 network, no model - so its answer is reproducible on a machine with no
 credential; only `--orx` asks the one question that leaves the machine.
 
+## The next step of a product flow
+
+`tezgah-research next --topic <t>` tells the session which step of a product flow
+comes next. Its step table is `FLOWS` (`hooks/tezgah_product.py::FLOWS`).
+Each step names its `id`, the `skill` that runs it, what it `leaves` behind and
+the `command` that writes it. The `product-flow` skill lists the same nine steps
+in prose and names `next` as their status source.
+
+Two flows exist. `metric-dashboard` is the default and has nine steps. `feature`
+drops the metrics and instrumentation steps, unless the topic's `flow.md` already
+holds `## metrics`. `--flow <f>` picks one.
+
+`next_steps` (`hooks/tezgah_product.py::next_steps`) computes each status from the
+topic's folder, `.tezgah/analysis/<topic>/`, and reads nothing else. Nothing
+stores a status. A step is `done`, `missing` or `due`:
+
+| Step | Done when |
+|---|---|
+| `forward-spec` | `.tezgah/analysis/<topic>/spec.md` exists |
+| `re-measure` | `flow.md` holds `## re-measure`. Before that it reads `due` once the `observe after: YYYY-MM-DD` date under `## decision` has passed |
+| every other step | `flow.md` holds its `## <step>` heading |
+
+The `design` and `build` commands start with `tezgah-design check`. The design
+check and the Stop UI rule judge those two steps. The flow only asks for their
+note. A topic that is not kebab-case (at most 64 characters) reads no file. A
+topic with no folder yet lists every step as `missing`.
+
+The text output prints one line per step, then one `next:` line:
+
+```
+<n>. <id> [<status>] <skill> - <detail>
+next: <skill> - <command>
+```
+
+The `next:` line names the first `missing` or `due` step's skill and command.
+With no such step it reads `next: nothing left`. `--json` prints the same steps
+as a list of objects with `id`, `skill`, `status`, `detail` and `command`.
+
+`next` exits 0 when it prints the steps. It exits 2 for an unknown flow or a
+missing `--topic`.
+
 ## The pair the order rule compares
 
 The order rule is decided on the commit graph, so it needs both files committable
@@ -442,18 +502,288 @@ in `hooks/tezgah_research.py`, a module the frozen set forbids a prediction's
 commit to touch without a human `granted_by` (`FROZEN_PATHS`), so the gate that
 decides which candidate survives is not machinery the candidate can rewrite.
 
-What the pair cannot catch: **a tolerance its own author sets wide enough**. The
-band is a sentence, not a measurement, and `check` can see that it is written and
-readable - never that 0.02 is tight. A line that writes "capability metric within
-5.0 of the baseline" has adopted the form of the two-gate rule and none of its
-force, and the review is the only place that is decided.
+What the pair cannot catch alone: **a tolerance its own author sets wide
+enough**. A line that writes "capability metric within 5.0 of the baseline" has
+adopted the form of the two-gate rule and none of its force. From rules 6 the band
+is read against a measurement. `evaluation.noise_band` is
+`{"experiment": "<the experiment dir that reran the unchanged baseline>",
+"spread": <the spread that rerun measured>}`. `check` warns in three cases. The
+line declares `capability_tolerance` and no `noise_band`. `noise_band.experiment`
+names no experiment of the line. The tolerance sentence holds a number wider than
+`spread`, so the tolerance passes what noise alone would. A digit inside a name
+such as `p95` is not that number (`_check_selection`,
+`hooks/tezgah_research.py::_check_selection`). Whether the rerun was a fair one
+stays the review's call.
+
+## Held-out set, repeats and noise band (rules 6)
+
+The measured line `rsi-borrow-screen` found three gaps. Of 27 decisions, 25 select
+a variant and report it on the same cells. Of 23 armed experiments, 13 run once per
+arm. Three lines declare a tolerance, and none of them measured it. Rules 6 add one
+warning for each (`_check_selection`, `hooks/tezgah_research.py::_check_selection`).
+Each stays a warning under `--strict` too, never a refusal (ADR 019):
+
+- **Held-out set.** A measured line may name its held-out set in
+  `evaluation.held_out` (a non-empty string). It may log each look at that set in
+  `held_out_log.jsonl` at the line root, one row
+  `{"set", "candidate", "date", "result"}` per look. `check` warns when a
+  `decisions/<id>/` holds comparison cells and the line names no `held_out`: the
+  variant was selected and reported on the same cells. It also warns when one
+  candidate looked at one set more than once: the held-out set became development
+  data for it.
+- **Repeats.** An experiment is armed when its `results.jsonl` rows carry `arm` or
+  `variant` with two or more values. `check` warns when no row has `repeat`,
+  `repeats` or `k` above 1 and its `protocol.md` states no `k:`/`repeats:` above 1.
+  An armless experiment is not read.
+- **Noise band.** `evaluation.noise_band`, read in "Two gates" above.
+
+A line opened under rules 5 or earlier is not read for any of the three.
+
+## Rules 7: exploratory lines
+
+A `qualitative` or `measured` line answers a question. Some asks want new ideas,
+methods or approaches instead of an answer. Rules 7 add the method `exploratory`
+for those asks (`hooks/tezgah_research.py::EXPLORE_RULES`,
+`hooks/tezgah_research.py::METHODS`). The line runs one campaign. Many ideas
+enter it, a funnel kills most of them, and a run under a frozen evaluator judges
+the few that remain. One campaign is one line, so "One open line at a time" still
+holds. `scope_problems` (`hooks/tezgah_research.py::scope_problems`) accepts
+`exploratory` only on a rules-7 line. On an older line it names `qualitative` and
+`measured` as the two methods the line can take.
+
+### The arena lock
+
+`init <slug> --ask "<the user's words>" --method exploratory --in "<covered>"
+--out "<left alone>" --arena "<problem>" --budget "<budget>"` opens
+the line. The arena is the problem in the user's words. The budget says how many
+ideas, pilots and full runs, and how much wall time, the campaign may spend. A
+measurable arena adds `--evaluator <path> --metric "<metric>"`. The two flags go
+together, and the evaluator has to be a file in the repository. A missing arena
+or budget is misuse (exit 2).
+
+`arena_record` (`hooks/tezgah_research.py::arena_record`) builds `state.json`
+`arena`. It holds the problem and the budget. A measurable arena also holds the
+evaluator path, the sha256 of the evaluator's bytes and the metric. `init` also
+writes `deliverable: {"kind": "finding"}`. The campaign delivers its staged ideas
+as findings, never as compared variants (`hooks/tezgah_research.py::init`).
+
+The lock has three halves:
+
+- `arena_problems` (`hooks/tezgah_research.py::arena_problems`) names an absent
+  arena, an empty problem or budget, and an evaluator with no sha256 or no metric.
+  `check` reads it through `scope_problems`. It refuses these past `bootstrap` and
+  warns at it.
+- `_check_arena_order` (`hooks/tezgah_research.py::_check_arena_order`) finds the
+  lock commit. That commit is the first one along HEAD whose `state.json` arena
+  names a problem and a budget. `ideas.jsonl` and every experiment's
+  `results.jsonl` have to enter the history after it. An arena that differs from
+  the locked one is a refusal too. A new arena means a new line.
+- `evaluator_problem` (`hooks/tezgah_research.py::evaluator_problem`) hashes the
+  evaluator again. While the hash differs from the locked one, the writer and
+  `check` refuse every stage row. The candidate a campaign judges must not move
+  its judge.
+- `append_stage` (`hooks/tezgah_research.py::append_stage`) also compares the
+  working `state.json` arena with the arena at the lock commit
+  (`hooks/tezgah_research.py::_arena_lock`). While they differ, it refuses every
+  stage row. So a rewritten `evaluator_sha256` does not reopen the campaign.
+
+`init` prints the next step: commit the arena with `tezgah-research commit` before
+the first idea. The arena replaces the one locked metric of a measured line.
+`_check_evaluation` (`hooks/tezgah_research.py::_check_evaluation`) and
+`_check_evaluation_order` (`hooks/tezgah_research.py::_check_evaluation_order`)
+skip an exploratory line for that reason.
+
+### Three files
+
+The campaign lives in three append-only files at the line root. One function
+judges each row type, and the writer and `check` both call it. No file stores a
+status. An idea's stage is its newest `stages.jsonl` row
+(`hooks/tezgah_research.py::campaign_stages`).
+
+| File | One row | Writer | Judge |
+|---|---|---|---|
+| `ideas.jsonl` (`IDEAS_FILE`) | `id` (`I<n>`, unused so far), `statement` (two sentences at most), `mechanism`, `trace` (an in-scope item), `operator` (one of `OPERATORS`), `generator` (`{family, model}`), `kill` (the result that would kill it), `date`, and `parents` for a `mutation` (one or more) or a `crossover` (two or more) | `idea <slug>` | `idea_problems` |
+| `stages.jsonl` (`STAGES_FILE`) | `idea`, `stage`, `evidence`, `reason` for a kill, `date` | `stage <slug> <idea> <stage>` | `stage_problems` |
+| `tournament.jsonl` (`TOURNAMENT_FILE`) | `a`, `b`, `judge` (`{family, model}`), `order` (`ab` or `ba`), `winner` (`a`, `b` or `tie`), `rationale` | `match <slug>` | `match_problems` |
+
+The field list is `IDEA_FIELDS` (`hooks/tezgah_research.py::IDEA_FIELDS`). The
+moves are `OPERATORS` (`hooks/tezgah_research.py::OPERATORS`). `user` marks an
+idea the person asked for. `PARENT_OPERATORS`
+(`hooks/tezgah_research.py::PARENT_OPERATORS`) sets how many parents a derived
+idea names. An idea outside the arena's scope gets one line under Open questions
+in `findings.md`, never a row.
+
+Every append goes through `_append_campaign`
+(`hooks/tezgah_research.py::_append_campaign`). It takes the file lock and reads
+the rows from the locked descriptor. It judges the new row against them, cuts any
+torn tail (`truncate_to_committed`) and writes. A refused append leaves no file
+behind. `check` refuses a committed row that a later version changed or dropped.
+
+### The stage funnel
+
+`STAGES` (`hooks/tezgah_research.py::STAGES`) gives the order: `proposed`,
+`duplicate`, `prior-art`, `screened`, `piloted`, `promoted`, `confirmed`, and
+`killed`. `stage_problems` (`hooks/tezgah_research.py::stage_problems`) holds
+the moves to it:
+
+- The idea row is the `proposed` stage. A stage row that says `proposed` is a
+  refusal.
+- A stage moves forward in that order only, or to `killed`. A kill needs
+  `--reason`.
+- A stage also needs its prerequisite somewhere in the idea's history
+  (`hooks/tezgah_research.py::PREREQUISITES`). `screened` needs a `prior-art`
+  row. `piloted` needs `screened`, `promoted` needs `piloted`, and `confirmed`
+  needs `promoted`.
+- `killed` is final. A revived idea is a new idea that names the old one as its
+  parent.
+- After `duplicate`, the only allowed row is `killed`. The same holds after a
+  `known` prior art.
+
+Each stage asks for its own evidence. `--evidence` takes a reference or a JSON
+object.
+
+| Stage | Evidence | What the judge asks |
+|---|---|---|
+| `duplicate` | `{"of": "<id>", "similarity": <0..1>}` | `of` names another idea of the line |
+| `prior-art` | `{"verdict": "novel\|incremental\|known", "nearest": [...], "delta": "<one sentence>"}` | `nearest` names at least `NEAREST_MIN` (3) notes. `literature/INDEX.jsonl` indexes each one, and not all of them are `agent-report`. `delta` is one sentence (`_prior_art_problems`) |
+| `screened` | none | `tournament.jsonl` holds at least one match that names the idea |
+| `piloted`, `promoted` | `<h>` or `experiments/<h>` | `protocol.md` names the idea id and repeats its `kill` text. `results.jsonl` holds a row. When the check asks git, `protocol.md` is in a commit. If `results.jsonl` is committed too, `protocol.md` entered the history before it (`_run_problems`) |
+| `confirmed` | `{"experiment": "<h>", "set": "<set>"}` | the arena has an evaluator. The experiment differs from every `promoted` row's experiment. The run passes the same `_run_problems` checks. The first `held_out_log.jsonl` row for that set names this idea. Each look of this idea at the set carries a `YYYY-MM-DD` date, and none is dated before the idea's promotion: an earlier look was part of the selection. A look logged after the confirmation changes nothing (`_confirm_problems`) |
+| `killed` | `--reason "<why>"` | a reason |
+
+A `known` prior art kills the idea in the same write. `append_stage`
+(`hooks/tezgah_research.py::append_stage`) needs `--reason` for it. It appends
+the prior-art row and its `killed` row under one lock, so no file state holds a
+known idea alive. `check` refuses a `known` prior art with no kill after it.
+
+### The tournament is a prior
+
+A match is one judge's verdict on a pair. `bradley_terry`
+(`hooks/tezgah_research.py::bradley_terry`) fits a strength per idea from the
+matches. `board` ranks the ideas by it. The score moves no stage. `screened`
+asks only that a match exists. An LLM ranking is a prior, and a run under the
+frozen evaluator is the judge.
+
+`_tournament_warnings` (`hooks/tezgah_research.py::_tournament_warnings`) warns
+about thin judging. A pair judged only by the family that generated one of its
+ideas warns, unless both generators' families judged it. A pair judged in one
+presentation order warns. An idea with fewer than two judges warns.
+
+### Reports: board, dedup, yield
+
+The three reports write nothing and exit 0. None of them is a gate.
+
+- `board <slug>` (`hooks/tezgah_research.py::board`) shows the arena and whether
+  the evaluator still hashes as locked. It shows each file's row count, each
+  idea's rank, stage, score, record, operator, generator family and next action,
+  and the campaign's next step. An idea whose prior art is `known` gets the
+  `stage ... killed --reason` command as its next action. That resumes a campaign
+  whose kill row was torn off.
+- `dedup <slug>` (`hooks/tezgah_research.py::dedup`) clusters the `proposed`
+  ideas by statement, at one similarity threshold. The lowest id of a cluster
+  represents it. For every other member it prints the `stage ... duplicate`
+  command to run. `similarity_matrix` (`hooks/tezgah_research.py::similarity_matrix`)
+  uses the static embedding when the feature is on and pinned. Otherwise it reads
+  BM25 scores (`hooks/tezgah_rank.py::scores`) as a similarity. Every output names
+  the backend and where its threshold came from.
+- `yield` (`hooks/tezgah_research.py::yield_report`) counts, per operator and per
+  generator family, how many ideas reached each stage. It lists the kill reasons.
+  It gives Spearman's rho between the board score and the pilot outcome
+  (`hooks/tezgah_research.py::spearman`). It proposes the next campaign's operator
+  weights (`hooks/tezgah_research.py::operator_weights`). `EXPLORE_SHARE` (0.2)
+  of each draw stays uniform, so a move with no payoff yet still gets tried. It
+  reads the open exploratory lines, or every one with `--all-lines`.
+
+### Resume from the files
+
+Nothing outside the three files holds campaign state. A fresh session runs
+`board` and goes on from its `next:` line. A writer that dies mid-append can
+leave a fragment past the last newline. `_campaign_rows`
+(`hooks/tezgah_research.py::_campaign_rows`) reads up to the committed boundary
+and reports the fragment's size. `board` prints it on a `resume:` line. The next
+append drops the fragment, so the fix is to run the append that crashed again.
+
+### How many ideas were tested
+
+Fifty ideas tested at the 5% level yield about 2.5 winners by chance. A reader
+cannot discount what nobody counted. `_check_tested`
+(`hooks/tezgah_research.py::_check_tested`) warns when `to_human/report.md` has
+no line that names `piloted` with the number of ideas that reached it. The same
+holds for `promoted`. A number followed by a full stop counts, as in "reached
+piloted: 2.". `board` prints both numbers on its `tested:` line.
+
+### The dedup threshold (two label sets)
+
+Si et al. called two seed ideas duplicates at cosine 0.8 on MiniLM. That number
+does not carry to another similarity. Two label sets measured it here.
+
+- The fixture: 40 idea-statement pairs, 20 of them duplicates. The author of the
+  code labelled them. The acceptance runner records the sweeps as fixture-scoped
+  experiments: `dedup-calibration` (BM25) and `dedup-calibration-embed`
+  (embed-mrl). Copies stay under `.tezgah/scratch/calibration/`.
+- MRPC: 400 pairs of the Microsoft Research Paraphrase Corpus test set, 200
+  paraphrases and 200 not, sampled with seed 87. Human annotators labelled them.
+  The pairs are news sentences, and the negatives share many words. At BM25 0.30
+  the sample kept every paraphrase and 95% of the negatives. The script and its
+  output are `.tezgah/scratch/calib2/run.py` and `out.txt`.
+
+| Backend | F1 at 0.8 (fixture / MRPC) | Default | F1 at the default (fixture / MRPC) |
+|---|---|---|---|
+| embed-mrl | 0.62 / 0.64 | 0.65 | 0.90 / 0.705 |
+| BM25 | 0.09 / 0.41 | 0.40 | 0.70 / 0.69 |
+
+The default is the threshold, in steps of 0.05, whose worse F1 over the two sets
+is highest. Neither the author's labels nor the news domain picks it alone. On
+MRPC the best F1 beats the always-duplicate baseline (0.667) by about 0.04. The
+defaults are a coarse filter for a session to review, not a judge.
+
+`DEDUP_THRESHOLDS` (`hooks/tezgah_research.py::DEDUP_THRESHOLDS`) holds the two
+values. Any other backend keeps `DEDUP_THRESHOLD`
+(`hooks/tezgah_research.py::DEDUP_THRESHOLD`), Si et al.'s 0.8, and the output
+calls it uncalibrated. `--threshold` overrides all of them. Its range is
+`(0, 1]`.
+
+### The evidence behind the method
+
+- Si et al., arXiv 2409.04109: about 5% of 4,000 generated seed ideas were not
+  duplicates (cosine 0.8). The best LLM judge (a Claude-3.5 pairwise ranker)
+  agreed with the human ranking 53.3% of the time. Split-half reviewer panels
+  agreed 56.1%.
+- The ideation-execution gap, arXiv 2506.20803: after execution, AI ideas lost
+  1.98 points overall and human ideas lost 0.63.
+- Gupta and Pruthi, arXiv 2502.16487: 24% of 50 AI research documents
+  paraphrased or substantially borrowed earlier work. Plagiarism detectors missed
+  them.
+- HindSight, arXiv 2603.15164: novelty as an LLM judges it correlates negatively
+  with realized impact (rho = -0.29).
+- Darwin Godel Machine, arXiv 2505.22954: an archive of stepping stones beats
+  hill-climbing. The loop also removed its own detection markers and faked test
+  logs.
+- ShinkaEvolve, arXiv 2509.19349: parent sampling by fitness and novelty,
+  novelty rejection by embedding, and UCB1 over models.
+- POPPER, arXiv 2502.09858: falsification experiments on measurable implications,
+  with Type-I error control.
+
+The consequences:
+
+- An LLM ranking is a prior, never a verdict.
+- A run under the frozen evaluator is the judge.
+- Each idea gets its own prior-art check. No idea reaches `screened` without a
+  `prior-art` row (`hooks/tezgah_research.py::PREREQUISITES`).
+- `dedup` and the operator weights keep the ideas diverse.
+- The report always states how many ideas the campaign tested.
+
+Rules 1-6, `FROZEN_PATHS` and ADR 009 stay as they were. Predictions and
+components take nothing new. `research-off` covers this method too.
 
 ## What `check` refuses, and what it only warns about
 
 A **refusal** (exit 1) is a guarantee the checker can decide. A **warning** is a
 guarantee it cannot: the artifact is not wrong, it is unverifiable. `--strict`
-turns that whole class into a refusal, which is what a release gate wants and
-what a session mid-flight must not have, so the default stays `warn`.
+turns the warnings the listed rules write through `_soft` into a refusal, which is
+what a release gate wants and what a session mid-flight must not have, so the
+default stays `warn`. A warning written outside `_soft` stays one. The section
+below names three groups of them.
 
 Refused:
 
@@ -532,6 +862,40 @@ Refused:
   nothing, or a finding whose `quote` does not occur verbatim in its `target`
   (`_check_review`, `hooks/tezgah_research.py::_check_review`).
 
+On an exploratory line (rules 7), `check` also refuses each of these
+(`_check_exploratory`, `hooks/tezgah_research.py::_check_exploratory`, called
+from `_check_standards`):
+
+- an arena that `arena_problems` faults, past `bootstrap`. The faults are no
+  arena object, no problem, no budget, and an evaluator with no sha256 or no
+  metric (`hooks/tezgah_research.py::arena_problems`).
+- an arena that differs from the one the lock commit holds. The same goes for an
+  `ideas.jsonl` or `results.jsonl` that entered the history before that commit
+  (`hooks/tezgah_research.py::_check_arena_order`).
+- an idea row that `idea_problems` faults
+  (`hooks/tezgah_research.py::idea_problems`). That means a missing field, a
+  `generator` that is not `{family, model}`, or an id that is not `I<n>` or
+  repeats an earlier one. It also means an operator outside `OPERATORS`, a parent
+  no earlier idea carries, or too few parents for a `mutation` or `crossover`. The
+  last cases are a statement of more than two sentences and a date that is not
+  `YYYY-MM-DD`. A trace to no in-scope item and a missing arena fail it too.
+- a stage row that `stage_problems` faults
+  (`hooks/tezgah_research.py::stage_problems`). The funnel above lists the
+  moves and the evidence each stage asks for. Every stage row fails while the
+  evaluator's hash differs from the locked one
+  (`hooks/tezgah_research.py::evaluator_problem`).
+- a stage row that skips its `PREREQUISITES` stage, and any row but `killed`
+  after `duplicate` or after a `known` prior art.
+- a `known` prior art with no `killed` row after it.
+- a match row that `match_problems` faults
+  (`hooks/tezgah_research.py::match_problems`). That means a side that names no
+  idea, an idea matched against itself, or a `judge` that is not
+  `{family, model}`. It also means an `order` outside `MATCH_ORDERS`, a `winner`
+  outside `MATCH_WINNERS`, or no `rationale`.
+- a campaign file line that does not parse or is not an object
+  (`hooks/tezgah_research.py::_campaign_rows`).
+- a committed campaign row that a later version changed or dropped.
+
 Warned, and refused under `--strict` - each is the honest state of an artifact
 this layer cannot decide on, not a defect:
 
@@ -629,7 +993,18 @@ this layer cannot decide on, not a defect:
   judgement, so no migration can write one for the lines that concluded before
   the rule existed.
 
-One warn is **not** promoted by `--strict`, and it is the only one: a `phase`
+On an exploratory line, two more warnings take this class. One is an arena
+fault at `bootstrap`. The other is a campaign file git cannot order against the
+arena lock (`_check_arena_order`).
+
+Three groups of warnings are **not** promoted by `--strict`. The rules-6
+three (held-out set, repeats, noise band) stay warnings by ADR 019. The rules-7
+four stay warnings for the same reason: a tournament is a prior and a count is a
+disclosure. They are a pair that only a generator family of one of its ideas
+judged, unless both generators' families judged it. They are a pair judged in one
+order, and an idea with fewer than two judges (`_tournament_warnings`). The fourth
+is a `report.md` that does not state how many ideas reached `piloted` and
+`promoted` (`_check_tested`). The last is a `phase`
 declared in `state.json` behind the phase the line's own artifacts show
 (`_check_derived_phase`, `hooks/tezgah_research.py::_check_derived_phase`). The field is the author's
 declared intent and `_check_report` and `_check_review` read it, so a derivation
@@ -827,11 +1202,15 @@ armed. It removes the rule, not just the mark - the diff is in `core_split`,
   frozen set they read (`FROZEN_PATHS`), the protocol order and its tracked pair,
   the protocol's two questions, the concluded report's limits, the `supersedes`
   relation, `component_report` with the state it reads, `migrate`, `source_run`,
-  `init` and `summary`.
+  `init` and `summary`, and the rules-7 campaign: the arena lock, the three row
+  judges and their writers, `board`, `dedup` and `yield_report`.
 - `hooks/tezgah_components.py` - the manifest: the one definition of an editable
   component, the keys a prediction row names and the rules a row's outcome is
   attributed to.
 - `bin/tezgah-research` - the CLI, its subcommands and its exit codes.
+- `hooks/tezgah_product.py` - the product-flow steps and the `next` status reader.
+- `hooks/tezgah_rank.py` - `scores`, the BM25 reading `dedup` falls back to when
+  the static embedding is off.
 - `hooks/tezgah_policy.py` - the `RESEARCH` paragraph a session is armed with.
 - `hooks/tezgah_context.py` - the prompt hint, the missing-orx note, the broken
   line note and the `research` mark.

package/docs/skills.md

@@ -32,7 +32,7 @@ skill is simply not read.
 
 opencode's plugin does inject prompt-time text - the builder's per-turn block,
 the conditional rules included
-(`hosts/opencode/plugins/tezgah.js:2629-2658`) - but that text names at most one
+(`hosts/opencode/plugins/tezgah.js:2652-2681`) - but that text names at most one
 skill (the hint), never the roster, so the installer writes one:
 `~/.config/tezgah/opencode-skills.md` always-on and
 `opencode-skills.full.md` on demand (`bin/tezgah-setup::SKILL_ROUTER`, `bin/tezgah-setup::SKILL_ROUTER_FULL`), the first
@@ -128,6 +128,12 @@ 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.
 
+Some skills route through their own `INDEX.md`, like design-library's 39 entries.
+The search indexes each routed entry as one row for the whole file, addressed
+`skill://<skill>/<path>` (`hooks/tezgah_skill_pick.py::_entries`). The vendored
+sections are short, and per section BM25 let them outrank whole skills on two
+common words.
+
 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
@@ -174,15 +180,16 @@ it (`tests/test_skills.py::SkillStandards`).
 | `ponytail` | Forces the laziest solution that works, in levels lite/full/ultra; fires on any coding task, or "be lazy", "yagni", "shortest path". |
 | `i-have-adhd` | Shapes output for a reader who acts on it - action first, numbered steps, errors as location/cause/fix; fires on any answer the reader must act on, not on code, commits or docs. |
 | `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. |
+| `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, and writes the `.tezgah/design/measurement.json` that `design-contract`'s check reads; 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 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". |
+| `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:`, clears an active task's phase and removes every merged worktree that holds nothing else; 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. |
+| `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 and a metric record per metric (North Star and inputs; goal, definition, window, baseline, logged or not), executed as a research line; fires on a product, feature, retention or roadmap question rather than a code change. |
+| `product-flow` | Carries a new product capability - a metric dashboard, a metric, a feature - from research to re-measure by running `tezgah-research next --topic <t>` and doing the first missing step with the skill it names; the skill lists the nine steps in prose and `FLOWS` in `hooks/tezgah_product.py` holds their done rules; fires on "bu veriye uygun metric dashboard tasarla" or a new-feature ask, not on an audit of an existing feature. |
 | `pm-frameworks` | The two vendored product methods the analysis skill defers to - intended-vs-implemented and the Opportunity Solution Tree - kept offline so an offline session reads the method instead of citing its name. |
-| `feature-audit` | Audits ONE feature across every layer it is spread over - the surfaces a person uses (a control, a list or table, a detail view, a filter, a picker, a step flow, a notification), the route, the authorization, the service and the data - by filling the capability, field-contract, flow/step and interaction-dependency matrices, where a disagreement between layers is a finding and a fix needing an absent capability becomes a capability-change proposal; fires on an admin screen, CRUD, form, wizard, data table, filter or permission question about an existing feature. |
-| `design-contract` | The artifact shape of the per-repo `.tezgah/design-contract.md` - colour roles, type scale, spacing unit and rhythm, the component inventory, the state set every interactive control and data view owes - the derivation rule that reads it out of the repository's own tokens, and the rules `bin/tezgah-design check` fails on; fires on a UI or component turn that needs a floor, a token, a state set, or the design check itself. |
+| `feature-audit` | Audits ONE feature across every layer it is spread over - the surfaces a person uses (a control, a list or table, a detail view, a filter, a picker, a step flow, a notification), the route, the authorization, the service and the data - by filling the capability, field-contract, flow/step and interaction-dependency matrices, where a disagreement between layers is a finding and a fix needing an absent capability becomes a capability-change proposal; fires on an admin screen, CRUD, form, wizard, data table, filter or permission question about an existing feature, and in forward mode specifies a feature not built yet so the post-build audit diffs against it. |
+| `design-contract` | The artifact shape of the per-repo `.tezgah/design-contract.md` - colour roles, type scale, spacing unit and rhythm, the component inventory, the state set every interactive control and data view owes - the derivation rule that reads it out of the repository's own tokens, the rules `bin/tezgah-design check` fails on, and the data-view rules for dashboards (`skills/design-contract/data-views.md`); fires on a UI or component turn that needs a floor, a token, a state set, or the design check itself. |
 | `design-library` | The vendored MC Dean design/UX subset - 39 skills in the `cognitive-accessibility`, `adaptive-interfaces`, `inclusive-interaction`, `visual-critique` and `design-research` plugins - read one entry at a time through its own `INDEX.md`, never the tree; fires when a UI or product turn needs a cognitive-load, inclusive-interaction or visual-critique method tezgah has no counterpart for. |
 | `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. |
@@ -198,6 +205,17 @@ The generated specialists load skills first (`hooks/tezgah_agents.py::SPECIALIST
 | `tezgah-security` | the host's `wstg-*`, `attack-*`, `ci-assessment` and `llm-security` skills, which tezgah does not ship |
 | `tezgah-tester` | none |
 
+### The product chain
+
+A new product capability runs as one chain: research -> `product-analysis` ->
+decision -> forward spec -> `design-contract` -> build -> re-measure. Each link
+leaves a file under `.tezgah/analysis/<topic>/` that names the one before it.
+`flow.md` holds one `## <step>` note per step. The forward spec
+(`feature-audit`'s forward mode) is `spec.md`. `FLOWS`
+(`hooks/tezgah_product.py::FLOWS`) holds the steps and their done rules.
+`tezgah-research next` prints them with their status (docs/research.md, "The
+next step of a product flow").
+
 ## Vendored material
 
 `NOTICE` records every third-party skill and its terms: it opens by saying the

package/docs/status-line.md

@@ -96,7 +96,7 @@ measure the surface cannot see, then armed-and-used or armed-not-used.
 | `graph` | a code-graph tool call (an `mcp__…codegraph…` tool) | `.no-graph` — a missing binary is `idx`'s report, not this mark's |
 | `orch` | a delegate call (`Task`/`Agent`/`spawn_agent`) or a subagent start | `orchestrate-off` |
 | `judge` | a shell command really ran `tezgah-triage` or `tezgah-docs` | `judge-off`, or no credential: no `TYPESAFE_API_KEY` and no non-empty `~/.config/typesafe/key`, and neither the fallback's `OPENROUTER_API_KEY` nor its `~/.config/openrouter/key` |
-| `gate` | never `on`: shown only as `gate✗`, right after the version, in two cases. One: the prompt hook found at least 3 gated calls in this session's transcript since its first turn: write and shell calls, every one of which the gate answers with a `began` or a `deny` row (Bash/PowerShell/Edit/Write/MultiEdit/NotebookEdit on Claude, `exec_command`/`shell`/`apply_patch` on Codex). Over the same span the ledger holds no row from the gate. A PostToolUse row is no proof: that hook keeps writing while a broken PreToolUse lets every call through. The same prompt carries the line "tezgah gate inactive on this host: ...". Two: a kill switch appeared after the session's first prompt; the prompt hook writes one `disarm` row naming it (`disarmed`, baseline a `switches` row of `<cache>/tezgah.db`). The mark is a `gate_inactive` row of the same database (`gate_inactive`, audit Phase 1.3) | a row from the gate appears and no switch armed mid-session is still armed |
+| `gate` | never `on`: shown only as `gate✗`, right after the version, in two cases. One: the prompt hook found at least 3 gated calls in this session's transcript since its first turn: write and shell calls, every one of which the gate answers with a `began` or a `deny` row (Bash/PowerShell/Edit/Write/MultiEdit/NotebookEdit on Claude, `bash`/`edit`/`write` `toolCall` blocks on omp, `exec_command`/`shell`/`apply_patch` on Codex). Over the same span the ledger holds no row from the gate. A PostToolUse row is no proof: that hook keeps writing while a broken PreToolUse lets every call through. The same prompt carries the line "tezgah gate inactive on this host: ...". Two: a kill switch appeared after the session's first prompt; the prompt hook writes one `disarm` row naming it (`disarmed`, baseline a `switches` row of `<cache>/tezgah.db`). The mark is a `gate_inactive` row of the same database (`gate_inactive`, audit Phase 1.3) | a row from the gate appears and no switch armed mid-session is still armed |
 | `drift` | never `on`: shown as `drift✗` when a session start found tezgah's own hook entries changed since install (`hooks/tezgah_attest.py::run`). One mark per session and host, a `harness_drift` row of `<cache>/tezgah.db` keyed `<session hash>.<host>`; the session's `attest` row names what drifted | the next clean start of that host in that session |
 | `crash` | never `on`: shown as `crash✗` when a hook of this session could not import its core and ran without tezgah (`hooks/tezgah_guard.py::import_failed`, mark an `import_crash` row of `~/.cache/tezgah/tezgah.db` keyed `<session hash>`). When `tezgah_context` itself is the module that failed, `statusline.py` prints `tezgah ✗ core import failed` instead of the line | never by itself: the mark stays for the session |
 
@@ -160,11 +160,11 @@ the command really ran it (34-38,84) and is the one writer that can earn `judge`
 (a run of `bin/tezgah-triage` or `bin/tezgah-docs`, `shell_kind`, `hooks/tezgah_context.py::shell_kind`)
 — plus `hooks/projects-auto-init.py::main`
 (`orch` on subagent start), `hosts/codex/hook.py::main`,
-`hosts/cursor/hook.py::dispatch`, hosts/opencode/plugins/tezgah.js:2144-2151,
-hosts/opencode/plugins/tezgah.js:2702, `hosts/omp/hook.py::handle`. Both Claude (hooks/hooks.json) and dsh
+`hosts/cursor/hook.py::dispatch`, hosts/opencode/plugins/tezgah.js:2167-2174,
+hosts/opencode/plugins/tezgah.js:2725, `hosts/omp/hook.py::handle`. Both Claude (hooks/hooks.json) and dsh
 (hosts/dsh/hooks.json) wire PostToolUse to that one shared hook, which is how dsh
 gets any used mark at all: with no local transcript, the store is the only channel
-its line has (hooks/projects-posttooluse.py:33-37).
+its line has (hooks/projects-posttooluse.py:45-49).
 
 Claude's line never reads the store: it parses `tool_use` blocks out of
 `payload["transcript_path"]` plus the subagent transcripts under it, which is how
@@ -185,7 +185,7 @@ Every other surface reads the store.
   `setWidget`, and it is plain because omp strips ANSI (12-29). `status_line()`
   builds the line and carries `idx_override`, so a per-tool redraw forks no git
   (`hosts/omp/hook.py::status_line`); it redraws on session start, session switch, turn end
-  and each watched tool result (hosts/omp/tezgah-hook.ts.in:541-569,607-612,653-678).
+  and each watched tool result (hosts/omp/tezgah-hook.ts.in:596-636,674-679,720-745).
   **Motion:** while the agent runs (`agent_start` until an `agent_end` whose
   `isTerminal` is not `false`) the widget leads with a braille spinner, the tool
   in flight (`tool_execution_start`/`_end`, "thinking" between tools) and the

package/docs/testing.md

@@ -69,11 +69,11 @@ No matrix cancels its other legs when one fails (`fail-fast: false`).
   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
+- `docs`, prose only: the citations audit, the clarity 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
+  audits the docs citations and clarity 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.