evidence-ledger git:20260726.1f35e1fA

Immutable. This exact content is served forever at /api/v1/blob/c3bea5d36b0f84e4.

---
name: evidence-ledger
description: "Record every material claim as a row in `00-control/evidence-ledger.md` carrying a source-authority level and a claim state (verified, corroborated, reported, inferred, unknown, not applicable), and keep observed, interpreted, unknown, and recommended content in visibly separate blocks. Use when inventorying sources, when drafting any sentence that asserts a fact, or when a verification pass asks what backs a claim. This skill MUST be consulted because an assertion without an `[EV-####]` citation and a claim state is indistinguishable from a guess, and a package whose claims cannot be traced to executable reality fails diligence at the first spot-check."
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
context: fork
agent: general-purpose
---

# Evidence Ledger

The register every material claim in the package traces back to. Owns claim states, source authority, and the separation of fact from interpretation.

## Iron Law

**NO ASSERTION WITHOUT A LEDGER ROW AND A CLAIM STATE. If you cannot cite `[EV-####]`, write "Unknown" instead of writing prose.**

The failure this prevents is not fabrication. It is the confident, plausible, unsourced sentence that a reader acts on — and that nobody can check six months later without redoing the whole inspection.

## What needs a row

A **material claim** is one that could change an investment, acquisition, partnership, procurement, or security decision; change how a teammate modifies, deploys, operates, or troubleshoots the system; change what a partner builds against; or change what a customer believes the product does, guarantees, stores, protects, or supports.

Everything else is prose and needs no row. "This document explains the deployment model" is prose. "Deployments are zero-downtime" is a claim, and a strong one.

## The six states

| State | Entry condition | May appear |
|---|---|---|
| `V` verified | Directly supported by authoritative current evidence, or an executed check whose output is retained | Internal and public, unqualified |
| `C` corroborated | Two independent current sources agree, **at least one authoritative for this claim type** | Internal and public, unqualified |
| `R` reported | Stated by a stakeholder or an existing document, not independently verified | Internal, labelled. **Never public** |
| `I` inferred | Reasoned from indirect evidence, chain stated | Internal, labelled. **Never public** |
| `U` unknown | Unavailable, inaccessible, or unresolvably contradictory | Internal, as a stated unknown |
| `N/A` | Demonstrably irrelevant, with a reason and evidence | Internal, at section level |

Two documents agreeing is not `C` when one was copied from the other. Independence means neither derives from the other; circular sourcing between package documents is a specific thing verification hunts for.

Full definitions, the seven authority levels, and per-project-type instantiation: `references/source-authority-and-claim-states.md`. Row shape, identifier grammar, non-file source conventions, and append rules: `references/evidence-ledger-schema.md`.

## Prefer executable reality

When sources conflict, record the conflict as a `CT-####` row, then prefer the higher-authority source: executed checks and runtime observation, then versioned code and immutable records, then current telemetry, then approved specifications, then tickets and prose, then recollection, then inference.

Three qualifications keep this honest:

1. **It is a default, not a substitute for judgment.** A level-1 observation against a misconfigured staging environment is worse than a level-4 approved specification for production.
2. **Higher authority is not the same as current.** Freshness is an independent axis, which is why every row carries `Observed` and `Version/env`.
3. **Authority describes the source, not the claim.** Reading an infrastructure definition is strong evidence about *what the file says* and weak evidence about *what is deployed*. Rows routinely need splitting on exactly this boundary.

## Citing

Inline, immediately after the asserted sentence: `Deployments run through a blue-green cutover. [EV-0042]`

Multiple rows: `[EV-0042, EV-0043]`. A paragraph where every sentence shares one row cites once at the end. A paragraph mixing supported and unsupported sentences must be split — a trailing citation does not retroactively cover the sentence before it.

Non-`V`/`C` claims carry their state in the prose, not only in the ledger:

- `Reported: the team states that backups are tested quarterly. [EV-0118, R]`
- `Inferred: the retry path appears idempotent based on the handler's key construction; not confirmed by an executed test. [EV-0207, I]`
- `Unknown: no evidence establishes whether the analytics replica is encrypted at rest. [AQ-0031]`

## Separate the four registers of speech

Never blend these in one paragraph. A reader must be able to tell, without checking anything, which is which.

| Register | Marker | Rule |
|---|---|---|
| **Observed** | Plain assertion + `[EV-####]` | What the evidence directly shows |
| **Interpreted** | `Inferred:` prefix or an `I`-state citation | What it probably means. Never stated as fact |
| **Unknown** | `Unknown:` prefix + `AQ-####` | What cannot be established. Never silently omitted |
| **Recommended** | `Recommendation:` prefix, in a recommendations section | What should change. **Never written as though already implemented** |

The last row is the most frequently violated. "Secrets are rotated every 90 days" describing an intention is a false statement about the present.

## Verify rather than describe

Where the action ceiling permits, execute the check instead of reading about it: run the documented setup, build, and test commands; compare API documentation against implemented routes; compare architecture prose against imports and deployment definitions; validate examples against schemas.

A check that could not run is `not executed` with the reason. Never presented as passed, never quietly omitted. `runTests: false` in the scope is a legitimate reason; "it seemed fine" is not.

## Absence is not evidence

No known incident is not proof of security. No open issue is not proof of quality. A missing test is not proof the behaviour is broken, and a passing test proves only what it asserts. Each of these is `U`, and each is more useful to a reader as an honest unknown than as a comfortable inference.

## Output Format

Append to the ledger table in `00-control/evidence-ledger.md`. Rows are append-only: corrections supersede, never overwrite.

```markdown
| Evidence ID | Claim | State | Source ref | Retrievable | Authority | Version/env | Observed | Freshness | Confidentiality | Public use | Consuming docs | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| EV-0001 | {atomic, falsifiable statement} | V | {locator} | yes | 2 | {sha} | {ISO date} | none | Internal | pending | {paths} | — |
```

Each run also appends to the ledger's executed-checks section:

```markdown
| Check | Scope | Environment | Date | Result | Evidence |
|---|---|---|---|---|---|
| {command} | {what it covers} | {env} | {ISO} | pass / fail / not executed | {artifact path or reason} |
```

Never copy a secret, a credential, or raw sensitive evidence into the ledger. Record the type, the location category, and the remediation need.

## Rationalization Prevention

| Excuse | Response |
|--------|----------|
| "This is obviously true, it does not need a row" | Obvious claims are the ones nobody re-checks. Rows are cheap; unchecked assumptions are not. |
| "The README says so, that is my evidence" | That is level 5 and yields `R`. It is not `V`, and it may never go public alone. |
| "Two docs agree, so it is corroborated" | Only if neither was copied from the other, and one is authoritative for this claim type. |
| "The test file exists, so the behaviour is verified" | A test that was not run is level 2 evidence about the assertions, not level 1 about the behaviour. |
| "The IaC says three replicas, so there are three replicas" | The file says three. What is deployed is a separate claim needing a separate row. |
| "There is no record of an incident, so it is reliable" | Absence of evidence is not evidence of absence. That is `U`. |
| "I will add the citations at the end" | Then you will approximate them. Cite as you write, while you still know which row you meant. |
| "It is a recommendation, everyone will understand" | Not once it is quoted out of context. Prefix it. |

## Integration

Loaded by `dossier-evidence-collector` during inventory, by `dossier-doc-drafter` for every document, and by `dossier-pass-a-evidence` during verification. `/dossier:baseline` and `/dossier:refresh` invoke it throughout drafting. `bin/dossier-ledger-lint.sh` enforces the mechanical rules.

References: `references/evidence-ledger-schema.md`, `references/source-authority-and-claim-states.md`, `references/register-schemas.md`.