SuperBizAgent-java/openspec/changes/archive/2026-07-04-rag-l0-domain-entity-hint/specs/rag-knowledge-retrieval/spec.md

ADDED Requirements

Requirement: Knowledge retrieval SHALL keep L0 as a hint provider

The lookup_knowledge retrieval flow SHALL retain L0 keyword/frontmatter matching but use it as domain, entity, and explainability hint data rather than as the sole final retrieval decision.

Scenario: L0 produces traceable hint data

• WHEN L0 matches one or more indexed knowledge entries
• THEN the retrieval flow SHALL expose matched titles, matched keywords, domains or categories, and entity terms as structured hint data

Scenario: L0 does not bypass semantic retrieval by default

• WHEN L0 returns exactly one match
• THEN the retrieval flow SHALL still attempt semantic L1 retrieval unless L1 is unavailable or explicitly disabled by configuration

Requirement: Knowledge retrieval SHALL use L0 domain as optional L1 filter

The retrieval flow SHALL use L0 domain/category information as an optional metadata filter for L1 retrieval when the domain is unambiguous.

Scenario: Single domain filter

• WHEN L0 hint data contains exactly one nonblank domain or category
• THEN the L1 retrieval request SHALL include that category as a metadata filter

Scenario: Ambiguous domain fallback

• WHEN L0 hint data contains zero domains or multiple domains
• THEN the L1 retrieval request SHALL run without an L0-derived category filter

Requirement: Knowledge retrieval SHALL preserve fallback evidence

The retrieval flow SHALL still return useful L0 evidence when L1 produces no usable result.

Scenario: L1 has no results

• WHEN L0 has at least one match and L1 returns no candidates
• THEN the tool SHALL return an L0-based primary result
• AND the relevance assessment SHALL not claim semantic support from L1

Scenario: L1 fails

• WHEN L0 has at least one match and L1 retrieval throws or fails
• THEN the tool SHALL return an L0-based primary result
• AND the tool invocation record SHALL preserve the L0 hint details

Requirement: Knowledge retrieval SHALL persist L0 hints

The system SHALL persist L0 hint details in tool_invocation.retrieval_details for lookup_knowledge calls.

Scenario: Retrieval details include L0 hints

• WHEN a lookup_knowledge call records a tool invocation
• THEN retrieval_details SHALL include L0 matched keywords, domains, entities, and titles when available

Scenario: Retrieval layer reflects cooperating retrieval

• WHEN both L0 hint data and L1 candidates participate in a lookup
• THEN the recorded retrieval layer SHALL be L0+L1