Decisions
A condensed view of the architecture and security decisions that are costly to reverse. The full, authoritative record is docs/DECISIONS.md in the repository.
Architecture
src/coreis the only place with logic. The CLI, MCP server and dashboard are thin wrappers over it, so they cannot drift apart.- Storage is SQLite through Node’s built-in
node:sqlite: no native build step, Node 22.13 or newer. Schema changes only by appending to the migrations list,PRAGMA user_versiontracks it, and a newer database is refused. - State lives in
<repo>/.pcs/, excluded through.git/info/exclude, so no tracked file is touched. - Git is observed by running
gitwith an argument array, never a shell string. - Observation (git, file hashing) happens before the database transaction, and the transaction only writes. Session start and end never fail because observing failed.
Evidence
- Every event carries a provenance:
verified,reportedorinferred. Handoffs keep them separate, and an AI’s completion claim is neververified. - A done task is verified only with a passing linked run whose repo fingerprint equals the current one. A passing run on different code is stale, and no passing run means reported only. A task’s status is never rewritten by evidence.
- Notes are events, not a table, so editing or deleting one is caught by
pcs verifyand there is nothing else to keep in sync.
Integrity
- Events are append-only (SQLite triggers) and hash-chained with SHA-256. Snapshots and test runs are immutable, and each digest is stored in a hash-chained event.
- The chain alone does not detect truncation of the newest events or a full recomputed rewrite. A signed anchor, with the ed25519 key kept outside the project, closes that gap.
- JSON exports are self-checking without PCS. The algorithm is written into the file.
Handoff and resume
- The default handoff location is
.pcs/HANDOFF.md, git-excluded, so writing a handoff never dirties the state PCS observes. - Resume treats an edited, deleted or missing handoff file as untrusted and rebuilds the brief from the hash-chained log, because a file on disk is an injection point.
- Resume no longer refuses when no handoff exists. The agent that stopped is exactly the one that cannot write it, so PCS writes it at pickup.
- Resume through MCP is a takeover: a new agent never gets recorded under a dead agent’s name.
- An integrity failure does not block the handoff. It is written with a warning and exit code 2.
Verification
pcs testruns the command itself, so the run is verified. The link to a task is a claim, so it is reported.- Commands run without a shell, with a hard timeout that kills the process tree. Only the last 8 KiB of output is stored, sanitised and redacted.
- The repo is observed and the command run before the database is opened, so a long test run never holds a lock.
Watcher, hooks and dashboard
- File events are never recorded as facts. They only trigger a fresh observation, and a snapshot is stored only when the fingerprint changed.
- Hooks run outside the model so continuity does not depend on the agent remembering. They never fail the agent, record honest reasons (
switched, nevercompleted), and never copy recorded text into the agent’s context. - The dashboard is read-only on purpose, bound to loopback, token-protected, and inserts data with
textContentonly.
MCP
- One tool per core action, with a
pcs_prefix. The project is fixed by--project, not by the client’s working directory. pcs_testis opt-in because a prompt-injected agent could abuse it.--read-onlyregisters only tools that cannot change anything.
Multi-repo
- One
.pcsper repository stays. A shared database would mix unrelated tamper-evident chains and make one repo’s corruption everyone’s problem. - The workspace is only a registry in
~/.pcs/workspace.json. With several projects registered, a missing or unknown project name is an error that lists the valid names: PCS never guesses which repo to write to.
Config and policy
- Every setting can only tighten the defaults. With both a global and a project file, a command must pass both allowlists.
- Rules that must hold belong in the global file, because the project file sits where an agent could edit it.
Quality gates
- CI runs on Ubuntu, Windows and macOS with Node 22 and 24: typecheck, lint, tests, build, a smoke run of the built CLI and
npm audit. - Coverage thresholds sit just under the current numbers so coverage cannot erode silently: they are floors, not goals.
- Real layouts are tested (normal repo, git worktree, submodule, detached HEAD, no commits), along with concurrent writers and fuzzed input.
Several of these decisions came from real findings: concurrent writers exposed a “database is locked” bug, worktrees exposed a missing git exclude, and the first two-agent test (Claude Desktop to Cursor) changed how resume and identity work.
Last updated on