SuperBizAgent-java/openspec/changes/archive/2026-07-04-rag-evidence-postprocess/specs/rag-knowledge-retrieval/spec.md

ADDED Requirements

Requirement: Knowledge retrieval SHALL return structured evidence blocks

The lookup_knowledge retrieval flow SHALL expose retrieved evidence as structured evidence blocks in addition to the existing compatibility fields.

Scenario: Evidence block contains source metadata

• WHEN a lookup_knowledge call returns evidence
• THEN each evidence block SHALL include source, title when available, breadcrumb when available, retrieval layer, content, and hit reasons

Scenario: Compatibility fields remain available

• WHEN evidence blocks are returned
• THEN the existing primary and supplement result fields SHALL remain available when their source evidence exists

Requirement: Knowledge retrieval SHALL deduplicate evidence blocks

The retrieval flow SHALL remove duplicate evidence blocks before returning them to the Agent.

Scenario: Duplicate source deduplication

• WHEN L0 and L1 produce evidence with the same source identity
• THEN the retrieval flow SHALL keep a single evidence block for that source
• AND the evidence block SHALL preserve hit reasons from both retrieval paths when available

Scenario: Postprocess count tracking

• WHEN evidence post-processing completes
• THEN the tool invocation details SHALL record candidate count and final evidence block count

Requirement: Knowledge retrieval SHALL persist evidence block summaries

The system SHALL persist compact evidence block summaries in tool_invocation.retrieval_details.

Scenario: Evidence summaries are persisted

• WHEN a lookup_knowledge call records a tool invocation
• THEN retrieval_details SHALL include evidence block summaries containing source, title, retrieval layer, score when available, and hit reasons

Scenario: Full content is not duplicated into retrieval details

• WHEN evidence block summaries are persisted
• THEN full evidence content SHALL be omitted or truncated so the trace record remains compact