kaloko 0.13.0 → 0.15.0

package/README.md

@@ -51,7 +51,7 @@ For example:
 
 > Draft a Kaloko scenario for https://example.com (home, pricing, contact)
 > with the seo, a11y and perf packs, run it on production read-only and
-> summarise what fails.
+> summarise its health.
 
 ## Run a scenario by hand (or in CI)
 
@@ -229,7 +229,11 @@ show (overlap, cut-off text, a raw translation key, an endless spinner);
 reviewers turn the right findings into comments with one click, and findings
 never change a verdict. Triage counts against the hosted-evaluation allowance,
 so it needs the Team plan or higher.
-The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
+Check packs (`seo`, `a11y`, `perf`, `usability`, `console`) report the app's
+health apart from acceptance: they never fail a step that meets its brief,
+`kaloko health` lists what is new since the previous run, and
+`kaloko health adopt` makes one check an acceptance criterion when the team
+wants it to decide. 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, and `kaloko stability --pull`

package/bin/qawalk.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { main } from '../src/cli.mjs'
 
-await main(process.argv.slice(2))
+// the command's name before the rename to Kaloko: it still works and says so once on stderr
+await main(process.argv.slice(2), { bin: 'qawalk' })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/changelog.v1.json

@@ -57,6 +57,11 @@
                             "run": { "type": ["string", "null"] },
                             "version": { "type": ["string", "null"], "description": "The release the picture belongs to (null: the newest accepted)." },
                             "image": { "type": ["string", "null"] },
+                            "video": {
+                              "type": "object",
+                              "description": "Present when the accepted run has a recording of the step and the reference does not say media=image: links like image, and the length.",
+                              "properties": { "mp4": { "type": ["string", "null"] }, "webm": { "type": ["string", "null"] }, "duration_ms": { "type": ["number", "null"] } }
+                            },
                             "canvas": { "type": ["string", "null"] }
                           }
                         }

package/schemas/config.v1.json

@@ -226,7 +226,8 @@
         "serve": { "type": "string", "description": "kind: design. Folder with one sub-folder per step (<step>/index.html, optional <step>/<locale>/index.html) and shared files in _shared/; relative to the config." },
         "fixtures": { "type": "string", "description": "kind: design. Folder of JSON fixtures live steps may fetch instead of real APIs; relative to the config." },
         "origins": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^https://(\\*\\.)?[A-Za-z0-9.-]+(:[0-9]{1,5})?/?$" }, "description": "kind: design. Origins the design loads fonts, stylesheets and images from (https://fonts.googleapis.com, https://*.cdn.example.com). The organization allows them in Settings → Security; kaloko design lint warns about one it does not allow. Scripts never load from them." },
-        "tokens_mode": { "type": "string", "description": "kind: design. Token mode (e.g. light, dark) steps are rendered in; default: the token set's first mode." },
+        "default_token_mode": { "type": "string", "description": "kind: design. Token mode (e.g. light, dark) steps are rendered in and the checks use; default: the token set's first mode. tokens_mode is its older name." },
+        "tokens_mode": { "type": "string", "description": "kind: design. The older name of default_token_mode; still read." },
         "token_modes": { "oneOf": [{ "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" } }, { "const": false }], "description": "kind: design. Token modes of the token set to render every step in, one capture per mode (keys <viewport>.mode-<name>); tokens_mode is the default and has the plain key. Not set: every mode of the set when it has two or more, except a set of only light and dark (left to color_schemes). false: only tokens_mode." },
         "html_view": { "type": "boolean", "default": false, "description": "Experimental (#42): keep a static HTML view of every capture (assets rehosted, scripts removed, secrets scrubbed). Refused on production unless the environment is readonly." },
         "base_url": {

package/schemas/evidence.v1.json

@@ -0,0 +1,257 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/evidence.v1.json",
+  "title": "Kaloko evidence (qawalk.evidence.v1)",
+  "description": "What a downstream generator reads from Kaloko to write its own documentation: the evidence of a run (kind run), of a release (kind release), the trace matrix on its own (kind trace) and the MANIFEST.json of an evidence package (kind package). The contract is additive: new fields may appear in v1, existing fields keep their meaning and type; a breaking change makes qawalk.evidence.v2. Kaloko never formats output for a particular QMS. Produced by GET /api/v1/orgs/<org>/runs/<id>/evidence, …/evidence.zip, …/trace.json, GET /api/v1/orgs/<org>/evidence?product=&version=, MCP get_evidence and kaloko evidence.",
+  "type": "object",
+  "required": ["schema", "kind"],
+  "properties": {
+    "schema": { "const": "qawalk.evidence.v1" },
+    "kind": { "enum": ["run", "release", "trace", "package"] }
+  },
+  "allOf": [
+    { "if": { "properties": { "kind": { "const": "run" } } }, "then": { "$ref": "#/$defs/run" } },
+    { "if": { "properties": { "kind": { "const": "release" } } }, "then": { "$ref": "#/$defs/release" } },
+    { "if": { "properties": { "kind": { "const": "trace" } } }, "then": { "$ref": "#/$defs/trace" } },
+    { "if": { "properties": { "kind": { "const": "package" } } }, "then": { "$ref": "#/$defs/package" } }
+  ],
+  "$defs": {
+    "time": { "type": ["string", "null"], "description": "ISO 8601 time in UTC (…Z), from the service's clock." },
+    "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256, lowercase hex." },
+    "refs": { "type": "array", "items": { "type": "string" }, "description": "Requirement references as written in the scenario (refs:), free text, never interpreted." },
+    "run": {
+      "type": "object",
+      "required": ["generated_at", "acceptance", "signing", "record", "run", "scenario", "steps", "signatures", "trace"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/time", "description": "When this document was made. It is not signed itself; record.sha256 names the signed record it was made from." },
+        "issuer": {
+          "type": "object",
+          "properties": {
+            "service": { "type": ["string", "null"], "description": "The Kaloko service that holds the run, e.g. https://kaloko.app." },
+            "commit": { "type": ["string", "null"], "description": "The service's deployed version (git commit), when known." },
+            "public_keys": { "type": ["string", "null"], "description": "URL of the public keys the record and the package manifest verify against (/.well-known/kaloko-signoff.json)." }
+          }
+        },
+        "org": { "type": ["object", "null"], "properties": { "slug": { "type": "string" }, "name": { "type": ["string", "null"] } } },
+        "acceptance": { "enum": ["none", "accepted", "returned"], "description": "The run's acceptance in Kaloko: accepted, returned, or none (nobody decided the run, or the decision was reset). A generator writes from this, never from the presence of other fields." },
+        "signing": { "enum": ["in_kaloko", "none"], "description": "in_kaloko: at least one electronic signature made in Kaloko stands (see signatures). none: no signature in Kaloko; if the approval is signed, it is signed in another system (the client's eQMS) and that system holds it." },
+        "record": {
+          "type": "object",
+          "description": "The signed record this evidence was derived from (record/kaloko-signoff.json in the package).",
+          "properties": {
+            "schema": { "type": ["string", "null"], "description": "kaloko.signoff.v1." },
+            "kind": { "enum": ["acceptance", "execution"], "description": "acceptance: the stored record of an accepted run (byte-identical on every download while its verdict and signatures stay). execution: a run that is not accepted; signed when made, not stored." },
+            "sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the record's canonical JSON without its signature: what kaloko signoff --verify prints as the record hash." },
+            "signed": { "type": "boolean", "description": "The record carries the service's Ed25519 signature." },
+            "kid": { "type": ["string", "null"], "description": "Id of the signing key." },
+            "issued_at": { "$ref": "#/$defs/time" },
+            "exported_by": { "type": ["string", "null"], "description": "Who downloaded the record first (e-mail)." }
+          }
+        },
+        "run": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "url": { "type": ["string", "null"], "description": "The run on the canvas." },
+            "project": { "type": ["string", "null"] },
+            "started_at": { "$ref": "#/$defs/time", "description": "When the walk started (the walking machine's clock)." },
+            "finished_at": { "$ref": "#/$defs/time", "description": "When the manifest was built (the walking machine's clock)." },
+            "version": { "type": ["string", "null"], "description": "Design version, for runs of design environments." },
+            "app_version": { "type": ["string", "null"], "description": "Version of the application under test, when the run names one." }
+          }
+        },
+        "scenario": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "title": { "type": ["string", "null"] },
+            "version": { "type": ["integer", "string", "null"], "description": "The scenario's own version: field, when set." },
+            "file": { "type": ["string", "null"], "description": "Path of the scenario file in the repository." },
+            "sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the scenario file as walked (CLI 0.15+; null before)." },
+            "refs": { "$ref": "#/$defs/refs" }
+          }
+        },
+        "environment": { "type": ["object", "null"], "description": "{ name, url }: the environment and its base URL." },
+        "git": { "type": ["object", "null"], "description": "{ commit, branch, repo } of the code the run walked, when known." },
+        "tools": {
+          "type": ["object", "null"],
+          "description": "What walked and evaluated the run.",
+          "properties": {
+            "cli": { "type": ["object", "null"], "description": "{ name, version } of the Kaloko CLI (null version: walked before 0.15)." },
+            "node": { "type": ["string", "null"] },
+            "os": { "type": ["string", "null"] },
+            "browsers": { "type": "array", "items": { "type": "string" }, "description": "Browser engines and versions seen in the captures, e.g. \"chromium 131.0.6778.33\"." },
+            "executor": { "type": ["object", "null"], "description": "{ kind: cli | agent, name }." },
+            "service": { "type": ["object", "null"], "description": "{ url, commit } of the service that signed the record." }
+          }
+        },
+        "manifest": { "type": ["object", "null"], "description": "{ path: run.json, sha256, bytes }: the run manifest as stored. Every signature is bound to this hash." },
+        "verdict": { "type": ["object", "null"], "description": "{ verdict: pending | accepted | returned, by, via: session | token | agent, at, note, country, counts_as_person }. via session is a person in the app; token and agent are never a person's decision." },
+        "approvals": { "type": ["object", "null"], "description": "{ required: [e-mail], people: [{ email, at }], tokens_and_agents: [{ email, at, via, counts_as_person: false }] }." },
+        "summary": { "type": ["object", "null"] },
+        "ai": { "type": ["object", "null"], "description": "{ advisory: true, models: [model id], statement }: AI verdicts are advisory; the decisions that count are a person's." },
+        "advisory": { "type": ["object", "null"], "description": "Results the run carries besides its acceptance criteria (e.g. a health section), copied as they are. They never change acceptance." },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "kind": { "type": "string" },
+              "title": { "type": ["string", "null"] },
+              "refs": { "$ref": "#/$defs/refs" },
+              "status": { "enum": ["pass", "partial", "fail", "skip"] },
+              "decision": { "type": ["object", "null"], "description": "The step's current decision: { id, state: approved | returned, by, at, via, agent?, counts_as_person, note?, attachments?: [{ id, name, type, bytes, sha256, by, at, path: decisions/<step>/<file> in the evidence package }], pin?, shape? }." },
+              "decisions": { "type": "array", "description": "Every decision on the step, oldest first, shaped like decision; superseded ones too (resolved_at, deleted: true without content)." },
+              "carried": { "type": ["object", "null"], "description": "An approval carried over from an earlier accepted run: { from_run, compared_run, kind, approved_by, approved_at, approved_via }." },
+              "criteria": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "string" },
+                    "text": { "type": ["string", "null"], "description": "The criterion as walked (from the scenario at the time of the run)." },
+                    "type": { "type": ["string", "null"], "description": "deterministic, semantic or manual." },
+                    "pack": { "type": "string", "description": "The pack the criterion came from, when it did." },
+                    "refs": { "$ref": "#/$defs/refs" },
+                    "verdict": { "type": "string", "description": "pass, fail, needs_review, not_evaluated or not_reached; the worst over locales and viewports after people's verdicts." },
+                    "assessed_by": { "enum": ["person", "ai", "deterministic", "none"] },
+                    "models": { "type": "array", "items": { "type": "string" }, "description": "AI models that assessed it." },
+                    "advisory": { "type": "boolean", "description": "true: the result is an AI's and no person decided this criterion." },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "locale": { "type": "string" },
+                          "viewport": { "type": "string" },
+                          "verdict": { "type": "string" },
+                          "score": { "type": "number", "description": "The AI's probability that the criterion holds (0–1)." },
+                          "assessed_by": { "enum": ["person", "ai", "deterministic", "none"] },
+                          "assessor": { "type": ["string", "null"], "description": "The person's e-mail, or the AI model id." },
+                          "advisory": { "type": "boolean" }
+                        }
+                      }
+                    },
+                    "reviewer": { "type": "array", "description": "Criterion verdicts set by people: { email, verdict, note, locale, at }." }
+                  }
+                }
+              },
+              "captures": {
+                "type": "array",
+                "items": { "type": "object", "properties": { "locale": { "type": "string" }, "viewport": { "type": "string" }, "path": { "type": ["string", "null"], "description": "Path in the run; the package stores it under captures/<path>." }, "sha256": { "$ref": "#/$defs/sha256" } } }
+              }
+            }
+          }
+        },
+        "signatures": {
+          "type": "array",
+          "description": "Electronic signatures made in Kaloko, oldest first, withdrawn ones included. Empty unless the organization signs in Kaloko.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "scope": { "enum": ["run", "step"] },
+              "step": { "type": ["string", "null"] },
+              "review": { "type": ["string", "null"], "description": "The step approval it signs (comment id)." },
+              "decision": { "type": "string", "description": "accepted (run) or approved (step)." },
+              "meaning": { "type": "string", "description": "The meaning the signer chose from the organization's list, as the label they saw." },
+              "meaning_id": { "type": ["string", "null"], "description": "subject_v 2: the meaning's id (reviewed, approved, verified, or the organization's own)." },
+              "lang": { "type": ["string", "null"], "description": "subject_v 2: the language the meaning's label was shown in (en, cs)." },
+              "subject_v": { "type": "integer", "description": "2 for signatures made since 7 Oct 2026; absent (1) before." },
+              "decision_sha256": { "type": ["string", "null"], "description": "subject_v 2: SHA-256 of the canonical decision { note, attachments [{ name, bytes, sha256 }], pin, shape } (a run: its note)." },
+              "name": { "type": "string", "description": "Printed name of the signer." },
+              "email": { "type": "string" },
+              "signed_at": { "$ref": "#/$defs/time" },
+              "time_zone": { "type": "string", "description": "The signer's IANA time zone." },
+              "local_time": { "type": "string", "description": "The signing time in the signer's zone with its UTC offset." },
+              "auth": { "type": "object", "description": "{ session: how the session signed in, second_step_at: when the second step was confirmed, second_step_by: kaloko | idp }." },
+              "verdict_at": { "$ref": "#/$defs/time" },
+              "manifest_sha256": { "$ref": "#/$defs/sha256" },
+              "subject_sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the canonical JSON { v: 1, run, step, decision, meaning, email, name, signed_at, manifest_sha256 } (subject_v 2 adds meaning_id, lang and decision_sha256): what was signed. kaloko signoff --verify recomputes it." },
+              "withdrawn": { "type": ["object", "null"], "description": "{ at, by, reason } once the decision changed; the signature is never rewritten otherwise." }
+            }
+          }
+        },
+        "decision_changes": { "type": "array", "description": "Withdrawn signatures: { at, by, reason, signature, scope, step, signed_by, meaning }." },
+        "audit": {
+          "type": "array",
+          "description": "The audit trail of the run, oldest first: rows of the audit log about the run (source audit_log) and its decisions from comments and criterion verdicts (source decisions).",
+          "items": { "type": "object", "properties": { "at": { "$ref": "#/$defs/time" }, "actor": { "type": ["string", "null"] }, "action": { "type": ["string", "null"] }, "target": { "type": ["string", "null"] }, "via": { "type": ["string", "null"] }, "agent": { "type": ["string", "null"] }, "country": { "type": ["string", "null"] }, "source": { "enum": ["audit_log", "decisions"] }, "detail": {} } }
+        },
+        "trace": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } }
+      }
+    },
+    "traceRow": {
+      "type": "object",
+      "description": "One row of the trace matrix: a requirement, a criterion, a step in one locale and viewport, its screenshot, the result and the decisions. A criterion's requirements are its own refs, its step's and its scenario's (requirement_level); a criterion without any gets one row with requirement null. The CSV has these columns in this order.",
+      "properties": {
+        "requirement": { "type": ["string", "null"] },
+        "requirement_level": { "enum": ["criterion", "step", "scenario", null] },
+        "run_id": { "type": ["string", "null"] },
+        "scenario_id": { "type": ["string", "null"] },
+        "scenario_version": { "type": ["integer", "string", "null"] },
+        "step_id": { "type": "string" },
+        "step_title": { "type": ["string", "null"] },
+        "criterion_id": { "type": "string" },
+        "criterion_text": { "type": ["string", "null"] },
+        "criterion_type": { "type": ["string", "null"] },
+        "locale": { "type": ["string", "null"] },
+        "viewport": { "type": ["string", "null"] },
+        "evidence_file": { "type": ["string", "null"] },
+        "evidence_sha256": { "$ref": "#/$defs/sha256" },
+        "result": { "type": ["string", "null"] },
+        "assessed_by": { "type": ["string", "null"] },
+        "assessor": { "type": ["string", "null"] },
+        "advisory": { "type": "boolean" },
+        "step_decision": { "type": ["string", "null"] },
+        "step_decided_by": { "type": ["string", "null"] },
+        "step_decided_at": { "$ref": "#/$defs/time" },
+        "step_decided_via": { "type": ["string", "null"] },
+        "step_signature_meaning": { "type": ["string", "null"] },
+        "step_signer_name": { "type": ["string", "null"] },
+        "step_signed_at": { "$ref": "#/$defs/time" },
+        "step_signer_time_zone": { "type": ["string", "null"] },
+        "step_comment": { "type": ["string", "null"] },
+        "run_verdict": { "type": ["string", "null"] },
+        "run_decided_by": { "type": ["string", "null"] },
+        "run_decided_at": { "$ref": "#/$defs/time" },
+        "run_decided_via": { "type": ["string", "null"] },
+        "run_signature_meaning": { "type": ["string", "null"] },
+        "run_signer_name": { "type": ["string", "null"] },
+        "run_signed_at": { "$ref": "#/$defs/time" },
+        "run_signer_time_zone": { "type": ["string", "null"] }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": ["release", "runs", "trace"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/time" },
+        "release": { "type": "object", "description": "{ product, version, released_on, tag, commit, runs: [run id] }." },
+        "runs": { "type": "array", "items": { "$ref": "#/$defs/run" }, "description": "The evidence of each run of the release the caller can read." },
+        "missing": { "type": "array", "items": { "type": "object", "properties": { "run": { "type": "string" }, "reason": { "type": "string" } } }, "description": "Runs of the release without evidence here, with the reason." },
+        "trace": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } }
+      }
+    },
+    "trace": {
+      "type": "object",
+      "required": ["rows"],
+      "properties": { "run": { "type": "string" }, "record_sha256": { "$ref": "#/$defs/sha256" }, "rows": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } } }
+    },
+    "package": {
+      "type": "object",
+      "required": ["files", "signature"],
+      "description": "MANIFEST.json of an evidence package, signed like a record (Ed25519 over its canonical JSON without signature).",
+      "properties": {
+        "created_at": { "$ref": "#/$defs/time" },
+        "issuer": { "type": "object", "description": "{ service, kid, public_keys }." },
+        "run": { "type": "string" },
+        "record_sha256": { "$ref": "#/$defs/sha256" },
+        "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sha256": { "$ref": "#/$defs/sha256" }, "bytes": { "type": "integer" } } } },
+        "missing": { "type": "array", "items": { "type": "string" }, "description": "Screenshots the record names that could not be read when the package was made." },
+        "signature": { "type": "object", "description": "{ alg: Ed25519, kid, value, canonical: kaloko-c14n-v1 }." }
+      }
+    }
+  }
+}

package/schemas/run.v1.json

@@ -50,6 +50,15 @@
         "file": {
           "type": "string"
         },
+        "sha256": {
+          "type": "string",
+          "description": "SHA-256 of the scenario file as it was walked (kaloko 0.15+)."
+        },
+        "refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Requirement references of the scenario (scenario refs:)."
+        },
         "source": {
           "type": [
             "string",
@@ -132,6 +141,16 @@
         "null"
       ]
     },
+    "tools": {
+      "type": "object",
+      "description": "What walked the run (kaloko 0.15+): cli {name, version}, node (the Node.js version), os (platform and architecture), browsers (engine versions seen in the captures).",
+      "properties": {
+        "cli": { "type": "object" },
+        "node": { "type": ["string", "null"] },
+        "os": { "type": ["string", "null"] },
+        "browsers": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "started_at": {
       "type": "string"
     },
@@ -227,6 +246,17 @@
         },
         "criteria": {
           "type": "object"
+        },
+        "health": {
+          "type": "object",
+          "description": "Health counts (advisory, CS Kondice): checks evaluated and findings by severity (error, warning; info = the evaluator was unsure), also per pack. Never part of pass, partial or fail.",
+          "properties": {
+            "checks": { "type": "integer" },
+            "error": { "type": "integer" },
+            "warning": { "type": "integer" },
+            "info": { "type": "integer" },
+            "packs": { "type": "object" }
+          }
         }
       }
     },
@@ -417,6 +447,11 @@
         "purpose": {
           "type": "string"
         },
+        "refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Requirement references of the step (refs: in the scenario)."
+        },
         "col": {
           "type": "integer"
         },
@@ -535,6 +570,11 @@
               "verdict": {
                 "$ref": "#/$defs/verdict"
               },
+              "refs": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Requirement references of the criterion (refs: in the scenario)."
+              },
               "by_locale": {
                 "type": "object"
               },
@@ -559,7 +599,33 @@
               },
               "check": {
                 "type": "object"
-              }
+              },
+              "pack": {
+                "type": ["string", "null"],
+                "description": "The check pack the criterion comes from. In criteria a pack criterion counts for acceptance only with acceptance: true; runs stored before health was split off have pack criteria here without it (readers show them as health; their stored verdicts stay)."
+              },
+              "acceptance": { "type": "boolean" },
+              "from": { "type": "string", "description": "The health check an adopted criterion came from (e.g. HC302)." }
+            }
+          }
+        },
+        "health": {
+          "type": "array",
+          "description": "Health checks (CS Kondice): criteria of check packs outside acceptance, shaped like criteria plus level (error or warning when the check fails). Advisory: they never decide the step status or the run verdict. Absent when the step has none.",
+          "items": {
+            "type": "object",
+            "required": ["id", "text", "verdict"],
+            "properties": {
+              "id": { "type": "string", "description": "Health check id, HC<n> (HC302). Runs written before 7 Oct 2026 store AC<n>; readers map it to HC<n>." },
+              "text": { "type": "string" },
+              "pack": { "type": ["string", "null"] },
+              "level": { "enum": ["error", "warning"] },
+              "verdict": { "$ref": "#/$defs/verdict" },
+              "by_locale": { "type": "object" },
+              "counts": { "type": "object", "description": "Stack steps: pages per verdict." },
+              "evidence": { "type": ["string", "null"] },
+              "check": { "type": "object" },
+              "help": { "type": "object" }
             }
           }
         },

package/schemas/scenario.v1.json

@@ -89,12 +89,23 @@
       "enum": ["landing", "work", "list", "settings", "form", "doc"],
       "description": "Default page type of every step (a step may set its own). landing: a public or marketing page; work: an app screen where people work (overview, canvas, inbox); list: a list or table of items; settings: settings or billing; form: a form to fill in; doc: documentation or long text. The usability pack picks its questions by type. Not set: landing for steps with the seo pack or scenarios allowed on production, work otherwise."
     },
+    "health": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Health (CS Kondice): the checks of packs are advisory, shown apart from acceptance and never part of a verdict. acceptance lists the packs whose checks still count for acceptance in this scenario, as they did before health was split off (the design pack always does). To make one check count, adopt it: kaloko health adopt <step>:<check> (e.g. home:HC103) adds the criterion AC103 with from: HC103.",
+      "properties": {
+        "acceptance": { "type": "array", "uniqueItems": true, "items": { "enum": ["seo", "usability", "a11y", "perf", "console", "errors", "app", "design"] } }
+      }
+    },
     "tags": {
       "type": "array",
       "items": {
         "type": "string"
       }
     },
+    "refs": {
+      "$ref": "#/$defs/refs"
+    },
     "nodes": {
       "type": "array",
       "minItems": 1,
@@ -193,6 +204,13 @@
     }
   },
   "$defs": {
+    "refs": {
+      "description": "Requirement references this part verifies, as your QMS or tracker writes them (URS-12, FS-3.4, JIRA-1234). Free text; Kaloko carries them into the run, the acceptance record and the trace matrix (qawalk.evidence.v1) and never interprets them.",
+      "type": "array",
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^\\S(.*\\S)?$" }
+    },
     "record": {
       "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
       "oneOf": [
@@ -277,6 +295,9 @@
         "purpose": {
           "type": "string"
         },
+        "refs": {
+          "$ref": "#/$defs/refs"
+        },
         "lane": {
           "type": "integer",
           "minimum": 0
@@ -341,7 +362,7 @@
               "design"
             ]
           },
-          "description": "Check packs whose criteria are added to this node (ids AC1xx seo, AC2xx usability, AC3xx a11y, AC4xx perf, AC5xx console, AC6xx errors, AC7xx app, AC8xx design: checks against the design reference)."
+          "description": "Check packs whose checks are added to this node. Health checks (advisory): HC1xx seo, HC2xx usability, HC3xx a11y, HC4xx perf, HC5xx console, HC6xx errors, HC7xx app. AC8xx design: checks against the design reference, always acceptance. A pack listed in health.acceptance adds its checks as acceptance criteria with the same number (HC302 → AC302)."
         },
         "capture": {
           "$ref": "#/$defs/capture"
@@ -532,6 +553,9 @@
           "type": "string",
           "description": "CSS selector to outline in the screenshot."
         },
+        "refs": {
+          "$ref": "#/$defs/refs"
+        },
         "check": {
           "oneOf": [
             {
@@ -549,6 +573,15 @@
           "type": "string",
           "description": "Set by the CLI on criteria that came from a pack."
         },
+        "from": {
+          "type": "string",
+          "pattern": "^(HC|AC)[0-9]+$",
+          "description": "The health check this criterion was adopted from (kaloko health adopt), e.g. HC302. The step's pack then leaves that check out of its health, so it is not shown twice. AC302 (written before the HC ids) reads as HC302."
+        },
+        "acceptance": {
+          "type": "boolean",
+          "description": "Set by the CLI on criteria of a pack that counts for acceptance (design, or health.acceptance). Without it a pack criterion is a health check: advisory, never part of a verdict."
+        },
         "environments": {
           "type": "array",
           "minItems": 1,

package/skills/kaloko/SKILL.md

@@ -22,8 +22,13 @@ description: >
   kaloko changelog draft, kaloko release) or a guide should show a step or
   be written, translated or checked (kaloko docs check), when screenshots,
   HTML or recordings must hide personal data (capture masks, pii: redact or
-  pseudonymize, kaloko share stopping on unmasked data), and when a run has
-  Clef triage findings (experimental) to read, mention or answer.
+  pseudonymize, kaloko share stopping on unmasked data), when a run has
+  Clef triage findings (experimental) to read, mention or answer, when
+  a run's health (the advisory checks of packs: SEO, accessibility,
+  performance, console) should be checked, fixed or adopted into acceptance,
+  and when a team's own repository turns runs into regulated documentation
+  (requirement refs, kaloko evidence, the evidence package, the evidence.ready
+  webhook).
 ---
 
 # Kaloko
@@ -39,6 +44,9 @@ the canvas, storage and collaboration are the service.
 - The captures are evaluated (`kaloko walk` ends with the verdicts; after
   `kaloko capture` run `kaloko evaluate`) and `kaloko build` ran; you report the summary line,
   failing criteria with evidence, and the preview path (or shared URL).
+- Health was checked before you hand over (`kaloko health`, MCP `get_health`):
+  you fixed what your change can fix, and you report the remaining counts and
+  what is new since the previous run, apart from the verdicts.
 - When the run was shared, its URL and the summary are in the issue or PR
   the work belongs to, the person got the review-mode link with what waits
   for them (`kaloko share` prints it; `kaloko review` repeats it), and you
@@ -83,11 +91,14 @@ Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
 config on Kaloko (`kaloko products sync`: it records no release) and list them
 (`kaloko products list`). Write, translate and fix
 guides in the docs folder, run `kaloko docs check`, and export them for a docs
-site (`kaloko export --format …`) into a local folder.
+site (`kaloko export docs --format …`) into a local folder.
 
 ## Ask first
 
-Changing acceptance criteria or scope, any production run, writing or
+Changing acceptance criteria or scope (adopting a health check into
+acceptance with `kaloko health adopt` is such a change; pulling checks a
+person already adopted with `kaloko health pull` is not), removing a pack or
+keeping one in acceptance (`health.acceptance`), any production run, writing or
 replacing a CI workflow (`kaloko ci github|gitlab`), uploading with
 `kaloko share` (on a design environment: publishing a version), setting a
 design reference or baseline, merging a design branch, keeping your version of
@@ -102,7 +113,8 @@ anything the environment profile blocks. Never trash an accepted run, a
 baseline, a run with review comments, or a run linked from an open PR or issue
 comment. Never approve a
 step or accept a run on a person's behalf, and never hand out a signed
-acceptance record (`kaloko signoff`) for a run a person has not accepted; report what waits for them
+acceptance record (`kaloko signoff`) for a run a person has not accepted, never present an AI verdict as a person's
+decision in generated documents, and never change the signature policy; report what waits for them
 (`kaloko review`, MCP `get_review_queue`) instead. Ask the person
 for secret values (passwords, tokens, gate credentials) and for sign-ins only
 they can do; never write secrets into the config, a scenario or a script. When
@@ -131,6 +143,9 @@ only when a person says that value may be uploaded.
   (`--heal`): [reference/execution.md](reference/execution.md)
 - Evaluation, JEV thresholds, the vision evaluator and its reasons, reading
   results: [reference/evaluation.md](reference/evaluation.md)
+- Health (CS Kondice): the advisory checks of packs, `kaloko health`,
+  severities, fixing before review, adopting a check into acceptance, alerts:
+  [reference/evaluation.md#health](reference/evaluation.md#health)
 - Clef triage findings (experimental): what they are, how to report them apart
   from the verdicts, `get_findings` and `answer_finding`:
   [reference/evaluation.md#triage-findings-experimental](reference/evaluation.md#triage-findings-experimental)
@@ -154,6 +169,10 @@ only when a person says that value may be uploaded.
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)
+- Evidence for regulated work (GxP): requirement `refs:`, `kaloko evidence`,
+  the evidence package and its check, the `evidence.ready` webhook, feeding a
+  team's own document templates, signatures and what an agent must never do:
+  [reference/evidence.md](reference/evidence.md)
 - Filing a returned step or a failing criterion in Jira or Linear, issue keys in
   branches, channels per project, and hosted runs of read-only scenarios on a
   schedule (`kaloko issue`, `kaloko schedule`):