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.

From each clean Git worktree:

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. For T3 lifecycle integration, server URLs, locks and recovery, see parallel worktrees.

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 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 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 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, custom rules, browser verification, examples, and consumer checks 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 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.