Snapshot Schema

Canonical snapshots are JSON files written under .eve/snapshots/.

{
  "id": "snap_123",
  "schemaVersion": "0.3.0",
  "title": "Add GitHub OAuth",
  "type": "feature",
  "summary": "Users can now sign in with GitHub.",
  "userVisibleChange": "The login screen now includes a GitHub sign-in option.",
  "relationships": {
    "corrects": [],
    "supersedes": [],
    "reverts": [],
    "dependsOn": [],
    "related": []
  },
  "risks": [],
  "timeline": [],
  "decisions": [],
  "validation": [],
  "plan": {
    "id": "plan_123",
    "revision": 1
  },
  "planConformance": {
    "status": "matched",
    "noPlanOnFile": false,
    "requiredChecksStatus": "matched",
    "policyMatched": true,
    "checkDefinitionsMatch": true,
    "scopeDrift": false,
    "changedPaths": ["cmd/eve/main.go"],
    "outOfScopePaths": []
  },
  "artifacts": [],
  "implementation": {
    "branch": "main",
    "gitState": "abc123",
    "commits": ["abc123"],
    "dirty": false
  },
  "createdAt": "2026-07-03T15:00:00Z"
}

Types

Snapshot type describes the kind of completed product work:

feature
bugfix
experiment
refactor
release

Risks

Risk severity must be one of:

low
medium
high

Timeline phases

Timeline phase must be one of:

planning
implementation
validation
review
release

Validation statuses

Validation status must be one of:

passed
failed
skipped

Snapshots created with a locked Plan reference include plan and planConformance. Older or adopted repositories can still create Snapshots without a Plan; those records include a loud no_plan conformance result.

Conformance status must be one of:

matched
failed
incomplete
no_plan

Artifact types

Artifact type describes the evidence attached to a snapshot:

screenshot
video
preview
url
note
log
conversation

Each artifact needs a uri, path, or url.

Schema file

The JSON Schema lives at:

schema/eve.snapshot.v0.schema.json