SuperBizAgent-java/openspec/changes/archive/2026-07-04-rag-l0-domain-entity-hint/proposal.md

Why

The current lookup_knowledge implementation treats a unique L0 keyword hit as high confidence and skips L1 semantic retrieval. That makes L0 too authoritative for the RAG refactor target: L0 should provide domain/entity hints, metadata-filter intent, and explainability while final evidence still comes from the retrieval pipeline.

What Changes

• Change L0 from final retrieval decision maker to domain/entity hint provider.
• Add structured L0 hint output that includes matched keywords, domains, entities, and matched titles.
• Make lookup_knowledge run L1 semantic retrieval by default even when L0 has a unique hit.
• Use L0 domain hints to pass category metadata filters into L1 when a single clear domain is detected.
• Persist L0 hint details in tool_invocation.retrieval_details.
• Keep lookup_knowledge as the explicit Agent tool entry point.
• No Spring AI VectorStore migration in this change.

Capabilities

New Capabilities

• rag-knowledge-retrieval: Defines runtime behavior for the explicit RAG knowledge retrieval tool, including L0 hinting and L1 retrieval cooperation.

Modified Capabilities

• None.

Impact

• Affects KnowledgeIndexService, LookupKnowledgeTool, and ToolInvocationRecorder.
• May affect retrieval latency because L1 is no longer skipped for unique L0 hits.
• Improves traceability by recording L0 matched keywords/entities/domains in retrieval details.
• Does not change document upload, chunking, Milvus schema, or Agent flow.