# Development

[Back to the README](../README.md)

## Local verification

Requires Node.js 24 or later. From a checkout:

```sh
npm ci --ignore-scripts
npm run verify
```

`verify` runs the quality gates first — both lint passes, the format check, both compiler projects, the baseline drift check and the policy verifier — then the committed harness, the numerical and work-limit checks, and an actual Pi extension-load check. It covers schema and structured result contracts, native nested validation/policy/evaluation errors and native tool-card rendering.

The individual gates run on their own: `npm run lint` (the semantic pass, then compiler diagnostics over the files a compiler project owns), `npm run lint:agent`, `npm run lint:fix`, `npm run format`, `npm run format:check`, `npm test`, `npm run lint:baseline`, and `npm run policy`. The configuration, the baseline it is checked against, and the harness probes are described in [AGENTS.md](../AGENTS.md).

The type-aware lint pass and `tsc` need a host with native builds for `oxlint-tsgolint` and TypeScript. On a host without them (Android on ARM64, for example) the compiler-dependent probes report an explicit skip, so the acceptance gate has to be run on a qualified host or in CI.

The locked development cohort uses Pi 1.5.0 and TypeBox 1.3.27. Pi supplies the schema and terminal UI libraries; `decimal.js` and `expr-eval-fork` are runtime dependencies. No evaluator or grammar compatibility layer is needed.

Update the development TypeBox pin alongside the qualified Pi host, using the version that host ships. Independent TypeBox updates are disabled in Renovate because they install duplicate host schema libraries and slow development startup. Each compatibility lane selects its host's TypeBox version.

## Compatibility qualification

The locked development cohort is reproducible local tooling. Release qualification selects the latest stable official Pi and the [fitchmultz/pi fork](https://github.com/fitchmultz/pi) main once per run, freezing the official version and fork commit throughout the checks.

Each host is qualified separately; a matching version string alone does not establish compatibility. CI runs the full verification against both frozen hosts, including fresh Git and packed npm consumers. See the [compatibility workflow](../.github/workflows/pi-compatibility.yml).

## Release process

When `NPM_RELEASE_ENABLED` is `true`, each main merge enters the automatic version queue. Its version PR must pass current-head compatibility and reviews before the main-only pipeline publishes matching npm and GitHub releases. The release caller reuses the same frozen host inputs for qualification and publishing. See the [version workflow](../.github/workflows/npm-version.yml), [release workflow](../.github/workflows/npm-release.yml), and [changelog](../CHANGELOG.md).