evidence-foundation

name	evidence-foundation
description	Build a traceable evidence foundation for research claims from user-provided sources and retrieval tools that are actually available. Use for literature grounding, source identity checks, claim-evidence mapping, evidence gaps, and creation of the canonical evidence-ledger.json sidecar.

Evidence Foundation

Create the evidence base that downstream design, drafting, and review Skills can inspect. Retrieval is optional; traceability is not.

Retrieval boundary

Use supplied sources first. Use a connected retrieval or browser tool only when it is actually available and authorized. Do not require a particular provider, API, account, or model. If a capability is unavailable or unconfigured, state that fact and continue only with the evidence already supplied.

Never claim exhaustive coverage, full-text access, source verification, or novelty based on model memory. Do not substitute a similar article for a target source. Do not bypass paywalls, authentication, CAPTCHA, or access controls.

Canonical sidecar

Create evidence-ledger.json from ../../templates/evidence-ledger.json. Minimum fields:

• top level: schema_version, status, evidence_cutoff, sources[], claims[], gaps[];
• source: source_id, type, locator, provenance, identity_status, verification_method, access_level, verified_at;
• claim: claim_id, text, source_ids[], status, disposition, evidence_anchors[], limitations[];
• evidence anchor: source_id, locator;
• gap: gap_id, description, required_action, status.

Use schema version pi-research/evidence-ledger/1.x. Top-level status is ready, partial, or blocked; only ready can pass. Claim status is supported, partially supported, contradicted, missing evidence, or not assessed. Claim disposition is use, use_with_limitations, remove, or stop. A partially supported claim may continue only as use_with_limitations with a non-empty limitation; contradicted, missing, and unassessed claims must be removed or stopped. Gap status is resolved, open, or blocked; only resolved can pass.

Source identity status is verified, partial, unverified, or mismatch; access level is metadata, abstract, full_text, or user_material. Every consequential claim must carry exact evidence anchors that name a registered source_id and a location inside that source. source_ids[] alone is not an evidence anchor. A mismatch or unverified source cannot support a claim whose disposition is use.

Also create a human-readable evidence-ledger.md from ../../templates/evidence-ledger.md. The Markdown must mirror the JSON and must not add evidence.

Workflow

1. Freeze the question, evidence cutoff, and search boundary.
2. Register each supplied or retrieved source with a stable ID.
3. Verify source identity using stable identifiers when possible, otherwise title, author, year, and venue. Record the method and result.
4. Record access level: metadata, abstract, verified full text, or user-provided material.
5. Map each consequential claim to source IDs and exact anchors. Keep the source-level identity/access record and the claim-level support location separate.
6. Classify claims as supported, partially supported, contradicted, missing evidence, or not assessed.
7. When a manuscript and reference list are supplied, run citation hygiene checks that are locally observable: in-text citation to reference-list coverage in both directions, duplicate entries, conflicting supplied metadata, identifier syntax, and claim-to-source-to-anchor coverage. Distinguish these structural checks from external identity or truth verification.
8. Record gaps and the concrete evidence or action needed to close them.

An identifier that resolves does not by itself prove that the source supports a claim. A structurally valid ledger does not establish scientific truth.

Fail-closed rules

Set ledger status to blocked when source identity is mismatched, a required artifact cannot be parsed, a supported claim lacks a traceable source, or a blocking gap remains. Tool failure is not verification. Do not auto-repair citations or silently downgrade mismatches.

Call record_checkpoint with the evidence cutoff, blocking gap, or strongest claim boundary before finishing. Prefix the statement with [evidence-ledger.json].

Output

Return the JSON path, Markdown mirror, coverage summary, citation-hygiene status when assessable, blocking gaps, and explicit limitations. Match the user's language.