Evidence and citations

Use this workflow when an answer, review, or report needs claims that can be traced to current repository source.

Distinguish discovery, identity, and proof

Frigg exposes three different layers:

1. A search or navigation row locates candidate evidence.
2. result_handle plus match_id binds that row to the source revision observed by its producer.
3. read_match verifies the binding against live source and returns the proof window.

A target_ref is an executable identity for navigation. It is not a quotation or durable citation. A handle is session-scoped and can expire or become stale after edits.

Produce a proof-bound read

1. Run search_text, search_symbol, search_hybrid, search_batch, document_symbols, or a navigation tool.

2. Select a row that includes match_id and a response that includes result_handle.

3. Call read_match with the pair:

   {
     "result_handle": "<RESULT_HANDLE>",
     "match_id": "m1",
     "before": 5,
     "after": 10,
     "presentation_mode": "citation"
   }

4. Cite the returned canonical path and the 1-based lines printed as LINE|content.

Citation presentation is available on read_file, read_match, and explore zooms. It changes rendering, not evidence trust. Prefer read_match when the claim depends on a specific earlier result; use read_file when you intentionally need current live source at a known path.

Recover from changed source

Frigg refuses to return bytes when a proof identity no longer matches live source:

Error	Action
STALE_HANDLE	Re-run the producer in the current session.
MIXED_HANDLE	Pair the match with the handle from the same response.
STALE_PROOF_ANCHOR	Re-run the producer against current source; do not cite the old location.

You can include the exact producer request as read_match.origin. Successful reads ignore it. On stale or mixed evidence, Frigg can use it to return a typed producer retry in next_actions without creating recursive read chains.

After editing a touched path, do not reuse its pre-edit proof handles. Check freshness and evidence for snapshot versus live-disk behavior.

Compose an evidence packet

Read frigg://policy/evidence-packet.json for the current claim schema and template. It describes a compact claim-to-source packet using fields such as:

• claim text;
• producer tool;
• canonical repository-relative path;
• 1-based source span;
• optional result_handle and match_id correlation.

The resource is a template, not a tool and not sealed authority. Populate it only from actual tool responses. A useful claim should state what the cited source demonstrates and keep uncertainty when navigation is heuristic or incomplete.

Use target references for deeper evidence

If the candidate row includes target_ref, copy it unchanged into navigation:

{
  "target": {
    "kind": "result_match",
    "result_handle": "<RESULT_HANDLE>",
    "match_id": "m1",
    "target_scope": "<OPAQUE_SCOPE>"
  },
  "include_definition": false,
  "limit": 50
}

Then proof-read the returned reference or definition rows. This preserves target identity while moving from discovery to code relationships.

Treat navigation trust honestly

• precise navigation is stronger than heuristic_no_precise, but still read completeness before claiming coverage.
• unavailable_no_precise is not evidence of absence.
• outgoing_calls is always provisional. Confirm material edges with a proof read, references, or structural search.
• An exact test_mention proves a literal mention under a test path, not that the test executes the target.

Use playbook citations only when required

A playbook-enabled extended runtime can run, replay, and compose citations from deterministic traces. Use that surface when a trace artifact or replay diff is a requirement. Normal evidence work should use producer rows plus proof reads.

Playbook citation composition skips failed steps and non-file results. Its citations point to source-bearing trace steps; they do not make old handles durable. See MCP resources, prompts, and playbooks.

Verify citations

Before publishing:

• confirm every claim has a source-bearing read;
• preserve the returned canonical path and 1-based span;
• remove citations from stale proof attempts;
• label ranked, heuristic, provisional, truncated, or incomplete evidence;
• avoid treating an omitted impact section as a zero result.

Source Anchors

• ../frigg/crates/cli/src/mcp/types/workspace.rs
• ../frigg/crates/cli/src/mcp/types/target.rs
• ../frigg/crates/cli/src/mcp/server/presentation.rs
• ../frigg/crates/cli/src/mcp/guidance.rs
• ../frigg/crates/cli/src/mcp/types/playbook.rs
• ../frigg/crates/cli/src/mcp/server/playbook.rs
• ../frigg/crates/cli/tests/citation_payloads.rs
• ../frigg/crates/cli/tests/tool_handlers/proof_handle_producers.rs