kaloko 0.14.0 → 0.15.0

package/skills/kaloko/reference/acceptance.md

@@ -39,28 +39,35 @@ sharpen each purpose and add the criteria the page must really meet.
 ## Check packs
 
 `packs: [seo]` or `packs: [seo, usability]` on a node adds a fixed set of
-criteria (ids `AC1xx` for `seo`, `AC2xx` for `usability`) at load time:
+health checks (ids `HC1xx` for `seo`, `HC2xx` for `usability`; acceptance
+criteria are `AC`, health checks `HC`, and the number is the check's: the
+same check kept in acceptance or adopted is `AC103` for `HC103`) at load time:
 `seo` checks one H1, title and description length, canonical, hreflang for
 every locale, Open Graph, indexing, viewport, `html lang`, overflow and
 console; `usability` checks unlabeled inputs and link texts and asks the
-evaluator questions that fit the step's page type. A node's own criterion with the
-same id wins. Pack criteria are marked `pack` on the canvas and do not count
-as drift in `--coverage`; the plan may still mention them by id. Use packs
-for public pages and landings; task flows keep their own criteria.
+evaluator questions that fit the step's page type. Pack checks are health,
+not acceptance: they are evaluated on every walk but never decide a step's
+verdict (see [evaluation.md#health](evaluation.md#health)). The `design` pack
+always counts for acceptance; `health: { acceptance: [seo] }` on the scenario
+keeps another pack in acceptance, which only the person decides. A node's own
+criterion with the same id wins and counts for acceptance (that is what
+`kaloko health adopt` writes). Pack checks do not count as drift in
+`--coverage`; the plan lists only what the brief asks for. Use packs for
+public pages and landings; task flows keep their own criteria.
 
 Set `page` on every step (or once on the scenario) so the usability pack
 asks the right questions:
 
 | `page` | for | asks |
 | --- | --- | --- |
-| `landing` | public and marketing pages | purpose in the first screen (`AC201`), exactly one primary call to action (`AC202`) |
-| `work` | app screens where people work: overview, canvas, detail, inbox item | the heading says what the screen is for (`AC205`) |
-| `list` | lists and tables: runs, projects, inbox | `AC205`, each item says what it is and how to open it (`AC207`) |
-| `settings` | settings, billing, tokens | `AC205`, each setting says what it changes and how it is saved (`AC208`) |
-| `form` | sign-up, sign-in, a form to fill in | `AC205`, how to send it and what happens next (`AC206`) |
-| `doc` | documentation, guides, terms | `AC201`, headings and short paragraphs (`AC209`) |
-
-Every type also gets `AC203` and `AC204`. Without `page` a step with the
+| `landing` | public and marketing pages | purpose in the first screen (`HC201`), exactly one primary call to action (`HC202`) |
+| `work` | app screens where people work: overview, canvas, detail, inbox item | the heading says what the screen is for (`HC205`) |
+| `list` | lists and tables: runs, projects, inbox | `HC205`, each item says what it is and how to open it (`HC207`) |
+| `settings` | settings, billing, tokens | `HC205`, each setting says what it changes and how it is saved (`HC208`) |
+| `form` | sign-up, sign-in, a form to fill in | `HC205`, how to send it and what happens next (`HC206`) |
+| `doc` | documentation, guides, terms | `HC201`, headings and short paragraphs (`HC209`) |
+
+Every type also gets `HC203` and `HC204`. Without `page` a step with the
 `seo` pack, or any step of a scenario allowed on production, is `landing`;
 everything else is `work`. Do not put `landing` on signed-in screens: "one
 primary call to action" is a marketing rule, and a work screen rightly offers
@@ -78,34 +85,35 @@ When a scenario walks several locales, a text check (`text_matches`,
 reads in one language only (it looks for diacritics and common Czech or
 English words; one plain word such as a brand name is left alone).
 
-- `a11y` (`AC3xx`): images with alt, links and buttons with a name, labelled
+- `a11y` (`HC3xx`): images with alt, links and buttons with a name, labelled
   fields, heading levels not skipped, WCAG AA text contrast, a `main`
-  landmark, unique ids (`AC301`–`AC307`, read from the page). After the
-  screenshot the walk also presses Tab through the page: `AC308` tab order
+  landmark, unique ids (`HC301`–`HC307`, read from the page). After the
+  screenshot the walk also presses Tab through the page: `HC308` 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,
+  mouse-only), `HC309` visible focus with at least 3 : 1 contrast (each stop
+  screenshotted focused and unfocused), `HC310` no keyboard trap (a modal
+  dialog may keep focus), `HC311` a skip link or main content within three
+  stops, `HC312` names from Chrome's accessibility tree (what a screen
+  reader announces). `HC313` landmarks (one `main`, labelled repeats) and
+  `HC314` 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,
+- `perf` (`HC4xx`): 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).
-  Override a limit with an own criterion of the same id, e.g.
+  Override a limit with an own criterion with the check's number as an AC
+  id (`AC401` for `HC401`), e.g.
   `{ id: AC401, text: LCP within 4 s, check: { type: deterministic, assert: perf_lcp, max: 4000 } }`.
-- `console` (`AC501`): the evaluator reads the step's console errors with its
+- `console` (`HC501`): the evaluator reads the step's console errors with its
   purpose and decides whether they touch what the step accepts (pass: only
   third-party noise; needs review: unsure; fail: relevant). Without errors it
   passes without a call. Keep `no_console_errors` where any error must fail.
 
-- `errors` (`AC6xx`) is for error pages. It checks:
+- `errors` (`HC6xx`) is for error pages. It checks:
   - a real 4xx/5xx status (a "soft 404" answering 200 fails);
   - a link to the home page and navigation or search;
   - no stack trace, SQL error or framework debug page;
@@ -120,7 +128,7 @@ step with `packs: [errors]`:
 - **404:** use `path: /no-such-page-{random}`. `{random}` becomes a new
   token on every walk, so no cache or an accidentally created page makes it
   pass. `kaloko draft` adds this step on its own.
-- **Exact status:** override AC601, for example
+- **Exact status:** override HC601 with your own AC601, for example
   `{ id: AC601, text: Answers 410, check: { type: deterministic, assert: http_status, value: 410 } }`.
   `http_status` also takes `min`/`max`; the default is 200–299.
 - **Every step:** each capture records the document's HTTP status. The
@@ -192,7 +200,8 @@ When the work has a repository and an issue number, make them visible:
 - scenario `id` carries the ticket (`TASK-1273-club-activation`, `WEB-12-checkout`); the CLI derives the issue number from it or from the branch (`feat/1273-…`) and links it to the repository's origin (`acme/shop#1273`);
 - set `issue: { number, repo?, url? }` explicitly when the id or branch cannot carry it (for example a Plane item);
 - the project is the repository name unless `project:` in `kaloko.config.yml` says otherwise; a single flow may sort itself elsewhere with `project: <slug>` in its scenario (optional). Projects are records of the organization: `kaloko projects` or MCP `list_projects` show the slugs to use; admins create them in Settings → Projects or assign a scenario in the overview, which wins over the scenario file;
-- the canvas header, the organization overview and `kaloko feedback` show `repo#number · title`, so name the scenario `title` for humans, not for the ticket.
+- the canvas header, the organization overview and `kaloko feedback` show `repo#number · title`, so name the scenario `title` for humans, not for the ticket;
+- requirement IDs from the team's tracker or QMS go into `refs:` on the scenario, a step or a criterion (`refs: [URS-12, FS-3.4]`, free text, never invented); they flow into the acceptance record and the trace matrix ([evidence.md](evidence.md)).
 
 ## Session and consent
 

package/skills/kaloko/reference/apps.md

@@ -216,7 +216,7 @@ dialog, webview and group.
   - `app_no_truncation`: texts ending in "…";
   - `app_no_crash`: FATAL EXCEPTION or ANR in logcat, a "keeps stopping"
     dialog, or the iOS app no longer running.
-- **Pack `app` (AC7xx):** those four checks, plus a semantic question about
+- **Pack `app` (HC7xx):** those four checks, plus a semantic question about
   the screen's purpose and next action.
 - **Web-only checks** (`no_overflow`, `http_status`, meta, `a11y_contrast`,
   `perf_*`, `url_*`, `style_*`, `js_equals`): these are "not evaluated" on

package/skills/kaloko/reference/design.md

@@ -353,7 +353,8 @@ Turn on `packs: [design]` (usually `[design, a11y]`) for the steps in the implem
 | AC802 | structure: headings, landmarks, actions and form fields as in the reference |
 | AC803 | tokens: authored colors, fonts, sizes, spacing and radii come from the token set |
 
-Contrast and the other accessibility basics come from the `a11y` pack: `packs: [design, a11y]`.
+The design checks count for acceptance. Contrast and the other accessibility basics come from the `a11y` pack
+(`packs: [design, a11y]`) as health: advisory, reported apart (see [evaluation.md#health](evaluation.md#health)).
 
 `kaloko evaluate` fetches the design reference (of the design branch linked to the git branch, if any) and
 fills the checks. Findings name what differs and the token to use; fix the implementation, not the reference.

package/skills/kaloko/reference/evaluation.md

@@ -68,6 +68,46 @@ evaluators:
 Report the reason with each `needs_review` or failing criterion; when the
 evaluator saw the screenshot, say so.
 
+## Health
+
+The checks of packs (`seo`, `a11y`, `perf`, `usability`, `console`,
+`errors`, `app`) are the run's **health** (CS *kondice*): advisory, stored in
+`node.health` and `summary.health` of `run.json`, never in `criteria`. They
+do not change a step's status, the run verdict, the review queue, carried
+approvals, required approvers, the acceptance record or exit codes. The
+`design` pack and packs listed in `health.acceptance` stay acceptance
+criteria. Runs shared before the split keep their stored verdicts; their pack
+criteria show as health.
+
+- **Check it before you hand over.** `kaloko walk` and `kaloko evaluate`
+  print one health line; `kaloko health` lists the findings by pack with
+  severity (error: people or search engines are shut out; warning: the rest;
+  info: the evaluator was unsure), what is new or fixed since the previous run
+  of the scenario, and a fix for each check. `--json` for the structure,
+  `--remote` (or MCP `get_health`) for a shared run.
+- **Fix what your change can fix**, walk the step again and check that the
+  finding is gone. Leave the rest and say so.
+- **Never hide health.** Do not remove a pack, raise a limit, narrow a
+  selector or add `environments:` to make a finding disappear. A limit or a
+  check that does not fit the project is the person's call; name it in the
+  report.
+- **Ids.** Health checks are `HC<n>` (`home:HC103`), acceptance criteria
+  `AC<n>`. Runs from before 7 Oct 2026 say `AC103` for the health check;
+  read it as `HC103`, and both ids work in commands and MCP.
+- **Adopting is the team's decision.** `kaloko health adopt <step>:<check>
+  [--text "…"]` writes the check into the scenario as an acceptance
+  criterion of the step (`home:HC103` becomes `AC103` with `from: HC103`),
+  so it counts for acceptance from the next walk. Do it only when
+  the person asks. Checks people adopted on the canvas (or through
+  `adopt_health_check`) wait on the service until `kaloko health pull` writes
+  them into the scenario; pulling them is routine, then walk those steps.
+- **Report it apart from the verdicts**: "Health: 2 errors (1 new), 5
+  warnings; fixed HC108 on home". Never present a health finding as a
+  failing criterion, or a clean health as acceptance.
+- `kaloko health --fail-on error` exits 1 on errors; use it in CI only where
+  the team asked for that gate. Hosted runs and CI runs alert on new errors
+  by themselves (inbox, mail, channels, webhook `health.worse`).
+
 ## Triage findings (experimental)
 
 When the organization switched the experiment on, `kaloko evaluate` also asks
@@ -111,7 +151,8 @@ turns them off; they do not count against the hosted allowance.
 
 After `kaloko build`, report: the summary line, each failing or
 `needs_review` criterion with step, locale, viewport and evidence, blocked
-requests if any, and the preview path. Do not claim a criterion passed when
+requests if any, the health counts (apart from the verdicts), and the preview
+path. Do not claim a criterion passed when
 it was not evaluated.
 
 `needs_review` is not a failure: look at the screenshot and state your

package/skills/kaloko/reference/evidence.md

@@ -0,0 +1,80 @@
+# Evidence for your own documentation (regulated work)
+
+Use this when a team's own repository turns Kaloko runs into its documents: test protocols, reports, trace
+matrices, release summaries for a quality system. Kaloko provides the evidence and a way to check it; the team's
+own templates and skills write the documents. Kaloko never formats anything for a particular QMS, and you do not put
+the team's SOP structure into Kaloko.
+
+The background for people (what a record proves, the two signing paths, known gaps) is in Kaloko's help, page
+*Kaloko in regulated work (GxP)*. Evidence is a Business feature.
+
+## The contract
+
+Everything below is `qawalk.evidence.v1` (`schemas/evidence.v1.json` in the `kaloko` package, every field
+described). Within v1 fields are only added; read the fields you need and ignore the rest.
+
+- `acceptance`: `none`, `accepted` or `returned`. Write your document from this field, never from the presence of
+  others.
+- `signing`: `in_kaloko` when a signature made in Kaloko stands, `none` otherwise. With `none` the approval, if any,
+  is signed elsewhere; your document says so ("executed in Kaloko; approval recorded in <your eQMS>").
+- `record.sha256` and `record.kind` (`acceptance` or `execution`): the signed record the evidence came from. Put the
+  hash into your document so a reader can tie it to the package.
+- `scenario` (`version`, `file`, `sha256`, `refs`), `environment`, `git`, `tools` (CLI, Node.js, OS, browsers,
+  service version).
+- `steps[].criteria[]`: the criterion text as walked, `refs`, and `results[]` per locale and viewport with
+  `assessed_by` (`person`, `deterministic`, `ai`, `none`) and `assessor` (an e-mail or a model id). `advisory: true`
+  means an AI result no person decided: never present it as a person's verdict.
+- `steps[].decision`, `verdict`, `approvals`: people's decisions apart from tokens' and agents'
+  (`counts_as_person`).
+- `signatures[]` (name, e-mail, `signed_at`, `time_zone`, `local_time`, `meaning`, `auth`, `withdrawn`) and
+  `decision_changes[]` with reasons.
+- `audit[]`: the run's audit trail; `trace[]`: the trace matrix, one row per requirement, criterion, step, locale and
+  viewport (columns in `TRACE_COLUMNS` order, the same as `trace.csv`).
+- A release (`kind: release`) has `runs[]` (each a run evidence), `missing[]` with reasons and one `trace[]`.
+
+## Getting it
+
+```bash
+npx kaloko evidence <run-id> --json > evidence.json            # one run, any shared run
+npx kaloko evidence --release 2.4.0 --product lims --json > release.json
+npx kaloko evidence <run-id> --csv > trace.csv                 # the trace matrix only
+npx kaloko signoff <run-id> --package --out evidence/          # the signed zip, checked on download
+npx kaloko signoff --verify evidence/kaloko-evidence-<run-id>.zip   # check it again later, no token needed
+```
+
+Over the API with a read token: `GET /api/v1/orgs/<org>/runs/<id>/evidence`, `…/evidence.zip`, `…/trace.csv`,
+`…/audit.csv`, and `GET /api/v1/orgs/<org>/evidence?product=<p>&version=<v>`. Over MCP: `get_evidence` with `run_id`, or
+`product` and `version`.
+
+## When it is ready
+
+An organization admin adds a webhook with the event `evidence.ready` (Settings → Integrations → Webhooks). It fires
+when a run is shared, accepted or returned, and when a release is recorded or updated. It is signed like every Kaloko
+webhook (`Kaloko-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">`); check the signature and the age of `t`
+before you trust it. The body:
+
+```json
+{ "id": "evt_…", "type": "evidence.ready", "created_at": "2026-10-07T10:00:00.000Z", "org": "acme",
+  "data": { "kind": "run", "reason": "accepted", "run": { "id": "2026-10-07-batch-x1y2z3", "scenario": "BATCH", "environment": "validation", "project": "lims", "verdict": "accepted" },
+            "acceptance": "accepted", "signing": "none", "schema": "qawalk.evidence.v1",
+            "evidence_url": "https://kaloko.app/api/v1/orgs/acme/runs/…/evidence", "package_url": "…/evidence.zip", "trace_csv_url": "…/trace.csv" } }
+```
+
+The URLs need a token (`Authorization: Bearer …`); the webhook never carries the evidence itself.
+
+A neutral client-side job, for example a small service or a CI job triggered by the webhook:
+
+1. Check `Kaloko-Signature` with the webhook's secret; drop events older than five minutes.
+2. Download `package_url` with a read token into your own storage.
+3. Run `npx kaloko signoff --verify <zip>`; stop and alert on any failure.
+4. Read `evidence.json` from the zip and hand it to your generator with your templates.
+5. Store the generated document next to the package and the record's SHA-256; your eQMS takes it from there.
+
+## Rules for an agent
+
+- Never accept, approve or sign for a person. Tokens and agents cannot sign; where an organization signs in Kaloko,
+  only a person does, in the app.
+- Never present `advisory` results as decisions, and never drop the AI model name from a result.
+- Do not turn the signature policy on or off; that is an admin's decision in Settings → Security.
+- Add `refs:` to scenarios, steps and criteria when the team gives you requirement IDs; do not invent them.
+- Keep the package as you got it. To change anything, generate a new document; the package stays the evidence.

package/skills/kaloko/reference/integrations.md

@@ -34,7 +34,7 @@ Ask before filing issues in bulk; one issue per real problem, not per criterion.
 
 Slack and Teams channels are chosen per project by an admin, with the events
 each wants (new run, returned, accepted, comment, mention, release recorded,
-waiting for approval) and quiet hours. Nothing to do from the CLI: sharing,
+waiting for approval, health got worse) and quiet hours. Nothing to do from the CLI: sharing,
 returning and recording a release reach the right channels. Restricted projects
 reach only channels that name them.
 
@@ -72,6 +72,11 @@ kaloko schedule hook <id>       # URL + secret that start the run after a deploy
   script that only calls `page.goto`). Steps that click or type are left out and
   named in the answer. Criteria decided: `exists`, `absent`, `count`, `text_*`,
   `attr_*`, `title_matches`, `meta_matches`; the rest shows "not evaluated".
+- Health alerts: a hosted run (and a run shared from CI) compares its health
+  with the previous run of the scenario and alerts the followers, the channels
+  and the `health.worse` webhook on a new error-level finding. Each schedule
+  sets it to `error` (default), `warning` or `off` on kaloko.app or with
+  `kaloko schedule add --health-alert`; changing it is the person's call.
 - Does not work for: native apps, local or private addresses (localhost, IPs,
   `.local`), header credentials, base URLs per locale.
 - For those, or for the full walk on a schedule, write a GitHub Actions

package/skills/kaloko/reference/mcp.md

@@ -49,6 +49,8 @@ is null. Projects and products come complete, without pages.
 | `get_started` | where the organization stands (`empty`, `sample`, `active`), its sample run, the next steps and a prompt; call it in a new project, see [first-run.md](first-run.md) |
 | `add_sample_run` | adds the sample run (or returns the one there is); needs an upload or full token and the Developer / Tester role |
 | `search_screens` | the screen library: newest screenshot of every step across the organization's flows (`q` words matched against titles, ids, paths, URLs, page title and H1; `project`, `product`, `module`, `scenario`, `locale`, `viewport`, `device`, `status`, `environment`; `source: design` or `all` for design versions; `group: none` for every locale and viewport; `cursor` from `next`), each with a signed image and the canvas link |
+| `get_health` | the advisory health of a run (`run_id`), the newest run of a scenario (`scenario`) or the trend of a project (`project`): findings by severity, pack and step with evidence and a fix, and what is new or fixed since the previous run; never a verdict, see [evaluation.md#health](evaluation.md#health) |
+| `adopt_health_check` | turns a health check into an acceptance criterion of the scenario (`run_id`, `step`, `check` such as `HC103`, `text` to reword it; it becomes `AC103` with `from: HC103`); Developer / Tester role. Only when the person asks; `kaloko health pull` then writes it into the scenario file |
 | `get_affected_steps` | which steps of a scenario changed files reach, with the reason per step (`scenario`, `changed_files`, `run_id`, `upstream`); route files are matched against the step paths and URLs of the newest run. Imports and `affects:` globs need the repository: `kaloko affected` follows them |
 
 ## Comment tools
@@ -63,6 +65,7 @@ is null. Projects and products come complete, without pages.
 | `answer_finding` | answers a finding (`run_id`, `node`, `locale`, `viewport`, `finding`, `kind`, `answer`: right, wrong or comment with the `comment_id` from `add_comment`); scope comment |
 | `get_triage_report` | the organization's Clef numbers of the last 90 days (read-only): findings shown and answered, precision and calibration per kind, findings turned into comments, median hours to the first review with and without findings, triage requests per useful finding. Report them as they are; the go/no-go is a person's |
 | `get_signoff_record` | the signed acceptance record of an accepted run (Business): approvals with provenance, criteria, capture hashes, signature |
+| `get_evidence` | the evidence of a run (any shared run) or a release (Business, `qawalk.evidence.v1`): acceptance and signing state, criteria as walked with `refs`, who assessed each result (AI advisory), screenshots with SHA-256, decisions, signatures, audit trail, trace matrix ([evidence.md](evidence.md)) |
 | `resolve_comment` | close a thread with a `note` that says what changed (it becomes the last reply) |
 | `reopen_comment`, `edit_comment`, `delete_comment` | reopen; edit or delete your own comment |
 | `create_issue` | a Jira or Linear issue from a step (`run_id`, `step`, `to`: jira or linear, optional `criterion`, `title`, `note`, `locale`, `viewport`, `target`): screenshot, criterion, notes and a link back; the step's thread resolves when the issue is done. Developer / Tester, scope comment; see [integrations.md](integrations.md) |

package/skills/kaloko/reference/stacks.md

@@ -29,7 +29,7 @@ step script only to prepare each page, for example to dismiss a dialog
   kind: stack
   title: Magazine articles
   purpose: Every article reads well and is findable.
-  packs: [seo]                              # the pack criteria apply to every page
+  packs: [seo]                              # health checks of every page (advisory)
   items:
     sitemap: /sitemap.xml                   # or urls / file / crawl / script (exactly one)
     match: '^/clanky/'                      # regex on the path with its query; exclude: '…' drops pages

package/src/cli.mjs

@@ -19,7 +19,7 @@ import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
 import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
-import { signoffCmd } from './lib/signoff.mjs'
+import { signoffCmd, evidenceCmd } from './lib/signoff.mjs'
 import { localized, readJson, UserError, UsageError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG, EXIT, parseDuration } from './lib/util.mjs'
 import { noteLegacy, legacyHint, resetLegacy, legacyInUse } from './lib/legacy.mjs'
 import { packageRoot } from './lib/schema.mjs'
@@ -35,6 +35,7 @@ import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
 import { expandPacks } from './lib/packs.mjs'
 import { upsertPrComment } from './lib/pr.mjs'
 import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
+import { healthCmd } from './lib/health.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
 import { parseArgs, helpFor, checkOptions, closest } from './lib/cli-args.mjs'
@@ -235,6 +236,16 @@ Results
   review [--run id] [--scenario id] [--json]
                                     What a person still has to decide on a shared run (failed, unsure, changed, returned,
                                     commented steps), approvals carried over unchanged steps, and the review-mode link
+  health [--run id] [--scenario id] [--remote] [--fail-on error|warning] [--json]
+                                    Health of a run, advisory and never part of a verdict: the checks of packs (SEO,
+                                    accessibility, performance, usability, console, error pages) by severity and pack,
+                                    and what is new or fixed since the previous run of the scenario (the current local
+                                    run; --remote, a shared run id or --scenario ask kaloko.app); --fail-on exits 1
+                                    when there are findings at that level
+  health adopt <step>:<check> [--text "…"]
+                                    Make a health check an acceptance criterion of the step in the scenario file, as is
+                                    or with your text; it counts for the step's verdict from the next walk
+  health pull [--scenario id]       Write the checks people adopted on kaloko.app into the scenario file
   comment [--step id | --flow] --note "…" [--status rejected|approved] [--run id] [--scenario id]
   comment --reply|--resolve|--reopen|--edit|--delete <id> [--note "…"] [--flow]
                                     Comment, answer and close feedback from the CLI (resolve with "Fixed in <commit>")
@@ -274,8 +285,18 @@ Results
                                     The signed acceptance record of an accepted run (Business): JSON and PDF with who
                                     approved what and when, criteria results and capture hashes, checked against the
                                     service's public key
-  signoff --verify <file.json|file.pdf> [--key file|url] [--json]
-                                    Check a record someone handed over (no token needed); exit 1 when it does not verify
+  signoff <run-id> --package [--out dir] [--lang cs|en] [--json]
+                                    The evidence package of any shared run, accepted or not (Business): the signed
+                                    record (JSON, PDF), evidence.json, the trace matrix (CSV, JSON), the audit trail,
+                                    the screenshots and a signed MANIFEST.json; checked after download
+  signoff --verify <file.json|file.pdf|file.zip> [--key file|url] [--json]
+                                    Check a record or an evidence package someone handed over (no token needed); exit 1
+                                    when it does not verify
+  evidence <run-id> [--csv] [--out file] [--json]
+  evidence --release <version> [--product p] [--csv] [--out file] [--json]
+                                    The evidence of a run or a release (Business, schema qawalk.evidence.v1): acceptance
+                                    and signing state, criteria as walked with requirement refs, results, screenshots
+                                    with SHA-256, decisions, signatures, audit trail; --csv prints the trace matrix
   stability --pull [--scenario id] [--json]
                                     Regions people drew on screenshots on kaloko.app (step detail → Mark a changing
                                     region) go into the scenario's ignore: of their steps; walk them again after
@@ -296,9 +317,12 @@ Jira and Linear (connected by an admin in Settings → Integrations)
 
 Hosted runs (read-only scenarios on Kaloko's browsers, Business plan)
   schedule add --scenario <file> --env <name> [--every day|week|manual] [--at 5] [--weekday mon] [--account key]
+       [--health-alert off|error|warning]
                                     Kaloko opens the scenario's pages every day or week (hour in UTC) and shares the
                                     run as you: public pages, HTTP Basic from the environment, or a saved session
-                                    (--account). Steps that click or type are left out; they need the full walk
+                                    (--account). Steps that click or type are left out; they need the full walk.
+                                    When a walk's health is worse than the previous one, the team hears about it:
+                                    new errors (default), new errors or warnings, or off
   schedule list | run <id> | pause <id> | resume <id> | remove <id> [--json]
   schedule hook <id> [--remove] [--json]
                                     A URL and secret that start the hosted run from a deploy (Vercel, Netlify) or
@@ -424,7 +448,9 @@ async function walkVerdicts ({ prefetch, run, scenario, config, root }) {
   const t0 = Date.now()
   await prefetch.done()
   const report = await evaluateRun({ run, scenario, config, root })
-  const fails = report.findings.filter((f) => f.verdict === 'fail'); const unsure = report.findings.filter((f) => f.verdict === 'needs_review')
+  // health checks (advisory) are counted apart; they never make a step fail
+  const health = report.findings.filter((f) => f.health); const accept = report.findings.filter((f) => !f.health)
+  const fails = accept.filter((f) => f.verdict === 'fail'); const unsure = accept.filter((f) => f.verdict === 'needs_review')
   say(`\nEvaluated ${report.evaluated} capture(s) in ${Math.round((Date.now() - t0) / 100) / 10} s: ${fails.length ? `${fails.length} failing` : 'nothing failing'}${unsure.length ? `, ${unsure.length} for a person to look at` : ''}.`)
   const line = (f) => `${f.node}${f.item ? `/${f.item}` : ''} ${f.locale}/${f.viewport} ${f.id}${f.why ? `: ${String(f.why).slice(0, 140)}` : ''}`
   // pack criteria say how to fix them; a fix repeated across steps and locales is printed once
@@ -433,6 +459,16 @@ async function walkVerdicts ({ prefetch, run, scenario, config, root }) {
   if (fails.length) say(`  ✕ ${fails.slice(0, 15).map(withFix).join('\n  ✕ ')}${fails.length > 15 ? `\n  … ${fails.length - 15} more (kaloko build lists them all)` : ''}`)
   if (unsure.length) say(`  ? ${unsure.slice(0, 8).map(line).join('\n  ? ')}${unsure.length > 8 ? `\n  … ${unsure.length - 8} more` : ''}`)
   if (report.skipped.length) say(`  Semantic criteria not evaluated: ${[...new Set(report.skipped.map((x) => x.split(': ').slice(1).join(': ')))].slice(0, 2).join('; ')}`)
+  if (health.length) say(healthLine(health))
+}
+
+/** One line on the health findings of an evaluation: counts by severity (one per check and step), never a verdict. */
+function healthLine (findings) {
+  const worst = new Map()
+  const rank = { error: 3, warning: 2, info: 1 }
+  for (const f of findings) { const k = `${f.node}:${f.id}`; if ((rank[f.severity] || 0) > (rank[worst.get(k)] || 0)) worst.set(k, f.severity) }
+  const n = (s) => [...worst.values()].filter((x) => x === s).length
+  return `Health (advisory, not part of any verdict): ${n('error')} error(s), ${n('warning')} warning(s)${n('info') ? `, ${n('info')} unsure` : ''}. Fix what you can before review; kaloko health lists them.`
 }
 
 const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : null)
@@ -1842,11 +1878,12 @@ const commands = {
       for (const x of report.skipped) { const [where, ...why] = x.split(': '); const k = why.join(': '); byReason.set(k, [...(byReason.get(k) || []), where]) }
       say(`Semantic criteria not evaluated:\n  - ${[...byReason].slice(0, 8).map(([why, where]) => `${where.length > 1 ? `${where.length} captures (${where.slice(0, 3).join(', ')}${where.length > 3 ? ', …' : ''})` : where[0]}: ${why}`).join('\n  - ')}`)
     }
+    if ((report.findings || []).some((f) => f.health)) say(healthLine(report.findings.filter((f) => f.health)))
     if (report.outdated.length) say(`Criteria changed after capture of ${report.outdated.join(', ')}: not evaluated. Run "kaloko evaluate --recheck --steps ${report.outdated.join(',')}": it rechecks the stored captures against the new criteria, deterministic and semantic, without walking again.`)
     // --json: the counts and every verdict a person or agent has to act on (fail, needs_review)
     if (args.json) {
       const pick = (f) => ({ step: f.node, ...(f.item ? { item: f.item } : {}), locale: f.locale, viewport: f.viewport, criterion: f.id, verdict: f.verdict, why: f.why || null, fix: f.fix || null })
-      say(JSON.stringify({ run: run.meta.id, evaluated: report.evaluated, semantic: { model: report.model, calls: report.semantic_calls, cached: report.semantic_cached, via: report.via.qawalk ? 'kaloko' : report.via['own-key'] ? 'own-key' : null }, vision: report.vision || null, triage: report.triage || null, findings: (report.findings || []).filter((f) => f.verdict === 'fail' || f.verdict === 'needs_review').map(pick), skipped: report.skipped, outdated: report.outdated }, null, 2))
+      say(JSON.stringify({ run: run.meta.id, evaluated: report.evaluated, semantic: { model: report.model, calls: report.semantic_calls, cached: report.semantic_cached, via: report.via.qawalk ? 'kaloko' : report.via['own-key'] ? 'own-key' : null }, vision: report.vision || null, triage: report.triage || null, findings: (report.findings || []).filter((f) => !f.health && (f.verdict === 'fail' || f.verdict === 'needs_review')).map(pick), health: (report.findings || []).filter((f) => f.health).map((f) => ({ ...pick(f), pack: f.pack, severity: f.severity })), skipped: report.skipped, outdated: report.outdated }, null, 2))
     }
   },
 
@@ -1858,7 +1895,7 @@ const commands = {
     const why = attentionLines(manifest)
     // --json: the run id, its summary, the preview file and the AI verdicts to act on
     if (args.json) { say(JSON.stringify({ run: manifest.id, summary: s, preview: file, manifest: join(run.dir, 'run.json'), attention: why.map((l) => l.trim()) }, null, 2)); return file }
-    say(`${manifest.id}: ${s.pass} pass · ${s.partial} partial · ${s.fail} fail · ${s.skip} not checked\nPreview: ${file}`)
+    say(`${manifest.id}: ${s.pass} pass · ${s.partial} partial · ${s.fail} fail · ${s.skip} not checked${s.health ? `\nHealth (advisory): ${s.health.error} error(s), ${s.health.warning} warning(s) in ${s.health.checks} checks (kaloko health)` : ''}\nPreview: ${file}`)
     if (why.length) say(`AI verdicts to act on (score and why):\n${why.join('\n')}`)
     return file
   },
@@ -2099,6 +2136,9 @@ const commands = {
     // how many steps still wait for a person (review mode); an older service answers 404 and the line is left out
     const queue = await client.request('GET', `/orgs/${config.org}/review-queue?run=${encodeURIComponent(data.run.id)}`).catch(() => null)
     if (queue?.counts) say(`  review: ${queue.counts.pending} of ${queue.counts.queue} step(s) wait for a person${queue.counts.carried ? `, ${queue.counts.carried} unchanged kept their approval` : ''} (kaloko review; review mode: ${queue.review_url})`)
+    // health checks people adopted into acceptance on kaloko.app (an older service leaves the field out)
+    const adopted = data.health_adoptions || []
+    if (adopted.length) say(`  adopted into acceptance, not in the scenario file yet (kaloko health pull writes them):\n${adopted.map((a) => `    + ${a.step}:${a.check} "${a.text}" — ${a.created_by}${a.created_via === 'agent' ? ' (agent)' : ''}`).join('\n')}`)
     if (!data.items.length && !flow.length) { say('  No open rejections or comments.'); return }
     // returned steps first: a reviewer said what should change
     const returned = data.items.filter((r) => r.status === 'rejected')
@@ -2141,10 +2181,30 @@ const commands = {
     const { config, root } = await context(args)
     let runId = args._[0] || (typeof args.run === 'string' ? args.run : null)
     if (!runId) { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
-    if (!runId) throw new UsageError('Usage: kaloko signoff <run-id> [--out dir] | kaloko signoff --verify <file.json|file.pdf>')
+    if (!runId) throw new UsageError('Usage: kaloko signoff <run-id> [--package] [--out dir] | kaloko signoff --verify <file.json|file.pdf|file.zip>')
     return signoffCmd({ config, args, say, client: service(config), runId })
   },
 
+  /** The evidence of a run or a release (qawalk.evidence.v1) for a client's own generator. */
+  async evidence (args) {
+    const { config, root } = await context(args)
+    let runId = args._[0] || (typeof args.run === 'string' ? args.run : null)
+    if (!runId && typeof args.release !== 'string') { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
+    return evidenceCmd({ config, args, say, client: service(config), runId })
+  },
+
+  /** Health (theme K): advisory checks of the packs, adopting one into acceptance, pulling adoptions (health.mjs). */
+  async health (args) {
+    return healthCmd({
+      args, say,
+      deps: {
+        context, runContext, buildManifest, service,
+        localRunExists: async (a) => { try { const { root, config } = await context(a); await resolveRun({ root, output: config.output, run: a.run }); return true } catch { return false } },
+        sharedRunId: async (a) => { const { root, config } = await context(a); const r = await resolveRun({ root, output: config.output }); if (!r.meta.shared) throw new UserError('The current run is not shared yet: run kaloko health without --remote for the local one, or kaloko share first.'); return r.meta.id }
+      }
+    })
+  },
+
   async review (args) {
     const { config, root } = await context(args)
     const client = service(config)

package/src/lib/build.mjs

@@ -25,7 +25,7 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
   const mailKeys = viewportNames.filter((k) => variantOf(meta.scope, k).browser === 'chromium')
   const nodes = []
   for (const node of scenario.nodes) {
-    if (node.kind === 'stack') { const p = pos.get(node.id); nodes.push(await buildStack({ run, node, base: { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: p.col, lane: p.lane }, captures, attachments })); continue }
+    if (node.kind === 'stack') { const p = pos.get(node.id); nodes.push(await buildStack({ run, node, base: { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: p.col, lane: p.lane, ...(node.refs?.length ? { refs: node.refs } : {}) }, captures, attachments })); continue }
     const caps = []
     // pages of a stack live in its items index; normal steps take their own captures only
     for (const c of captures.filter((x) => x.node === node.id && !x.item)) {
@@ -74,6 +74,8 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
     app_version: meta.app_version ?? meta.version ?? null,
     environment: meta.environment,
     executor: meta.executor,
+    // what walked it: the CLI, Node.js, the OS and the browser engines seen in the captures (acceptance records)
+    tools: toolsOf(meta, nodes),
     started_at: meta.started_at,
     finished_at: new Date().toISOString(),
     scope: meta.scope,
@@ -91,6 +93,13 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
   }
 }
 
+/** The tools of a run: kaloko and its version, Node.js, the OS, and every browser version a capture reports. */
+export function toolsOf (meta, nodes) {
+  const browsers = new Set()
+  for (const n of nodes) for (const vps of Object.values(n.captures || {})) for (const c of Object.values(vps || {})) if (c?.browser_version) browsers.add(c.browser_version)
+  return { cli: meta.tools?.cli || { name: 'kaloko', version: null }, node: meta.tools?.node || process.version, os: meta.tools?.os || `${process.platform} ${process.arch}`, browsers: [...browsers].sort() }
+}
+
 /** The recording entry of a sidecar as the manifest carries it: file paths, duration, size, markers. */
 async function recEntry (run, e) {
   const r = await readJson(join(run.dir, e.file), null)

package/src/lib/capture.mjs

@@ -11,6 +11,11 @@ import { maskSpec, maskList, inPage, maskInPage, rememberPii, knownPii, maskMail
  * Encodes a PNG screenshot inside the page (no native dependency): the image as WebP (or PNG, lossless) and a
  * WebP thumbnail for the canvas grid; `marks` are numbered circles drawn on the image (documentation captures).
  */
+/** "chromium 131.0.6778.33" or null: the browser of a page (Playwright), never failing a capture. */
+export function browserVersion (page) {
+  try { const b = page.context().browser(); const v = b?.version?.(); return v ? `${b.browserType?.().name?.() || 'browser'} ${v}` : null } catch { return null }
+}
+
 export async function encodeImage (page, png, { format = 'webp', quality = 0.82, thumbWidth = 640, thumbQuality = 0.8, marks = [], scale = 1, masks = [] } = {}) {
   const result = await page.evaluate(async ({ dataUrl, format, quality, thumbWidth, thumbQuality, marks, scale, masks }) => {
     const img = new Image()
@@ -300,6 +305,8 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         node: node.id, locale, viewport, url,
         ...variantFields(scope, viewport),
         captured_at: new Date().toISOString(),
+        // the engine and its version, for the record of what walked the run (acceptance records, evidence)
+        browser_version: browserVersion(page),
         criteria_hash: criteriaHash(node),
         console_errors: errors, blocked_requests: blocked,
         ...result,

package/src/lib/cli-args.mjs

@@ -29,6 +29,7 @@ export const HIDDEN = {
   history: ['lang'],
   tokens: ['env', 'version'],
   stability: ['scenario'],
+  health: ['text'],
   status: ['branch'],
   feedback: ['branch'],
   share: ['branch', 'name', 'notes', 'notes-preview', 'strict', 'mine', 'theirs', 'lang'],

package/src/lib/draft.mjs

@@ -65,7 +65,7 @@ export function draftScenario (pages, { id, title } = {}) {
     `Source of truth for intent. Machine scenario: next to this file. Drafted by \`kaloko draft\` from ${pages.length} page(s) of ${origin} on ${new Date().toISOString().slice(0, 10)}; sharpen purposes and criteria before relying on it.`, '',
     '## Goal and scope', '', `Public pages of ${host} read well, are findable, accessible and fast, as a visitor sees them. Read-only on production; nothing is submitted.`, '',
     '## Steps and criteria', '',
-    'Every page step also runs the packs `seo` (AC1xx), `a11y` (AC3xx), `perf` (AC4xx) and `console` (AC501); the error page runs `errors` (AC6xx).', '',
+    'Every page step also runs the packs `seo` (HC1xx), `a11y` (HC3xx), `perf` (HC4xx) and `console` (HC501); the error page runs `errors` (HC6xx). Pack checks are the health of the pages: advisory, reported apart, never part of a verdict. Adopt one into the criteria below (`kaloko health adopt <step>:<check>`) when it must decide acceptance.', '',
     ...nodes.flatMap((n) => [`### ${n.id} — ${n.title} (\`screen\`)`, '', `- Path: \`${n.path}\``, `- Purpose: ${n.purpose}`, ...n.criteria.map((c) => `- ${c.id}: ${c.text}.`), '']),
     '## Environments and limits', '', `production (read-only, as a visitor): add \`environments.production: { base_url: ${origin}, readonly: true }\` to kaloko.config.yml if it is not there.`, '',
     '## Change log', '', '| Date | Commit | Change |', '|---|---|---|', `| ${new Date().toISOString().slice(0, 10)} | — | Drafted from the pages by kaloko draft. |`, ''

package/src/lib/evaluate.mjs

@@ -11,6 +11,7 @@ import { needsDrift, driftForCapture, loadTokens, driftCacheDir } from './drift.
 import { packHelp } from './pack-help.mjs'
 import { tokenCriteria, storedValueChecks, STYLE_ASSERTS } from './assertions.mjs'
 import { appliesToState } from './manifest-core.mjs'
+import { isHealthCriterion, findingSeverity, toAcceptanceId } from './health-core.mjs'
 
 /** Latest capture per node/locale/viewport. */
 export function latestCaptures (entries) {
@@ -19,7 +20,10 @@ export function latestCaptures (entries) {
   return [...map.values()]
 }
 
-export const criteriaHash = (node) => sha256(node.criteria || [])
+// `acceptance` (a pack kept in acceptance) changes what decides the verdict, not what a capture checks
+// a pack check hashes in its AC form whatever its role (HC302 in health, AC302 in acceptance): moving a pack in or out of
+// acceptance, and the HC ids themselves (7 Oct 2026), leave the captures of before valid
+export const criteriaHash = (node) => sha256((node.criteria || []).map(({ acceptance, ...c }) => (c.pack ? { ...c, id: toAcceptanceId(c.id) } : c)))
 /** A criterion with `environments` (e.g. [production]) applies only there; without a known environment it applies. */
 export const appliesOn = (c, environment) => !environment || !Array.isArray(c.environments) || !c.environments.length || c.environments.includes(environment)
 /** Environment and step state (#46): a criterion with `states:` applies only to captures of those states. */
@@ -177,7 +181,8 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       await writeJson(paths.step(stepIdOf(entry), entry.locale, entry.viewport, 'eval.json'), evaluation)
       report.evaluated++
       // what did not pass, for the walk summary and agents: step, locale, viewport, criterion and why
-      for (const c of criteria) if (c.verdict === 'fail' || c.verdict === 'needs_review') report.findings.push({ node: entry.node, ...(entry.item ? { item: entry.item } : {}), locale: entry.locale, viewport: entry.viewport, id: c.id, verdict: c.verdict, type: c.type, why: c.evidence || (c.score != null ? `AI ${Math.round(c.score * 100)} % yes${c.reason_source === 'model' ? `: ${c.reason}` : ''}` : c.note) || null, ...(c.reason ? { reason: c.reason } : {}), ...((node.criteria || []).find((x) => x.id === c.id)?.pack && packHelp(c.id) ? { fix: packHelp(c.id).fix } : {}) })
+      // health checks (pack criteria outside acceptance) are reported apart: advisory, never a verdict
+      for (const c of criteria) if (c.verdict === 'fail' || c.verdict === 'needs_review') { const def = (node.criteria || []).find((x) => x.id === c.id); report.findings.push({ node: entry.node, ...(entry.item ? { item: entry.item } : {}), locale: entry.locale, viewport: entry.viewport, id: c.id, verdict: c.verdict, type: c.type, why: c.evidence || (c.score != null ? `AI ${Math.round(c.score * 100)} % yes${c.reason_source === 'model' ? `: ${c.reason}` : ''}` : c.note) || null, ...(c.reason ? { reason: c.reason } : {}), ...(def?.pack && packHelp(c.id) ? { fix: packHelp(c.id).fix } : {}), ...(isHealthCriterion(def) ? { health: true, pack: def.pack, severity: findingSeverity(c.verdict, c.id) } : {}) }) }
     }
   }
   } finally { if (drift?.browser) await drift.browser.close(); await vision?.close(); await triage?.close() }