SuperBizAgent-java/openspec/changes/archive/2026-07-04-rag-evidence-postprocess/design.md

Context

The previous change converted L0 into a hint provider and made L0/L1 cooperate. The next step is to stop treating the tool output as an unstructured primary/supplement pair. The Agent can keep receiving compatible fields, but retrieval internals and traces should have structured evidence blocks.

This change is a bridge toward later DocumentPostProcessor-style behavior. It should be small enough to archive independently and should not introduce Spring AI dependencies.

Goals / Non-Goals

Goals:

• Add EvidenceBlock DTOs to LookupResult.
• Create evidence blocks from L0 matches and L1 results.
• Deduplicate evidence by stable source key.
• Capture source, title, breadcrumb, score, retrieval layer, hit reasons, and content preview.
• Persist evidence blocks and postprocess counts in tool_invocation.retrieval_details.

Non-Goals:

• Do not implement neighbor chunk expansion yet.
• Do not replace primary/supplement output.
• Do not add cross-encoder or LLM rerank.
• Do not migrate to Spring AI DocumentPostProcessor yet.

Decisions

Decision: Add evidence blocks while preserving existing result fields

LookupResult will gain List<EvidenceBlock> evidenceBlocks. Existing primary, supplement, found, relevanceLevel, and completenessHint remain compatible.

Rationale: this lets the Agent continue using the current shape while tests and traces begin validating the new evidence model.

Decision: Keep postprocess rule-based

The evidence builder will use deterministic rules:

• L0 entries become L0 evidence.
• L1 candidates become L1 evidence.
• Same source key is deduplicated.
• Hit reasons are collected from L0 hints, L1 rank, category filters, and fallback state.

Rationale: this is explainable, cheap, and suitable before introducing framework postprocessors.

Decision: Persist compact evidence summaries

ToolInvocationRecorder will store compact evidence block metadata, not full content, inside retrieval_details.

Rationale: tool_invocation should remain useful for trace review without duplicating large chunks.

Risks / Trade-offs

• Evidence source keys may be imperfect before full metadata normalization -> fall back to file path, metadata, title, then rank.
• Agent prompts may ignore evidenceBlocks initially -> keep primary/supplement compatibility.
• Adding content previews increases tool output size -> cap evidence content length.