023-Quote-anchored citations for code-grounded reviews

Type: ../types/adr.md · Status: accepted

Status: accepted Date: 2026-06-01 Extends: ADR-011 Amended by: ADR-059 (external authorization is collection-owned)

Context

agent-memory-system-review notes make agent-generated claims about external systems. Today those claims cite the source at document granularity — a source-relative file path in a code span, or a commit-pinned GitHub URL. That is enough to locate the file but not to check the claim: a cited file can be real while the cited paragraph does not support the assertion. The citation-faithfulness literature names this gap directly (a citation can be structurally correct yet unfaithful) and finds coarse document-level citation insufficient for verification.

The mature anchor format for "point at a span in a source that may drift" is settled prior art. The W3C Web Annotation Data Model and Hypothesis's fuzzy-anchoring implementation both converge on the same answer: the quoted text is the robust anchor (a TextQuoteSelector), and byte/character offsets are only an optional locating cache — they are brittle and never load-bearing for verification. The same work separates two layers we keep distinct here:

  • Structural grounding — the quoted text actually appears in the cited source.
  • Semantic faithfulness — the source actually supports the claim.

Only the first is mechanizable cheaply. The second is not left to ad-hoc judgment either: it is operationalized as the semantic/grounding-alignment review gate, which reads the cited source and checks attribution accuracy, scope overreach, and whether the conclusion follows from the evidence. This ADR addresses the structural half; the gate is its semantic complement, and the two are designed to compose — quote-anchoring narrows the structural question to a deterministic check so the gate's LLM judgment can spend itself on faithfulness rather than re-confirming the quote exists.

One constraint is specific to this collection and shapes the whole design: the reviewed source is not retained in the KB. ADR-011 and the review type require reviews to remain readable without the source; the type's constraints forbid storing the source tree under reviews/; the checkout (source_dir) is transient, prepared by the parent skill at review time and gone afterward. So a later, repo-local validator cannot resolve a quote against the source — the bytes are not there. But review citations pin an immutable commit, so "does this quote resolve?" is a one-time question answered at authoring time, not a drift question that recurs.

Decision

Adopt quote-anchored citations for load-bearing findings in main analyses and their specialist handoffs. The exact-result and memory-report types define the current contract; the agent-memory-system-review type retains the historical convention.

The convention

A load-bearing claim is anchored by quoting the verbatim supporting text as a blockquote whose final line is a --- attribution naming the source location pinned to the reviewed commit (a source-relative path in a code span, or a commit-pinned blob URL). The quoted text is the anchor; the pinned commit is the position. No byte offsets, character spans, or ids — the quote is self-relocating and the commit is immutable, so nothing else is needed.

Coverage

Quote the minimum source text supporting disputed mechanisms, comparison classifications and assessments. Retain each passage once on the supporting canonical record; lens overlays and the compact review may refer to that record. Ordinary navigation citations remain valid. A complete main result or memory report with no quote anchor fails structural validation. That minimum cannot certify that every load-bearing finding has adequate evidence; claim support remains a semantic check.

Verification splits by where the source lives

  • Resolution is a publication check. analyse-agentic-system resolves every quote in its exact result, memory report and compact review candidate against the Git blob at the run's recorded full commit. It never reads quote evidence from the worktree. A missing blob, mismatched repository or revision, or quote absent after whitespace normalization blocks publication. This check belongs to the parent publication bundle because that boundary has the frozen source and every candidate byte together. Historical memory reviews are outside this publication path. The specialist memory report is an analytical handoff, not independent semantic clearance; publication does not create a semantic-review job.
  • The standing validator checks shape only. For reviews it confirms each quote-anchored citation is well-formed and names a source. It cannot resolve the quote offline, because the source is not retained — and does not need to, because the pinned commit cannot drift.
  • kb/sources/ is where standing resolution would live. Snapshots there are retained immutably in the repo, so a future standing validator could resolve quotes against them with no network. Not built now (one use site today); recorded as the natural home if the convention is reused.

Authorization lives in COLLECTION.md; citation shape lives in the type spec

agent-memory-systems/COLLECTION.md authorizes links to the reserved external destination. The agent-memory-system-review type then refines that permission with its quote-anchor, commit-pinning, and validation rules. The type owns the specialized citation shape, but cannot independently broaden the collection's permitted targets (ADR 059).

Consequences

Easier

  • Claims become self-evidencing. A reader sees the supporting text inline instead of a file path they cannot open — this strengthens ADR-011 rather than fighting it.
  • The structural half of grounding becomes mechanical. The grounding-alignment gate's "quote-level accuracy" check gets a deterministic component, freeing the gate's judgment for whether the claim follows.
  • No schema, no new file kinds, no offsets. The anchor is markdown the review already contains; the validator reuses document parsing.

Harder

  • Authors must quote precisely. A paraphrase in the blockquote fails resolution. The blockquote must be verbatim.
  • Resolution depends on the frozen source being available during publication. Because the source is not retained, a quote outside that checked publication path cannot be verified later from the KB alone without retrieving the external repository at the pinned commit.

Not changing

  • Document-level citations remain valid for ordinary navigation. Load-bearing findings retain quoted evidence in the exact result; line numbers do not replace verification of the text.
  • Semantic faithfulness requires a separate judgment. The semantic/grounding-alignment gate supplies that judgment when invoked; quote resolution does not invoke it or imply that it passed.
  • The reviewed source stays out of the KB (ADR-011 and the type constraints stand).

Relevant Notes