feat(harness,rag): dual LLM audit fields, run conclusion, and hybrid quality

Persist provider reasoning and assistant text separately on agent_reasoning_audit
(DeepSeekAssistantMessage path), extract diagnosis_run.conclusion, enrich RAG
tool audit (step_id/query/qualityScore), gate empty mysql tools, drop devtools,
and align MVP docs after live E2E verification.

openspec/changes/archive/2026-07-28-rag-quality-score-unify/.archive-ready

@@ -0,0 +1 @@
+

openspec/changes/archive/2026-07-28-rag-quality-score-unify/.committed

@@ -0,0 +1,6 @@
+Committed OpenSpec
+change: rag-quality-score-unify
+committed_at: 2026-07-28
+scale: standard
+interface_impact: L2
+gate: proposal+design+specs+tasks+cross-artifact+audit

openspec/changes/archive/2026-07-28-rag-quality-score-unify/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-28

openspec/changes/archive/2026-07-28-rag-quality-score-unify/brief.md

@@ -0,0 +1,20 @@
+# Brief: rag-quality-score-unify
+
+## Background
+
+True BM25 hybrid retrieval is live, but post-processing still normalizes as if every score were dense L2 and re-ranks with L0 keyword contains boosts. That splits ranking authority from quality gates and double-counts lexical signal.
+
+## Goals
+
+- Unify score labels to `dense` | `hybrid`.
+- Single `toQualityScore`; label-agnostic post-process.
+- Preserve retrieval rank; remove boost re-rank.
+- Hybrid quality = pure rank mapping (slice 1).
+
+## Scope
+
+Internal RAG pipeline: store emission, normalizer, evidence post-process, tests, architecture docs.
+
+## Non-goals
+
+Fine re-rankers, query rewrite, neighbor chunks, schema rebuild, ACI field renames, removing dense comparison mode.

openspec/changes/archive/2026-07-28-rag-quality-score-unify/decisions.md

@@ -0,0 +1,136 @@
+# Decisions — rag-quality-score-unify
+
+## sm-flow meta
+
+- **Checkpoint**: Discover（clarify + context + propose + grill）
+- **Scale**: standard
+- **Capability**: sm-flow 内置协议；openspec CLI `new change`；grill 使用内置协议（conversation-confirmed + evidence-driven），标注 fallback：未调用外部 `grill-with-docs` skill 文件执行器
+- **Slug**: `rag-quality-score-unify`
+- **OpenSpec path**: `openspec/changes/rag-quality-score-unify/`
+
+## Clarify summary
+
+| 项 | 内容 |
+|---|---|
+| 问题 | hybrid 已 RRF 融合，后处理仍 L2 伪装 + 关键词 boost 改序，质量信号不统一 |
+| 期望 | label 仅 dense/hybrid；toQualityScore 唯一归一化；后处理保 rank、去 boost 改序 |
+| 影响代码 | `MilvusHybridKnowledgeStore`, `VectorSearchService`, `KnowledgeEvidencePostProcessor`, retrieval 包新类, DTO 注释, 测试, 架构文档 |
+| 非目标 | 精排/rewrite/邻块、删 dense mode、改 ACI 字段结构、改 schema |
+
+## Context summary (devflow)
+
+| 来源 | 结论 | 需进 OpenSpec |
+|---|---|---|
+| `devflow/index.md` | rag-chunk-identity / bm25-hybrid / hybrid-rrf 均 archived | 是：承接不回退 |
+| `rag-bm25-hybrid-drop-sdk/decisions.md` | 曾要求 dense L2 enrichment 兼容阈值 | **是：本 change 废止该 decision** |
+| glossary | lookup_knowledge 为证据工具；不在此改 ACI 主结构 | 是：非目标 |
+| 架构文档 §6.0 | mode dense=对照，hybrid=主路径 | 是：保留 |
+
+**index 使用状态**: 已命中相关 RAG 条目。
+
+## Question pool (grill)
+
+| ID | 维度 | 模式 | 问题 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | user-interview（对话已确认） | 一级 scoreLabel 是否只有 dense/hybrid，bm25_only 不作正式 label？ | **已确认** |
+| Q2 | 边界 | user-interview（对话已确认） | 后处理是否去掉关键词 contains 加分改序，仅保 originalRank？ | **已确认** |
+| Q3 | 边界 | user-interview（对话已确认） | 归一化是否唯一 toQualityScore；后处理 label-agnostic？ | **已确认** |
+| Q4 | 验收 | user-interview（对话已确认） | dense mode 保留作召回对照；主路径 hybrid？ | **已确认** |
+| Q5 | 技术 | evidence-driven | 当前代码是否仍 L2 回填 + boost 重排？ | **已查证** |
+| Q6 | 技术 | evidence-driven | Agent ACI 是否暴露 scoreLabel？ | **已查证** |
+| Q7 | 验收 | user-interview（对话已确认） | 接受 relevance_level / retry 分布变化？ | **已确认** |
+| Q8 | 边界 | user-interview | hybrid quality 切片 1 是否采用**纯 rank 映射**（不做 max(rank,denseSim)）？ | **已确认** |
+
+### Q1–Q4, Q7 用户确认摘录（本会话）
+
+- Label：「应该只有 hybrid 和 dense」「bm25_only 不是第三种」→ 同意收成两种。
+- 归一化：「抽取抽象转换…后处理抽象统一」→ 同意。
+- 后处理：「关键词打分不合理」「可以，就按照这个」（去 boost 改序 + 归一化一起做）。
+- mode：保留 dense 作对照，写入架构 §6.0。
+- 行为变化：讨论中已说明 hybrid 顺序/等级/retry 会变，用户要求按该方案实施（经 sm-flow）。
+
+### Q5 evidence-driven
+
+- `MilvusHybridKnowledgeStore.searchHybrid`：RRF 后仍 dense 回填 L2 / `bm25_only_no_dense`。
+- `KnowledgeEvidencePostProcessor.score`：`normalizeL2` + domain/entity/keyword/source_type 加分，按 `finalScore` 降序。
+- `LookupKnowledgeTool`：`isLowQuality` 看 `topSimilarity`（来自 baseScore）。
+
+### Q6 evidence-driven
+
+- Agent 主契约 `RagToolResult` / projector 暴露 evidence 列表与 relevance_level，不依赖 scoreLabel 字符串；改 label 为内部/L2 影响。
+
+### Q8 用户确认（2026-07-28）
+
+- **问题原文**: hybrid 的 qualityScore（切片 1）采用哪种映射？
+- **用户选择**: 纯 rank 映射（推荐）
+- **确认状态**: 已确认
+- **实现约束**: `toQualityScore(hybrid)` = `rankToQuality(originalRank, batchSize)`；不看 RRF 原分量纲；不做 `max(rank, denseSim)`；不在 hybrid 路径为质量闸门再查/回填 dense L2。
+
+---
+
+## Discover status
+
+- [x] clarify
+- [x] context
+- [x] propose (`proposal.md`)
+- [x] grill 完成（Q1–Q8 均已关闭）
+
+**Discover checkpoint: 完成。**
+
+---
+
+## Commit checkpoint
+
+### Capability
+
+- specify: sm-flow 内置 + openspec status/instructions（fallback：按 template 手写 design/specs/tasks）
+- audit: sm-flow 内置协议（未调用外部 zoom-out）
+- commit gate: 文件完整性 + 一致性检查后写入 `.committed`
+
+### Cross-artifact 对齐
+
+| 链路 | 状态 |
+|---|---|
+| brief/proposal 目标范围 → design | 已对齐 |
+| design 决策（label/normalizer/保序/去 boost/纯 rank）→ specs | 已对齐 |
+| specs 可观察行为 → tasks 可执行切片 | 已对齐 |
+| decisions Q1–Q8 → proposal/design/specs | 已对齐 |
+
+### Audit（≤5 句）
+
+1. 链路仍是 Tool→Retriever→Store→Post→Pack→Project，无新外部系统。  
+2. 分数所有权上收 store 发射 + normalizer；后处理只裁剪与质量闸门。  
+3. 废止 bm25-hybrid 的「dense L2 enrichment」决策，属有意行为变化（L2 接口影响）。  
+4. 风险主要是 hybrid 序数 quality 与阈值标定，已记入 design Risks。  
+5. 不触及 Agent ACI 字段名与 Milvus schema。
+
+### Commit gate checklist
+
+- [x] proposal / design / specs / tasks / brief 存在
+- [x] 核心概念在 design 有对应
+- [x] design 关键决策在 tasks 有任务
+- [x] tasks 可验证（checkbox 纵向切片）
+- [x] 无未确认 user-interview
+- [x] `.committed` 已创建
+
+**Commit checkpoint: 完成。Committed OpenSpec 就绪。**
+
+**下一步**: 等待用户明确授权 **Apply**（例如「开始 apply / 实现」）。未授权前不改业务接线代码。
+
+---
+
+## Apply checkpoint
+
+- **Capability**: openspec-apply-change + Committed OpenSpec tasks
+- **授权**: 用户「实现」
+- **完成**: tasks.md 全部勾选
+- **验证**:
+  - `RetrievalScoreNormalizerTest` 4 passed
+  - `KnowledgeEvidencePostProcessorTest` 6 passed
+  - `LookupKnowledgeToolTest` 7 passed
+  - `VectorSearchServiceTest` 2 passed
+  - `VectorKnowledgeSearchAdapterHybridTest` 1 passed
+- **已知限制**: hybrid quality 为本轮 rank 序数映射，跨 query 绝对值不可比；阈值可能需后续标定
+- **行为变化**: 已落地（去 L2 回填、去 boost 改序、label dense/hybrid）
+
+**Apply checkpoint: 完成。** 可进入 Archive（需用户确认是否 archive OpenSpec）。

openspec/changes/archive/2026-07-28-rag-quality-score-unify/design.md

@@ -0,0 +1,134 @@
+# Design: rag-quality-score-unify
+
+## Context
+
+- Knowledge path already uses single `MilvusHybridKnowledgeStore` (MilvusClientV2) with dense + BM25 + RRF.
+- Chunk-level `evidenceKey` dedup and `retrieve-k` / `return-n` are landed.
+- Gap: hybrid ordering is RRF, but post-process still pretends scores are L2 and re-ranks with L0 keyword contains boosts.
+- Prior design in `rag-bm25-hybrid-drop-sdk` required dense L2 enrichment for threshold compatibility — **this change supersedes that decision**.
+
+Stakeholders: `lookup_knowledge` internal pipeline; Agent ACI field *names* unchanged; operators comparing `retrieval.search.mode=dense|hybrid`.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+1. First-class `scoreLabel` values: only `dense` | `hybrid` (aliases canonicalize).
+2. Single `toQualityScore` adapter; post-process is label-agnostic.
+3. Preserve retrieval `originalRank` as sort authority; remove keyword/domain boost re-ranking.
+4. Hybrid quality = pure rank mapping over the current candidate batch (confirmed).
+5. Keep `mode=dense` for offline recall comparison; production default remains hybrid.
+
+**Non-Goals:**
+
+- Cross-encoder / query rewrite / neighbor chunks.
+- Schema rebuild or collection rename.
+- Changing Agent-facing ACI JSON field names.
+- Configurable `max(rank, denseSim)` quality (future).
+
+## Decisions
+
+### D1 — Two labels only
+
+| label | `score` meaning | quality mapping |
+|---|---|---|
+| `dense` | L2 distance (smaller better) | `1 - clamp(l2)/maxL2Distance` |
+| `hybrid` | engine fused score optional in `rawScore`; **not** used as L2 | `rankToQuality(originalRank, batchSize)` |
+
+Canonicalize legacy strings: `l2_distance`→dense; `rrf_fused` / `bm25_only_*`→hybrid.
+
+**Why not keep `bm25_only`:** it is not a search mode; it was a L2-fake patch. Hybrid path hits are all `hybrid`.
+
+### D2 — Stop dense L2 overwrite on hybrid hits
+
+`searchHybrid` SHALL:
+
+1. Run `hybridSearch` + RRFRanker.
+2. Emit hits in RRF order with `scoreLabel=hybrid`, `originalRank=1..n`.
+3. Set `rawScore` from engine when present; `score` MAY equal raw fused score or rank placeholder — MUST NOT be replaced by dense L2 for post-process consumption.
+4. MUST NOT set `bm25_only_no_dense` or force `score=maxL2Distance` for threshold faking.
+5. MUST NOT run a parallel dense search solely to rewrite scores (slice-1 pure rank quality).
+
+`searchDense` SHALL emit `scoreLabel=dense` and L2 in `score`.
+
+### D3 — `RetrievalScoreNormalizer` is the only label branch
+
+```text
+qualityScore = RetrievalScoreNormalizer.toQualityScore(
+  scoreLabel, score, originalRank, batchSize, maxL2Distance)
+```
+
+- Hybrid: linear rank map — rank 1 → 1.0; rank n → ~1/n floor so last item > 0.
+- Dense: existing L2 formula (behavior parity for dense mode).
+
+Post-processor, `isLowQuality`, and `relevance_level` consume **only** `qualityScore` (exposed today as `baseScore` / `topSimilarity` fields for minimal DTO churn).
+
+### D4 — Post-process sort and boosts
+
+```text
+order = originalRank ASC, then stable evidenceKey
+// NO finalScore = base + 0.15 domain + ...
+```
+
+- Remove additive boosts from sort key and from `finalScore` used for ordering.
+- Optional: if L0 hint string matches, append explanatory `hitReasons` only (e.g. `l0_keyword_overlap`) — zero score delta.
+- Keep: evidenceKey dedup, max-chunks-per-document, return-n, excerpt truncate.
+- `relevance_level`: compare top `qualityScore` to existing thresholds; **remove** `hasHintSupport` gate for PRECISE.
+- `isLowQuality` / category unfiltered retry: unchanged control flow, new score semantics.
+
+### D5 — Trace fields
+
+- `RerankTrace` may keep `baseScore`/`finalScore` names but both equal `qualityScore` when boosts are zero; `boostReasons` empty or explanation-only reasons without `:+0.xx` score deltas.
+- Prefer renaming comments to “quality trace”; no Agent contract change required.
+
+### D6 — WIP files
+
+Workspace may contain draft `RetrievalScoreLabels` / `RetrievalScoreNormalizer`. Apply MUST align them to this design (or replace) and wire call sites; drafts alone are not done.
+
+## Interface impact
+
+- **Level: L2** — internal DTO semantics (`score`, `scoreLabel`), post-process ordering and relevance distribution.
+- Agent ACI: field names stable; `relevance_level` *values distribution* may change (accepted behavioral change).
+
+## Data flow (target)
+
+```text
+VectorSearchService (mode dense|hybrid)
+  -> hits{ rank, score, scoreLabel=dense|hybrid, rawScore? }
+  -> KnowledgeDocumentRetriever candidates
+  -> KnowledgeEvidencePostProcessor
+       for each: qualityScore = toQualityScore(...)
+       sort by originalRank
+       dedup / caps / return-n
+       relevance + topSimilarity from qualityScore
+  -> pack / assemble / project
+```
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|---|---|
+| Rank→quality not comparable across queries | Document; thresholds may need later tune; dense mode still L2-absolute |
+| Hybrid top quality always high if batch small | batchSize = candidate list size after retrieve; rank1 always 1.0 by design for “best of this round” |
+| PRECISE without hint support more often | Accepted; semantic/rank quality no longer gated on contains |
+| Tests assert boost re-order | Update `LookupKnowledgeToolTest.rerankUsesHintMatches...` |
+| Old label strings in sidecar/eval | canonicalize in normalizer |
+
+## Migration Plan
+
+1. Deploy code; no Milvus schema migration.
+2. Default `retrieval.search.mode=hybrid` unchanged.
+3. Rollback: revert change; old L2-enrichment behavior returns.
+4. Optional ops: A/B dense vs hybrid recall using mode switch (unchanged capability).
+
+## Open Questions
+
+- None for slice-1 (Q8 confirmed: pure rank).
+- Follow-up: threshold calibration after live traces; optional denseSim blend.
+
+## Audit notes (inline)
+
+Module chain: Tool → Retriever → Store → PostProcessor → Packer → Projector.  
+Ownership: retrieval scores owned by store+normalizer; evidence assembly by post-processor; Agent view by projector.  
+No new cross-module lifecycle. Couples only internal RAG pipeline.  
+Supersedes hybrid L2-enrichment ADR-equivalent decision from bm25-hybrid change.

openspec/changes/archive/2026-07-28-rag-quality-score-unify/proposal.md

@@ -0,0 +1,80 @@
+# Change: Unify RAG quality score (dense/hybrid labels) and stop keyword boost re-rank
+
+## Why
+
+BM25 hybrid 已在库内完成 dense + BM25 + RRF 融合，但后处理仍：
+
+1. 把 hybrid 结果**伪装成 L2** 再 `normalizeL2`（含 `bm25_only_no_dense` 弱分占位）；
+2. 用 L0 domain/entity/keyword **contains 加分改主序**。
+
+这导致：排序信号与质量闸门分裂；词面信号被 BM25 与后处理**双重计分**；「词面热、语义冷」的片段可能被抬到前面；hybrid 的 RRF 序被冲掉。
+
+需要统一：**检索负责序，后处理只做 quality 归一化 + 裁剪装配**。
+
+## What Changes
+
+### 检索层（`MilvusHybridKnowledgeStore` / `VectorSearchService`）
+
+- 一级 `scoreLabel` 仅两种：`dense` | `hybrid`（与 `retrieval.search.mode` 对齐）。
+- **废弃**正式一级 label：`l2_distance` / `rrf_fused` / `bm25_only_no_dense`（可读兼容映射到 dense/hybrid）。
+- `mode=dense`：`score` = L2 距离，`label=dense`，`originalRank` = ANN 序。
+- `mode=hybrid`：`label=hybrid`；**不再**用 dense L2 覆盖主 `score`；**不再**对 BM25-only 伪造 maxL2；`originalRank` = RRF 返回序；`rawScore` 可保留引擎融合分。
+- `mode=dense|hybrid` **保留**：hybrid 为线上主路径；dense 为同库对照/评测（已写入架构 §6.0）。
+
+### 归一化（新）
+
+- 新增唯一转换点 `RetrievalScoreNormalizer.toQualityScore(label, score, rank, batchSize, maxL2)` → `qualityScore ∈ [0,1]`（越大越好）。
+  - `dense`：`1 - clamp(L2)/maxL2Distance`
+  - `hybrid`：按 **rank** 映射（本轮 batch 线性），不把 RRF 原分当 L2 套公式。
+- Label 差异**只**在此消化。
+
+### 后处理（`KnowledgeEvidencePostProcessor`）
+
+- **统一流程**，只消费 `qualityScore` + `originalRank`（label-agnostic）。
+- **排序主序 = `originalRank` 升序**（保检索序）；去掉 domain/entity/keyword/source_type **加分改序**。
+- L0 contains 匹配若保留，仅写入 `hitReasons` / trace 解释，**不参与 sort key、不加 finalScore**。
+- `relevance_level` / `isLowQuality` / category unfiltered retry：只看 top `qualityScore` 与既有阈值；**不再**要求 `hasHintSupport` 才能 PRECISE。
+- 保留：evidenceKey 去重、`max-chunks-per-document`、`return-n`、excerpt 截断、EvidenceBlock 装配。
+
+### 文档 / 测试
+
+- 更新 `mvp/architecture/RAG知识检索架构.md` §6 分数与后处理约定。
+- 单测：dense 路径 quality 与现 L2 归一化一致；hybrid 保序且不被 keyword 打乱；无 `bm25_only` 一级 label；旧 label 别名可 canonicalize。
+
+## Non-goals
+
+- Cross-encoder / listwise 精排、query rewrite、邻块扩展。
+- 删除 `mode=dense` 对照开关。
+- 改变 Agent 可见 ACI 字段结构（`evidence[]` / `relevance_level` 枚举名可不变；**分布会变**）。
+- 修改 Milvus schema / 强制全量 rebuild（本 change 不改 collection 结构）。
+- 上线可配 `max(rank, denseSim)` 混合 quality（可后续迭代；本 change 切片 1 用纯 rank 映射 hybrid）。
+
+## Context constraints (from devflow)
+
+- 承接 archived：`rag-chunk-evidence-identity-dedup`、`rag-bm25-hybrid-drop-sdk`、`rag-hybrid-search-rrf`、`modular-rag-pipeline`。
+- 单一知识后端仍为 `MilvusHybridKnowledgeStore`（V2）；不得恢复 sdk/spring 主路径路由。
+- Agent 投影仍不暴露 raw fused score / 完整 contextPack 作为主契约（内部 LookupResult/trace 可保留调试字段）。
+- 历史 decision「Dense L2 enrichment for threshold compatibility」**本 change 有意废止**，改为 qualityScore 统一闸门。
+
+## Impact
+
+- **行为变化（对内检索质量语义）**：
+  - hybrid 下证据顺序更贴近 RRF；
+  - 词面命中不再被后处理 contains 二次抬序；
+  - `relevance_level` 与 unfiltered retry 触发分布可能变化；
+  - BM25-only 命中不再被标成 quality≈0。
+- **接口影响**：L2（内部 DTO/注释/scoreLabel 字符串约定）；Agent ACI 字段名不变。
+- **风险**：hybrid rank→quality 为序数映射，绝对值不跨 query 可比；阈值 0.75/0.5 可能需后续观测再调（本 change 先沿用配置项）。
+
+## Scale
+
+- **standard**（多文件、有意行为变化、需 design + specs + tasks + 测试）。
+
+## Depends on
+
+- 已落地 hybrid schema + chunk evidenceKey（archived changes 如上）。
+- 对话已确认的设计口径（见 change `decisions.md`）。
+
+## WIP note
+
+- 工作区可能已有未接线的 `RetrievalScoreLabels` / `RetrievalScoreNormalizer` 草稿文件；apply 阶段以 **Committed OpenSpec** 为准接入或改写，不视为已完成实现。

openspec/changes/archive/2026-07-28-rag-quality-score-unify/specs/rag-retrieval-quality-score/spec.md

@@ -0,0 +1,94 @@
+# rag-retrieval-quality-score Specification
+
+## Purpose
+
+Unify knowledge retrieval score labels and quality normalization so dense and hybrid modes share one post-process pipeline without L2 faking or keyword boost re-ranking.
+
+## ADDED Requirements
+
+### Requirement: Primary score labels SHALL be only dense or hybrid
+
+Knowledge search hits used by `lookup_knowledge` SHALL set `scoreLabel` to `dense` or `hybrid` (after any legacy alias canonicalization). The system SHALL NOT treat `bm25_only_no_dense`, `rrf_fused`, or `l2_distance` as distinct first-class labels in new emissions.
+
+#### Scenario: Dense mode labels hits as dense
+
+- **WHEN** `retrieval.search.mode` is `dense` and search returns hits
+- **THEN** each hit SHALL have `scoreLabel` canonicalizing to `dense`
+- **AND** `score` SHALL be the dense L2 distance
+
+#### Scenario: Hybrid mode labels hits as hybrid
+
+- **WHEN** `retrieval.search.mode` is `hybrid` and search returns hits
+- **THEN** each hit SHALL have `scoreLabel` canonicalizing to `hybrid`
+- **AND** hit order SHALL follow the hybrid/RRF result order via `originalRank`
+
+#### Scenario: Legacy aliases canonicalize
+
+- **WHEN** a candidate carries a legacy label such as `l2_distance` or `rrf_fused` or `bm25_only_no_dense`
+- **THEN** quality normalization SHALL canonicalize it to `dense` or `hybrid` respectively before computing quality
+
+### Requirement: Hybrid search SHALL NOT overwrite scores with dense L2 for post-process
+
+When hybrid search runs, the store SHALL NOT replace hybrid hit scores with a parallel dense L2 map for the purpose of post-process thresholds, and SHALL NOT assign max-L2 weak placeholders under a `bm25_only_*` primary label.
+
+#### Scenario: No L2 enrichment overwrite
+
+- **WHEN** hybrid search completes
+- **THEN** post-process input scores SHALL NOT be forced to dense L2 solely for threshold compatibility
+- **AND** the system SHALL NOT emit `bm25_only_no_dense` as the primary score label on new hits
+
+### Requirement: Quality score SHALL be produced by a single normalizer
+
+The pipeline SHALL compute a `qualityScore` in `[0, 1]` (higher is better) using one normalizer API that branches only on canonical label.
+
+#### Scenario: Dense quality from L2
+
+- **WHEN** label is `dense` and score is L2 distance `d` with configured `maxL2Distance`
+- **THEN** `qualityScore` SHALL equal `max(0, 1 - min(d, maxL2Distance) / maxL2Distance)` (null score → 0)
+
+#### Scenario: Hybrid quality from rank
+
+- **WHEN** label is `hybrid` and `originalRank` is `r` within a candidate batch of size `n` (`n >= 1`)
+- **THEN** `qualityScore` SHALL be a monotonically non-increasing function of `r` over that batch
+- **AND** rank `1` SHALL map to `1.0` when `n >= 1`
+- **AND** the mapping SHALL NOT require dense L2 or RRF raw magnitude
+
+### Requirement: Post-process SHALL preserve retrieval rank order
+
+Evidence post-processing SHALL order candidates by `originalRank` ascending (stable tie-break allowed). It SHALL NOT re-order primarily by L0 domain/entity/keyword/source_type additive boosts.
+
+#### Scenario: Keyword overlap does not promote lower rank
+
+- **WHEN** candidate A has `originalRank=1` and candidate B has `originalRank=2`
+- **AND** B matches more L0 keywords via string contains than A
+- **THEN** after post-process acceptance order, A SHALL appear before B among accepted blocks (subject only to dedup/caps removing one of them)
+
+#### Scenario: Structural caps still apply after rank order
+
+- **WHEN** more than `rag.max-chunks-per-document` chunks share a docId
+- **THEN** only the best-ranked (lowest `originalRank`) up to the cap SHALL remain
+- **AND** `rag.return-n` SHALL still bound total blocks
+
+### Requirement: Relevance and low-quality gates SHALL use qualityScore only
+
+`relevance_level`, completeness hints, `topSimilarity` (or equivalent top quality field), and category-filter low-quality retry decisions SHALL use the normalized `qualityScore`, not raw L2-under-hybrid fakes and not keyword-boosted final scores.
+
+#### Scenario: Low quality uses top qualityScore
+
+- **WHEN** post-process finishes with at least one evidence block
+- **THEN** low-quality detection SHALL compare the top `qualityScore` to the configured reference threshold
+- **AND** SHALL NOT require L0 hint contains-match to treat the result as usable when quality meets threshold
+
+#### Scenario: PRECISE does not require hint support
+
+- **WHEN** top `qualityScore` is at or above the highly-relevant threshold
+- **THEN** the system MAY assign `PRECISE` or `HIGHLY_RELEVANT` without requiring domain/entity/keyword contains support
+
+### Requirement: Dense mode remains available for recall comparison
+
+Configuration `retrieval.search.mode=dense` SHALL remain supported as a same-collection baseline that runs dense ANN only, without removing hybrid as the default production mode.
+
+#### Scenario: Mode dense still callable
+
+- **WHEN** mode is `dense`
+- **THEN** search SHALL call dense ANN only and label hits `dense`

openspec/changes/archive/2026-07-28-rag-quality-score-unify/tasks.md

@@ -0,0 +1,39 @@
+# Tasks: rag-quality-score-unify
+
+## 1. Score contract utilities
+
+- [x] 1.1 Finalize `RetrievalScoreLabels` (`dense` / `hybrid` + canonicalize legacy aliases)
+- [x] 1.2 Finalize `RetrievalScoreNormalizer.toQualityScore` (dense L2 formula; hybrid pure rank map with batchSize)
+- [x] 1.3 Unit tests for normalizer: dense L2 edges; hybrid rank monotonicity; alias canonicalize
+
+## 2. Store / search emission
+
+- [x] 2.1 `searchDense`: emit `scoreLabel=dense`, L2 `score`, stable rank order
+- [x] 2.2 `searchHybrid`: emit `scoreLabel=hybrid`; keep RRF order as `originalRank`; stop dense L2 overwrite and `bm25_only_*` labels; no parallel dense probe for score rewrite
+- [x] 2.3 Update `VectorSearchService.SearchResult` / adapter comments so `score`+`scoreLabel` contract matches design
+- [x] 2.4 Ensure `KnowledgeDocumentRetriever` / `VectorKnowledgeSearchAdapter` propagate `scoreLabel`, `score`, `rawScore`, `originalRank` unchanged
+
+## 3. Post-process
+
+- [x] 3.1 `KnowledgeEvidencePostProcessor`: compute quality via normalizer; sort by `originalRank` ASC (stable tie-break)
+- [x] 3.2 Remove domain/entity/keyword/source_type additive boosts from ordering/`finalScore`
+- [x] 3.3 Optional: L0 overlap only as explanatory `hitReasons` (no score delta)
+- [x] 3.4 `relevance_level` / `isLowQuality` / `topSimilarity` use qualityScore only; drop `hasHintSupport` gate for PRECISE
+- [x] 3.5 Keep evidenceKey dedup, max-chunks-per-document, return-n, excerpt truncate
+
+## 4. Tests
+
+- [x] 4.1 Update `KnowledgeEvidencePostProcessorTest` for rank order + caps under new scoring
+- [x] 4.2 Update `LookupKnowledgeToolTest.rerankUsesHintMatchesAndContextPackPreservesMetadata` (no boost re-order; metadata/context pack still ok)
+- [x] 4.3 Adjust any tests asserting `l2_distance` / boost reasons `:+0.xx` as needed
+- [x] 4.4 Run targeted unit tests for touched classes
+
+## 5. Docs
+
+- [x] 5.1 Update `mvp/architecture/RAG知识检索架构.md` §6 score/post-process (replace L2-enrichment narrative)
+- [x] 5.2 Align `application.yml` comments if still describing L2-only post-process for hybrid
+
+## 6. Verify
+
+- [x] 6.1 Confirm no production path still sets `bm25_only_no_dense` or overwrites hybrid scores with L2 for thresholds
+- [x] 6.2 Note known limitation: hybrid quality is ordinal within batch; thresholds may need later calibration