Evidence packet

Purpose

An evidence packet collects the material needed to judge a proposed result. It contains a manifest, references to artifacts, provenance for each check, and an explicit account of missing or partial verification. It gives an evaluator a bounded input instead of asking it to reconstruct a run from chat history and temporary logs.

The packet records observations. It does not decide whether those observations are good enough. That decision belongs to an evaluator or approval checkpoint.

When to use

Build an evidence packet whenever work will be evaluated outside the process that produced it. This includes proposed code changes, release candidates, infrastructure plans, generated reports, migrations, and automated incident responses.

For a low-risk local edit, the packet can be a small manifest with a diff and one test result. For a production change, it may include build output, focused and regression checks, artifact digests, policy decisions, screenshots, and a list of checks that could not run.

Inputs and outputs

Inputs:

• the intent brief reference and workflow run identifier;
• the exact proposed artifact or change digest;
• test, build, lint, security, or evaluation results;
• logs and visual captures needed to support an acceptance check;
• tool names, versions, commands, timestamps, and execution environments;
• known gaps, skipped checks, warnings, and operator notes.

Outputs:

• an immutable packet manifest with its own digest;
• content-addressed references to included artifacts;
• a mapping from acceptance checks to supporting evidence;
• a completeness status such as complete, partial, or blocked;
• explicit declarations for absent evidence.

Smallest useful interface

type EvidenceItem = {
  id: string;
  kind: "change" | "check" | "log" | "capture" | "decision";
  uri: string;
  digest: string;
  producedBy: string;
  producedAt: string;
  exitStatus?: number;
};

type EvidencePacket = {
  runId: string;
  intentRef: string;
  subjectDigest: string;
  status: "complete" | "partial" | "blocked";
  items: EvidenceItem[];
  acceptanceMap: Record<string, string[]>;
  gaps: string[];
};

function sealEvidence(packet: EvidencePacket): {
  packetRef: string;
  packetDigest: string;
};

Sealing should reject an item without provenance or a referenced artifact that cannot be read. The packet digest should cover the manifest and the digests of its artifacts.

Example

runId: run-1842
intentRef: checkout-timeout-fix@1
subjectDigest: sha256:41de...
status: partial
items:
  - id: change
    kind: change
    uri: artifact://run-1842/checkout.patch
    digest: sha256:41de...
    producedBy: implementation-worker@3
    producedAt: 2026-08-13T09:14:00Z
  - id: timeout-test
    kind: check
    uri: artifact://run-1842/timeout-test.txt
    digest: sha256:21a7...
    producedBy: test-runner/node-24
    producedAt: 2026-08-13T09:18:00Z
    exitStatus: 0
acceptanceMap:
  timeout-response:
    - timeout-test
  successful-checkout-regression: []
gaps:
  - The full checkout integration suite could not reach its container registry.

The packet is useful even though it is partial. It supports the timeout claim and makes the missing regression evidence visible. An evaluator can return an insufficient-evidence verdict instead of treating the successful focused test as proof of the whole intent.

Failure modes

• The packet contains only a prose summary. Reviewers cannot inspect the source material. Include artifact references and digests.
• A passing exit code has no command or environment. The result cannot be interpreted or repeated. Record the producer, version, invocation, and relevant environment identity.
• Logs are dumped without a manifest. Important failures get buried and the evaluator must infer which log supports which claim. Map evidence to each acceptance check.
• Missing checks disappear. A packet looks complete because skipped work is absent. List gaps and derive status from required evidence.
• Evidence refers to a different change. Bind every packet to the exact subject digest and reject a packet when the artifact changes.
• The worker labels its own interpretation as fact. Separate observations, such as command output, from worker notes and inferred explanations.
• Secrets enter the packet. Redact credentials and sensitive payloads before storage. Keep a record that redaction occurred without preserving the secret.

What it does not solve

An evidence packet does not prove that a test is well designed, that an environment matches production, or that a screenshot shows the right user flow. It does not make the producer independent. It also does not replace the source systems that enforce access and retention. The packet gives evaluation a stable input; it cannot supply judgment that the workflow never defined.

Related reading

• Intent brief
• Independent evaluator
• Human approval checkpoint
• A passing test is not a good result