Get started
Core concepts
One vocabulary runs through the whole ecosystem: an evidence record that escalates trust from an in-loop log to a signed, audit-grade attestation.
The evidence record
Everything starts with one shape — the evidence record, defined once in github.com/zegit-zoo/common/evidence (schema version 0.1) and emitted by every producer (mongoose, the plugins, zegit). There is a single record shape across all trust levels; only the envelope grows.
Each record binds itself to git state — a commit_sha and tree_sha (or, outside a repo, a dirty flag plus a diff hash). It carries the producer, an actor (a human or an agent harness + model), the steps that ran, optional reviewers, an optional policy decision, and the envelope.
| Field | Meaning |
|---|---|
producer | What emitted the record — mongoose, agent-guardrails, or zegit. |
actor | Who acted — kind: human or agent (with harness + model). |
subject | The git binding: commit_sha, tree_sha, dirty, diff_sha256, run_id. |
steps[] | What ran — each with a kind (job/agent/skill/check/review) and status. |
policy_ref | The policy the record was produced under (a digest, optionally a contract hash). |
decision | The policy verdict — nil until evaluated. |
envelope | The trust level — see below. |
Envelopes: the trust ladder
The same record climbs three trust levels. This is the spine of the whole platform — the upgrade from log to proof is just running the next tool over the same record.
| Level | What it is | Set by |
|---|---|---|
| unsigned | An in-loop local record. No signature. | mongoose / the plugins |
| validated | A policy Decision has been stamped on; still unsigned. | zg evidence evaluate --stamp |
| signed | DSSE-wrapped and signed; audit-grade. | zg validate / zg evidence sign |
AoV — Attestation of Validation
An AoV is a signed (envelope-level signed) evidence record, produced by zg validate on success. It proves that a passkey-authenticated identity asserts this validation ran under this policy, for a specific commit and tree. It is stored in Git itself, as a blob at refs/zegit/aov/<commit_sha>, and pushed alongside your commits by the zg init pre-push hook.
What a v1 AoV does and doesn't prove
An AoV is non-repudiable and audit-grade: it binds an identity, a commit, a tree, and a policy. It does not yet prove the validation actually executed as claimed — that needs attested runner images (a post-MVP tier). The platform is deliberately honest about this.
Short-lived certs expire
Verification checks the signer certificate at the current time, so an AoV becomes unverifiable once its short-lived cert expires. Re-run zg validate to re-sign.
DSSE & in-toto
A signed AoV is a DSSE envelope wrapping an in-toto Statement whose predicate is the evidence record. DSSE/in-toto compatibility is a day-one requirement, so the signatures interoperate with the wider supply-chain tooling ecosystem.
The policy engine
The policy engine evaluates a record and returns one of three decisions. The mapping to enforcement is fixed:
| Decision | Meaning | Enforcement |
|---|---|---|
| ALLOW | All gates passed; policy permits autonomous delivery. | Gateway accepts the push. |
| REQUIRE_REVIEW | A reviewer was non-passing, or risk policy requires review. | Routed to a Tag Request / approval. |
| BLOCK | A required step failed, evidence is stale, or risk blocks. | Gateway rejects with a ZG_ERR_* code. |
Evaluation is first-match-wins: an invalid required task contract blocks; stale evidence (the record's commit/tree ≠ the pushed commit/tree) blocks; a missing required step blocks; a non-passing reviewer requires review; otherwise the risk policy decides. See the exact ordering and the matching error codes.
Know · work · prove
The three tools map to a mnemonic that also describes the data flow:
- meerkat knows — agents query a curated knowledge base before they act.
- mongoose works — the agent does the work and emits an unsigned record per run, bound to git state.
- zegit proves — that same record is evaluated, signed into an AoV, and gated at the release boundary.
mongoose only ever emits unsigned records; the editor plugins do the same. Signing is always zegit's job — which is why "the upgrade from log to proof is just installing zegit."
Authoritative reference, generated from the component repos. Spot something stale? Tell us.