# Architecture PurrCode is organized around four primary subsystems. | Component | Responsibility | |---|---| | **PawGate** | Deterministic policy, contextual judgment, constraints, and human approval gates | | **Claw** | Credential-scrubbed execution inside a worktree-scoped sandbox | | **Whisker** | Repository context retrieval, indexing, filtering, and risk signals | | **NineLives** | Durable events, checkpoints, restart reconciliation, recovery, and rollback | The simplified runtime flow is: ```text User task ↓ Repository context ↓ Model proposal ↓ PawGate policy and judgment ↓ Durable exact-action authorization ↓ Claw verification and isolated execution ↓ Validation evidence ↓ Review, apply, commit, export, or rollback ``` ## Core principles 1. **Model output is a proposal, not authority.** A model may recommend an action, but it cannot authorize its own execution. 2. **Execution is isolated.** Coding work runs in detached Git worktrees under PurrCode-managed storage. Your active working tree is not silently modified, overwritten, stashed, or discarded. 3. **Completion requires evidence.** Passed, failed, timed out, unavailable, undetected, skipped, and uncertain are distinct states. Skipped or unavailable validation is never reported as success. 4. **Recovery is conservative.** Interrupted actions are not blindly replayed. NineLives restores durable state and flags uncertain effects for explicit review. 5. **Local-first does not mean resource-unaware.** Ollama and LM Studio are supported while avoiding unnecessary model loading during startup. 6. **External capabilities remain governed.** Skills, MCP servers, downloaded packages, web research, and repository content are untrusted inputs. ## The alignment loop (v1.5) Everything above answers *did the agent change the repository safely*. v1.5 adds a loop that answers a different, more common failure: validation passes and the change still is not what was asked for. ```text User message ↓ Intent compiler → expectation contract (requirements quote the user verbatim) ↓ Implementation, PawGate/Claw, deterministic validation (as above) ↓ Requirement coverage review ─┐ Independent code review ─────┼─ each is fresh: none sees the implementer's own transcript User-alignment review ───────┘ ↓ Delivery gate — reads durable session state, not the model's own completion claim ├─ ready → session completes ├─ blocking findings → bounded automatic correction → re-review ├─ still unfinished → work continues, citing the gate's actual reason └─ needs a decision → returned to the user, with what was tried ``` | Property | What enforces it | |---|---| | A requirement cannot be invented | The intent compiler refuses a clause whose `quotation` is not text the user actually sent; the runtime, not the model, resolves which message it came from | | A mid-task correction revises, not appends | Restating a requirement resets progress made under the old wording rather than standing a new one beside it | | A reviewer cannot see the implementer's reasoning | The review input type has no field to carry it | | A reviewer cannot repair what it finds | Reviews return findings and verdicts only; repair is a separate, later step | | Completion is read from the log, not asserted | The delivery gate is recomputed from durable session state at every completion attempt, including the last one | The alignment benchmark (20 fixed tasks) scores the same way: from the tree a run left behind, never from the run's own reviewers, since a run where they were wrong looks identical from inside to one where they were right. See [`docs/v1.5-architecture.md`](https://github.com/Weilin0723/PurrCode/blob/main/docs/v1.5-architecture.md) in the main repository for the full design. ## The model provider is outside the trusted boundary A provider can generate a proposal, but it cannot directly authorize or execute that proposal. ## Shared session state The CLI, TUI, and native IDE use the daemon-owned runtime instead of independent competing agent loops. All state flows through the daemon — the IDE owns no session store, no model state, no permission state, and no execution path. The daemon exposes typed presentation endpoints (activity, validation, summary, usage) so clients share one vocabulary instead of each inventing a reading of the durable event log. For the durable security properties, see [Security](Security.md). For recovery behavior, see [Recovery](Recovery.md).