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

1. L0 Hint Model

• 1.1 Add structured L0 hint analysis in KnowledgeIndexService.
• 1.2 Preserve exactMatch compatibility for existing callers.

2. Retrieval Flow

• 2.1 Update LookupKnowledgeTool so unique L0 hits no longer skip L1 by default.
• 2.2 Apply a category filter to L1 only when L0 hint data has one clear domain.
• 2.3 Preserve L0 fallback evidence when L1 is empty or fails.
• 2.4 Adjust relevance assessment so PRECISE no longer depends only on unique L0.

3. Trace Recording

• 3.1 Extend ToolInvocationRecorder.LookupKnowledgeRecord with L0 matched keywords, domains, and entities.
• 3.2 Persist L0 hint fields in retrieval_details.

4. Tests

• 4.1 Add or update unit tests for L0 hint extraction.
• 4.2 Add or update tests for lookup_knowledge unique-L0 plus L1 participation.
• 4.3 Run targeted tests and the RAG retrieval baseline evaluator.

5. Validation

• 5.1 Run OpenSpec validation for the change.
• 5.2 Review git diff to confirm only expected code/spec/test files changed.