Testigo — From Intent to Proof

Testigo is an open protocol for traceability, compliance and verification of actions executed by humans and AI agents, together.

Its purpose is to guarantee that every significant action can demonstrate:

• why it was performed;
• which human intent originated it;
• which requirement it was fulfilling;
• who — or which agent — executed it;
• what the human approved (and why);
• what evidence it produced;
• and what final result was deployed or used.

Testigo is not a task manager, a CI/CD platform, a coding agent or a payment system. It is a trust layer that connects the original intent with the execution and the verifiable evidence of the outcome. Witness, not gatekeeper: it records; it never orchestrates or blocks.

The chain

intent (prompt / ticket)
  → turn (agent works)
    → human approval (allow/deny + reason)
    → tool results
    → evidence (working-tree snapshots, files changed)
  → turn end
→ signed proof packet → anyone verifies, no install

Every link is an event in an append-only, sha256 hash-chained ledger (one per project, local-first). A segment of that ledger exports as an in-toto Statement signed as a DSSE Ed25519 envelope — the proof packet — verifiable with the standalone HTML verifier in this repo, or any DSSE tooling.

Quickstart: verify the example

1. Open the hosted verifier at https://cyl-castillo.github.io/testigo/verifier/testigo-verifier.html (or verifier/testigo-verifier.html locally). No install; verification runs entirely in your browser — the page makes no network requests with your packet.
2. Drop examples/demo.proofpack.json on it.
3. You should see: signature valid, subject digest OK, hash chain intact — including one redacted event (linkage verified, content declared unverifiable), one stub (an out-of-case event pruned to hashes), and a declared RFC 3161 timestamp (a real freetsa.org token over the packet's signature; the page checks the imprint and hands you the token plus the openssl commands rather than pretending to verify CMS in the browser).

Spec

The protocol is specified in SPEC.md (v0.1, draft). The predicate schema lives in schema/predicate-v0.1.schema.json.

Implementing a verifier? The conformance suite has golden vectors isolating every verification step — including valid signatures wrapped around internal defects — plus a zero-dependency reference verifier (node conformance/verify.mjs).

Reference implementation: agent-console (≥ v0.48.0) — captures the ledger ambiently from Claude Code / Codex sessions (prompts, approvals, tool results, per-turn diffs), exports and signs packets, and stamps console-made commits with Testigo-Case: trailers resolved from ledger evidence.

Packets can also commit to records held elsewhere — the Claude Code transcript at each turn end, an Anthropic Compliance API export, a GitHub agent session log — as external_evidence events (SPEC §1.7): the chain carries the record's location and sha256, a receiver with the platform's copy recomputes it. This is how a packet composes with what the platforms already log instead of competing with it.

Packets also record how the turn ended: a check_run event when the agent runs a recognized test or check command (passed or failed, exit code, sha256 of the full output) and a commit event when the work reaches git (SPEC §1.7). They are declared by the producer and the verifier labels them that way; what makes them checkable is what they bind — the output digest and the commit sha.

The engine-neutral reference core — ledger, export, verification, timestamps, external evidence — lives in packages/core; adapters per engine build on it (the Claude Code plugin ships a vendored copy, see #25 for the Codex and other plugins that follow).

Lightweight capture without the console: cli/ is a zero-dependency Node CLI that witnesses any Claude Code session via hooks, links cases, and exports signed packets — with the capture-scope differences stated plainly. Install it as a Claude Code plugin (this repo is its own marketplace):

/plugin marketplace add cyl-castillo/testigo
/plugin install testigo@testigo

Honesty by design

Testigo prefers a smaller true claim over a bigger false one:

• The local ledger is tamper-evident, not tamper-proof — signing happens at export, and a packet proves segment integrity + who signed it, not that the ledger is complete.
• The event→turn binding is heuristic (same terminal between a prompt and its stop), not cryptographic. The spec says so.
• Redacted events keep their original hashes: chain linkage stays verifiable, content verification is explicitly reported as unavailable.
• The packet embeds its public key for convenience; the trust anchor is the key id compared out-of-band with the publisher.

Real-world case study: a production deploy, witnessed

On 2026-07-15, a production deploy of Fixy (a Uruguayan services marketplace operated with AI agents) was verified through a Testigo- recorded session: one human intent (/fixy-status), three agent commands — each individually approved by a human — three captured results (services, API health, release state), and an empty turn diff proving the verification was read-only. Chain intact, packet signed and verified.

A redacted packet of this session is published at examples/fixy-deploy-verification.proofpack.json — drop it on the verifier: the human intent, the three approval decisions and the empty turn diff are fully verifiable; the agent's commands and outputs are redacted per the protocol (payload excluded, chain linkage intact, reported as such). The un-redacted packet stays private; both are signed by the same key:

event sequence	prompt → snapshot → (approval_request → approval_decision → tool_result) ×3 → turn_end
human approvals	3/3 commands, each with an explicit decision
turn diff	files: [] — read-only, provably
digest (private, full)	f8d7db3fff68a80dbc545acac6f4cb08ece4b5295f709235a4491fd5025d9e72
digest (published, redacted)	af21a0b7bfe48022764831415f1c82f45211f0b886ad59bbe4a19842308e0ceb
signer key id	8caf09075df11abbbdea5cd1d120a5654d8d1ce2a32e2a6f018dde557c5014da
generator	agent-console/0.79.0 (re-exported 2026-09-16 from the same ledger, after the redactionCount fix; the redacted segment digest is unchanged)

That a proof can be referenced without being revealed is part of the design: the digest and key id above commit publicly to evidence that can be disclosed selectively later (per-event redaction keeps the chain verifiable).

Status

• Spec: v0.2 (draft; additive over v0.1 — the process context of §2.6: provider, context artifacts, session window, owner — mirrors the FINOS Agentic Process Evidence shapes; packet format and predicate type URI unchanged, see docs/ape-mapping.md).
• Spec v0.1: field names and predicate type are stable within v0.1.
• Reference implementation: shipping since agent-console v0.45.0 (ledger), v0.46.0 (turn results), v0.47.0 (packets + verifier), v0.48.0 (timelines + commit trailers), v0.49.0 (pre-sign redaction review — the published case study below was produced with it).
• Spec'd and additive: git-ref ledger anchoring (§1.6), RFC 3161 timestamp of the packet signature (§2.5 — the demo example carries a real token).
• Roadmap: sigstore keyless signing, requirement links beyond Jira, cross-project cases.

License

MIT — see LICENSE.