kaloko 0.4.8 → 0.4.9

package/README.md

@@ -81,6 +81,15 @@ what still waits for a person, so it can pass the link on. Agents never
 approve for people: their decisions are marked and do not count as a
 person's.
 
+Every AI verdict comes with one sentence saying why. Criteria marked
+`vision: true`, and answers the text evaluator is unsure about, get a second
+look at the screenshot from a vision model (`ANTHROPIC_API_KEY`, or through
+Kaloko); `kaloko build` lists what to act on with the score and the reason.
+The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
+link) and reads names from the accessibility tree. Pixel diffs skip the
+regions a step ignores; `kaloko walk --stability 3` and `kaloko stability`
+find the clocks, ads and carousels worth ignoring.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
@@ -98,6 +107,17 @@ npx kaloko share --name "Checkout v2"     # a version of the whole flow
 npx kaloko reference --design --version 2 # after the team accepted it
 ```
 
+Developers and their agents build from what was approved. *Dev mode* (`D` in the step detail) shows each
+element's box, sizes and distances, its colors, type and spacing with the token every value comes from (or a
+warning when it is not a token), contrast against WCAG AA, the `:hover`, `:focus`, `:active` and disabled states,
+and its images. The same data is the step spec an agent reads, and `kaloko drift` checks the implementation
+against it:
+
+```bash
+npx kaloko spec payment                   # elements, styles → tokens, states (also MCP get_step_spec)
+npx kaloko walk && npx kaloko drift       # expected token vs actual value per element; exit 1 while it differs
+```
+
 On the canvas, *Prototype* (or `P`) presents the steps full screen as live pages: click through links between
 steps, switch the device, walk with the arrow keys, and share a link that opens straight into a step. The rules
 for pages that work everywhere are in `skills/kaloko/reference/portable-html.md`.
@@ -141,7 +161,9 @@ captured HTML, page text and console output.
 - **Service and evaluator**: `KALOKO_TOKEN` for `share`, `feedback`, `review`, `inbox` and clean-up (`runs`, `trash`, `prune`, `keep`, `archive`)
   (`npx kaloko login` approves one in the browser and saves it to `~/.config/kaloko/.env`, or create it in your
   organization's settings); `TYPESAFE_API_KEY` for the
-  semantic evaluator (optional). Both names can be changed in the config.
+  semantic evaluator and `ANTHROPIC_API_KEY` for the vision evaluator (both
+  optional; without them Kaloko evaluates on your plan's allowance). The names
+  can be changed in the config.
 
 `npx kaloko doctor` checks that every variable the config names is set and that
 each environment lets you in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -45,6 +45,32 @@
             "signals": { "type": "boolean", "default": true, "description": "Quick signals on every screen (purpose met, expected language, looks broken); never change verdicts." },
             "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "default": 6, "description": "Evaluator requests in flight at once." }
           }
+        },
+        "vision": {
+          "description": "Second, vision-capable evaluator (#17): sees the screenshot (a crop for scoped criteria) and answers with a probability and a one-sentence reason. Asked only for criteria with vision: true and for text answers in the uncertain band; false turns it off.",
+          "oneOf": [
+            { "const": false },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "provider": { "enum": ["anthropic"], "default": "anthropic" },
+                "model": { "type": "string", "default": "claude-opus-5-5", "description": "Model id of the provider (Anthropic Messages API with image input)." },
+                "api_key_env": { "type": "string", "default": "ANTHROPIC_API_KEY" },
+                "base_url": { "type": "string", "default": "https://api.anthropic.com" },
+                "when": { "enum": ["uncertain", "flagged", "always", "off"], "default": "uncertain", "description": "flagged: only criteria with vision: true; uncertain: those plus text answers in the uncertain band; always: every semantic criterion (most expensive)." },
+                "uncertain": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2, "default": [0.15, 0.85], "description": "Text scores strictly between these go to the vision evaluator." },
+                "max_calls": { "type": "integer", "minimum": 0, "default": 40, "description": "Vision requests per evaluation (uncached); the rest stay with the text answer." },
+                "max_width": { "type": "integer", "minimum": 320, "maximum": 1568, "default": 1000, "description": "Images are scaled down to this width (px)." },
+                "tile_height": { "type": "integer", "minimum": 400, "maximum": 1568, "default": 1400, "description": "A full page is cut into tiles of this height." },
+                "max_tiles": { "type": "integer", "minimum": 1, "maximum": 4, "default": 2, "description": "Tiles of a full page sent at most (from the top); scoped criteria get a crop instead." },
+                "effort": { "enum": ["low", "medium", "high"], "default": "low" },
+                "reason_language": { "type": "string", "default": "en", "description": "Language of the one-sentence reasons (en, cs, …)." },
+                "hosted": { "type": "boolean", "default": true, "description": "Without a local key, ask through the organization's service (counts against the monthly allowance; one vision question counts as 5)." },
+                "concurrency": { "type": "integer", "minimum": 1, "maximum": 8, "default": 3 }
+              }
+            }
+          ]
         }
       }
     },

package/schemas/scenario.v1.json

@@ -262,6 +262,11 @@
         "capture": {
           "$ref": "#/$defs/capture"
         },
+        "ignore": {
+          "type": "array",
+          "description": "Regions left out of pixel comparisons (clocks, ads, carousels): a selector, or a rectangle in page pixels of one viewport. kaloko stability suggests them.",
+          "items": { "$ref": "#/$defs/ignoreRegion" }
+        },
         "items": {
           "type": "object",
           "additionalProperties": false,
@@ -500,6 +505,13 @@
             "a11y_contrast",
             "a11y_main",
             "a11y_unique_ids",
+            "a11y_focus_order",
+            "a11y_focus_visible",
+            "a11y_keyboard_trap",
+            "a11y_skip_link",
+            "a11y_ax_names",
+            "a11y_landmarks",
+            "a11y_aria",
             "perf_lcp",
             "perf_cls",
             "perf_ttfb",
@@ -588,6 +600,10 @@
             "console"
           ],
           "description": "console: the evaluator reads the captured console errors with the step purpose (triage) instead of the page"
+        },
+        "vision": {
+          "type": "boolean",
+          "description": "Also show the evaluator the screenshot (a crop of scope when set): layout, imagery, brand. Needs a vision evaluator (evaluators.vision)."
         }
       }
     },
@@ -632,6 +648,22 @@
         }
       }
     },
+    "ignoreRegion": {
+      "type": "object",
+      "additionalProperties": false,
+      "oneOf": [
+        { "required": ["selector"] },
+        { "required": ["rect", "viewport"] }
+      ],
+      "properties": {
+        "selector": { "type": "string", "minLength": 1, "description": "CSS selector; every visible match is ignored." },
+        "rect": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 4, "maxItems": 4, "description": "[x, y, width, height] in CSS pixels of the page." },
+        "viewport": { "type": "string", "description": "The viewport a rect belongs to." },
+        "viewports": { "type": "array", "items": { "type": "string" }, "description": "Only in these viewports (selector)." },
+        "locales": { "type": "array", "items": { "type": "string" }, "description": "Only in these locales." },
+        "note": { "type": "string" }
+      }
+    },
     "capture": {
       "type": "object",
       "additionalProperties": false,

package/schemas/spec.v1.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/spec.v1.json",
+  "title": "qawalk.spec.v1",
+  "description": "The step spec (#42 Dev mode): what to build for one step as it was approved. Written by the in-page engine src/lib/devspec.mjs at capture (steps/<step>/<locale>/<viewport>.spec.json, and the capture record of a design revision); the canvas Dev mode runs the same engine on the live page. Served by GET …/scenarios/<id>/steps/<step>/spec, MCP get_step_spec and kaloko spec. Elements are listed in page order; a style lists only what differs from what the element inherits (page, then the parent element).",
+  "type": "object",
+  "required": ["schema", "elements"],
+  "$defs": {
+    "value": {
+      "type": "object",
+      "description": "A computed value (colors as #rrggbb[aa], lengths in px) and the token it maps to. token: the DTCG path (several, space-separated, for a shorthand such as padding; 0 for a zero side); null when the set has tokens of that kind but none fits and none is near. nearest: the closest token when the value is not one. mode: the mode whose value it is (light, dark, …). hard: the stylesheet typed the raw value although the token exists. var: the custom property the author used when it names no token.",
+      "required": ["value"],
+      "properties": {
+        "value": { "type": "string" },
+        "token": { "type": ["string", "null"] },
+        "nearest": { "type": "string" },
+        "mode": { "type": "string" },
+        "hard": { "type": "boolean" },
+        "var": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "styles": {
+      "type": "object",
+      "description": "CSS property → value: color, background-color, border-color, font-family, font-size, font-weight, line-height, letter-spacing, padding, gap, row-gap, column-gap, border-width, border-radius, box-shadow, opacity, display and flex or grid properties.",
+      "additionalProperties": { "$ref": "#/$defs/value" }
+    }
+  },
+  "properties": {
+    "schema": { "const": "qawalk.spec.v1" },
+    "title": { "type": "string" },
+    "lang": { "type": ["string", "null"] },
+    "viewport": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 },
+    "size": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Document width and height." },
+    "tokens": { "type": ["object", "null"], "description": "The token set the values were mapped with (the step's tokens.json); null without one.", "properties": { "count": { "type": "integer" }, "modes": { "type": "array", "items": { "type": "string" } } } },
+    "page": { "$ref": "#/$defs/styles", "description": "Typography and text color of the page (body), inherited by every element that does not say otherwise." },
+    "elements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["i", "parent", "tag", "sel", "styles"],
+        "properties": {
+          "i": { "type": "integer" },
+          "parent": { "type": "integer", "description": "Index of the nearest listed ancestor, -1 at the top." },
+          "tag": { "type": "string" },
+          "role": { "type": ["string", "null"], "description": "ARIA role, explicit or implicit (button, link, heading, main, textbox, …)." },
+          "name": { "type": ["string", "null"], "description": "Accessible name or own text (at most 80 characters)." },
+          "sel": { "type": "string", "description": "A CSS selector of the element in the design page (ids, data-testid and classes first)." },
+          "box": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "x, y, width, height in CSS px of the page." },
+          "styles": { "$ref": "#/$defs/styles" },
+          "contrast": { "type": "object", "properties": { "ratio": { "type": "number" }, "aa": { "type": "boolean" } } },
+          "states": { "type": "object", "description": "hover, focus, active, disabled → the styles that change in that state (the page's rules forced on the element).", "additionalProperties": { "$ref": "#/$defs/styles" } },
+          "asset": { "type": "object", "properties": { "kind": { "enum": ["img", "svg"] }, "src": { "type": "string" }, "size": { "type": "array" }, "alt": { "type": ["string", "null"] } } }
+        }
+      }
+    },
+    "used": { "type": "object", "description": "Token path → number of values that use it.", "additionalProperties": { "type": "integer" } },
+    "off": { "type": "array", "description": "Values outside the token set, most frequent first.", "items": { "type": "object", "properties": { "prop": { "type": "string" }, "value": { "type": "string" }, "count": { "type": "integer" }, "nearest": { "type": ["string", "null"] }, "sel": { "type": "string" } } } }
+  }
+}

package/skills/kaloko/SKILL.md

@@ -11,7 +11,9 @@ description: >
   reviewer rejected on a canvas, what is waiting in the Kaloko inbox, or how
   to report a run in an issue, and when designing screens of a flow in a
   design environment (live HTML steps, drafts, versions, the design
-  reference, checking implementation against it).
+  reference, checking implementation against it), and when implementing a
+  screen that has an approved design (read the step spec, build with its
+  tokens, check drift).
 ---
 
 # Kaloko
@@ -32,6 +34,10 @@ the canvas, storage and collaboration are the service.
   for them (`kaloko share` prints it; `kaloko review` repeats it), and you
   read `kaloko feedback` and `kaloko inbox` before continuing on that task.
 - Changes to intent are written back to `ACCEPTANCE.md` (change log row).
+- When you implemented a step from an approved design: you read its spec
+  (`kaloko spec <step>`), walked the implementation with `packs: [design]`,
+  and `kaloko drift` is clean or the PR names each difference left for a
+  person to decide.
 - On a design environment: the folder follows the bundle rules and
   `kaloko design lint` shows no error, `kaloko walk` and `kaloko sync` ran,
   `kaloko status` shows no conflict, and you read the draft's feedback; a
@@ -77,7 +83,8 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/stacks.md](reference/stacks.md)
 - Choosing playwright, agent or manual per step, and driving the shared
   browser with your capabilities: [reference/execution.md](reference/execution.md)
-- Evaluation, JEV thresholds and reading results: [reference/evaluation.md](reference/evaluation.md)
+- Evaluation, thresholds, the vision evaluator and its reasons, reading
+  results: [reference/evaluation.md](reference/evaluation.md)
 - Environments, access (gates, accounts, sign-in), e-mails, readonly and
   production rules, and what is yours to arrange for the project's stack:
   [reference/environments.md](reference/environments.md)
@@ -94,6 +101,9 @@ they can do; never write secrets into the config, a scenario or a script.
   references, handoff, tokens, the design pack, canvas edits, branches, HTML
   view, presenting the prototype, exports, bringing your own design skill):
   [reference/design.md](reference/design.md)
+- Implementing a screen from the approved design: read the step spec, build
+  with its tokens, walk, check drift, fix:
+  [reference/design.md#implement-from-the-approved-design](reference/design.md#implement-from-the-approved-design)
 - Writing design pages that work on the live step, from disk and in other
   tools (relative URLs, no CDNs, state in the URL, deterministic content,
   links between steps; what `kaloko design lint` checks):

package/skills/kaloko/reference/acceptance.md

@@ -40,8 +40,21 @@ for public pages and landings; task flows keep their own criteria.
 
 - `a11y` (`AC3xx`): images with alt, links and buttons with a name, labelled
   fields, heading levels not skipped, WCAG AA text contrast, a `main`
-  landmark, unique ids. A subset of WCAG 2.2 AA checked in the page; it does
-  not replace an audit with a screen reader.
+  landmark, unique ids (`AC301`–`AC307`, read from the page). After the
+  screenshot the walk also presses Tab through the page: `AC308` tab order
+  (hidden focus, big jumps back, positive `tabindex`, controls left out or
+  mouse-only), `AC309` visible focus with at least 3 : 1 contrast (each stop
+  screenshotted focused and unfocused), `AC310` no keyboard trap (a modal
+  dialog may keep focus), `AC311` a skip link or main content within three
+  stops, `AC312` names from Chrome's accessibility tree (what a screen
+  reader announces). `AC313` landmarks (one `main`, labelled repeats) and
+  `AC314` ARIA (unknown roles and attributes, references to missing ids,
+  `aria-hidden` over focusable content) are read from the page. The first
+  five focus stops are kept as screenshots and the canvas can draw the tab
+  order on the capture. The walk only moves focus: nothing is clicked or
+  typed, and the page is left unfocused at the top. Stack steps walk the
+  keyboard on their first five pages. Still a subset of WCAG 2.2 AA; it
+  does not replace an audit with a screen reader.
 - `perf` (`AC4xx`): LCP ≤ 2.5 s, CLS ≤ 0.1, TTFB ≤ 800 ms, page weight ≤ 3 MB,
   measured in this walk's browser since the page load (lab values: the
   machine and network of the walk matter; compare runs, not absolutes).
@@ -227,3 +240,22 @@ skips a session's nodes there. The canvas shows a chip with the person on
 every step, groups the step list by person and draws hand-offs between
 people as dashed arrows. Sessions run one after another, never in parallel,
 and never share cookies.
+
+## Ignore regions
+
+Clocks, ads, carousels and "3 minutes ago" change on every capture and make
+pixel diffs noisy. List them on the step and both the canvas diff and the
+design pixel check (`AC801`) leave them out:
+
+```yaml
+- id: home
+  ignore:
+    - { selector: "#clock" }                       # every visible match
+    - { selector: ".ad-slot", viewports: [desktop] }
+    - { rect: [0, 620, 1280, 240], viewport: desktop } # page pixels of one viewport
+```
+
+Do not guess them: `kaloko walk --stability 3` notes what moves while the
+page sits still, and `kaloko stability` compares the step with earlier runs
+and writes suggestions (see [execution.md](execution.md)). Ignore only noise;
+a region that matters to a criterion stays in.

package/skills/kaloko/reference/design.md

@@ -39,8 +39,10 @@ design/
   the bundle.
 - Links between steps are plain relative links to the page: `<a href="../payment/index.html">`. The canvas
   follows them; `data-kaloko-go="payment"` (or `data-qawalk-go`) moves to that step whatever the `href` says.
-- Reference token values as CSS custom properties (`var(--color-accent)`), so the inspector and the token
-  check see where values come from.
+- Reference token values as CSS custom properties named after the token path (`color.accent` →
+  `var(--color-accent)`), so Dev mode, the step spec and the token check see which token a value comes from.
+  Define interaction states in CSS (`:hover`, `:focus-visible`, `:active`, `:disabled`): Dev mode and the spec
+  read them from the stylesheet.
 - Write pages by the portable HTML rules ([portable-html.md](portable-html.md)): relative URLs only, bundled
   fonts, no CDNs, state in the URL instead of storage, deterministic content, viewport meta and `lang`.
   `kaloko design lint` checks the folder; `kaloko sync` runs it first and stops on errors (things that break on
@@ -94,8 +96,39 @@ Development builds from the design reference:
 - `kaloko export --live [--version n] --out design/` writes the live files into a folder.
 - MCP `get_step` (scenario, step, `ref: design`) returns the file list, a signed entry URL, the token set, the
   page structure and open comments; `list_step_changes` names the steps that changed since the last reference.
+- MCP `get_step_spec` (or `kaloko spec <step>`) returns what to build, element by element, with tokens; see
+  [Implement from the approved design](#implement-from-the-approved-design).
 - Translate to the project's stack with the project's own skills; keep the step ids and the token names.
 
+## Implement from the approved design
+
+Use this when you build or change a screen that has an approved design step (a design reference, or a version
+the person names). The step spec says what was approved in the terms you write code in: elements in page order
+with role, accessible name and selector, and their colors, typography, spacing, radius, shadow and layout, each
+value with the DTCG token it comes from. People see the same data in the canvas: *Dev mode* (`D`) in the step
+detail.
+
+1. **Read the spec** of each step you build: `kaloko spec <step>` (default `--ref design`; `--ref v4`, `draft` or a
+   run id), or MCP `get_step_spec`. `--json` gives `qawalk.spec.v1` (`schemas/spec.v1.json`).
+2. **Implement with the tokens.** A line such as `button "Pay" 120×44 bg #2e6bff=color.brand.primary · pad 12px
+   20px=space.3 space.5` means `background: var(--color-brand-primary); padding: var(--space-3) var(--space-5)`
+   (the custom property is the token path with dots as dashes) or the project's own token mechanism. `not a token;
+   nearest x` means the design itself used a raw value: ask the designer before you copy it, and say so in the PR.
+   `:hover`, `:focus`, `:active` and `:disabled` lines are states to build; `(light)` names the mode of a value.
+   Keep the roles and names: they are how the implementation is matched with the design.
+3. **Walk it** with `packs: [design]` on the implementation steps; the capture then stores the implementation's
+   spec next to the screenshot.
+4. **Check drift**: `kaloko drift [step]` compares the walked run with the design reference of the linked design
+   branch and exits 1 while something differs. A shared run: MCP `get_step_drift` (`run`: id or `latest`).
+   Findings name the element, the expected token and value, and what the page has; `typed raw` means the value
+   is right but should come from the token; `not found` means the design's element (by role and name) is missing.
+5. **Fix and repeat** until drift is clean or what is left is a decision for a person (a missing element on
+   purpose, a raw value the designer accepted); report those in the PR instead of hiding them.
+
+Specs exist for captures made with the current CLI: walk the design and sync again if `kaloko spec` says there is
+none. The pixel, structure and token checks of the design pack (`AC801`–`AC803`) still run in `kaloko evaluate`;
+drift is the per-element view an agent can act on.
+
 ## Your data is yours
 
 Everything exports in open formats, readable without Kaloko:

package/skills/kaloko/reference/evaluation.md

@@ -10,9 +10,11 @@ answer, so running it again is cheap.
 - deterministic results computed in the live page at capture time (with
   evidence: selector snippet, measured value);
 - the semantic evaluator for semantic criteria. It is a replaceable provider;
-  the default is JEV by TypeSafe (`TYPESAFE_API_KEY`), which returns only a
-  probability per question (`score`, 0–1). Verdicts: `pass` ≥ 0.85,
-  `fail` ≤ 0.15, otherwise `needs_review` (thresholds in config);
+  the default is JEV by TypeSafe (`TYPESAFE_API_KEY`), which reads the
+  reduced page state (no images) and returns only a probability per question
+  (`score`, 0–1). Verdicts: `pass` ≥ 0.85, `fail` ≤ 0.15, otherwise
+  `needs_review` (thresholds in config);
+- a vision evaluator for a second look with the screenshot (below);
 - `manual` criteria stay `not_evaluated` until a reviewer decides.
 
 Where the evaluator runs: with `TYPESAFE_API_KEY` set locally, your own key; without it, the organization's
@@ -25,6 +27,47 @@ report with the reason `kaloko evaluate` gives.
 The default evaluator is text-only and most accurate in English. It is weak
 at numbers, which is why those are checked deterministically.
 
+## Vision and reasons
+
+Every semantic verdict carries one sentence, `reason`, shown as "Why" next to
+the score on the canvas, in `kaloko build`, in the walk summary and in
+`get_run_summary`. With only the text evaluator the sentence says what it
+read and how sure it was (JEV gives no explanation). The vision evaluator
+gives a real one: it sees the screenshot, or a crop of the criterion's
+`scope` (or `highlight`), and answers with a probability and what in the
+image decided it. It is asked for:
+
+- criteria with `vision: true` on the check (layout, imagery, "looks like the
+  brand", anything the text cannot show);
+- text answers in the uncertain band (0.15–0.85 by default), which would
+  otherwise go to a person.
+
+Its answer replaces the score (the text score stays as `text_score` in the
+evaluation). Cost stays bounded: only those criteria, one request per
+capture, images scaled to 1000 px wide and at most two tiles of a full page,
+at most 40 uncached requests per evaluation, and answers cached by content
+like the text ones. The provider is Anthropic's Messages API
+(`ANTHROPIC_API_KEY`, model from `evaluators.vision.model`, default
+`claude-opus-5-5`). Without the key it goes through the organization's
+service, where one vision question counts as five of the monthly allowance;
+when the text evaluator runs with your own `TYPESAFE_API_KEY`, the vision
+evaluator also waits for your own key (`evaluators.vision.hosted: true`
+lets it use the service anyway).
+Configure or switch it off in `kaloko.config.yml`:
+
+```yaml
+evaluators:
+  vision:
+    when: uncertain      # flagged (only vision: true) | always | off
+    uncertain: [0.15, 0.85]
+    max_calls: 40
+    reason_language: en  # cs for Czech reviewers
+  # vision: false        # text evaluator only
+```
+
+Report the reason with each `needs_review` or failing criterion; when the
+evaluator saw the screenshot, say so.
+
 When a criterion comes back `needs_review`, read the reduced state the
 evaluator saw (`steps/<node>/<locale>/<viewport>.capture.json`, key `state`)
 and the screenshot. Either the page is genuinely unclear (report it), the

package/skills/kaloko/reference/execution.md

@@ -73,3 +73,21 @@ The environment policy and gate apply to every context the CLI creates (the
 shared browser, `walk` sessions, one-off captures): blocked paths and, when
 readonly, non-GET requests outside `allowed_post_paths` fail and are listed as
 blocked requests in the capture; the gate's credentials go to its origins only.
+
+## Noisy regions (`--stability`, `kaloko stability`)
+
+When pixel diffs between runs keep flagging the same clock, ad or carousel:
+
+```bash
+kaloko walk --stability 3        # 3 screenshots per capture, a moment apart; what moved is noted
+kaloko stability                 # this run against the 3 previous local runs of the scenario
+kaloko stability --apply         # adds the suggested ignore: to each step (block-style YAML only)
+```
+
+`kaloko stability` writes `stability.json` and `stability.yml` into the run
+and prints the suggestions per step: a selector when an element of the stored
+page covers the region, otherwise a rectangle for one viewport. Look at the
+screenshots before applying; a region that changed because the page really
+changed is not noise. `--same-commit` compares only runs of the same commit,
+`--runs a,b` names them, `--last N` sets how many runs are compared. Capture
+the steps again after applying: the capture records the ignored regions.

package/skills/kaloko/reference/mcp.md

@@ -23,7 +23,7 @@ file.
 | Tool | Use it for |
 |---|---|
 | `list_runs` | published runs, newest first; filters `scenario`, `project`, `verdict`, `author`, `environment`, `branch`, `limit` |
-| `get_run_summary` | one run: statuses per step and locale, criteria that need attention with evidence, screenshot URLs, verdict, baseline, canvas URL, open feedback |
+| `get_run_summary` | one run: statuses per step and locale, criteria that need attention with evidence (semantic ones with score and the evaluator's one-sentence `reason` per locale and viewport), regions ignored in pixel diffs and regions seen moving (`ignored_regions`, `unstable_regions`), screenshot URLs, verdict, baseline, canvas URL, open feedback |
 | `get_feedback` | run verdict with note, approved steps, unresolved rejections and comments, failed manual criteria (`run_id`, or `scenario` for its latest run) |
 | `list_notifications` | the token owner's inbox (`unread_only`, `limit`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
@@ -65,6 +65,8 @@ The same data and permissions as the REST API; each tool is its REST route.
 |---|---|
 | `get_draft` | which revision each step shows, step status, who changed it (person or agent) |
 | `get_step` | the handoff: live files, signed entry URL, token set, page structure, open comments (`ref`: draft, design, vN, run id) |
+| `get_step_spec` | what to build for a step as approved: elements with role, name and selector, styles mapped to tokens, states, contrast (`ref`: design by default, draft, vN, run id; `format` text or json) |
+| `get_step_drift` | how an implementation run (`run`: id or `latest`) differs from the design reference, per element: expected token against the actual value |
 | `get_step_history` | versions, and revisions of a step with authors |
 | `list_step_changes` | steps that differ between two references (default design reference → draft) |
 | `get_references`, `get_tokens` | design reference and baseline; the project's token set |

package/src/cli.mjs

@@ -17,7 +17,8 @@ import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher, gateFo
 import { configureGate } from './lib/linkcheck.mjs'
 import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
-import { buildManifest, writePreview } from './lib/build.mjs'
+import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
+import { stabilityCmd } from './lib/stability.mjs'
 import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote } from './lib/util.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
@@ -35,6 +36,7 @@ import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
+import { specCmd, driftCmd } from './lib/spec-cli.mjs'
 import { walkDesign, syncDesign, publishVersion, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
@@ -101,6 +103,8 @@ Run
                                     verdicts and what failed (--no-evaluate skips that; kaloko evaluate redoes it)
        [--items a,b] [--limit N]    Stack steps (kind: stack, many pages of one template): only pages whose id or
                                     path contains a, b; at most N pages (default items.limit, 500)
+       [--stability N]              Take N screenshots of each capture a moment apart and note regions that move
+                                    (clocks, carousels); kaloko stability turns them into ignore suggestions
   status                            Show what the current run has captured
                                     Scenarios may declare "sessions" (people in the flow); walk keeps one browser context per session and locale
 
@@ -143,6 +147,10 @@ Results
                                     Newest capture of every step as steps/<step>/<locale>/<viewport>.<ext> plus
                                     index.json (documentation layer, Business plan); unchanged files are skipped
   public [--run id] [--off]         Make a shared run readable without sign-in (admin; testers may refresh an already public scenario)
+  stability [--last 4 | --runs a,b] [--same-commit] [--apply] [--json]
+                                    Regions that change on every run or move while the page is idle (clocks, ads,
+                                    carousels): ignore suggestions per step in <run>/stability.yml; --apply adds
+                                    them to the scenario (ignore:), and pixel diffs then skip them
   compare [--run id] [--baseline id | --design] [--json]
                                     Text diff of two runs: step statuses, criterion verdicts, scores and evidence
                                     (default: current run against the scenario baseline, else the previous run)
@@ -160,6 +168,12 @@ Design (environments with kind: design; live HTML steps in a folder)
   share [--name <text>] [--branch b]  Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged"
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
+  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]
+                                    What to build for a step as approved: elements with role, name and selector, styles
+                                    mapped to DTCG tokens (or the nearest one), :hover/:focus/:active/:disabled, contrast
+  drift [step] [--ref design|vN] [--remote <run id|latest>] [--json]
+                                    How this implementation run differs from the approved design (expected token vs actual
+                                    value, raw values, missing elements and states); exit code 1 when something differs
   reference [--scenario id] (--design|--baseline) (--run id|--version n|--off) [--branch b]
                                     Show or set the design reference (accepted version) and the baseline
   tokens pull|push|check|validate [--project p] [--file tokens.json|tokens.resolver.json] [--mode m] [--json]
@@ -704,7 +718,7 @@ const commands = {
         return
       }
       const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
-      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null })
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
@@ -828,7 +842,7 @@ const commands = {
               // the automatic capture runs unless this script invocation captured the step itself: a crop is an
               // attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
               let captured = false
-              const capture = (opts = {}) => { captured = true; return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {} }).then((r) => { prefetch?.add(r, run.dir); return r }) }
+              const capture = (opts = {}) => { captured = true; return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); return r }) }
               await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
               if (!captured) await capture()
               say(`✓ ${node.id} ${locale}`)
@@ -949,6 +963,7 @@ const commands = {
     const report = await evaluateRun({ run, scenario, config, root })
     const via = report.via.qawalk ? ` via Kaloko${report.hosted?.limit != null ? ` (${report.hosted.questions} of ${report.hosted.limit} questions this month)` : ''}` : report.via['own-key'] ? ' with your key' : ''
     say(`Evaluated ${report.evaluated} capture(s); semantic evaluator ${report.model}${via}: ${report.semantic_calls} call(s), ${report.semantic_cached} cached.`)
+    if (report.vision?.asked) say(`Vision evaluator ${report.vision.model}: ${report.vision.asked} capture(s) with flagged or uncertain criteria, ${report.vision.calls} call(s), ${report.vision.cached} cached${report.vision.skipped.length ? `; not asked: ${[...new Set(report.vision.skipped.map((x) => x.split(': ').slice(1).join(': ')))].slice(0, 2).join('; ')}` : ''}.`)
     if (report.skipped.length) {
       // one line per reason: "12 captures: TYPESAFE_API_KEY is not set …"
       const byReason = new Map()
@@ -964,9 +979,15 @@ const commands = {
     const file = await writePreview({ run, manifest })
     const s = manifest.summary
     say(`${manifest.id}: ${s.pass} pass · ${s.partial} partial · ${s.fail} fail · ${s.skip} not checked\nPreview: ${file}`)
+    const why = attentionLines(manifest); if (why.length) say(`AI verdicts to act on (score and why):\n${why.join('\n')}`)
     return file
   },
 
+  async stability (args) {
+    const { config, root, run, scenario } = await runContext(args)
+    await stabilityCmd({ root, config, run, scenario, args, say })
+  },
+
   async preview (args) {
     const file = await commands.build(args)
     say(pathToFileURL(file).href)
@@ -989,7 +1010,7 @@ const commands = {
     await writePreview({ run, manifest })
     const files = new Set()
     for (const n of manifest.nodes) {
-      for (const byVp of Object.values(n.captures || {})) for (const c of Object.values(byVp)) [c.image || c.png, c.thumb, c.html, c.eval, c.tree].filter(Boolean).forEach((p) => files.add(p))
+      for (const byVp of Object.values(n.captures || {})) for (const c of Object.values(byVp)) [c.image || c.png, c.thumb, c.html, c.eval, c.tree, c.spec].filter(Boolean).forEach((p) => files.add(p))
       for (const a of n.attachments || []) files.add(a.file)
       // stack steps: the items index and every page's files
       if (n.stack?.items) {
@@ -1097,6 +1118,25 @@ const commands = {
     await historyCmd({ config, scenarioId, client: service(config), args, say })
   },
 
+  async spec (args) {
+    const { config, root } = await context(args)
+    let run = null
+    try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
+    const scenario = run ? await loadScenario(resolve(root, run.meta.scenario_file)).catch(() => null) : typeof args.scenario === 'string' && /\.ya?ml$/.test(args.scenario) ? await loadScenario(resolve(args.scenario)) : null
+    const scenarioId = await scenarioIdOf(args, config, root)
+    let client = null
+    if (!args.local) { try { client = service(config) } catch (e) { if (!run) throw e } }
+    await specCmd({ config, client, run, scenario, scenarioId, args, say })
+  },
+
+  async drift (args) {
+    const { config, root } = await context(args)
+    let run = null
+    try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
+    const scenarioId = await scenarioIdOf(args, config, root)
+    await driftCmd({ config, client: service(config), run, scenarioId, args, say })
+  },
+
   async reference (args) {
     const { config, root } = await context(args)
     const scenarioId = await scenarioIdOf(args, config, root)