# pi-let documentation

`pi-let` is a Pi extension for branch-scoped, persistent autonomous goals. A goal is a contract, not an instruction to self-certify: the worker must submit a candidate, configured deterministic checks run, then a fresh-context judge must approve it.

## Guides

- [Getting started](getting-started.md) — install, create, inspect, pause, and resume a goal.
- [Goal contracts and commands](contracts-and-commands.md) — all creation options, editing, verifier syntax, and command behavior.
- [Lifecycle and architecture](architecture.md) — extension wiring, event flow, scheduling, state transitions, persistence, and progress detection.
- [Completion and verification](completion-and-verification.md) — tool schemas, verifier execution, judge protocol, and failure handling.
- [Reference](reference.md) — exported TypeScript surfaces, data schemas, custom entries/messages, UI, and output modes.
- [Operations, security, and development](operations-and-security.md) — trust boundary, limits, recovery, testing, and release checks.

## At a glance

1. `/goal <objective>` creates an active state on the current session branch and queues one hidden worker turn.
2. Before every active worker turn, pi-let appends the goal protocol and contract to Pi’s existing system prompt.
3. Only `agent_settled` can account a turn and queue the next continuation. User and other pending messages always take priority.
4. The worker calls `goal_complete` with evidence. Only contract-approved verifiers execute; their executable and arguments are passed directly to `pi.exec`, not a shell.
5. A separate, evidence-only model context returns a strictly parsed verdict. Only its `complete` verdict changes the state to `complete`.

Goals persist as custom session entries but are restored only from `sessionManager.getBranch()`. Active restored goals are deliberately changed to `paused`, so recovery always requires `/goal resume`.