docs: build a claim registry tied to modern comparative evidence

Problem

ContextWeaver's public claim surface still reflects the historical runtime story: token reduction, bounded routing, context firewall/gateway breadth and a compiler/runtime capability surface.

#758 now makes D1 — deterministic capability snapshot + semantic drift — the active product hypothesis. Claims must follow that evidence reset rather than preserve architecture through marketing language.

This issue is the canonical claim discipline for #855/#847 and eventual distribution. It is not a request to invent stronger claims.

Evidence classes

Every material public claim should be classified as:

proven

Supported by a reproducible artifact under the exact scoped contract being claimed.

fixture-bound

True for a committed deterministic fixture/test but not evidence of general user value.

unverified

Plausible product hypothesis without enough comparative/adoption evidence.

rejected

A claim evidence contradicted or the project deliberately refuses to make. Keep these discoverable so future agents do not reintroduce them.

D1 claims to track first

Deterministic snapshot

Candidate claim:

Identical supported source bytes produce a deterministic normalized capability snapshot under the documented D1 schema/adapter contract.

Evidence required: #857 tests/CI and exact source/version scope.

Do not generalize this to all agent configuration, runtime state, external resources or provider behavior.

Semantic capability diff

Candidate claim:

D1 reports capability additions/removals and structured field paths changed between two valid snapshots, separating documentation-only changes from invocation-contract changes under its documented heuristic taxonomy.

Important caveat: D1 does not claim a complete JSON-Schema compatibility/breaking-change decision procedure. potentially_breaking is a review hint for specified paths such as required/type/enum.

MCP/OpenAPI/native normalization

Claim support only for the exact source representations covered by tests and maintained examples.

For MCP, distinguish the logical D1 comparison identity from the historical schema-sensitive routing identity. Do not imply live MCP execution/discovery is required for snapshot/diff.

verify

Candidate claim:

D1 verifies snapshot structure, ordering/identity invariants and the capability digest.

Explicit non-claims: security certification, authorization, deployment approval, runtime trust or tool correctness.

D1 user-value claim remains unverified

The strategic D1 proposition is:

Capability snapshots + semantic drift materially improve a real review/manual/risk process enough that independent users retain the workflow.

This stays unverified until #840/#855/#658/#551 produce evidence. A green test suite or successful maintained fixture cannot upgrade it.

D2 / D3 remain unverified

D2 — bounded / phase-aware context compilation

Do not claim current differentiated user value until contemporary native mechanisms are compared and real users show consequential pull.

D3 — deterministic custom routing

Do not claim superiority to modern provider-native tool search/deferred loading or simple retrieval. #445/#560/#492 are blocked evidence tracks, not current proof.

Historical token/context claims

#841 identified a mixed-estimator evidence defect. Until repaired:

• do not use the historical percentage reduction headline to sell D1;
• treat old ranges as methodologically suspect fixture evidence;
• do not silently rewrite estimator provenance;
• even repaired naive-all-tools comparisons are not evidence of superiority to contemporary native tool search;
• prompt-input reduction is not end-to-end cost or task-success evidence.

The D1 README/front door (#847) should not need token reduction to explain the product experiment at all.

Historical runtime/firewall/gateway claims

Existing code/docs may continue to describe behavior that is still shipped truthfully, but distinguish:

1. behavior exists;
2. behavior is maintained for current compatibility/security obligations;
3. behavior is part of the active product expansion thesis.

Only (1)/(2) may currently be true for many historical surfaces. Do not turn existing implementation into evidence that the product should continue investing in it.

Do not claim:

• every agent needs ContextWeaver;
• the gateway should be a production control plane;
• custom routing is generally better than native tool search;
• phase-aware compilation improves answer quality by default;
• the context firewall is superior to current runtime/provider intermediate-result mechanisms;
• ContextWeaver replaces authn/authz/orchestration/execution;
• Weaver Stack composition is required to use D1.

Adoption claims

Only #551/#658/#840/#855 evidence can justify language such as:

• independent projects use D1;
• D1 is retained in real workflows;
• unassisted users reach first value reliably;
• capability drift is a painful problem for target teams;
• removing ContextWeaver would create meaningful inconvenience.

Stars, forks, downloads, synthetic demos, maintainer-created integrations, contributor activity and AI-authored integrations do not prove adoption.

Canonical registry

Create/update docs/claims.md or equivalent with concise fields:

Claim	Status	Exact scope	Baseline / alternative	Reproducer/evidence	Caveat / falsifier	Freshness

Prefer links to evidence over duplicated narrative.

For externally changing baselines, record evaluation date/provider/product/version where applicable.

README / distribution discipline

Before targeted D1 distribution is interpreted:

• #847 front door must use only appropriately scoped D1 claims;
• maintained example success is labelled fixture evidence, not user-value proof;
• ordinary Git/config/tests are named as the obvious alternative;
• #841 token headline is absent from D1 selling copy while unresolved;
• #855/#658 funnel evidence remains separate from traffic/stars/downloads.

Before broad launch under #350, refresh any externally changing comparison claims.

Acceptance criteria

• canonical claim registry is D1-first;
• deterministic snapshot/diff/verify claims have exact scope and reproducers;
• D1 user value remains unverified until real evidence exists;
• D2/D3 differentiated-value claims remain unverified unless their gates run;
• #841 historical token claims are quarantined/scoped correctly;
• existing runtime behavior is not confused with active product-thesis evidence;
• adopter claims require #551/#658/#840/#855;
• rejected/non-claims are explicit and discoverable;
• #847 and future distribution materials link/use the registry accurately.

Related

• #758 — controlling survival decision
• #855 — distribution-quality gate
• #856 / #857 — D1 implementation evidence
• #847 — D1-first README
• #841 — token evidence integrity
• #840 / #658 / #551 — problem, activation and retention evidence
• #445 — blocked D2/D3 comparative evidence
• #350 — broad distribution after proof

Start with docs/claims.md or its equivalent and review #856/#857, #841, and the acceptance criteria. Record D1, historical, D2/D3, adoption, and rejected/non-claim entries with exact scope, evidence links, caveats, and freshness. Done means #847 and future distribution material use only appropriately scoped registry claims.