# Workspace setup and verification

The authoritative toolchain pins are `.node-version` / `.nvmrc` and `package.json` (`engines`, `packageManager`, and `devEngines.runtime`). Use the pinned pnpm; it installs the exact project Node runtime recorded in the lockfile and uses it for scripts, without changing the machine's Node selection. The helpers verify both pins. See [pnpm runtime management](https://pnpm.io/package_json#devenginesruntime).

From each clean Git worktree:

```sh
pnpm worktree:setup
pnpm workflow:context
pnpm verify
git status --short
```

Setup performs a frozen-lockfile install and installs Chromium. Installation and verification must leave tracked source unchanged. For Linux browser system dependencies, see [browser verification](testing.md). For T3 lifecycle integration, server URLs, locks and recovery, see [parallel worktrees](worktrees.md).

`pnpm verify` is the complete guarded gate. Its actual stages live in `package.json#scripts.verify:checks`; consult that script rather than relying on a second copied inventory. It preserves formatting, strict lint/types, builds, baseline/rule/architecture checks, meaningful module/browser verification, built consumers, and workflow regressions. The workflow records the tested commit and full source fingerprint before/after the run, command output, exit code, and evidence paths. A source change during verification fails certification. Development checks may run on dirty source; a reviewable handoff requires final committed, clean source and matching evidence.

Use `pnpm format` for formatting and targeted scripts while working. Stop a dev server in this worktree before running build or verification. Use another worktree for parallel work. Internal `*:checks` commands are called by the guarded gate; direct package-manager commands that mutate outputs are not supported parallel entry points.

Build before running standalone typed lint/type checks or `pnpm check:baseline` in a fresh checkout: workspace imports resolve the supported built declaration entries. `pnpm verify` establishes these artifacts in workspace dependency order before linting and type checking; it does not rely on a previous development build. Build output and local dependencies are ignored.

The workspace includes SDK modules and the portable agent-reporting module. See [portable reports](../integration/portable-reports.md) for bug reports, retained attempts and report bundles. `pnpm example:report` builds the workspace and generates the report example under the same worktree ownership guard.

See [static quality gates](static-quality.md) for complexity/size limits, test exemptions, filename conventions, Knip entries, and the narrowly scoped consumer exceptions. These gates and their regression tests remain required stages of `verify:checks`.

## Add or change a module

Read [foundation](../architecture/foundation.md) and the live task's accepted decisions. Register actual module ownership, public exports, dependency direction and environment in `tooling/architecture/policy.mts`. Register its TypeScript/lint/test environment. Keep tests beside their module and cross-module journeys in `testing/`; add packages only when real consumers justify them.

[Architecture enforcement](architecture-checks.md), [custom rules](rules/no-private-imports.md), [browser verification](testing.md), [examples](examples.md), and [consumer checks](consumer-checks.md) describe their specific workflows. Portable/functions-only entries keep React, CSS and browser/server globals out of eager loading. Prototypes receive the complete production policy.

## Agent completion

Read [reliable agent development](../agents/reliability.md) before starting, resuming, reviewing or handing off work. Read live tracker state and exact prerequisites; run the complete gate and observed T3 browser verification; map acceptance criteria to evidence; review standards, spec and combined integration. A verified branch is reviewable until accepted. Maintain one repository version; independent package release families are outside the accepted foundation.