docs(rag): 补录 RAG 迭代各任务评审报告

docs/superpowers/plans/rag-task-3-report.md

@@ -0,0 +1,63 @@
+# RAG 迭代 Task 3 实现报告（含评审修订 D1 的 index_dir）
+
+## 状态
+**GREEN — 已完成并通过测试**
+
+- 先写失败测试（RED：因 `impact_rag.py` 缺失触发 `ModuleNotFoundError`）
+- 实现 `ImpactRAG` 及 D1 修订项 `index_dir`
+- 重新运行测试：`2 passed`
+
+## Commit
+`feat(rag): 新增 ImpactRAG 索引/检索服务（含 index_dir）`
+
+涉及文件：
+- `src/genesis/rag/impact_rag.py`（新增）
+- `tests/test_impact_rag.py`（新增）
+
+## 测试输出摘要
+```
+python -m pytest tests/test_impact_rag.py -q
+2 passed in 2.86s
+```
+
+测试用例：
+1. `test_retrieve_returns_relevant_chunk`：验证 `index` + `retrieve` 能做到 chunk 级语义召回（FakeEmbedder 词袋向量 + cosine），返回结果含 `OrderController`。
+2. `test_index_dir_reads_text_files`：验证 `index_dir` 仅索引文本源文件（白名单扩展名），跳过 `binary.bin` 与非文本/空文件，返回索引片段数为 1，且可检索到内容。
+
+## 自我审查
+- `index`：将 `(文件名, 文本)` 切分为 chunk（默认 800 字，按段落聚合），前缀 `[文件名]`，批量 embed 后 `store.add`。
+- `index_dir`（D1）：`Path(root).rglob("*")` 遍历，按扩展名白名单过滤，UTF-8 `errors="ignore"` 读取，跳过空文本与读取异常；返回实际索引文件数（即 sources 数，非 chunk 数 —— 与 brief 文档及测试断言 `n == 1` 一致）。
+- `retrieve`：空查询直接返回 `[]`；否则 embed 查询向量后调用 `store.search`。
+- 测试中对 `RagStore(":memory:")` 采用 `try/finally` 包裹 `close()`，避免 ResourceWarning。
+
+## 一句话摘要
+实现 `ImpactRAG` 的 `index`/`retrieve` 与 D1 修订项 `index_dir`，2 项测试全绿，可为上传即索引（Task 5 接线）提供目录级源码索引能力。
+
+## 顾虑
+- 运行指定测试文件时，全局 pytest 覆盖率配置（要求 99%）会报 `Required test coverage of 99.0% not reached`，但本任务验证仅需 `2 passed`，不影响功能正确性；若 CI 以全量套件口径执行，需单独豁免或补充本模块覆盖率。
+- `index_dir` 返回的是"索引文件数"而非"片段数"；brief 文档两处措辞略不一致（接口签名注释写"返回索引的片段数"，测试与示例暗示为文件数），当前实现以测试断言为准（文件数）。
+
+## 修复后验证
+
+### 状态
+**GREEN — 分支测试补全，覆盖率 100%**
+
+针对评审发现（空 query 行为未测 + fail_under=99 硬要求），补全 `index`/`index_dir`/`retrieve` 全部分支测试与防御性过滤，并更新 `index_dir` docstring 为"返回索引的文件数"。
+
+### 修改摘要
+涉及文件：
+- `src/genesis/rag/impact_rag.py`
+  - `index`：对 `_split` 结果过滤空片段（`if piece.strip():`），避免空向量噪声 chunk。
+  - `index_dir`：docstring 由"片段数"更正为"文件数"；读取文本后叠加内容级跳过（空文本 `if not text.strip(): continue`、含 NUL 字节二进制误带扩展名 `\x00` 跳过）。
+- `tests/test_impact_rag.py`：新增 10 个用例，覆盖空 query、空文本源、非目录 root、空文件、读取异常、大写扩展名、空目录、NUL 二进制、单段超长与多段拆行。
+
+### 测试输出摘要
+```
+python -m pytest tests/test_impact_rag.py -q --cov=genesis.rag.impact_rag --cov-report=term-missing
+src\genesis\rag\impact_rag.py      53      0     26      0   100%
+12 passed in 0.28s
+```
+（注：若沿用全局 `addopts` 的 `--cov=genesis`，整体覆盖率会因只跑单文件而低于 99% 告警，但 `impact_rag.py` 本文件覆盖率为 100%、12 例全绿，符合本次验收口径。）
+
+### 一句话摘要
+补全 `ImpactRAG` 分支测试与防御后，`impact_rag.py` 达到语句/分支 100% 覆盖，原 2 例与新 10 例共 12 例全绿。