evidence-kit

A held-constant test baseline and a committed per-run evidence manifest for the validate stage: a stage stamp proves a stage was invoked, evidence-kit proves it produced its green result. The manifest is a versioned, hashable wire contract (# contract: evidence-manifest v1) an external verifier can consume, so the kit is adoptable with or without an iteration lifecycle.

The gates: check-evidence-baseline (baseline grammar, blocking-slug liveness, scenario coverage, flip causation), check-evidence-manifest (manifest grammar and, where lifecycle drives the tree, close-entry green block + validate-stamp coupling), check-battery-roster (the runner doc’s battery block against the suite roster) and check-producer-liveness (no stage entry while the producer is still running). The tools that drive it are non-gate arms of the gate binary, reached through gate-sdk’s front end: --run-validate (the codified spine that runs the suites and records evidence), --diff-baseline (the situational runtime diff) and --emit baseline-claims (each baseline row as a measured: oracle line, for prose that quotes one). See SPEC.md for the full contracts.

This file ships in the installer payload; what that payload withholds, and where this page’s SPEC.md links then resolve, is gate-sdk/SPEC.md §Consumer payload.

Install

Vendor the kit beside gate-sdk (required), then:

Register the gates — add each to your gates.list except check-producer-liveness, which step 6 wires at stage entry instead:
```
check-evidence-baseline
check-evidence-manifest
check-battery-roster
check-producer-liveness   # entry hook only — never gates.list, see step 6
```
The pre-commit hook runs the gates their # graph: manifests trigger, read at commit; --install-hooks on the gate binary GATE_SDK_NATIVE_BIN names places both hooks in a clone once, and a gate registered later is reached with no re-install.

Seed the two surfaces — .workflow/validate-baseline.txt:

# contract: evidence-kit/SPEC.md §Baseline manifest — held-constant validate baseline: <suite> <scenario> <status> [<slug> [reproduces-at=<rev>]]

and .workflow/validate-evidence.txt:

# contract: evidence-manifest v1

(override the paths with EVIDENCE_KIT_BASELINE_FILE / EVIDENCE_KIT_MANIFEST_FILE).

Configure the suites — copy templates/evidence-config.knobs into your gates dir as evidence-config.knobs, naming EVIDENCE_KIT_SUITES (one EVIDENCE_KIT_SUITES[] = <suite> line each, or EVIDENCE_KIT_SUITES[] <- EVIDENCE_KIT_FIXTURE_SUITES for the derived fixture suites, whose run commands are derived too), an EVIDENCE_KIT_RUN_<suite> command per other suite, and the EVIDENCE_KIT_PARSER adapter (exit-code for a whole-suite pass/fail, libtest for per-test result logs, or your own log-parsing command).
Record evidence at validate — run --run-validate on the gate binary GATE_SDK_NATIVE_BIN names; it runs each suite, diffs the baseline, and records one evidence line per suite — written to the manifest in a single fold once the whole roster has run, so a suite needing a clean worktree may sit anywhere in it.
Optional lifecycle integration — set LIFECYCLE_KIT_BOUNDARY_TRUNCATE to the evidence manifest so a new iteration starts from the contract header, and the manifest gate’s close-entry and stamp-coupling assertions arm automatically.
Wire check-producer-liveness on LIFECYCLE_KIT_ENTRY_PREFLIGHT rather than in gates.list, its command naming the lock file through a name-resolving front end rather than a path (<stage>=<front end> check-producer-liveness <lock-file>; SPEC.md §check-evidence-manifest owns why a preflight entry names the gate), at whichever stage entries must not begin while --run-validate is still running. It asks whether a producer is in flight, not whether the tree is consistent, so a battery that --run-validate itself invokes would red every run against that run’s own lock. See SPEC.md §check-producer-liveness.

Test

Run this arm with the gate binary GATE_SDK_NATIVE_BIN names, where init places it. In PowerShell, spell the line ./scripts/checkwright-gates <arm> at the repository root, with .exe on native Windows:

gates="${GATE_SDK_NATIVE_BIN:-./scripts/checkwright-gates}"
"$gates" --run-gate-tests evidence-kit/gate-tests evidence-kit/checks

License

Licensed under Apache-2.0, with the text in LICENSE beside this file in an installed copy and at the repository root in the source tree.