@r1z4x/tezgah 1.5.0 → 1.6.0

package/hooks/tezgah_product.py

@@ -0,0 +1,107 @@
+"""The product-flow playbook (plan 074, ADR 025): the one place its steps are
+written. `next_steps` computes each step's status from the topic's files under
+`.tezgah/analysis/<topic>/` - `flow.md`, one `## <step>` heading per step, and
+`spec.md` - and nothing stores it."""
+import datetime
+import os
+import re
+
+import tezgah_paths as tp
+
+# A topic becomes a path below, so anything outside kebab-case reads no file.
+TOPIC = re.compile(r"(?=.{1,64}\Z)[a-z0-9]+(?:-[a-z0-9]+)*")
+OBSERVE = re.compile(r"observe after:\s*(\d{4}-\d{2}-\d{2})", re.I)
+
+
+def _step(sid, skill, first=""):
+    """A step whose artifact is its `## <sid>` note in flow.md; `first` is what
+    the session does before writing it."""
+    return {"id": sid, "skill": skill,
+            "leaves": "## %s in .tezgah/analysis/<topic>/flow.md" % sid,
+            "command": "%swrite ## %s in .tezgah/analysis/{topic}/flow.md"
+                       % (first, sid)}
+
+
+# `{topic}` in a command is filled per topic. The design check and the Stop UI
+# rule judge design and build; the flow only asks for their note.
+_STEPS = (
+    _step("research", "research"),
+    _step("metrics", "product-analysis"),
+    _step("assumptions", "product-analysis"),
+    _step("decision", "product-analysis"),
+    _step("instrumentation", "product-analysis"),
+    {"id": "forward-spec", "skill": "feature-audit",
+     "leaves": ".tezgah/analysis/<topic>/spec.md",
+     "command": "feature-audit forward mode: write .tezgah/analysis/{topic}/spec.md "
+                "naming the decision"},
+    _step("design", "design-contract", "tezgah-design check, then "),
+    _step("build", "design-contract", "tezgah-design check, then "),
+    _step("re-measure", "analyze-app", "measure the decision's metric again, then "),
+)
+FLOWS = {
+    "metric-dashboard": _STEPS,
+    # A feature may reuse a metric another topic owns: its own metric steps join
+    # the flow only when its flow.md holds `## metrics` (`next_steps`).
+    "feature": tuple(s for s in _STEPS if s["id"] not in ("metrics", "instrumentation")),
+}
+
+
+def _sections(text):
+    """{step: body} of the `## <step>` headings in `text`, lower-cased."""
+    parts = re.split(r"^##[ \t]+(.+?)[ \t]*$", text, flags=re.M)
+    return {parts[i].lower(): parts[i + 1] for i in range(1, len(parts) - 1, 2)}
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def next_steps(repo, topic, flow="metric-dashboard", today=""):
+    """[{"id", "skill", "status", "detail", "command"}] for `topic` under `flow`,
+    status one of done | missing | due, read from `.tezgah/analysis/<topic>/` of
+    `repo`. A topic outside TOPIC or with no folder lists every step missing."""
+    if flow not in FLOWS:
+        raise ValueError("unknown flow %r (%s)" % (flow, ", ".join(FLOWS)))
+    try:
+        day = datetime.date.fromisoformat(today) if today else datetime.date.today()
+    except ValueError:
+        raise ValueError("today %r is not YYYY-MM-DD" % (today,)) from None
+    safe = isinstance(topic, str) and TOPIC.fullmatch(topic)
+    rel = os.path.join(".tezgah", "analysis", topic if safe else "<topic>")
+    folder = os.path.join(tp.workspace(repo), "analysis", topic) if safe else ""
+    notes = _sections(_read(os.path.join(folder, "flow.md"))) if folder else {}
+    flow_rel = os.path.join(rel, "flow.md")
+    spec_rel = os.path.join(rel, "spec.md")
+    steps = FLOWS["metric-dashboard"] if flow == "feature" and "metrics" in notes \
+        else FLOWS[flow]
+
+    def status(sid):
+        if sid == "forward-spec":
+            return ("done", "%s exists" % spec_rel) \
+                if folder and os.path.isfile(os.path.join(folder, "spec.md")) \
+                else ("missing", "%s does not exist" % spec_rel)
+        if sid in notes:
+            return "done", "%s ## %s" % (flow_rel, sid)
+        if sid == "re-measure":
+            after = OBSERVE.search(notes.get("decision", ""))
+            try:
+                when = datetime.date.fromisoformat(after.group(1)) if after else None
+            except ValueError:
+                when = None
+            if when is not None:
+                return ("due", "observe after %s has passed" % when) if day > when \
+                    else ("missing", "observe after %s, not yet" % when)
+            return "missing", "no observe after: in %s ## decision" % flow_rel
+        return "missing", "no ## %s in %s" % (sid, flow_rel)
+
+    out = []
+    for s in steps:
+        state, detail = status(s["id"])
+        out.append({"id": s["id"], "skill": s["skill"], "status": state,
+                    "detail": detail, "command": s["command"].format(
+                        topic=topic if safe else "<topic>")})
+    return out

package/hooks/tezgah_research.py

@@ -2842,9 +2842,9 @@ def _check_append_only(repo, label, path, errors, warnings, hard):
         old = [line for line in older.splitlines() if line.strip()]
         new = [line for line in newer.splitlines() if line.strip()]
         if new[:len(old)] != old:
-            _soft(errors, warnings, hard, "%s was rewritten after the run: a committed "
-                  "row changed or went missing, and results are append-only - a "
-                  "correction is a new row" % label)
+            _soft(errors, warnings, hard, "%s was rewritten after the run: a "
+                  "committed row changed or went missing, and results are "
+                  "append-only - a correction is a new row" % label)
             return
 
 

package/hooks/tezgah_skill_pick.py

@@ -347,10 +347,40 @@ def skill_roots(extra=()):
     return out
 
 
+# One routing line of a skill's own INDEX.md: `name - what it makes - path`.
+_INDEX_ROW = re.compile(r"^\S+ - .+ - (\S+/SKILL\.md)\s*$")
+
+
+def _entries(root, name):
+    """[(skill, path)] for one skill directory: its SKILL.md, then every entry its
+    INDEX.md routes to. design-library keeps 39 entries under
+    `<plugin>/skills/<entry>/SKILL.md` and reaches them only through that index,
+    so a search over top-level files alone never saw a word of them. A nested
+    entry is addressed `<skill>/<path>`, the form `skill://` resolves."""
+    base = os.path.join(root, name)
+    out = [(name, os.path.join(base, "SKILL.md"))]
+    try:
+        with open(os.path.join(base, "INDEX.md"), encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return out
+    # A row is followed only inside the skill's own directory: an absolute path,
+    # a `..` or a symlink out would index a file the skill does not ship.
+    inside = os.path.realpath(base) + os.sep
+    for line in lines:
+        hit = _INDEX_ROW.match(line)
+        if not hit or os.path.isabs(hit.group(1)):
+            continue
+        path = os.path.join(base, hit.group(1))
+        if os.path.realpath(path).startswith(inside):
+            out.append(("%s/%s" % (name, hit.group(1)), path))
+    return out
+
+
 def _rows(roots=None):
     """[(skill, path, title, start, end, text)] over every installed skill's
-    sections, deduplicated on the file's realpath so a skill five hosts link
-    is one entry, not five."""
+    sections, and the entries a skill's INDEX.md routes to, deduplicated on the
+    file's realpath so a skill five hosts link is one entry, not five."""
     out, seen = [], set()
     for root in (skill_roots() if roots is None else roots):
         try:
@@ -358,14 +388,23 @@ def _rows(roots=None):
         except OSError:
             continue
         for name in names:
-            path = os.path.realpath(os.path.join(root, name, "SKILL.md"))
-            if not os.path.isfile(path):
-                continue
-            for title, start, end, text in sections(path):
-                if (path, start) in seen:
+            for skill, raw in _entries(root, name):
+                path = os.path.realpath(raw)
+                if not os.path.isfile(path):
                     continue
-                seen.add((path, start))
-                out.append((name, path, title, start, end, text))
+                secs = sections(path)
+                if "/" in skill and secs:
+                    # A routed entry is one row, the whole file: its short
+                    # sections out-scored whole skills on two common words
+                    # ("give", "thing") and silenced the right hint, while the
+                    # entry as a whole still carries its topic's words.
+                    secs = [(secs[0][0], secs[0][1], secs[-1][2],
+                             "\n".join(s[3] for s in secs))]
+                for title, start, end, text in secs:
+                    if (path, start) in seen:
+                        continue
+                    seen.add((path, start))
+                    out.append((skill, path, title, start, end, text))
     return out
 
 
@@ -490,9 +529,10 @@ def rank_postings(query, posts, lengths, k):
 
 
 def _signature():
-    """[[root, skill, mtime_ns, size]] per installed SKILL.md: what a rebuild
-    keys on. The file's own stat, not its directory's - installing, editing or
-    removing one skill is exactly the change the cache must notice."""
+    """[[root, skill, mtime_ns, size]] per installed SKILL.md and per entry an
+    INDEX.md routes to: what a rebuild keys on. The file's own stat, not its
+    directory's - installing, editing or removing one skill is exactly the
+    change the cache must notice."""
     sig = []
     for root in skill_roots():
         try:
@@ -500,11 +540,12 @@ def _signature():
         except OSError:
             continue
         for name in names:
-            try:
-                st = os.stat(os.path.join(root, name, "SKILL.md"))
-            except OSError:
-                continue
-            sig.append([root, name, st.st_mtime_ns, st.st_size])
+            for skill, path in _entries(root, name):
+                try:
+                    st = os.stat(path)
+                except OSError:
+                    continue
+                sig.append([root, skill, st.st_mtime_ns, st.st_size])
     return sig
 
 

package/hooks/tezgah_task.py

@@ -2,8 +2,8 @@
 """The active task: one plan file's phase and its path allowlist.
 
 A task is not a second record beside the plan - it IS the plan file under
-`.tezgah/plans/open/`, with two optional frontmatter keys that the user's own CLI
-(bin/tezgah-task) writes and no agent ever does:
+`.tezgah/plans/open/`, with two optional frontmatter keys that only its CLI
+(bin/tezgah-task, run by the orchestrating session itself) writes:
 
     phase: implementation        # discovery | implementation | verification
     allowed_paths:               # globs, relative to the repo root
@@ -158,6 +158,12 @@ _MARKER = re.compile(r"unverifiable(?![-\w])", re.I)
 # why") has no separator there and is not a declaration.
 _SEPARATORS = ":,;(-"
 _SPAN = re.compile(r"`([^`\n]+)`")
+# A runner whose test entry point is a bare subcommand: `pnpm test`, `cargo
+# test`, `uv run pytest` carry no option and no path, yet each is the command.
+# The runner has to be the first word, so `run the tests` stays prose.
+_RUNNERS = ("npm", "pnpm", "yarn", "bun", "deno", "cargo", "go", "make", "mix",
+            "dotnet", "gradle", "mvn", "poetry", "uv")
+_SUBCOMMANDS = ("test", "run")
 
 
 def _argument(token):
@@ -179,14 +185,16 @@ def _argument(token):
 
 def names_command(text):
     """Does this acceptance item name the command that proves it? A command is a
-    backticked run of two or more words carrying an option, a path or a script:
-    `bin/tezgah-docs --citations`, `python3 -m unittest tests/test_task.py`. A
-    citation (`hooks/tezgah_task.py`, `plan:line`) is not one, and an invocation
-    with no argument at all is not recognised either - both are reported, which
-    is the safe direction for a report a person reads."""
+    backticked run of two or more words carrying an option, a path or a script
+    (`bin/tezgah-docs --citations`, `python3 -m unittest tests/test_task.py`), or
+    a known runner followed by `test` or `run` (`pnpm test`, `npm run test`). A
+    citation (`hooks/tezgah_task.py`, `plan:line`) is not one, and any other
+    invocation with no argument is not recognised either - both are reported,
+    which is the safe direction for a report a person reads."""
     for span in _SPAN.findall(text):
         tokens = span.split()
-        if len(tokens) > 1 and any(_argument(token) for token in tokens[1:]):
+        if len(tokens) > 1 and (any(_argument(token) for token in tokens[1:]) or
+                                (tokens[0] in _RUNNERS and tokens[1] in _SUBCOMMANDS)):
             return True
     return False
 

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.0",
+  "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": {
@@ -19,7 +19,6 @@
     "output-styles/",
     "commands/",
     "docs/",
-    "agents/",
     "statusline.py",
     "MANIFEST",
     "CHANGELOG.md",

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).