# How to Validate Code Changes in PI-Desktop: The Complete Workflow

> Learn how to validate code changes in PI-Desktop with this complete workflow. Execute type-checking linting unit tests sync specs run E2E tests and merge after gates pass.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**To validate code changes in PI-Desktop, you must execute local type-checking, linting and unit tests, synchronize any relevant specification documents, run the mandatory end-to-end test suites mapped in the E2E matrix, and complete the merge through an isolated request branch after all remote gates pass.**

PI-Desktop enforces a rigorous validation pipeline that ties local checks to architectural constraints defined in the **frozen process model**. This guide maps the exact steps required to ensure every change remains correct, secure, and synchronized with the project's immutable delivery rules.

## Local Validation Pipeline

Every modification to the codebase begins with the standard validation commands documented in the [README.md](https://github.com/vastsa/PI-Desktop/blob/main/README.md). These gates catch type errors, style violations, and regression bugs before they enter the shared pipeline.

### Type Checking and Static Analysis

Run the static analysis tools to verify type safety across the TypeScript boundaries:

```bash
pnpm typecheck        # Validates types across Renderer and Main processes

pnpm lint             # Enforces ESLint and Prettier rules

```

According to the repository structure, these commands traverse the **Renderer → Preload IPC → Electron Main** layers to ensure interface contracts remain intact.

### Unit and Integration Tests

Execute the fast feedback test suite to verify business logic in isolation:

```bash
pnpm test             # Runs unit and integration tests

```

This validates behavior within the **Node Agent Runtime** and **Rust Host Core** without spinning up the full Electron application.

## Specification Synchronization (R1)

If your change touches user-visible behavior, protocol definitions, or API surfaces, you must update the corresponding specification documents. The [03-ai-development-workflow.md](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/03-ai-development-workflow.md) mandates **R1 — Spec-first / Spec-sync**: every code-bearing change must be accompanied by synchronized documentation.

- Update `docs/spec/` files to reflect behavioral changes
- Verify protocol updates in the **pi-ai** and **pi-agent-core** interface definitions
- Cross-reference the [AGENTS.md](https://github.com/vastsa/PI-Desktop/blob/main/AGENTS.md) file if modifying agent-centric workflows

## End-to-End Testing Requirements (R3)

PI-Desktop requires that every code change passes at least one relevant E2E suite selected from the coverage matrix. Consult the [04-e2e-test-plan.md](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/04-e2e-test-plan.md) to identify which suites map to your modified surface area.

```bash

# Example: Running the UI regression suite for a component change

pnpm e2e:ui

# Example: Running the full integration suite for protocol changes

pnpm e2e:integration

```

If a required suite cannot execute in your local environment due to hardware constraints or external dependencies, you must record this limitation per the *Local Validation and E2E Execution Policy* and ensure the suite passes in the trusted CI environment before merging.

## The Request Branch Workflow (R4)

PI-Desktop uses an immutable **request-branch/worktree policy** that isolates development from the `main` branch. This prevents contamination of the frozen process model spanning **Electron Main → Rust Host Core → pi-agent-core**.

### Creating Isolated Worktrees

Instead of switching branches in your working directory, create a dedicated worktree:

```bash
git fetch origin main
git worktree add -b feat/your-feature ../worktrees/feat-your-feature origin/main
cd ../worktrees/feat-your-feature

```

This approach maintains a clean `main` worktree while allowing isolated validation of your changes across the full architecture stack.

### Conventional Commits and Push

Follow **R2 — Commit-per-change** by staging your changes with a conventional commit message:

```bash
git add .
git commit -m "feat(ui): add dark-mode toggle button"
git push -u origin feat/your-feature

```

Open a pull request targeting `main` and verify that the remote CI pipeline executes the required E2E suites listed in the [E2E test plan](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/04-e2e-test-plan.md).

## Merge Gates and Cleanup

After the PR passes all automated gates—including the mandatory E2E coverage specified in **R3**—merge using the repository's merge gate:

```bash
gh pr merge <PR-NUMBER> --merge

```

Immediately clean up the isolated workspace to prevent worktree sprawl:

```bash
git worktree remove ../worktrees/feat-your-feature
git branch -d feat/your-feature

```

This cleanup step ensures compliance with the **Definition of Done** defined in the AI-development workflow specification.

## Summary

- **Run local gates first**: Execute `pnpm typecheck`, `pnpm lint`, and `pnpm test` to catch errors early in the Renderer and Main processes.
- **Sync specifications**: Update relevant `docs/spec/` files whenever modifying user-visible or protocol-visible behavior per rule R1.
- **Execute mandatory E2E**: Select and pass at least one E2E suite from the coverage matrix in [`docs/spec/06-delivery/04-e2e-test-plan.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/04-e2e-test-plan.md) per rule R3.
- **Use request branches**: Create isolated worktrees for each change and merge only after passing remote gates per rule R4.
- **Clean up worktrees**: Remove temporary worktrees and branches immediately after merging to maintain repository hygiene.

## Frequently Asked Questions

### What local commands are required to validate code changes in PI-Desktop?

You must run `pnpm typecheck` for static analysis, `pnpm lint` for code style enforcement, and `pnpm test` for unit and integration validation. These commands verify type safety across the Electron IPC boundary and business logic within the Rust Host Core and Node Agent Runtime.

### When is it mandatory to update the specification documents?

Specification updates are mandatory whenever your change affects user-facing behavior, protocol definitions, or API contracts. This aligns with **R1 — Spec-first / Spec-sync** in the AI-development workflow spec. Changes to the pi-ai or pi-agent-core interfaces always require synchronized documentation updates in the `docs/spec/` directory.

### How do I determine which E2E test suites to run?

Consult the coverage matrix in [docs/spec/06-delivery/04-e2e-test-plan.md](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/04-e2e-test-plan.md). The matrix maps code surfaces (UI components, protocol handlers, agent runtimes) to specific suites such as `e2e:ui` or `e2e:integration`. Every code-bearing change must pass at least one relevant suite before merging.

### What is the frozen process model and why does it affect validation?

The frozen process model defines the immutable architecture stack: **Renderer → Preload IPC → Electron Main → Rust Host Core / Node Agent Runtime → pi-ai / pi-agent-core**. This strict layering prevents unsafe cross-boundary changes. The validation pipeline enforces compliance with this model by requiring specification updates and E2E tests that verify cross-process communication contracts remain unbroken.