# Development validation

[Documentation index](../README.md)

Repository handoff is not complete until the current validation gates have been
run or a concrete environment blocker is recorded.

## Required gate

Run:

```sh
prettier . --write
npm run check
git diff --check
```

When reviewing staged work, also run as appropriate:

```sh
git diff HEAD --check
```

## What `npm run check` does

The repository check command validates the development source and tests.

It discovers the extension's TypeScript source and runs, under one bounded
suite deadline:

1. Node syntax checking for every extension TypeScript file;
2. an import check for the extension entry point;
3. the complete Node test set.

The test phase uses:

```text
--experimental-test-module-mocks
--experimental-strip-types
--test
--test-timeout=10000
```

## Process containment

Validation phases run in detached POSIX process groups.

On the suite deadline, the runner attempts:

1. `SIGTERM`;
2. a bounded grace period;
3. `SIGKILL` when required;
4. bounded proof that the process group disappeared.

A phase that leaks descendants after normal exit is reported as a failure and
cleaned through the same group boundary.

Windows is not supported by this process-group validation runner.

## Focused tests

During implementation, run the smallest relevant test files first. Then
always run the full repository gate before final acceptance.

## Dependency availability

A fresh auxiliary worktree may not contain `node_modules`.

Do not silently install dependencies as part of a source-only task unless that
installation is authorized. If validation uses an existing dependency tree via a
temporary link, record that fact and remove the link afterward.

## Failed or non-converging check

Record:

- exact command;
- exit/result classification;
- process evidence when relevant;
- cleanup result;
- whether failure is source-related or environment-related.

Do not claim a passing full check from a partial focused run.

## Live verification

Deterministic tests are the repository gate. Cross-process Pi/Herdr behavior may
also require the live smoke suite.

See [Smoke testing](smoke-testing.md).