@r1z4x/tezgah 1.5.1 → 1.6.0

package/hosts/opencode/plugins/tezgah.js

@@ -21,10 +21,7 @@
 //     this host asks for its answer rather than keeping a JS copy of it (the
 //     rule-by-rule port below is documented as incomplete and divergent, which
 //     is exactly why a new rule never enters through it). The same ask covers
-//     the record's shell route - a bash command that would move the phase or
-//     the allowlist - through the same CLI and the same rule, asked only on a
-//     command that names the task CLI (see TASK_CLI for the bound), and the
-//     language rule's own shell route: a command that would create a branch, a
+//     the language rule's own shell route: a command that would create a branch, a
 //     commit subject or a PR/issue title is put to the same CLI under the same
 //     kind of bound (see IDENT_CMD), so the word list stays in hooks/tezgah_lang
 //     and a non-English identifier is refused here with the core's own answer.
@@ -249,9 +246,10 @@ const CLASS_NOTE = {
   transient: "it names a failure the host's own client may retry - a " +
     "timeout, a connection error, a rate limit, a 5xx - and an identical " +
     "repeat by the agent adds nothing to that",
-  user: "it names something only the user can fix - a credential, a login, " +
-    "an access grant - so stop and ask the user for it rather than change " +
-    "the approach",
+  user: "it names something only the user can supply - a credential, a " +
+    "login, an access grant - so take a route that needs none first " +
+    "(another provider or member, a local run, a public source) and ask the " +
+    "user once, naming what it unlocks, only when none is left",
   permanent: "an assertion or a bad argument does not change by re-running it",
 }
 const NO_CLASS_NOTE = "the host reported no error text for it, so the class " +
@@ -548,25 +546,12 @@ const WRITE_TOOLS = new Set(["edit", "write", "multiedit", "notebookedit",
 // hosts send.
 const BASH_TOOLS = new Set(["bash", "shell", "command", "exec_command",
   "run_command", "powershell", "pwsh"])
-// The core's task rule has a shell half no write tool takes: a command that
-// moves the active task's own record (`hooks/tezgah_gate.TASK_CHANGE`), which is
-// how an agent moves the phase or the allowlist it is being held to instead of
-// retyping the record file. The rule, and the masking that lets a command merely
-// naming the CLI through, are the core's, so its answer is asked for and used
-// verbatim; what stays here is only the pre-test that decides whether asking is
-// worth a spawn. A spawn per bash call would tax every command in the session
-// for a rule about one, so the core is asked when the raw command names the CLI
-// and carries an argument - loose on purpose in that direction, because a
-// commit message or a comment that mentions the CLI costs one spawn whose answer
-// comes back empty, while a pre-test tight enough to miss nothing would be the
-// second implementation this host exists not to keep.
-const TASK_CLI = /\btezgah-task\b\s+\S/
 // The control rule's shell half (`hooks/tezgah_gate.control_reason`): a line
 // that could change tezgah's own control plane - a program that writes, removes
 // or moves a path, or a redirect, before a name that plane holds; or one of its
 // CLIs with an argument. The rule, its path table and its `~`/`$HOME`/XDG
 // expansion are the core's; this is only the bound on asking, loose the same
-// way TASK_CLI is: a false hit costs one spawn whose answer comes back empty.
+// way IDENT_CMD is: a false hit costs one spawn whose answer comes back empty.
 const CONTROL_CMD = /(?:\b(?:touch|rm|rmdir|unlink|shred|truncate|chmod|chown|chgrp|mv|mkdir|tee|cp|ln|install|rsync|dd|sed|perl|git|sh|bash|zsh)\b|>)[\s\S]*(?:tezgah|\.no-|\.husky|\.git\/hooks|\.claude|\.codex|\.cursor|opencode|\.omp|\.local\/share)|\btezgah-(?:gate(?:\.py)?\s+decide|(?:capture|pony|adhd)(?:\.py)?\s+\S|context(?:\.py)?\s+(?:attest|user_prompt)\b|(?:codex|cursor)-hook\b)|\bprojects-(?:auto-init|pretooluse|posttooluse|stop)\b|\bhook\.py\b/
 // The same bound for the language rule: the command shapes that dream up an
 // identifier which outlives the session - `git commit` (its message), `git
@@ -2709,26 +2694,21 @@ export const Tezgah = async ({ directory }) => {
           await noteDeny(sessionID, deny === ATTRIB_DENY ? "attribution"
             : deny === EXPLORE_DENY ? "explorer" : "shortcut", deny, tool, args, base)
         }
-        // Two rules with a shell route, asked of the core in one spawn (TASK_CLI
-        // and IDENT_CMD carry which commands are worth asking about, and why
-        // their pre-tests are loose): a command that names the task CLI may be
-        // moving the phase or the allowlist this session is held to, and a
-        // command that creates an identifier may be putting a branch, a commit
-        // subject or a PR/issue title into the repository's history for good.
-        // Both refusals are the core's own text - the same ones a write to the
-        // record and a non-English artifact get - and this file keeps neither
-        // rule. The core masks the command, so one that only mentions the CLI
-        // comes back empty and falls through to the rules below. Asked ahead of
-        // shell rules for the same reason the Python gate orders them there
-        // (hooks/tezgah_gate.decision: shortcut, attribution, lang, task, secret,
-        // repeat): a call another rule would refuse is counted as that rule and
-        // never as a repeat.
+        // Shell routes asked of the core in one spawn (IDENT_CMD
+        // carries which commands are worth asking about, and why its pre-test is
+        // loose): a command that creates an identifier may be putting a branch,
+        // a commit subject or a PR/issue title into the repository's history for
+        // good. The refusal is the core's own text and this file keeps no copy
+        // of the rule. Asked ahead of shell rules for the same reason the Python
+        // gate orders them there (hooks/tezgah_gate.decision: shortcut,
+        // attribution, lang, task, secret, repeat): a call another rule would
+        // refuse is counted as that rule and never as a repeat.
         const cmd = BASH_TOOLS.has(tool)
           ? String(args.command || args.cmd || "") : ""
-        // A piped check (hooks/tezgah_integrity.piped_check) is the third: the
+        // A piped check (hooks/tezgah_integrity.piped_check) is the second: the
         // core decides whether the pipe hides the check's status, and it rides
         // `verify-off` like the other integrity denials.
-        if (!deny && !asked && cmd && (TASK_CLI.test(cmd) || IDENT_CMD.test(cmd) ||
+        if (!deny && !asked && cmd && (IDENT_CMD.test(cmd) ||
             (shortcuts && cmd.includes("|") && verifyCommand(cmd)))) {
           asked = true
           deny = await gateReason(tool, args, dir, sessionID, core)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
   "license": "MIT",
   "repository": {

package/skills/analyze-app/SKILL.md

@@ -136,6 +136,63 @@ Screenshots, traces and tree dumps go to the app artifact directory
 (`PLAYWRIGHT_MCP_OUTPUT_DIR`, default `~/.cache/tezgah/apps`). Return the file
 path; keep image tokens out of the context.
 
+## Measurement for design-contract
+
+`tezgah-design check` judges a measurement, and this loop is what writes it:
+`.tezgah/design/measurement.json`, one entry per component the repository's
+`.tezgah/design-contract.md` lists. Read the computed styles with `browser_evaluate`,
+one selector per component:
+
+```js
+() => {
+  const PROPS = ["font-size", "padding", "gap", "color", "background-color",
+                 "width", "height"];
+  const LIST = [["Button", "interactive", "button.primary"],
+                ["RevenueTile", "data", "[data-widget=revenue]"]];
+  return {components: LIST.map(([name, kind, selector]) => {
+    const style = getComputedStyle(document.querySelector(selector));
+    return {name, kind, states: [],
+            styles: Object.fromEntries(PROPS.map(p => [p, style.getPropertyValue(p)]))};
+  })};
+}
+```
+
+For a focusable component, read `outline-style`, `outline-width` and `box-shadow`
+only after focusing it from the keyboard (`browser_press_key` Tab until it has
+focus, so `:focus-visible` applies): at rest they are `none`, and the
+`focus-visible` rule reads a resting `none` as a missing focus ring. For an animated
+component add `transition-duration`, which the `reduced-motion` rule reads.
+`states` is filled from what was observed, never from source: a computed
+style shows only the state the page is in, so each state name goes in after the
+component was driven or routed into it and read again. The file is this shape - an
+object with a `components` list, or the bare list:
+
+```json
+{"components": [
+  {"name": "Button", "kind": "interactive",
+   "states": ["default", "hover", "focus", "active", "disabled", "loading",
+              "error"],
+   "styles": {"font-size": "16px", "padding": "8px 12px", "gap": "8px",
+              "color": "rgb(17, 17, 17)", "background-color": "rgb(255, 255, 255)",
+              "width": "120px", "height": "40px"}},
+  {"name": "RevenueTile", "kind": "data",
+   "states": ["empty", "loading", "skeleton", "error", "offline", "partial",
+              "long-text", "permission-denied"],
+   "styles": {"font-size": "14px", "padding": "16px",
+              "color": "rgb(17, 17, 17)", "background-color": "rgb(255, 255, 255)"}}]}
+```
+
+`kind` is `interactive` or `data`, and it decides which half of the contract's state
+set the component owes; a component without one is unjudged.
+
+## The re-measure of a product flow
+
+Under `product-flow`, what the running app showed after a decision's observe-after
+date is the topic's re-measure: write it under `## re-measure` in
+`.tezgah/analysis/<topic>/flow.md` with the decision it measures, the value, the
+verdict (met, missed or unobservable), the evidence class `ui-observed` and the
+screenshot or tree dump path. The `product-flow` skill gives the order of the steps.
+
 ## Looking at the screen
 
 The tree answers structure; the image answers hierarchy, rhythm, colour and feel.

package/skills/design-contract/EVALS.md

@@ -1,6 +1,6 @@
 # Evals
 
-Three inputs a session can be handed where this skill could misfire, and what a
+Four inputs a session can be handed where this skill could misfire, and what a
 good answer has to contain. Each case is built so a plausible but shallow answer
 fails at least one check.
 
@@ -74,6 +74,29 @@ finding", and `states.data` is a field "The contract must carry ... exactly".
 
 ---
 
+## Case 4 - The trap: a dashboard with only its happy state
+
+**Input**
+> Bu veriye uygun bir metric dashboard tasarla. (attached: `signups.csv` -
+> date, plan, country, signups, activations)
+
+**Must contain**
+- [ ] Names the dashboard type, operational or analytical, before the layout
+- [ ] Picks each chart by the question it answers (comparison, trend, part-to-whole, distribution, relationship), with length or position for quantity and colour only as a redundant cue
+- [ ] Shows every number with its comparison (target, previous period or benchmark), its window and its unit, and 3-5 key metrics by default
+- [ ] Lists per widget the states `check` requires of a data view (empty, loading, skeleton, error, offline, partial, long-text, permission-denied) plus configuration-needed and stale with an "as of" time
+- [ ] Takes the metrics from `product-analysis`'s metric record (goal, definition, window, baseline, logged) instead of inventing them
+
+**Must not**
+- Encode a magnitude in colour, or use a pie or gauge for a comparison
+- Design only the loaded state
+
+**Why this case** - `data-views.md` says "Colour never encodes a magnitude", that
+"A bare number cannot be judged", and that every widget "owes each of these
+states". A data file pulls toward drawing its columns in their happy state.
+
+---
+
 ## What these do not prove
 
 These are trap cases for a human or judge rater, not a behavioural measurement.

package/skills/design-contract/SKILL.md

@@ -70,6 +70,9 @@ opens. Field names and prose stay English.
   owns. A component the measurement shows that is not listed is a
   `component-inventory` violation, so a new component is added here, in the same
   turn it is written.
+- `components[].decision` - optional, the product decision that asked for the
+  component: the topic and the decision as written under `## decision` in
+  `.tezgah/analysis/<topic>/flow.md`.
 
 ```json
 {
@@ -101,6 +104,18 @@ wrong - and a component whose measurement does not show a state it owes gets a
 `state-coverage` violation naming the states it is missing. `kind` decides which
 half applies, so a component measured without one is unjudged, never passed.
 
+A dashboard, chart or metric tile also follows [data-views.md](data-views.md): the
+dashboard type, chart choice by question, context and window per number, and the
+widget states.
+
+## The product decision behind a component
+
+A component built for a product decision names it in its `decision` field, such
+as `{"name": "RevenueTile", "kind": "data", "decision": "signup-dashboard: ship
+the revenue tile"}`, the decision written under `## decision` in
+`.tezgah/analysis/<topic>/flow.md`. A component with no decision behind it leaves
+the field out. The `product-flow` skill gives the order of the steps.
+
 ## Derivation
 
 Read the repository's own token source. In this order, and nothing else:
@@ -144,7 +159,8 @@ repository owns, so list them in the turn that writes a new one.
 ```
 
 `--measured` takes the JSON the running-app read produces - the per-component
-computed styles and observed states - or a dash for stdin:
+computed styles and observed states - or a dash for stdin; `analyze-app`'s
+"Measurement for design-contract" section writes it with `browser_evaluate`:
 
 ```json
 {"components": [

package/skills/design-contract/data-views.md

@@ -0,0 +1,86 @@
+# Data views
+
+The rules a dashboard, a chart or a metric tile is held to, on top of the state set
+in `SKILL.md`. The metrics themselves - which ones, their definition, window,
+baseline and whether they are logged - come from `product-analysis`'s Metrics
+section; this file decides how they are shown. Each rule names its source, and a
+rule with no primary source found says so.
+
+## The dashboard type comes first
+
+Decide whether the screen is **operational** - critical information read quickly
+during a time-sensitive task - or **analytical** - at-a-glance information for
+analysis and decision making (NN/g). Carbon draws the same line as presentation
+against exploration dashboards. The type sets the density, the refresh rate and
+how much interaction the screen owes; a dashboard that has not named its type has
+not named its user.
+
+## Chart choice follows the question
+
+Name the question each view answers, then pick the encoding:
+
+| The question | Encoding | Source |
+|---|---|---|
+| comparison - which is bigger? | bars on a common baseline | NN/g (length on a common scale) |
+| trend - how did it move over time? | a line over a time axis | NN/g (position) |
+| part-to-whole - what share is each? | a stacked bar, or a bar of shares | tezgah's own: no primary source read |
+| distribution - how is it spread? | a histogram or a box plot | tezgah's own: no primary source read |
+| relationship - does one move with another? | a scatter plot | NN/g (position on two axes) |
+
+Length and position carry quantity, because people compare them accurately; area
+and angle (pie, gauge, radar) do not (NN/g, after Cleveland and McGill). Colour
+never encodes a magnitude: it is a redundant grouping cue beside a label, a shape
+or a position, and every chart passes the greyscale test - it still reads with the
+colour removed (NN/g; the design library's `colour-independence` entry).
+
+## Every number has context and a window
+
+A bare number cannot be judged: "Compared to what? Is this good or bad?" (Few,
+*Common Pitfalls in Dashboard Design*). Every figure shown carries its comparison
+- a target, the previous period or a benchmark - and the window it covers, and is
+formatted with its unit and no more precision than the decision needs (Few's
+"excessive detail or precision" pitfall). The record behind each comes from the
+metric's `baseline` and `window` fields.
+
+## Three to five metrics by default
+
+The default view shows 3-5 key metrics and the primary actions; the rest sit
+behind a fuller view the user opens (the design library's `simplified-views`
+entry). Carbon's "Limit the number of metrics" and Few's "exceeding the
+boundaries of a single screen" say the same. The most important metric gets the
+largest area and the highest contrast (Carbon).
+
+## The widget state set
+
+Every widget - tile, chart, table - owes each of these states, and a state that
+does not exist is a finding:
+
+| State | What it shows | Source |
+|---|---|---|
+| loading | that data is on the way, in the widget's own frame | Carbon's loading pattern, seen but not read at source |
+| no-data | that the query returned nothing, and what would fill it | Carbon empty states |
+| error | that the system failed, per widget, with a text-only message when many fail | Carbon empty states ("Systems issue") |
+| permission-denied | that data exists but this user may not see it | Carbon empty states ("Permissions issue") |
+| configuration-needed | that the widget cannot run until something is set up | Carbon empty states ("Configuration required") |
+| stale | the last good data, with its "as of" time | tezgah's own rule: no primary source found |
+| partial | which part of the data is missing, beside what arrived | tezgah's own rule: no primary source found |
+
+Against the contract: loading, error, partial and permission-denied are already in
+`states.data`, and no-data is its `empty`; configuration-needed and stale are
+reported as observed state names beside the shipped set, and their absence is a
+finding the reviewer names, since `check` does not require them.
+
+## Sources
+
+- Stephen Few, *Common Pitfalls in Dashboard Design* (2006),
+  http://www.perceptualedge.com/articles/Whitepapers/Common_Pitfalls.pdf
+- NN/g, *Dashboards: Making Charts and Graphs Easier to Understand* (2017),
+  https://www.nngroup.com/articles/dashboards-preattentive/
+- Carbon Design System, Dashboards,
+  https://www.carbondesignsystem.com/data-visualization/dashboards
+- Carbon Design System, Empty states,
+  https://www.carbondesignsystem.com/building-blocks/core/patterns/empty-states
+- The design library: [colour-independence](../design-library/adaptive-interfaces/skills/colour-independence/SKILL.md)
+  ("Always test charts in greyscale") and
+  [simplified-views](../design-library/adaptive-interfaces/skills/simplified-views/SKILL.md)
+  (its Dashboard Simplification patterns: a default of three to five key metrics).

package/skills/feature-audit/SKILL.md

@@ -10,7 +10,8 @@ description: >
   panel, a CRUD screen, a form, a wizard or step flow, a search or picker control,
   a data table, a bulk action, a permission surface, or a "why does this not work
   / what is missing here / make this better" ask, and whenever a UI improvement
-  needs a capability the system does not have. The unit of analysis is the
+  needs a capability the system does not have, or a feature not built yet needs
+  the same matrices as a spec before the build. The unit of analysis is the
   feature, not the screen: a screen-level review cannot see a capability no
   surface reaches, a contract field no view renders, or a step whose precondition
   nothing enforces. Not for the whole product - use `product-analysis`.
@@ -32,7 +33,9 @@ assume: run it on the one feature in scope and feed its findings into their axes
 Pick **one feature**: one entity (a person, an order, a record) plus every action
 a user can take on it, plus every screen and endpoint that carries those actions.
 Write the boundary down: the entity, the actions, the screens, the endpoints, the
-files. A feature that cannot be bounded this way is two features.
+files. A feature that cannot be bounded this way is two features. A feature that
+does not exist yet is bounded the same way from the decision that asks for it, and
+runs in forward mode (below).
 
 The surfaces in scope are **every interface element and every data view** - a form
 control, a list or table, a detail view, a filter or facet, a picker, a step
@@ -234,6 +237,31 @@ it; a proposal with no rejectable artifact; a schema-touching step with no migra
 phases; a flag with no lifetime or owner; a contract change with no ADR and no
 pre/post check pair.
 
+## Forward mode
+
+For a feature not built yet, the same five matrices are the spec. Before the build,
+fill matrices 1-5 from the decision that asks for the feature - capability x layer,
+field contract, flow and step, interaction dependency, and the surface patterns
+with every state each control and data view owes - into
+`.tezgah/analysis/<feature>/spec.md`. Each row cites the decision line it comes
+from; a cell the decision does not settle is marked `[OPEN: question]`, so the gap
+is asked before it is built, not discovered after.
+
+After the build, run the normal audit on the built feature and diff it against
+`spec.md` row by row. Every disagreement is a finding: a capability the spec names
+and no layer delivers, a field the spec defines and no view renders, a state the
+spec owes and the running app does not show, and a layer the build added that the
+spec never asked for. An agreement is a row too.
+
+## Citing the product decision
+
+A feature built from a product decision cites that decision. In forward mode,
+`spec.md` names the decision it implements, as written under `## decision` in
+`.tezgah/analysis/<topic>/flow.md`, and the post-build audit names the same
+decision beside each disagreement it finds. Under `product-flow` the spec's folder
+is the product topic, `.tezgah/analysis/<topic>/spec.md`, because that is the path
+`next` reads. The `product-flow` skill gives the order of the steps.
+
 ## Every finding carries a Prevent line
 
 A finding that only describes the defect will be met again next quarter. For each
@@ -321,6 +349,7 @@ NN/g data tables and infinite scrolling. axe-core rule tags and the 57% figure:
 `https://github.com/dequelabs/axe-core`.
 
 Where the depth lives: `product-analysis` (the five axes this feeds), `analyze-app`
-(how a running surface is read), `research` (where the artifact lives),
+(how a running surface is read), `research` (how a claim and the source an audit
+cites are recorded),
 `intended-vs-implemented` (documentation against code - this skill compares layer
 against layer).

package/skills/plan-add/EVALS.md

@@ -52,7 +52,7 @@ repository, never the project's".
 
 ---
 
-## Case 3 - The trap: starting the task on the user's behalf
+## Case 3 - The trap: handing the lifecycle back to the user
 
 **Input**
 > Make a plan for splitting `hooks/tezgah_gate.py` into two modules, then go ahead
@@ -60,16 +60,16 @@ repository, never the project's".
 
 **Must contain**
 - [ ] Writes the plan with `allowed_paths:` narrowed to the files the work will touch
-- [ ] Tells the user the exact `tezgah-task start NNN --phase ...` command, scope included, as theirs to run
-- [ ] Explains that `implementation` is refused while the tree is dirty or the plan carries no allowlist
+- [ ] Runs `tezgah-task start NNN --phase discovery` itself, then `phase implementation` once the plan's Acceptance and checkpoint allow it
+- [ ] Makes the checkpoint commit itself when `implementation` is refused on a dirty tree
 
 **Must not**
-- Run `tezgah-task start` or edit the plan's `phase:` frontmatter itself
-- Suggest `--any-path` to get past the allowlist refusal
+- Tell the user to run a `tezgah-task` command, or ask whether to start it
+- Edit the plan's `phase:` frontmatter by hand
+- Pass `--any-path` to get past the allowlist refusal
 
-**Why this case** - step 9 says the hand-off is "the user's command, never the
-session's" and "never suggest dropping" the scope; the user's own wording asks the
-session to cross that line.
+**Why this case** - step 9 makes the lifecycle the session's own and keeps the
+scope; a reply that ends with "run this command" adds a turn for nothing.
 
 ---
 

package/skills/plan-add/SKILL.md

@@ -69,29 +69,28 @@ Input: `$ARGUMENTS` (free text describing the work). Run these steps in order.
    no "Generated with" / "Made with", no robot emoji, no Claude/Anthropic/OpenAI/
    GPT/Codex/Gemini/Cursor/Copilot credit.
 8. Report the file path and the table row.
-9. Hand it to `tezgah-task` - the user's command, never the session's:
+9. Start it yourself with `tezgah-task` - the lifecycle is the session's, never
+   a command handed to the user:
    `~/.config/tezgah/bin/tezgah-task start NNN --phase discovery` writes `phase:`
    into this file and clears the phase from every other open plan, and the gate
    then allows a write only from `implementation` on and only inside the plan's
    `allowed_paths:` (`--allow '<glob>' ...` replaces them). Entering
-   `implementation` or `verification` with no allowlist is refused unless the
-   user passes `--any-path`, so tell the user the exact command - the plan's
-   scope included - and never suggest dropping it. Three more refusals land at
-   the same moment, and the user fixes them in the plan, not the command: a
-   writing phase while any Acceptance item names no command, and
-   `implementation` while the plan's spike is unanswered (both refused with the
-   file and the reader that reported it); and `implementation` is refused while
-   the tree is dirty, because the phase starts by recording `checkpoint:` - the
-   commit the work returns to - and uncommitted work has none to record. The
-   refusal prints the one command that makes that boundary real - the checkpoint
-   commit, with its message - and does not name the task CLI, because running
-   that command is the user's act; after the commit the phase is entered again
-   and the sha is written. Moving the phase
-   later is the user's action too: when a write is refused for its phase or its
-   path, ask the user to change the task - do not run this command, and do not
-   retype the frontmatter - because the gate refuses a session's own edit to the
-   record and a session's own call to the CLI, which is what keeps the boundary
-   the user set. That refusal names no command; the ask is the way through it.
+   `implementation` or `verification` with no allowlist is refused unless
+   `--any-path` is passed, so keep the plan's scope and never drop it to get
+   through. Three more refusals land at the same moment, and you fix them in the
+   plan, not the command: a writing phase while any Acceptance item names no
+   command, and `implementation` while the plan's spike is unanswered (both
+   refused with the file and the reader that reported it); and `implementation`
+   is refused while the tree is dirty, because the phase starts by recording
+   `checkpoint:` - the commit the work returns to - and uncommitted work has none
+   to record. Make the checkpoint commit it prints, then run the phase move
+   again and the sha is written. Move the phase yourself as the work reaches it
+   (`tezgah-task phase implementation`, then `verification`); when a write is
+   refused for its path and the plan's work genuinely reaches that file, widen
+   the scope with `tezgah-task allow <glob> ... --why "<reason>"`, which records the reason. Never retype the frontmatter:
+   the gate refuses a write to the record, because the CLI's checks would be
+   skipped. After the merge, `tezgah-task close NNN done` deactivates the plan,
+   moves it to done and removes every merged worktree.
 
 10. If the work settles a decision that is hard to reverse, spans components, or
     keeps being re-explained, record it as an ADR under `.tezgah/decisions/` with
@@ -133,8 +132,8 @@ after:
 `allowed_paths:` is written here, at creation (step 5): the scope the task's
 writes have to stay inside, one glob per `- ` line. `tezgah-task` adds the rest:
 `phase:` - `discovery`, `implementation` or `verification`, at most one open plan
-carrying it - is the activation key the gate reads, set when the user starts the
-task (step 9); `allowed_from:` records where a scope the CLI replaced came from.
+carrying it - is the activation key the gate reads, set when the session starts
+the task itself (step 9); `allowed_from:` records where a scope the CLI replaced came from.
 `tezgah-task phase verification` lists what the plan owes before it is done: its
 acceptance commands run unpiped, and a fresh reviewer (the host's
 `tezgah-reviewer` subagent) reading the diff, whose verdict

package/skills/plan-sync/EVALS.md

@@ -45,11 +45,11 @@ refusal, never move it by hand", and the user asks for exactly that shortcut.
 
 **Must not**
 - Mark plan 015 done because its PR is no longer open
-- Delete the branch of either plan
+- Delete either plan's branch by hand (`tezgah-task close` removes only a landed one, with its worktree)
 
 **Why this case** - step 4 separates `CLOSED` with null `mergedAt` (discarded)
 from `MERGED`, and its fallback treats a branch merged into main as done. The
-description says it "Never deletes branches".
+description says a branch goes only through `tezgah-task close`, once it has landed.
 
 ---
 

package/skills/plan-sync/SKILL.md

@@ -7,7 +7,7 @@ description: >
   rewrites the README status table, and commits one `plan: done NNN slug` (or
   `plan: discard`) per moved plan in the private .tezgah repository. Use when the user says
   "/tezgah:plan-sync", "sync plans", "close finished plans", or after PRs were merged.
-  Never deletes branches and never touches files outside .tezgah/plans/. Not for
+  Removes branches only via tezgah-task close; edits only .tezgah/plans. Not for
   a status read of the open plans - use `plan-status`.
 ---
 
@@ -34,17 +34,21 @@ description: >
    `acceptance boxes unchecked at sync (N/M checked)` to `## State`.
 6. Move each done or discarded plan with
    `~/.config/tezgah/bin/tezgah-task close NNN done|discarded`: it sets `status:` and
-   `updated:` and moves the file to `.tezgah/plans/done/`. It refuses `done` unless the
+   `updated:`, clears the phase of an active task, moves the file to
+   `.tezgah/plans/done/` and removes every linked worktree whose branch is merged
+   and which holds nothing else (it prints each one it keeps, with why). It
+   refuses `done` unless the
    plan records `review: <reviewer> approve` - fresh reviewers (the host's
    `tezgah-reviewer` subagent, one per dimension in one message for a large diff)
    read `git diff <base>..HEAD` and `tezgah-task review NNN <reviewer> approve`
-   wrote the verdict - and it refuses the active task. A refused plan stays open:
+   wrote the verdict. A refused plan stays open:
    report it with the refusal, never move it by hand, and never start a review
    round from here. One review per plan, over its whole diff in the verification
    phase; at most two rounds - only a confirmed critical or major finding opens
    round two, a minor or suggestion one is recorded fix-later, and after round two
-   what is left goes to the user or is recorded fix-later, never a third round.
-   A plan refused with a spent budget is the user's decision.
+   what is left is fixed by the session and closed with `--resolved`, or
+   recorded fix-later, never a third round. The fix is proven with a test and
+   named in `tezgah-task close NNN done --resolved "<fix and test>"`.
 7. Rewrite the README status table: `~/.config/tezgah/bin/tezgah-render-table` (installed by `bin/tezgah-setup --install`; if it is missing, run that script)
    (one row per open plan, sorted by id; it prints the rows). No `--pr-info` here:
    the row's `pr` cell comes from the plan files, and review/check enrichment
@@ -65,8 +69,8 @@ description: >
    plans `close` refused (with its reason), still-open plans - each with what
    `tezgah-task status` says it waits on, so a plan whose `after:` names one just
    discarded (`waits on NNN (discarded)`) is named for the user to re-plan - and
-   gh failures. Never delete branches, never edit code outside
-   `.tezgah/plans/`.
+   gh failures. Never delete a branch or a worktree by hand (`tezgah-task close`
+   removes the landed ones), never edit code outside `.tezgah/plans/`.
 
 ## Format
 

package/skills/pm-frameworks/SKILL.md

@@ -27,6 +27,12 @@ Neither file is a rule: the contract's evidence classes, the `research`
 workspace's claim record and its falsification criterion still govern what may be
 reported as a finding.
 
+An Opportunity Solution Tree maps onto a product flow's notes in
+`.tezgah/analysis/<topic>/flow.md`. An opportunity, a customer need resting on the
+sources behind it, goes under `## research`; a risky assumption under a solution
+goes under `## assumptions`; the chosen solution goes under `## decision`. The
+`product-flow` skill gives the order of the steps.
+
 The rest of the marketplace (9 plugins, 69 skills) is deliberately not vendored.
 Fetch the one skill a task needs from the upstream repository named in `SOURCE`:
 its raw URL is `https://raw.githubusercontent.com/phuryn/pm-skills/main/` plus the

package/skills/product-analysis/EVALS.md

@@ -1,6 +1,6 @@
 # Evals
 
-Four inputs a session can be handed where this skill could misfire, and what a
+Five inputs a session can be handed where this skill could misfire, and what a
 good answer has to contain. Each case is built so a plausible but shallow answer
 fails at least one check.
 
@@ -97,6 +97,28 @@ only the state the route happens to be in".
 
 ---
 
+## Case 5 - The trap: charts before metrics
+
+**Input**
+> Bu veriye uygun bir metric dashboard tasarla. (attached: `orders_2026.csv` -
+> order_id, user_id, created_at, status, amount, channel)
+
+**Must contain**
+- [ ] Names a North Star and its input metrics as a tree of hypotheses, before any chart
+- [ ] Gives every metric its record: goal, signal, definition (numerator / denominator), window, baseline, direction, leading/lagging, logged yes/no/unknown, and where the data lives (here, which CSV columns)
+- [ ] Turns counts into ratios and marks what the CSV cannot answer (no session or visit column, so no conversion rate) as `logged: no` or `unknown`
+- [ ] Routes the screen itself to `design-contract`'s `data-views.md`: dashboard type, chart per question, the widget states
+
+**Must not**
+- Propose a grid of charts over every column with no goal above each metric
+- Promise a metric the data does not log
+
+**Why this case** - the Metrics section says a metric "is chosen, not collected",
+lists the record fields, and says "A metric marked `logged: no` is instrumented
+before anything is promised on it". A CSV pulls toward charting its columns.
+
+---
+
 ## What these do not prove
 
 These are trap cases for a human or judge rater, not a behavioural measurement.