@r1z4x/tezgah 1.5.1 → 1.6.0

package/docs/citations-baseline.json

@@ -21,7 +21,7 @@
     "unjudged": 2
   },
   "docs/gate.md": {
-    "unjudged": 40
+    "unjudged": 39
   },
   "docs/glossary.md": {
     "unjudged": 12

package/docs/clarity-baseline.json

@@ -42,10 +42,10 @@
     "semicolons": 11
   },
   "docs/gate.md": {
-    "long_sentences": 67,
-    "passive": 32,
+    "long_sentences": 66,
+    "passive": 31,
     "replace_words": 1,
-    "semicolons": 45
+    "semicolons": 44
   },
   "docs/glossary.md": {
     "long_sentences": 51,

package/docs/contract.md

@@ -276,7 +276,10 @@ sentence of the rule.
 
 `PROMPT_HINTS` (`hooks/tezgah_context.py::PROMPT_HINTS`) is one compiled pattern per key
 — `spec`, `consult`, `research`, `product`, `graph`, `fanout` — and `classify_prompt()` returns the keys
-a prompt matches (`hooks/tezgah_context.py::classify_prompt`). `fanout` arms on the
+a prompt matches (`hooks/tezgah_context.py::classify_prompt`). It also adds `product`
+for a data ask: a dashboard, a chart or a metric to choose. The check reads each
+clause on its own (`hooks/tezgah_context.py::_data_ask`). A code marker in that
+clause keeps the ask out: a file name, an identifier, SQL or a build word. `fanout` arms on the
 shape of the request, not a word. Two list entries on their own lines arm it.
 An entry starts with `1.`, `1)`, `1 -`, `1:`, `a)` or a bullet. An inline
 `1. ... 2. ...` arms it too. So do three files named as one list, "First, ...

package/docs/feature-audit.md

@@ -1,7 +1,8 @@
 # Feature audit: one feature, every layer
 
 Audience: the agent and the maintainer answering "why does this screen do that"
-or "make this feature better" on an existing product surface.
+or "make this feature better" on an existing product surface. It also serves
+whoever specifies a feature before the build.
 
 A screen review judges what is on the screen. Most of what goes wrong in a real
 feature is not on the screen: it is a disagreement between two layers - the surface
@@ -20,7 +21,7 @@ sourced to WAI-ARIA APG and WCAG 2.2.
 It is reached the same way `product-analysis` is: the `product` task class arms the
 rule (`hooks/tezgah_context.py::PROMPT_HINTS`), whose coherence paragraph
 (`hooks/tezgah_policy.py::CORE`) names the feature unit and the matrices, and
-`skills/product-analysis/SKILL.md:51` runs the coherence pass before its axes.
+`skills/product-analysis/SKILL.md:74` runs the coherence pass before its axes.
 `skills/tezgah-contract/SKILL.md:725-737` carries the long form for a session that
 reads the contract.
 
@@ -38,6 +39,24 @@ step flow, a notification. It is not a form-only method.
 | Interaction dependency | the controls whose change alters another's valid set | dependents, required action on change, state owner, announcement | a stale dependent value; a silent reset; a filter showing a state the view no longer has |
 | Surface pattern | the controls, data views, flows and notifications | the decidable rule, with its source | a combobox with no expanded state; a results count announced nowhere; a destructive confirmation that hides what it destroys |
 
+## Forward mode: the spec before the build
+
+For a feature that does not exist yet, fill the five matrices from the decision
+first. They go into `.tezgah/analysis/<feature>/spec.md` before the build. Mark a
+cell the decision leaves open, and ask it. Never guess it.
+
+After the build, run the normal audit and compare it with `spec.md` row by row.
+Every disagreement is a finding. Examples: a capability no layer delivers, a field
+no view renders, a missing state, an unasked layer. The method lives
+in `skills/feature-audit/SKILL.md`, "Forward mode".
+
+The decision the spec builds from is the one written under `## decision` in
+`.tezgah/analysis/<topic>/flow.md`. `spec.md` names it, and so does the audit
+after the build. The `product-flow` skill orders the steps around the audit:
+`tezgah-research next --topic <t>` reads the forward spec as done once `spec.md`
+exists (`hooks/tezgah_product.py::next_steps`). See "The next step of a product
+flow" in `docs/research.md`.
+
 ## The gate that makes it more than advice
 
 A finding whose fix names a layer that does not exist yet is not a UI finding. It
@@ -128,7 +147,7 @@ rubric, then three passes of the feature-audit skill:
 ## Source of truth
 
 - `skills/feature-audit/SKILL.md` - the method: the five matrices, the proposal
-  gate, the per-surface rule table and the hand-check list
+  gate, the forward-mode spec, the per-surface rule table and the hand-check list
 - `skills/product-analysis/SKILL.md` - the coherence pass and the artifact element
   that carries the matrices
 - `hooks/tezgah_context.py` - `PROMPT_HINTS`, whose `product` alternation carries
@@ -137,3 +156,5 @@ rubric, then three passes of the feature-audit skill:
   `skills/tezgah-contract/SKILL.md` as its long form
 - `tests/test_context.py`, `tests/test_setup.py` - the arming table and the router
   line that pin the wiring
+- `skills/product-flow/SKILL.md` and `hooks/tezgah_product.py::FLOWS` - the step
+  order around the forward spec and the audit, printed by `tezgah-research next`

package/docs/gate.md

@@ -93,7 +93,7 @@ It reads the arguments of `touch`, `rm`, `rmdir`, `unlink`, `mv`, `chmod`, `mkdi
 It reads the value of `cp -t`, `curl -o`, `wget -O`, `tar -C` on extraction and `unzip -d` (`OPTION_TARGETS`). It expands `~`, `$HOME` and the XDG
 variables first. It follows a `cd` within the line and reads past `if`/`then`/`do`/`!`/`{`. It opens `eval` and `bash -c`, and any flag cluster holding
 `c` is `-c`. A path counts as written and with its last link resolved. A quoted word is a word, so a grep or a commit message that names a switch passes. `SHELL_WRITE` stays as it was: it feeds the
-task phase rule and the opencode mirror. The task CLI stays the task rule's (below), so `task-off` still removes all of that rule. Told: what the call would
+task phase rule and the opencode mirror. The task CLI is not a control-plane target: the session runs it itself (see the task rule below). Told: what the call would
 change, and that the user changes it in their own terminal (`CONTROL_DENY` `hooks/tezgah_gate.py::CONTROL_DENY`). The text names no command. Standing. No switch
 but `pretooluse-off` removes the rule, and that switch is a protected file. The rule cannot tell a change the user asked for from one the agent chose. It
 refuses both inside the session, and it never sees the user's own terminal. Plan 050's replay of three weeks of real ledgers found the two evidence-only
@@ -159,22 +159,21 @@ Scratch is skipped: a temp file or a device (`hooks/tezgah_integrity.py::scratch
 Told: re-read the file and re-apply the change to what is on disk now (`RACE_DENY`
 `hooks/tezgah_gate.py::RACE_DENY`). Standing (`RACE_REFUSE = True` `hooks/tezgah_gate.py::RACE_REFUSE`) — a notice would not close a silent overwrite — and it lifts only by time.
 
-### Task — the user's own phase and path allowlist
+### Task — the active plan's phase and path allowlist
 
 Trigger: a write tool, or a shell command that writes a file, while an active task is set — a plan file under `.tezgah/plans/open` whose frontmatter carries a valid
 `phase` (`tezgah_task.active`). The phase refuses a write in a reading phase (`hooks/tezgah_gate.py::TASK_PHASE_DENY`) and a shell command that writes one (`hooks/tezgah_gate.py::TASK_SHELL_DENY`,
-against `hooks/tezgah_gate.py::SHELL_WRITE`); the allowlist refuses a target outside it (`hooks/tezgah_gate.py::TASK_SCOPE_DENY`) — a write tool's path, and a shell command's redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`); and the record itself is refused twice over — a write whose target IS it, by a write tool or a shell redirect/`tee`
-(`hooks/tezgah_gate.py::TASK_RECORD_DENY`) and a shell command that would change it through the CLI, named by its basename with or without `.py` (`hooks/tezgah_gate.py::TASK_UNLOCK_DENY`, matched on the masked text by `hooks/tezgah_gate.py::TASK_CHANGE`). Told:
-none of them names the command that lifts it, on purpose — with the unlock printed, an armed arm removed or disabled the gate in 25 of 25 runs and obeyed it in none
-(`hooks/tezgah_gate.py:882-886`) — so each names the phase or the allowlist as the user's to change. Standing: only the record changing lifts it.
+against `hooks/tezgah_gate.py::SHELL_WRITE`); the allowlist refuses a target outside it (`hooks/tezgah_gate.py::TASK_SCOPE_DENY`) — a write tool's path, and a shell command's redirect or `tee` target (`hooks/tezgah_gate.py::write_paths`); and a write whose target IS the record, by a write tool or a shell redirect/`tee`, is refused
+(`hooks/tezgah_gate.py::TASK_RECORD_DENY`), because only `bin/tezgah-task` writes it and that CLI makes the checks a retyped frontmatter would skip. Told:
+the move that lifts it, made by the session itself — `tezgah-task phase implementation` or `tezgah-task allow <glob> ... --why "<reason>"` — since the orchestrator owns the plan lifecycle and the CLI refuses
+the move until the plan's Acceptance, spike and checkpoint are in order, and records the reason for a widened scope (`allowed_why:`). Standing: only the record changing lifts it.
 Scratch meets no allowlist: a temp file or a device, such as `pytest > /tmp/check.log` (`hooks/tezgah_gate.py::task_reason`). Build output inside the repo stays held. Off: `task-off`
-(`hooks/tezgah_gate.py::decision`). It fails open wherever the question cannot be answered: no active task, no readable record; the record is written by `bin/tezgah-task` and
-never by the agent, so this rule refuses on a decision the user made rather than one the gate inferred.
+(`hooks/tezgah_gate.py::decision`). It fails open wherever the question cannot be answered: no active task, no readable record.
 
-The fifth refusal under the same rule is the checkpoint. Trigger: a write, or a shell command that writes a file (`hooks/tezgah_gate.py::SHELL_WRITE`), while the task is in
+The fourth refusal under the same rule is the checkpoint. Trigger: a write, or a shell command that writes a file (`hooks/tezgah_gate.py::SHELL_WRITE`), while the task is in
 `phase: implementation`, its record reads `checkpoint: pending <sha>`, that sha is still the checkout's HEAD and the tree is dirty (`checkpoint_reason()`
 `hooks/tezgah_gate.py::checkpoint_reason`, `hooks/tezgah_gate.py::CHECKPOINT_DENY`). Told: the task it read, that the record holds a `pending` checkpoint, and the one command
-that makes the boundary real - unlike the refusals above it names that command, because running it *satisfies* the rule rather than taking it off. Standing: the recorded sha is the switch, not the tree - the commit
+that makes the boundary real - it names that command because running it *satisfies* the rule rather than taking it off. Standing: the recorded sha is the switch, not the tree - the commit
 the refusal names moves HEAD off that sha, so the refusal clears itself, where keying on the word `pending` alone left the phase waiting on a record only
 `bin/tezgah-task` rewrites. Off, with the rest of the rule: `task-off`. It fails open wherever the question cannot be answered: no record, no `checkpoint:` key, a
 checkpoint that is a plain sha (the boundary is already real), a `pending` with no sha, a sha this checkout's HEAD does not name, and a repo whose HEAD cannot be read.
@@ -236,7 +235,7 @@ tail still shows that failure, under `verify-off` (`hooks/tezgah_gate.py::decisi
 ### Loop — the identical attempt that already failed twice
 
 Trigger: the same call (same `call_id`) failed `LOOP_ATTEMPTS = 2` times already in the current user turn (`hooks/tezgah_gate.py::LOOP_ATTEMPTS`, `hooks/tezgah_gate.py::loop_reason`). Told: attempt N
-of an identical call, the failure class read from the ledger (`transient`, `user`, `permanent`, `unknown`; the cap is the same for every class, and a `user` failure - a 401/403, a missing credential, a login - says to ask the user), "change the approach or stop" (`hooks/tezgah_gate.py::loop_reason`). Standing while the ledger tail still shows those
+of an identical call, the failure class read from the ledger (`transient`, `user`, `permanent`, `unknown`; the cap is the same for every class, and a `user` failure - a 401/403, a missing credential, a login - says to take a route that needs no credential first and ask the user once only when none is left), "change the approach or stop" (`hooks/tezgah_gate.py::loop_reason`). Standing while the ledger tail still shows those
 failures. Under `verify-off` (`hooks/tezgah_gate.py::decision`).
 
 ### Retry — the session-wide ceiling

package/docs/index.json

@@ -267,7 +267,8 @@
         "what do init, claim, migrate and source write",
         "how does a session learn that a research line is broken",
         "what lights the research mark and how is the layer switched off",
-        "why may a new research line not be opened while another is unfinished"
+        "why may a new research line not be opened while another is unfinished",
+        "what does tezgah-research next print for a product flow, and when is a decision due for re-measure"
       ],
       "answers_tr": [
         "bir araştırma hattı nerede yaşar ve ne tutar",
@@ -275,11 +276,13 @@
         "init, claim, migrate ve source ne yazar",
         "bir oturum bir araştırma hattının bozuk olduğunu nasıl öğrenir",
         "araştırma işaretini ne yakar ve katman nasıl kapatılır",
-        "başka biri bitmemişken neden yeni bir araştırma hattı açılamaz"
+        "başka biri bitmemişken neden yeni bir araştırma hattı açılamaz",
+        "tezgah-research next bir ürün akışı için ne yazdırır ve bir karar ne zaman yeniden ölçülmeli"
       ],
       "sources": [
         "hooks/tezgah_research.py",
         "bin/tezgah-research",
+        "hooks/tezgah_product.py",
         "hooks/tezgah_policy.py",
         "hooks/tezgah_context.py",
         "skills/research/SKILL.md",
@@ -294,12 +297,18 @@
       "answers": [
         "what is a skill here and how does it reach a host",
         "which skills ship and what does each do",
-        "how do I add a skill without breaking the router or the install report"
+        "how do I add a skill without breaking the router or the install report",
+        "which skill designs a metric dashboard and where do its data-view rules live",
+        "does the local skill search reach design-library's nested entries",
+        "which skill carries a new metric dashboard or feature from research to re-measure"
       ],
       "answers_tr": [
         "burada beceri nedir ve bir hosta nasıl ulaşır",
         "hangi beceriler gelir ve her biri ne yapar",
-        "yönlendiriciyi veya kurulum raporunu bozmadan nasıl beceri eklerim"
+        "yönlendiriciyi veya kurulum raporunu bozmadan nasıl beceri eklerim",
+        "metrik dashboard tasarımını hangi beceri yapar ve veri görünümü kuralları nerede",
+        "yerel beceri araması design-library'nin iç girdilerine ulaşır mı",
+        "yeni bir metrik dashboard'u veya özelliği araştırmadan yeniden ölçüme hangi beceri taşır"
       ],
       "sources": [
         "bin/tezgah-setup",
@@ -309,7 +318,10 @@
         "commands/",
         "NOTICE",
         "tests/test_setup.py",
-        "tests/test_skills.py"
+        "tests/test_skills.py",
+        "hooks/tezgah_skill_pick.py",
+        "skills/design-contract/data-views.md",
+        "skills/product-flow/SKILL.md"
       ]
     },
     {
@@ -320,12 +332,14 @@
       "answers": [
         "what does a feature-level audit cover that a screen review misses",
         "what are the five matrices and the capability-change proposal",
-        "how is the feature-audit skill reached and what evidence backs it"
+        "how is the feature-audit skill reached and what evidence backs it",
+        "how do I specify a feature before it is built and audit it against that spec"
       ],
       "answers_tr": [
         "özellik düzeyinde bir denetim, ekran incelemesinin kaçırdığı neyi kapsar",
         "beş matris ve yetenek değişikliği önerisi nedir",
-        "özellik denetimi becerisine nasıl ulaşılır ve onu hangi kanıt destekler"
+        "özellik denetimi becerisine nasıl ulaşılır ve onu hangi kanıt destekler",
+        "bir özelliği yapılmadan önce nasıl tanımlarım ve yapıldıktan sonra o tanıma göre nasıl denetlerim"
       ],
       "sources": [
         "skills/feature-audit/SKILL.md",

package/docs/research.md

@@ -238,14 +238,59 @@ 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` |
 
 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
@@ -832,6 +877,7 @@ armed. It removes the rule, not just the mark - the diff is in `core_split`,
   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_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

@@ -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/hooks/tezgah_agents.py

@@ -222,8 +222,9 @@ def _reviewer_body(host):
         "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"
+        "fix-later, and after round two what is left is fixed by the session\n"
+        "and closed with `--resolved`, or recorded fix-later, never a third\n"
+        "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"

package/hooks/tezgah_components.py

@@ -103,7 +103,8 @@ COMPONENTS = [
      "switch": "research-off", "editable": False, "revert": "git"},
     {"key": "product", "label": "product",
      "files": ["hooks/tezgah_policy.py", "skills/product-analysis/SKILL.md",
-               "skills/feature-audit/SKILL.md"],
+               "skills/feature-audit/SKILL.md", "skills/product-flow/SKILL.md",
+               "hooks/tezgah_product.py"],
      "switch": "research-off", "editable": True, "revert": "git"},
     {"key": "attribution", "label": "attribution",
      "files": ["hooks/tezgah_policy.py", "hooks/tezgah_gate.py"],

package/hooks/tezgah_context.py

@@ -787,16 +787,16 @@ def task_line(task):
     and refuses a write the phase or the allowlist excludes, but a refusal
     costs a turn - so the phase rides every user turn, and the refusal is never
     the first the session hears of it. One line because it is paid every turn;
-    the allowlist is the globs as written, and the phase is stated as the user's
-    to move rather than as a command to run: the line used to print the CLI the
-    user types, and E7b watched the session run that command five times in a row
-    against a gate that refuses it every time. A line that names an act the gate
-    refuses is an invitation to a loop."""
+    the allowlist is the globs as written, and the phase is stated as the
+    orchestrator's own move: the session runs `tezgah-task` itself when the
+    work reaches the next phase and closes the plan when it is done, never
+    handing those steps to the user."""
     paths = ", ".join(task.get("allowed_paths") or []) or "any path in the repo"
-    return ("Active task %s is in phase `%s`; writes allowed on: %s. The phase "
-            "belongs to the user - ask them for the one this work needs, and "
-            "do not move it yourself." % (task.get("id"), task.get("phase"),
-                                          paths))
+    return ("Active task %s is in phase `%s`; writes allowed on: %s. Move the "
+            "phase yourself with `tezgah-task phase <next>` when the work reaches "
+            "it, and `tezgah-task close %s done` when it is merged - never hand "
+            "these steps to the user." % (task.get("id"), task.get("phase"),
+                                          paths, task.get("id")))
 
 
 # --- the resume block: the live turn state a compact loses -------------------
@@ -1186,10 +1186,61 @@ def constraint_notice(cwd, session_id):
     return " ".join(render(subagent_core(core_for(cwd)[0])).split())
 
 
+# A data ask said by its output: a dashboard, a chart, a KPI, a metric to choose.
+# "Bu veriye uygun bir metric dashboard tasarla" armed nothing before plan 072.
+# These words are code words as often as product words (`dashboard.json`, a
+# metrics endpoint, a progress `gösterge`, the clipboard `pano`), and two rounds
+# of noun denylists inside the product regex kept missing the next code sense.
+# So the ask is judged per clause: it arms `product` only when no code marker -
+# a file name, an identifier, SQL, a build, test or runtime word - shares its
+# clause (decision 006: qualify the stem, never drop it).
+DATA_ASK = re.compile(
+    r"\b(?:(?:design|create|make|build|sketch|propose|need|want)\w* (?:\w+ ){0,4}"
+    r"(?:dashboard|charts?|visuali[sz]ation)|"
+    r"(?:metri[ck]s?|kpis?|data|sales|revenue|veri\w*|satış\w*|gelir\w*) "
+    r"(?:\w+ ){0,2}(?:dashboard|pano)|"
+    r"(?:dashboard|gösterge panel)\w* (?:\w+ ){0,4}(?:tasarla|oluştur|hazırla|"
+    r"yap|göster)\w*|"
+    r"(?:what|which) (?:\w+ ){0,3}(?:metri[ck]s|kpis|charts?) (?:\w+ ){0,3}"
+    r"(?:should|to|do|matter|would)|"
+    r"what should (?:\w+ ){0,3}dashboard show|"
+    r"(?:choose|pick|define|track|design)(?:s|ing)? (?:\w+ ){0,3}(?:metri[ck]s|kpis)|"
+    r"(?:metri[ck]s|kpis) (?:should|to|do|would) (?:\w+ ){0,2}"
+    r"(?:track|measure|use|watch)|success metrics?|"
+    r"(?:suggest|recommend)\w* (?:\w+ ){0,3}charts?|öner\w* (?:\w+ ){0,3}grafi\w*|"
+    r"hangi (?:metri[ck]\w*|kpi\w*|grafi\w*|göstergeleri?)|"
+    r"(?:metri[ck]\w*|kpi\w*) (?:\w+ ){0,3}(?:tasarla|seç|tanımla|belirle|takip|izle)\w*|"
+    r"gösterge panel\w*|visuali[sz]\w* (?:\w+ ){0,3}(?:data|numbers|veri\w*)|"
+    r"data visuali[sz]ation|veri\w* (?:\w+ ){0,3}görselleştir\w*)")
+CODE_SENSE = re.compile(
+    r"\w\.(?:py|tsx?|jsx?|json|go|rs|ya?ml|sql|java|rb|css|html)\b|\b\w+_\w+\b|"
+    r"/metrics\b|\bselect\b.{0,200}?\bfrom\b|\b(?:tables?|columns?|schema|sql|queries|"
+    r"query|bundle|webpack|vite|tests?|ci|counters?|registry|pipeline|backend|"
+    r"handlers?|structs?|endpoints?|exporters?|export\w*|servers?|librar\w*|"
+    r"packages?|modules?|database|index\w*|indeks\w*|"
+    r"middleware|debugger|data (?:structure|flow)s?|clipboard|spinner|threads?|"
+    r"commit|git|functions?|class|component|prop|hooks?|prometheus|grafana|"
+    r"kibana|statsd|opentelemetry|config\w*|provision\w*|api|routes?|snake_case|"
+    r"veri yapı\w*|fonksiyon\w*|bileşen\w*|modül\w*|dosya\w*|kopyala\w*|"
+    r"seçici\w*|yükleme|ilerleme|paket\w*)\b")
+
+
+def _data_ask(low):
+    """Does one clause of the prompt ask for a data view or a metric choice with
+    no code marker beside it? A clause ends at `!`, `?`, `;`, a newline or a full
+    stop followed by a space, so `dashboard.json` stays one clause."""
+    return any(DATA_ASK.search(clause) and not CODE_SENSE.search(clause)
+               for clause in re.split(r"[!?;\n]|\.\s", low))
+
+
 def classify_prompt(text):
-    """The conditional rule keys a prompt arms, from the shared hint table."""
+    """The conditional rule keys a prompt arms, from the shared hint table, plus
+    `product` for a data ask (DATA_ASK, gated per clause by CODE_SENSE)."""
     low = (text or "").lower()
-    return {key for key, pattern in PROMPT_HINTS if re.search(pattern, low)}
+    keys = {key for key, pattern in PROMPT_HINTS if re.search(pattern, low)}
+    if "product" not in keys and _data_ask(low):
+        keys.add("product")
+    return keys
 
 
 def prompt_text(payload):
@@ -1435,8 +1486,8 @@ DEFAULT_BUDGET = 13000
 # exists to prevent, not one it may cause.
 DROP_ORDER = ("knowledge", "worktrees", "lessons", "skill", "lessons_turn",
               "taste", "plans", "subagents", "steer", "orca", "consult", "research",
-              "research_broken", "graph", "offnote", "orchestrate", "index",
-              "resume", "scratch", "task", "delta", "pointer")
+              "research_broken", "graph", "offnote", "orchestrate",
+              "index", "resume", "scratch", "task", "delta", "pointer")
 
 
 def _first_item(text):
@@ -1577,7 +1628,7 @@ GATE_INACTIVE = (
     "tezgah gate inactive on this host: %d gated tool call(s) since this "
     "session's first turn and not one row from the gate, so the shortcut "
     "denials and the Stop check are not running. Say so before claiming a check "
-    "passed, and ask the user to run `tezgah-setup --report`.")
+    "passed, run `tezgah-setup --report` yourself and quote its MISS rows.")
 
 
 def _iso_epoch(value):