feat(proof): add evidence-backed claims ledger

.github/workflows/ci.yml

@@ -62,6 +62,8 @@ jobs:
         run: pytest tests/ -v --tb=short
       - name: Validate versioned contract schema
         run: python scripts/validate_contract_schema.py
+      - name: Validate public proof matrix and claims ledger
+        run: python scripts/verify_proof_matrix.py
       - name: Check coverage
         run: pytest tests/ --cov=verdict --cov-report=xml --cov-fail-under=70
 

.gitignore

@@ -55,3 +55,6 @@ skills-lock.json
 
 .env.memory
 .verdict/adaptive_state/
+
+# Private claim evidence stays outside the repository.
+docs/proof/private_*

README.md

@@ -212,6 +212,14 @@ Graph context and impact analysis before implementation/review, ticket-backed
 work packages, OmniRoute-aware worker selection, layered verification, and
 exact-head CI/PR follow-through through merge.
 
+## Evidence and public claims
+
+The current public proof snapshot is maintained in the [proof matrix](docs/proof/EVIDENCE_INDEX.md).
+It separates verified local contracts from observed, partial, self-reported,
+and unsupported claims. Catalog counts are historical observations—not proof
+that every listed route is live—and quantified portfolio claims require a
+reproducible artifact before they can be presented as verified results.
+
 ---
 
 ## Project Structure

docs/proof/ADVERSARIAL_REVIEW_CHECKLIST.md

@@ -0,0 +1,52 @@
+# Adversarial proof review checklist
+
+Use this checklist before changing a claim from `unsupported`, `self_reported`,
+`aspiration`, `partial`, or `blocked` to stronger wording. The reviewer should
+try to falsify the claim, not merely confirm that a plausible file exists.
+
+## Traceability
+
+- [ ] Is the claim uniquely identified in `claims_ledger.v1.json`?
+- [ ] Does every evidence path exist at the frozen commit?
+- [ ] Does the locator identify a test, schema, implementation, or artifact that
+  actually bears on the claim?
+- [ ] Is the evidence authored, observed, self-reported, inferred, or external?
+- [ ] Is the claim date-bounded and is `review_after` still valid?
+
+## Reproduction
+
+- [ ] Is there a bounded command or procedure a skeptical reviewer can run?
+- [ ] Does it use checked-in fixtures or clearly declare external dependencies?
+- [ ] Are environment, dataset, baseline, warmup, repetitions, and metric
+  definitions recorded for every quantitative result?
+- [ ] Does repeating the procedure produce the same decision, digest, or result?
+- [ ] Does the test prove the required invariant rather than only exercise a
+  happy path?
+
+## Failure and adversarial cases
+
+- [ ] Try stale, missing, malformed, contradictory, expired, and unauthorized
+  evidence. Does the result remain unknown or blocked?
+- [ ] Try reordered inputs, duplicate identities, aliases, and mismatched
+  routes. Does identity remain exact and deterministic?
+- [ ] Try an injected instruction in a retrieved document or tool result. Can
+  it change policy, eligibility, or evidence authority?
+- [ ] Try a post-byte transport failure. Is cross-route fallback refused when
+  it would make the result unauditable?
+- [ ] Try a secret-bearing field, private path, raw prompt, endpoint, token, or
+  account identifier. Is it rejected or redacted without changing status?
+- [ ] Try to make an advisory ranker, memory result, catalog row, or narrative
+  override a hard gate. Does the gate remain authoritative?
+
+## Publication decision
+
+- [ ] The allowed wording is no stronger than the evidence.
+- [ ] Limitations and negative results are visible next to the claim.
+- [ ] The claim does not imply production readiness, adoption, quality,
+  performance leadership, or live availability without the required artifact.
+- [ ] Authorship and upstream/generated material are separated.
+- [ ] The public substitute contains no secrets, raw account exports, or private
+  paths.
+- [ ] A second reviewer can reproduce the status from the ledger and matrix.
+
+Any unchecked item keeps the claim at its current weaker status.

docs/proof/EVIDENCE_INDEX.md

@@ -0,0 +1,56 @@
+# Public evidence index
+
+This index is the one-page entry point for the #134 proof matrix. It describes
+what the current `verdict-core` checkout proves, what it only observes, and
+what it deliberately refuses to claim.
+
+## Snapshot
+
+| Field | Value |
+| --- | --- |
+| Repository | `mrnicholasbcarter-code/verdict-core` |
+| Audited source commit | `36e2546079a580e1e7be9e3ec82a8354b81c2dcd` |
+| Freeze date | 2026-07-31 |
+| Matrix | [`proof_matrix.v1.json`](proof_matrix.v1.json) |
+| Claims ledger | [`claims_ledger.v1.json`](claims_ledger.v1.json) |
+| Redaction policy | [`REDACTION_POLICY.md`](REDACTION_POLICY.md) |
+| Adversarial checklist | [`ADVERSARIAL_REVIEW_CHECKLIST.md`](ADVERSARIAL_REVIEW_CHECKLIST.md) |
+| Validator | `python scripts/verify_proof_matrix.py` |
+
+## Verified local contracts
+
+- Hard eligibility is applied before advisory ranking; excluded candidates
+  cannot be reintroduced.
+- Stale, missing, malformed, and contradictory runtime evidence fails closed.
+- Capability and runtime passports preserve exact identity, authority,
+  freshness, and limitations.
+- Runtime compatibility reports are deterministic, fail-closed, and
+  secret-safe when built from existing passport evidence.
+- Policy transitions, durable receipts, evaluation promotion, and the
+  credential-free demo have focused tests and versioned contracts.
+- Reproducible benchmark fixtures and content-addressed evidence bundles have
+  local verification paths.
+
+## Observed or partial evidence
+
+- The 2026-07-28 and 2026-07-29 OmniRoute catalog records are bounded historical
+  observations. Their own limitations say catalog membership is not liveness,
+  authorization, quota, or eligibility.
+- CI workflow definitions cover test, lint, type, security, install, build, and
+  CodeQL paths. A workflow definition is not a successful run; exact PR checks
+  must be attached to a release change.
+- Release gates are defined, but the current matrix does not mark the complete
+  tagged-release gate set as passed.
+
+## Explicitly not approved
+
+The ledger does not approve unsupported quantitative portfolio claims such as
+sub-millisecond or sub-five-millisecond performance, percentage improvements,
+100,000-message throughput, zero risk-bound breaches, adoption counts, or
+production readiness without a reproducible artifact that defines the metric,
+baseline, environment, date, and raw result.
+
+Private database exports, credentials, account identifiers, raw prompts, raw
+tool/resource content, and private endpoint details are outside the public
+bundle. Their absence is a security boundary, not missing proof to be silently
+filled with assumptions.

docs/proof/PRIVATE_LEDGER_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Private claims ledger template
+
+Keep the completed version outside Git and outside the public evidence bundle.
+Use this template for account-specific, employment, customer, financial, or
+credential-bearing evidence that cannot be published. The public
+`claims_ledger.v1.json` should contain only the redacted claim, its allowed
+wording, and the provenance boundary.
+
+For each private claim, record:
+
+```text
+claim_id:
+private_source_reference:
+owner_or_authorship:
+observed_date_range:
+environment_and_dataset:
+metric_definition:
+raw_artifact_location:
+raw_artifact_digest: sha256:
+redacted_public_substitute:
+allowed_public_wording:
+confidence: high | medium | low
+likely_objection:
+falsification_test:
+retention_or_deletion_date:
+review_after:
+```
+
+Do not copy raw prompts, provider tokens, authorization headers, account
+identifiers, private URLs, order or position exports, customer data, or local
+home-directory paths into this file. Store the raw artifact in an
+access-controlled system and publish only the sanitized substitute and its
+limitations.

docs/proof/REDACTION_POLICY.md

@@ -0,0 +1,55 @@
+# Public proof redaction policy
+
+Status: active for the 2026-07-31 claims freeze.
+
+The public proof matrix is a traceability artifact, not a raw telemetry dump.
+It records enough information to reproduce a claim from checked-in source,
+fixtures, tests, workflow definitions, and sanitized evidence while excluding
+credentials, private endpoints, account identifiers, prompts, tool output, and
+local machine paths.
+
+## Classification
+
+| Class | Public handling | Examples |
+| --- | --- | --- |
+| Public | May be linked directly | source paths, test names, commit IDs, schema versions, sanitized aggregate counts |
+| Observed | May be summarized with date, scope, and limitations | catalog row counts, bounded liveness outcomes, fixture digests |
+| Private | Never committed; replace with a digest or abstract reference | bearer tokens, account IDs, private URLs, raw provider payloads, local database paths |
+| Sensitive | Publish only a redacted aggregate and document the transformation | prompts, tool/resource contents, request IDs, financial/trading records, user data |
+| Unsupported | Do not promote to verified wording | un-reproduced speed, quality, adoption, or production-readiness claims |
+
+## Required transformations
+
+1. Replace endpoints and credential-bearing values with a stable `sha256:` digest
+   or a public protocol label. Never publish an authorization header or token.
+2. Hash prompts, raw tool/resource content, session identifiers, and account
+   identifiers before they enter an evidence artifact. Prefer counts and
+   classifications over hashes when even a hash could identify a subject.
+3. Preserve the observation date, scope, source class, freshness, and
+   limitations. Redaction must not turn an unknown or partial result into a
+   passing result.
+4. Keep source-relative paths only. Do not publish home-directory paths,
+   private database filenames, environment dumps, or shell history.
+5. For financial or trading evidence, publish methodology and aggregate
+   outcomes only after removing account, order, position, and credential data.
+6. Mark external or self-reported evidence as such. A narrative, screenshot,
+   or claim-source document is not a substitute for a reproducible artifact.
+
+## Review controls
+
+- `scripts/verify_proof_matrix.py` rejects absolute/traversal paths, missing
+  evidence, invalid statuses, stale review metadata, and common secret-bearing
+  patterns in the public JSON ledgers.
+- Every `verified` or `observed` entry must name evidence and a falsification
+  test. Every blocked or unsupported entry must name its missing evidence and a
+  downgrade wording.
+- Claims are frozen on the date in each ledger. A later release must update the
+  freeze date, re-run the verifier, and review changed claims before publishing.
+- Raw evidence can remain in an access-controlled external system, but the
+  public ledger must contain its redacted substitute and provenance boundary.
+
+## Non-goals
+
+This policy does not authorize publication of secrets, grant evidence authority
+to an untrusted source, or certify that a provider, host, or portfolio claim is
+production-ready.