{
  "markdown": "# evidence-readiness\n\n**Checks whether an agent execution trace contains the evidence a post-hoc\ncausal reconstruction would require.**\n\nWhen an AI agent causes a loss — a bad config change, a cross-session data\nleak, contaminated output cascading between agents, a prompt injection —\nsomeone eventually has to reconstruct *why* from the trace. Traces from\ngeneral-purpose agent instrumentation cannot support that reconstruction: the\nevidence was never recorded. This repository contains the evidence-readiness\nspecification ([SPEC.md](SPEC.md)), a checker that evaluates a trace against\nit, and reference fixtures showing what conformant instrumentation looks like.\n\n## What this is — and is not\n\n- **It checks that evidence is *present*, not that it is *true*.** A\n  fabricated-but-internally-consistent trace passes. This tool authenticates\n  nothing, and its result must never be relayed as \"this agent is safe.\"\n- **It never determines whether a failure occurred.** It answers \"does this\n  trace contain what a reconstruction of class X would require,\" never \"did\n  class X occur.\" It contains no detection or scoring logic.\n- **This repository does not contain the reconstruction engine.** The\n  specification is published so the method is assessable; the engine is\n  available for inspection under the terms in `SOURCE_AVAILABILITY.md`.\n- **Four failure classes** are covered: `config_drift`,\n  `session_isolation_failure`, `cascade_contamination`, `prompt_injection`.\n  A fifth (`tool_misuse`) was investigated and declined for stated\n  structural reasons — a documented negative result, not a gap (SPEC.md §8).\n- The spec is **a profile of the OTel GenAI semantic conventions: core OTel\n  plus documented extensions** (SPEC.md §2). It carries no standards-body\n  endorsement.\n\n## Who it is for\n\n- **Engineers instrumenting agents** who want incidents to be\n  reconstructable after the fact — diff your trace against a conformant\n  fixture and see what to add.\n- **Reviewers** (insurers, auditors, counterparties) evaluating whether an\n  agent system's telemetry would support retrospective loss adjudication.\n- **Coding agents**: see `llms.txt`, `spec.json` (the machine-readable\n  spec export, generated — never hand-maintained), and the MCP server\n  in `src/evidence_readiness/mcp_server.py` (configuration below).\n\n## Quickstart (60 seconds)\n\n```bash\n# from a clone of this repository\npip install .\nevr check path/to/trace.json        # or a directory of traces\nevr check --json path/to/traces/    # machine-readable report\nevr check --require-class prompt_injection path/to/trace.json\n```\n\nThe package has **zero runtime dependencies**; `pip install .` in any\nPython ≥3.10 environment is the whole setup. Equivalent `uvx` forms, both\nexercised: `uvx --from . evr check ./traces` from a clone, and\n`uvx --from evidence-readiness evr check ./traces` from the package index.\n\n**Both need `--from`, and the trailing `evr` is not optional.** A bare\n`uvx evidence-readiness ...` runs the console script *named for the\ndistribution*, and that script is the MCP server (below), not the checker\n— it reads standard input, ignores the arguments, and exits successfully\nwithout checking anything.\n\nExit codes carry no reconstruction vocabulary: `0` all requirements met ·\n`1` one or more requirements partially met · `2` one or more requirements\nunmet · `3` malformed input (SPEC.md §9 is the source of record).\nUniversal requirements (EVR-R1..R6) drive the exit code; per-class evidence\nreadiness is reported separately, and `--require-class` folds a named\nclass's readiness into the exit code. For every failed requirement the\noutput names the specific missing field and the span kind it belongs on.\n\nEvery run ends with the same statement this README opened with: **presence,\nnot truth** — evidence being present does not make it authentic, and a\npassing trace is not a safe agent.\n\n## CI: check every PR (GitHub Action)\n\nA spec is read once; a check that runs on every PR changes instrumentation\nbehavior. Add this to a workflow in the repository that produces your\ntraces (`evidence-readiness` is this repository's owner once published; from\nwithin this repository itself, `uses: ./.github/actions/readiness-check`):\n\n```yaml\nsteps:\n  - uses: actions/checkout@v4\n  - uses: evidence-readiness/spec/.github/actions/readiness-check@main\n    with:\n      trace-path: traces/\n```\n\nThat is the whole setup — the default GitHub runner's `python3` is\nsufficient, and the Action installs the (zero-dependency) checker itself.\nThe step fails when the checker's exit code exceeds\n`minimum-passing-exit-level` (default `0`; exit-code semantics as in the\nQuickstart above). Optional `required-classes` folds named classes'\nevidence requirements into the exit code. Outputs: `exit-code`,\n`exit-meaning`, `report-path` (full JSON report), and\n`per-class-readiness`. PR annotations name each incomplete requirement's\nspecific missing field and span kind. Every annotation is a statement\nabout the **trace telemetry**, never about the agent: an annotated PR has\nincomplete evidence, not a detected failure — and a clean run is not a\nsafe agent. This repository's own CI (`.github/workflows/ci.yml`)\ndogfoods the Action against `fixtures/`, asserting the expected —\ndeliberately nonzero — exit codes per bucket.\n\n## MCP server (agent surface)\n\n`src/evidence_readiness/mcp_server.py` exposes the checker and the\nrequirement data to agents over the Model Context Protocol (stdio).\nThree tools: `check_trace_readiness` (file, directory, or inline JSON —\ninline content is processed in memory and never written anywhere),\n`get_requirement`, and `list_class_requirements`.\n\nInstalling the package delivers **three** console scripts, and it is worth\nbeing precise about which is which before you copy anything below:\n\n| script | what it runs |\n|---|---|\n| `evr` | the checker CLI — this is the one a human wants |\n| `evr-mcp` | the MCP server, on stdio |\n| `evidence-readiness` | the MCP server, on stdio — same target as `evr-mcp`, named for the distribution so that per-invocation runners which resolve `<package>` to a like-named script find it |\n\nSo `evidence-readiness` is **not** the checker. Typing it at a shell gets a\nserver waiting for JSON-RPC on stdin, which looks like a hang. Use `evr`.\n\nIf the package is installed, the `evr-mcp` console script is the whole\nconfiguration:\n\n```json\n{\n  \"mcpServers\": {\n    \"evidence-readiness\": {\n      \"command\": \"evr-mcp\"\n    }\n  }\n}\n```\n\nFrom a clone, with nothing installed, run the module by path instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"evidence-readiness\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"/absolute/path/to/evidence-readiness/src/evidence_readiness/mcp_server.py\"\n      ]\n    }\n  }\n}\n```\n\nEither way it needs no dependencies, and the second form needs no\ninstallation. It is **local-only**: no network calls, no phone-home,\nnothing persisted.\nIt deliberately has **no submission tool** — the server never transmits\nanything; submitting a trace anywhere is a human decision gated on the\n`CONTRIBUTING.md` disclaimer and a redaction judgment an agent cannot\nmake. Every tool description carries the presence-not-truth statement,\nso a readiness result cannot reasonably be relayed as \"this agent is\nsafe.\"\n\n<!-- mcp-name: io.github.BrienBounded/evr -->\n\n\n## Status\n\nThe specification is versioned ([SPEC.md](SPEC.md) carries its current\nversion and correction log) and the checker is implemented against it,\nwith reference fixtures (`fixtures/`), the machine-readable export\n(`spec.json`), the agent surface (`llms.txt`, the MCP server), and the CI action\n(`.github/actions/readiness-check/`) in place. The methodology and\nlimitations paper is drafted ([PAPER.md](PAPER.md)); its front-matter\nbanner records which sections have had an adversarial read and which\nhave not. The standing\ndisclosure policy is [SOURCE_AVAILABILITY.md](SOURCE_AVAILABILITY.md);\nreporting and trace-submission terms are\n[CONTRIBUTING.md](CONTRIBUTING.md), with redaction guidance in\n[REDACTION.md](REDACTION.md) and release verification in\n[RELEASING.md](RELEASING.md). Corrections are logged in `CHANGELOG.md`.\nThe spec is descriptive: every requirement is backed by an observed outcome\nin a validation record of 240 reconstruction attempts, **222 of them\nsynthetic** — backing is per-requirement, from the specific cases that\nexercised it, not a property measured across all 240 (18 real-world\nWho&When cases validate the abstention direction only; the split is stated\nwherever the count appears — SPEC.md §1).\n\n## Attribution\n\nBrien Buckman\n\nLicensed under Apache-2.0 (see `LICENSE`).\n\nThe substance of this repository's development record is public:\ncorrections that affect published content are logged in\n[CHANGELOG.md](CHANGELOG.md), and the development defect record, as it\nbears on the method, is summarized in PAPER.md §8.6. The commit history\nin which these files were drafted and revised is not published.\n",
  "bytes": 8954,
  "sha": "c43bc5adf4b0b7bea9b61814d6427f84f2efa9083b10d4829e86a67e2986df25",
  "repo_slug": "evidence-readiness/spec",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_brienbounded_evr_318b9843/readme"
}