Validators and the release gate
Why every capability carries an executable check that asserts behaviour and wiring, and how the release gate decides which checks must pass.
Every capability in Kernlift carries a validator, an executable script that checks the feature works and is reachable. A release gate determines which of those checks must pass. The full list of scripts is in Validators.
One validator per capability
scripts/validate/*.ts holds one check per capability, each exposed as a validate:* script in
package.json and chained into pnpm validate:all. A change is not finished until its validator exists
and passes. Modules ship their own validators too, named in their manifest.
A validator reports each check it ran, most as a JSON report with the evidence for each, and exits non-zero when any check fails.
Behaviour and wiring, not file existence
A check that only asserts a file exists passes while the file sits unreferenced by any route. This repository has shipped that bug more than once, so validators assert behaviour and wiring. The usual shapes are:
| Shape | What it proves |
|---|---|
Run a repository or service with validate- prefixed fixtures against the real database, then remove them | The logic works on real tables, including failure paths |
| Render pages with the real marketing snapshot in both locales | The page shows real data in English and Chinese, with no hardcoded prices |
| Read routes, shells and dictionaries | The feature is reachable: routed, guarded, in the navigation and translated |
Validators never fake a provider. Checks that need real credentials are part of external validation.
The release gate
Not every validator passes today. pnpm validate:all runs the whole chain and stops at the first
failure, so it cannot serve as a gate while some checks are known to fail. CI runs
pnpm validate:gate:
| Group | How the gate treats it |
|---|---|
| Validators not listed as known failures | Must pass; any failure is a regression |
Validators in scripts/validate/known-failures.json | Run too; one that starts passing must be removed from the list |
validate:all, validate:gate, validate:storage-drivers | Not run by the gate. The storage driver check writes real objects to a bucket, so it runs only deliberately |
Each known failure carries a written reason and what fixing it takes. The list may only shrink. A validator that starts failing must be fixed and must not be added to it. When you change something, record the pass and fail set before and after, and confirm you did not turn a passing check red.
External validation
Local validators check state machines and not-configured paths. Checks against real providers need
sandbox or production credentials and run separately through pnpm validate:external. Without
credentials those checks are reported as skipped, and EXTERNAL_VALIDATE_STRICT=true makes a skipped
check fail. See Runtimes and database adapters.
Notable validators
| Script | Proves |
|---|---|
validate:auth-boundary | Every API route is guarded or explicitly public with a reason |
validate:migrations | Both migration chains replay and match the schema |
validate:billing-fulfilment | Billing notifies every enabled fulfilment plugin once, records failures and retries them from the scheduled round |
validate:optional-agent | The web app is complete without the agent service, and its scheduled jobs run under one lock |
validate:plugins | The plugin registry rejects conflicts, disabling cascades, and every contributed entry reaches a route file |
validate:store-boundary | Nothing that sells Kernlift has come back into the template |
validate:products | Server-side pricing, licence issue and revoke, bundle expansion |
validate:registry | Foundation plus modules reproduce the checkout; the foundation type-checks alone |
validate:init-cli | Tokens never in argv, unlicensed refusal, upgrades keep local edits |
validate:skills | Skills reference only real scripts, paths, routes and commands |
validate:module-catalog | Module pages render from the real snapshot with no price literals |
validate:docs | Bilingual navigation and links resolve; module, Agent API, schema and environment references match source |
validate:landing-blocks | Home page counts are counted from the checkout |
validate:products, validate:module-catalog, validate:docs and validate:landing-blocks belong to the store project; a project created from the template does not have them.
Files
change-path.ts resolves an OpenSpec change whether it is active or archived, so no
validator hardcodes a change directory. render.ts server-renders a page so a check can assert
on the rendered markup. fixtures.ts creates and
removes the validate-prefixed rows a check needs, so it does not depend on seed data.
Next steps
Run background jobs
Make sure the scheduled jobs run on your platform, run a round by hand, and act on the warning /setup shows when they stop.
Use coding-agent skills
Use the SKILL.md workflows in skills/ to learn a project, create projects, build, install and remove modules, add pages, configure providers and deploy.