---
id: PX-PLAN-TXNM7OUB
type: plan
title: Verification Cadence and Compatibility Matrix
spec: PX-SPEC-DZLVGRW4
status: draft
depends_on:
  - PX-PLAN-_BUERPCN
  - PX-PLAN-XQFSKHHG
---

## Outcome

Hooks, normal CI, and release CI each run the checks matching their cost budget.
Release artifacts are verified across a Pi, Node, and OS matrix that yields an explicit minimum supported Pi version.

Verified current state: pre-commit and pre-push both run `check` + `lint` repository-wide; `.ci/ci.kdl` runs `check`, `lint`, `test`, `e2e` on push to `trunk` in a Playwright image; Pi pinned at 0.87.0.

## Behaviors

```mermaid
flowchart TB
  v1["1. Hooks scope to changed extensions"] --> v2["2. Normal CI adds release build + package verification"]
  v2 --> v3["3. Release CI runs matrix on snapshot"]
  v3 --> v4["4. Minimum Pi version recorded and enforced"]
```

1. `pre-commit`: changed-scope lint and focused typecheck (deterministic, offline); `pre-push`: full `check` and `unit` + `contract` projects.
   Hook tasks derive scope from `git diff --name-only`; unchanged extensions are skipped.
2. `.ci/ci.kdl`: `check`, `lint`, one `//:test`, `build-all --release`, `packages` project on current Pi, native and UI suites.
3. `.ci/release.kdl` on `vX.Y.Z` tags: restore snapshot, run `packages` project across Pi versions × Node LTS/current × Linux, Windows, macOS where Luci provides runners; missing OS runners are reported as gaps, not silently passed.
   Initial Pi range starts broad (several minor versions back) and narrows empirically.
4. Minimum supported Pi version lives in extension source manifests as the `peerDependencies` range and in the root `package.json`; a check fails when the matrix result and the declared range disagree.

## Gate structure

```mermaid
flowchart LR
  commit["pre-commit: changed lint + focused tsc"] --> push["pre-push: check + unit + contract"]
  push --> ci["ci.kdl: full static + test + release build + current Pi packages + native + UI"]
  ci --> release["release.kdl: matrix over snapshot"]
  release --> min["declared minimum Pi"]
```

Touched: `mise.toml` (`pre-commit`, `pre-push`, `ci`, `release-ci`, changed-scope helper task), `.ci/ci.kdl`, `.ci/release.kdl`, `scripts/scope.ts`, `package.json` and `extensions/*/package.json` version ranges, `scripts/extensions.mjs` compatibility check.

## Constraints

- Hooks never install browsers, run matrices, publish, instrument coverage, or run mutation and fuzz campaigns.
- Hook management stays through `mise generate git-pre-commit`.
- Luci job definitions delegate to Mise tasks; no logic in KDL beyond environment setup.

## Verification

- [ ] Committing a change in one extension runs lint and typecheck for that extension only.
- [ ] Pushing runs complete static checks and source tests without browser installs.
- [ ] `ci.kdl` run includes release build and current-Pi package verification.
- [ ] Release job output lists pass/fail per Pi × Node × OS cell and derived minimum.
- [ ] Declared Pi range mismatch with matrix results fails `check`.