AGENTS.md@modules/pi git:20260925.32a2a97A

Immutable. This exact content never changes and is served at /api/v1/blob/7fdb52d7f90da3fd.

# pi submodule conventions

scope: `modules/pi`

## commits

- include the submodule in commit scopes.
- format: `<type>(pi/<scope>): <summary>`
- examples:
  - `feat(pi/code-review): add schema-based startup gating`
  - `test(pi/e2e): add config-gating smoke coverage`
  - `docs(pi/skills): add config-gating hotspot workflow`

## history

- preserve true history.
- prefer small in-tree commits over squashy cleanup.
- stage only files for the current slice.
- ignore unrelated `*.sync-conflict-*` junk unless the task is explicitly about them.

## tests

- **everything inline** — use `if (import.meta.vitest) { ... }` blocks at the bottom of source files. no `__tests__/` directories.
- **run vitest via scripts** — use `pnpm run test` (or `pnpm exec vitest run ...` for targeted files).
- **test outcomes, not implementation** — "prompt appears in editor" not "sendUserMessage was called".
- **only mock boundaries** — file system, network, LLM. never mock the system under test.
- **thin wrappers don't need execution tests** — sub-agents that just call `piSpawn` have no meaningful unit tests. their value is prompt quality, which is an eval, not a unit test.
- **TUI components**: mock theme to strip ANSI (`fg: (_, text) => text`), assert on `render(width)` output.
- **export internals for testing**, but don't advertise in package.json exports.

**what to test inline:**

- string transformations
- type guards / validators
- parsing / data extraction
- pure utility functions
- extension registration (with minimal tracking mocks)

**what NOT to test:**

- "was piSpawn called with correct args" — that's testing piSpawn's contract
- string interpolation / template assembly — trivial
- config pass-through — just data

verify with:

- `pnpm exec tsc -p tsconfig.build.json --noEmit`
- `pnpm run test`

tool-schema changes must exercise the provider request builder, not just
TypeBox validation or registration. run the `packages/core/prompt-patch`
tests; after building, set `PI_TEST_BUILT_TOOLS=1` to also compare source and
built registries. with authorization for an existing Codex OAuth request,
`node scripts/check-codex-tools.mjs --live` checks actual provider acceptance
(`--built` checks dist). it disables tool execution and sends no session history.
an SDK dependency patch requires restarting pi; `/reload` only reloads extensions.

## style

- smallest viable diff.
- copy proven patterns from nearby adopters before inventing a new shape.
- prefer sdk/session-level probes when startup registration needs stronger proof than local spies.