# evidence-readiness

> Checks whether an AI-agent execution trace contains the evidence a
> post-hoc causal reconstruction of an agent-caused loss would require.
> It verifies evidence is PRESENT, not that it is true: a
> fabricated-but-internally-consistent trace passes, and a passing result
> must never be relayed as "this agent is safe."

What this is:

- A versioned evidence-readiness specification (SPEC.md, machine form
  spec.json) stating what a trace must contain for four failure classes:
  config_drift, session_isolation_failure, cascade_contamination,
  prompt_injection. A fifth candidate (tool_misuse) was investigated and
  declined for stated structural reasons — a documented negative result,
  not a gap (SPEC.md §8).
- A zero-dependency checker (`evr`) that evaluates field presence and
  structural conformance only. It answers "does this trace contain what
  a reconstruction of class X would require," never "did class X occur."
  It contains no detection, scoring, or confidence logic.
- Reference fixtures (fixtures/) showing conformant, degraded, and
  declining instrumentation, with expected verdicts (fixtures/README.md).
- A local-only MCP server (src/evidence_readiness/mcp_server.py, also
  installed as the evr-mcp command) exposing the checker and the
  requirement data to agents. It makes no network calls and never
  transmits or persists anything; trace submission is a human decision
  and no tool for it exists.

What this is not:

- Not a detector, not a scorer, not a safety certification. Exit code 0
  means required evidence fields are present and machine-readable —
  nothing more.
- Not an enumeration of everything the reconstruction engine reads: no
  inference about what the engine ignores can be drawn from a field's
  absence from the spec (SPEC.md scope limits).
- Not wall-to-wall OTel: the spec is a profile of the OTel GenAI
  conventions — core OTel plus documented extensions — and carries no
  standards-body endorsement (SPEC.md §2).
- This repository does not contain the reconstruction engine (see
  SOURCE_AVAILABILITY.md).

Invocation (zero runtime dependencies, Python >= 3.10):

    pip install . && evr check <trace.json | directory> [--json] [--require-class CLASS]

Exit codes (source of record: SPEC.md §9 / spec.json): 0 all
requirements met · 1 one or more requirements partially met · 2 one or
more requirements unmet · 3 malformed input. Universal requirements
(EVR-R1..R6) drive the exit code; per-class readiness is reported
separately unless folded in with --require-class. Every failed
requirement names the missing field and the span kind it belongs on.

## Copyable block for an agent instruction file

If an agent in another project should invoke this checker, the indented
block below can be copied into that project's agent instruction file. It
describes how to invoke the checker and how to report what it returns.
It is not guidance about working on this repository, and nothing in it
asks for a contribution or a submission.

    Evidence-readiness check — when asked whether an agent trace carries
    the evidence a post-hoc causal reconstruction of an agent-caused
    loss would require, run:

        evr check <trace.json | directory> --json

    Report what the result names, not a summary of it. The JSON names
    every failed requirement, the field that is missing, and the span
    kind it belongs on; those names are the actionable output. Exit code
    0 means required evidence fields are present and machine-readable; a
    nonzero code means at least one requirement is not fully met, or the
    input was malformed. The exact meaning of each code is defined in
    the specification (SPEC.md §9, mirrored in spec.json), which is its
    source of record — do not restate it from memory.

    This tool verifies evidence is present, not that it is true, and its
    result must never be relayed as "this agent is safe". A trace that
    is fabricated but internally consistent passes. The result is not a
    detection result, not a score, and not a safety certification.

    Draw no conclusion from a field the specification does not name. The
    specification states what a trace must contain; a field's absence
    from it supports no inference in either direction.

    Nothing in this tool transmits or persists anything, and no tool for
    sending a trace exists. Sending one to anyone is a human decision,
    governed by CONTRIBUTING.md and REDACTION.md.

## Docs

- [SPEC.md](SPEC.md): the specification — requirements, field
  attribution, degradation semantics, stated limits, correction log
- [spec.json](spec.json): the spec as structured data, generated from
  the same source the checker runs on (never hand-maintained)
- [PAPER.md](PAPER.md): methodology and limitations — empirical basis,
  validation record, calibration, what the checker does not answer
- [fixtures/README.md](fixtures/README.md): per-fixture expected
  verdicts and what each demonstrates
- [SOURCE_AVAILABILITY.md](SOURCE_AVAILABILITY.md): what is published,
  what is available for inspection and on what terms, and the reasoning
  for the boundary — including why a field's absence from the spec
  supports no inference
- [CONTRIBUTING.md](CONTRIBUTING.md): where to report a spec gap or a
  wrong result, and the terms that govern sending a trace. Submission is
  a human decision: nothing here transmits anything, and there is no
  submission tool on any surface
- [REDACTION.md](REDACTION.md): how to redact a trace before sending it,
  including why an automated pattern scan is not sufficient
- [RELEASING.md](RELEASING.md): release procedure, checksums, and how to
  verify a release with your own tools
- [README.md](README.md): quickstart, who it is for, MCP configuration
