Improve DB-backed retrieve scoring

Author: tae2089

guide/annotations.md

@@ -63,6 +63,40 @@ Use `ccg://{namespace}/{path}#{symbol}` in `@see` when a behavior depends on cod
 
 The path and symbol are optional, so `ccg://auth-svc/internal/auth` can point at a package/path scope and `ccg://auth-svc/` can point at a whole namespace.
 
+## Retrieval Quality
+
+Annotations are retrieval features. `retrieve_docs` and generated docs rank
+file-level evidence from structured buckets such as `@index`, `@intent`,
+`@domainRule`, `@sideEffect`, `@requires`, `@ensures`, and `@see`. Better
+annotations make natural-language retrieval more precise, but only when the
+tags describe real behavior.
+
+Use tags by need:
+
+| Situation | Preferred tags |
+|-----------|----------------|
+| File/package should be discoverable as a unit | `@index` |
+| Public function, handler, CLI command, service method, or UI workflow has a clear purpose | `@intent` |
+| Policy, constraint, false-positive/false-negative criterion, or operational rule matters | `@domainRule` |
+| Code writes DB/files, calls network, changes cache, logs important events, or starts processes | `@sideEffect` |
+| Receiver or input state is changed | `@mutates` |
+| Input contract or output guarantee matters to callers | `@requires`, `@ensures` |
+| Understanding requires jumping to another implementation or namespace | `@see` |
+
+Good retrieval annotations use the words an engineer or LLM would naturally ask
+for, while staying faithful to the code. For example, if a UI graph component
+focuses a resolved `ccg://` node, the annotation should say so. Do not add
+unrelated keywords just to increase score; broad or false terms make unrelated
+files outrank the real implementation.
+
+Avoid over-annotation:
+
+- Skip trivial getters, setters, tiny wrappers, and obvious one-line helpers.
+- Do not repeat the same keyword across many tags unless each tag adds distinct
+  evidence.
+- Prefer one accurate `@domainRule` over several vague `@intent` lines.
+- Keep `@see` for real navigation edges, especially cross-namespace references.
+
 ## AI-Driven Annotation
 
 Coding agents with the `/ccg-annotate` skill can analyze your codebase and

guide/ko/annotations.md

@@ -59,6 +59,39 @@ func AuthenticateUser(username, password string) (string, error) {
 
 path와 symbol은 선택 사항입니다. `ccg://auth-svc/internal/auth`는 패키지/경로 범위, `ccg://auth-svc/`는 네임스페이스 전체를 가리킬 수 있습니다.
 
+## Retrieval 품질 (Retrieval Quality)
+
+어노테이션은 retrieval feature입니다. `retrieve_docs`와 생성 문서는
+`@index`, `@intent`, `@domainRule`, `@sideEffect`, `@requires`, `@ensures`,
+`@see` 같은 구조화된 bucket을 파일 단위 근거로 점수화합니다. 자연어 검색
+품질은 좋은 어노테이션으로 올라가지만, 태그가 실제 동작을 설명할 때만
+효과가 있습니다.
+
+필요에 맞게 태그를 선택하십시오:
+
+| 상황 | 권장 태그 |
+|------|-----------|
+| 파일/패키지가 하나의 검색 단위로 발견되어야 함 | `@index` |
+| public 함수, handler, CLI command, service method, UI workflow의 목적이 중요함 | `@intent` |
+| 정책, 제약, false-positive/false-negative 기준, 운영 규칙이 중요함 | `@domainRule` |
+| DB/파일 write, 네트워크 호출, 캐시 변경, 중요한 로그, 프로세스 실행이 있음 | `@sideEffect` |
+| receiver 또는 입력 상태를 변경함 | `@mutates` |
+| 입력 계약이나 결과 보장이 호출자에게 중요함 | `@requires`, `@ensures` |
+| 다른 구현이나 namespace로 이동해야 이해됨 | `@see` |
+
+좋은 retrieval 어노테이션은 엔지니어나 LLM이 자연스럽게 물어볼 표현을
+사용하되, 코드의 실제 역할을 벗어나지 않습니다. 예를 들어 UI graph
+component가 resolved `ccg://` node를 focus한다면 어노테이션에도 그 사실이
+드러나야 합니다. 점수를 올리기 위해 관련 없는 키워드를 넣지 마십시오.
+넓거나 거짓인 표현은 실제 구현이 아닌 파일을 위로 올립니다.
+
+과한 어노테이션은 피하십시오:
+
+- 단순 getter/setter, 작은 wrapper, 자명한 한 줄 helper는 건너뜁니다.
+- 각 태그가 별도 근거를 추가하지 않는다면 같은 키워드를 반복하지 않습니다.
+- 모호한 `@intent` 여러 줄보다 정확한 `@domainRule` 하나가 낫습니다.
+- `@see`는 실제 이동 가치가 있는 연결, 특히 cross-namespace ref에 사용합니다.
+
 ## AI 기반 어노테이션 (AI-Driven Annotation)
 
 `/ccg-annotate` 스킬을 사용할 수 있는 코딩 에이전트는 코드베이스를 분석하여

internal/ctxns/namespace.go

@@ -1,4 +1,4 @@
-// @index context.Context에 namespace를 전파하는 유틸리티 패키지.
+// @index context.Context에 namespace를 전파하고 namespace-scoped DB/search/query 호출의 기본값을 정규화하는 유틸리티 패키지.
 package ctxns
 
 import "context"
@@ -10,7 +10,7 @@ type ctxKey struct{}
 const DefaultNamespace = "default"
 
 // Normalize replaces an empty namespace with DefaultNamespace, leaving other values unchanged.
-// @intent guarantee callers always observe a non-empty namespace string for store and query layers.
+// @intent normalize namespace query parameter values so store, retrieve_docs, and DB search layers always observe a non-empty namespace string.
 func Normalize(ns string) string {
 	if ns == "" {
 		return DefaultNamespace

internal/db/db.go

@@ -1,4 +1,4 @@
-// @index Database connection and search-backend selection helpers for SQLite and PostgreSQL.
+// @index Database connection, SQLite WAL/busy_timeout, connection pool, and search-backend selection helpers for SQLite and PostgreSQL.
 package db
 
 import (
@@ -69,7 +69,7 @@ func Open(driver, dsn string) (*gorm.DB, error) {
 
 // ConfigurePool applies database-specific connection pool settings.
 // @intent apply connection-pool limits that match each database driver's concurrency model.
-// @domainRule sqlite is pinned to MaxOpenConns=1 because it supports only one writer at a time.
+// @domainRule sqlite is pinned to MaxOpenConns=1 because it supports only one writer at a time and FTS query workloads share the same DB file.
 // @mutates sqlDB connection-pool settings.
 func ConfigurePool(sqlDB SQLDBPool, driver string) {
 	if driver == "sqlite" {

internal/mcp/handler_docs_test.go

@@ -1127,8 +1127,8 @@ func TestRetrieveDocs_DBPrimaryTakesPrecedenceOverDocIndex(t *testing.T) {
 	}
 
 	response := decodeRetrieveDocsResponse(t, result)
-	if len(response.Results) != 1 {
-		t.Fatalf("results = %d, want 1: %#v", len(response.Results), response.Results)
+	if len(response.Results) == 0 {
+		t.Fatalf("results = 0, want DB primary result")
 	}
 	if !strings.Contains(response.Results[0].Content, "DB fallback content") || !strings.Contains(response.Results[0].DocPath, "internal/db/only.go") {
 		t.Fatalf("expected DB primary result, got %#v", response.Results[0])

internal/mcp/tools_docs.go

@@ -25,7 +25,7 @@ func docsTools(h *handlers) []server.ServerTool {
 				mcp.WithString("node_id", mcp.Description("Tree node ID as shown in search/retrieve/tree results (e.g. 'community:internal/analysis', 'package:internal/core', or 'file:internal/core/runtime.go'). Omit only for a bounded overview with depth set.")),
 				mcp.WithString("community_id", mcp.Description("Deprecated alias for node_id; accepts any tree node ID for compatibility.")),
 				mcp.WithNumber("depth", mcp.Description("Maximum tree depth to return (1=top-level communities/packages, 2=plus child packages/files). Recommended when node_id is omitted. Default: 0 (unlimited, only for small namespaces).")),
-				mcp.WithString("namespace", mcp.Description("Namespace. When set, reads that namespace's DB tree or wiki-index.json fallback.")),
+				mcp.WithString("namespace", mcp.Description("Namespace. When set, reads that namespace's DB-backed tree.")),
 			),
 			Handler: h.getRagTree,
 		},
@@ -39,20 +39,20 @@ func docsTools(h *handlers) []server.ServerTool {
 		},
 		{
 			Tool: mcp.NewTool("search_docs",
-				mcp.WithDescription("Search the RAG document tree by keyword. Matches against node labels and summaries. Returns breadcrumb paths to matching nodes."),
+				mcp.WithDescription("Search DB-backed documentation candidates by keyword. Matches graph nodes and annotation evidence, then returns breadcrumb paths to matching files."),
 				mcp.WithString("query", mcp.Description("Search keyword (case-insensitive)"), mcp.Required()),
 				mcp.WithNumber("limit", mcp.Description("Maximum number of results (default: 10, max: 500)")),
-				mcp.WithString("namespace", mcp.Description("Namespace. When set, searches the namespace-specific doc-index.json.")),
+				mcp.WithString("namespace", mcp.Description("Namespace. When set, searches that namespace's DB-backed documentation candidates.")),
 			),
 			Handler: h.searchDocs,
 		},
 		{
 			Tool: mcp.NewTool("retrieve_docs",
-				mcp.WithDescription("Retrieve relevant generated docs for a natural-language or multi-keyword query. Uses DB-backed graph evidence first, falls back to doc-index.json when DB retrieval is unavailable, and returns matched evidence plus bounded document content."),
+				mcp.WithDescription("Retrieve relevant generated docs for a natural-language or multi-keyword query. Uses DB-backed graph evidence and returns matched evidence plus bounded document content."),
 				mcp.WithString("query", mcp.Description("Natural-language or multi-keyword retrieval query"), mcp.Required()),
 				mcp.WithNumber("limit", mcp.Description("Maximum number of document results (default: 5, max: 50)")),
 				mcp.WithNumber("content_limit", mcp.Description("Maximum bytes of Markdown content per result (default: 4000, max: 20000; use 0 to omit content)")),
-				mcp.WithString("namespace", mcp.Description("Namespace. When set, retrieves from that namespace's DB rows or namespace-specific doc-index.json fallback.")),
+				mcp.WithString("namespace", mcp.Description("Namespace. When set, retrieves from that namespace's DB rows and generated docs.")),
 				mcp.WithBoolean("explain", mcp.Description("When true, include available per-result diagnostics such as field_scores, literal_score, expanded_terms, and expansion_score (default: false).")),
 			),
 			Handler: h.retrieveDocs,

internal/retrieval/helpers.go

@@ -25,7 +25,7 @@ func IsRetrievableNodeKind(kind model.NodeKind) bool {
 }
 
 // DBFileGroup은 파일 경로별로 묶인 DB 후보 노드 그룹이다.
-// @intent retrieve_docs DB 폴백이 파일 단위 결과 세분성을 유지하도록 후보를 그룹화한다.
+// @intent retrieve_docs DB-backed 결과가 파일 단위 세분성을 유지하도록 후보를 그룹화한다.
 type DBFileGroup struct {
 	FilePath string
 	Nodes    []model.Node
@@ -39,39 +39,102 @@ func DBCandidateLimit(limit int) int {
 }
 
 // MatchedTerms는 쿼리 문자열을 소문자 토큰으로 분리하고 중복을 제거한다.
-// @intent DB 폴백 응답 증거를 위해 검색 쿼리를 결정론적 소문자 용어로 토큰화한다.
+// @intent DB-backed 응답 증거를 위해 검색 쿼리를 결정론적 소문자 용어로 토큰화하고 코드 식별자 alias를 보강한다.
 func MatchedTerms(query string) []string {
 	seen := map[string]struct{}{}
 	terms := make([]string, 0)
-	for term := range strings.FieldsSeq(strings.ToLower(query)) {
-		term = strings.Trim(term, `"'()[]{}.,:;!?`)
+	addTerm := func(term string) {
+		term = strings.TrimSpace(term)
 		if term == "" {
-			continue
+			return
 		}
 		if _, ok := seen[term]; ok {
-			continue
+			return
 		}
 		seen[term] = struct{}{}
 		terms = append(terms, term)
 	}
+	for term := range strings.FieldsSeq(strings.ToLower(query)) {
+		term = strings.Trim(term, `"'()[]{}.,:;!?`)
+		addTerm(term)
+	}
+	baseLen := len(terms)
+	for i := 0; i+1 < baseLen; i++ {
+		left, right := terms[i], terms[i+1]
+		if left == "" || right == "" || strings.Contains(left, "_") || strings.Contains(right, "_") {
+			continue
+		}
+		for _, alias := range []string{left + "_" + right, left + right} {
+			addTerm(alias)
+		}
+	}
+	for _, term := range terms[:baseLen] {
+		for _, alias := range retrievalTermAliases(term) {
+			addTerm(alias)
+		}
+	}
 	return terms
 }
 
+// @intent expand common natural-language retrieval terms into code identifier variants without calling an LLM reranker.
+func retrievalTermAliases(term string) []string {
+	switch term {
+	case "reference":
+		return []string{"ref", "refs"}
+	case "references":
+		return []string{"reference", "ref", "refs"}
+	case "ref":
+		return []string{"reference", "refs"}
+	default:
+		return nil
+	}
+}
+
 // TextContainsAnyTerm은 텍스트가 주어진 용어 중 하나라도 포함하는지 대소문자 무시로 확인한다.
-// @intent DB 폴백 매칭 필드 진단을 위한 단순 대소문자 무시 용어 포함 검사를 수행한다.
+// @intent DB-backed 매칭 필드 진단을 위한 단순 대소문자 무시 용어 포함 검사를 수행한다.
 func TextContainsAnyTerm(text string, terms []string) bool {
 	if text == "" || len(terms) == 0 {
 		return false
 	}
 	lower := strings.ToLower(text)
 	for _, term := range terms {
-		if term != "" && strings.Contains(lower, term) {
+		if containsRetrievalTerm(lower, term) {
 			return true
 		}
 	}
 	return false
 }
 
+// @intent match natural-language terms against code identifiers and hyphenated prose using the same collapsed form.
+func containsRetrievalTerm(lowerText, term string) bool {
+	if term == "" {
+		return false
+	}
+	if strings.Contains(lowerText, term) {
+		return true
+	}
+	if !strings.ContainsAny(lowerText, "_-/.:#") {
+		return false
+	}
+	collapsedTerm := collapseRetrievalText(term)
+	if collapsedTerm == term || len(collapsedTerm) < 3 {
+		return false
+	}
+	return strings.Contains(collapseRetrievalText(lowerText), collapsedTerm)
+}
+
+// @intent collapse separators so cross_namespace, cross-namespace, and cross namespace can match the same evidence.
+func collapseRetrievalText(text string) string {
+	var b strings.Builder
+	b.Grow(len(text))
+	for _, r := range text {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
 // NodeMatchesTerms는 노드 또는 어노테이션 텍스트가 검색 용어 중 하나라도 일치하는지 확인한다.
 // @intent 저장된 노드 또는 어노테이션 텍스트가 검색 용어와 일치하는지 감지한다.
 func NodeMatchesTerms(node model.Node, terms []string) bool {
@@ -133,7 +196,7 @@ func BuildDBResult(group DBFileGroup, annotations map[uint]*model.Annotation, te
 }
 
 // BuildDBResultWithOptions derives one file-level retrieve_docs candidate and optional diagnostics.
-// @intent score DB-backed retrieve_docs candidates from structured annotation buckets while keeping FTS order as a deterministic tie-breaker.
+// @intent score DB-backed retrieve_docs candidates from structured annotation buckets while preserving backend rank in response order.
 func BuildDBResultWithOptions(group DBFileGroup, annotations map[uint]*model.Annotation, terms []string, index int, opts Options) ragindex.RetrieveResult {
 	score, fieldScores, matchedTerms := ScoreDBFields(group.Nodes, annotations, terms)
 	fields := sortedFieldNames(fieldScores)
@@ -151,7 +214,7 @@ func BuildDBResultWithOptions(group DBFileGroup, annotations map[uint]*model.Ann
 		Summary:       summary,
 		DocPath:       filepath.ToSlash(filepath.Join("docs", filepath.FromSlash(group.FilePath)+".md")),
 		Path:          DBPath(group.FilePath),
-		Score:         score*1000 + orderScore(index),
+		Score:         score,
 		MatchedTerms:  matchedTerms,
 		MatchedFields: fields,
 	}
@@ -162,8 +225,8 @@ func BuildDBResultWithOptions(group DBFileGroup, annotations map[uint]*model.Ann
 	return result
 }
 
-// MatchedFields는 DB 폴백 파일 히트를 설명하는 노드 메타데이터 또는 어노테이션 버킷을 보고한다.
-// @intent DB 폴백 매칭 필드 진단을 위해 어떤 노드 메타데이터 또는 어노테이션 버킷이 파일 히트를 설명하는지 보고한다.
+// MatchedFields는 DB-backed 파일 히트를 설명하는 노드 메타데이터 또는 어노테이션 버킷을 보고한다.
+// @intent DB-backed 매칭 필드 진단을 위해 어떤 노드 메타데이터 또는 어노테이션 버킷이 파일 히트를 설명하는지 보고한다.
 func MatchedFields(nodes []model.Node, annotations map[uint]*model.Annotation, terms []string) []string {
 	return sortedFieldNames(ScoreDBFieldBreakdown(nodes, annotations, terms))
 }
@@ -217,26 +280,26 @@ func scoreDBFields(nodes []model.Node, annotations map[uint]*model.Annotation, t
 			}
 			if lowerName == term {
 				addOnce("label", 12, term)
-			} else if strings.Contains(lowerName, term) {
+			} else if containsRetrievalTerm(lowerName, term) {
 				addOnce("label_contains", 7, term)
 			}
-			if strings.Contains(lowerQN, term) {
+			if containsRetrievalTerm(lowerQN, term) {
 				addOnce("qualified_name", 4, term)
 			}
-			if strings.Contains(lowerPath, term) {
+			if containsRetrievalTerm(lowerPath, term) {
 				addOnce("path", 2, term)
 			}
 			if ann == nil {
 				continue
 			}
-			if strings.Contains(strings.ToLower(ann.Summary), term) || strings.Contains(strings.ToLower(ann.Context), term) {
+			if containsRetrievalTerm(strings.ToLower(ann.Summary), term) || containsRetrievalTerm(strings.ToLower(ann.Context), term) {
 				addOnce("annotation_text", 2, term)
 			}
-			if strings.Contains(strings.ToLower(ann.RawText), term) {
+			if containsRetrievalTerm(strings.ToLower(ann.RawText), term) {
 				addOnce("generic", 1, term)
 			}
 			for _, tag := range ann.Tags {
-				if !strings.Contains(strings.ToLower(tag.Value), term) && !strings.Contains(strings.ToLower(tag.Name), term) {
+				if !containsRetrievalTerm(strings.ToLower(tag.Value), term) && !containsRetrievalTerm(strings.ToLower(tag.Name), term) {
 					continue
 				}
 				addOnce(dbFieldName(tag.Kind), dbFieldWeight(tag.Kind), term)
@@ -297,17 +360,8 @@ func sortedTerms(terms map[string]struct{}) []string {
 	return out
 }
 
-// @intent keep DB backend candidate order as a small deterministic tie-breaker after structured scoring.
-func orderScore(index int) int {
-	score := dbCandidateCap - index
-	if score < 0 {
-		return 0
-	}
-	return score
-}
-
-// DBSummary는 그룹화된 DB 폴백 노드에서 첫 번째 사용 가능한 어노테이션 요약/태그 값을 선택한다.
-// @intent 첫 번째 사용 가능한 어노테이션 요약 또는 태그 값을 간결한 파일 수준 DB 폴백 요약으로 선택한다.
+// DBSummary는 그룹화된 DB-backed 노드에서 첫 번째 사용 가능한 어노테이션 요약/태그 값을 선택한다.
+// @intent 첫 번째 사용 가능한 어노테이션 요약 또는 태그 값을 간결한 파일 수준 DB-backed 요약으로 선택한다.
 func DBSummary(nodes []model.Node, annotations map[uint]*model.Annotation) string {
 	for _, node := range nodes {
 		ann := annotations[node.ID]
@@ -326,8 +380,8 @@ func DBSummary(nodes []model.Node, annotations map[uint]*model.Annotation) strin
 	return ""
 }
 
-// DBPath는 정규화된 파일 경로 세그먼트로부터 DB 폴백 결과의 비어있지 않은 경로 조각을 생성한다.
-// @intent 정규화된 파일 경로 세그먼트로부터 DB 폴백 결과의 비어있지 않은 경로 조각을 생성한다.
+// DBPath는 정규화된 파일 경로 세그먼트로부터 DB-backed 결과의 비어있지 않은 경로 조각을 생성한다.
+// @intent 정규화된 파일 경로 세그먼트로부터 DB-backed 결과의 비어있지 않은 경로 조각을 생성한다.
 func DBPath(filePath string) []string {
 	parts := strings.Split(filepath.ToSlash(filePath), "/")
 	path := make([]string, 0, len(parts)+1)
@@ -340,8 +394,8 @@ func DBPath(filePath string) []string {
 	return path
 }
 
-// DBMatches는 그룹화된 DB 폴백 노드에 대한 간결한 검색 스타일 증거 항목을 생성한다.
-// @intent 그룹화된 DB 폴백 노드에 대한 간결한 검색 스타일 증거 항목을 생성한다.
+// DBMatches는 그룹화된 DB-backed 노드에 대한 간결한 검색 스타일 증거 항목을 생성한다.
+// @intent 그룹화된 DB-backed 노드에 대한 간결한 검색 스타일 증거 항목을 생성한다.
 func DBMatches(nodes []model.Node, annotations map[uint]*model.Annotation) []ragindex.SearchResult {
 	if len(nodes) == 0 {
 		return nil