Spec

Documentation

These docs describe the specification and v0 design of Surety. They are the source of truth that the implementation tracks against. Every page carries a status badge so you know what is shipped, drafted, or specced.

Status legend

• Shipped — Implemented and stable in the OSS core
• Draft — Implementation in progress, may change
• Spec — Specification finalized; implementation tracks it
• Coming Soon — Planned, not yet specified in detail

Where to start

If you want the conceptual model, read Evidence Pack v0 first — it is the central artifact every other doc points at. After that, Policy file explains how teams declare what Surety should enforce, and Gates & maturity explains how Surety labels what's real versus stub.

If you want the runtime and event side, read Safe runtime for the sandbox model and Event protocol for the on-the-wire shape.

Architecture in one paragraph

Surety is a CLI plus a GitHub App that wraps any AI coding agent. It runs the agent inside a Docker sandbox with policy-enforced paths, secrets, and egress; calls real scanners as gates; writes a transactional event log to SQLite (Postgres in Enterprise); produces a schema-versioned, content-hashed, Sigstore-signable evidence pack; and renders that pack into a GitHub Check Run and PR comment. Same evidence pack across every executor — Claude Code, Codex, Copilot, Cursor, OpenHands, Devin, and human PRs.