Evidence ledger

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.

| 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:

| 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.