@furongjun1999/dsh-memory 0.4.4 → 0.4.5

package/docs//350/256/244/347/237/245/345/233/276_/347/264/242/345/274/225/344/270/216/345/267/245/347/250/213/350/247/204/350/214/203/345/214/226_/350/256/241/345/210/222_v0.1.md

@@ -0,0 +1,496 @@
+# 认知图 · 索引与工程规范化 计划 v0.1
+
+> 来源：`agi-architectures/外部agi架构可学习优点.md` 复核表 **#12 文档体系** 与 **#8 manifest 元数据规范**
+> （两条均判 DEFER，先决条件分别是「先说清缺哪一份索引」「确认三字段是否真缺」——本文档即对该先决的正面回答）
+> 目标工程：**dsh-memory / md_cg（认知图 + 记忆 OS）**
+> 证据口径：源码级逐行核对（`mcp_server.py` / `codeindex.py` / `mdcg.py` / `nodefile.py` / `sources.py` / `sustain.py`）
+> 时间：2026-09-10
+
+---
+
+## 判定单
+
+```
+条件空间：观测位置=全局(设计者) | 观测工具=md_cg 源码逐行核对 + docs/ 30 份 + 复核表 #12/#8
+          | 时间窗口=当前迭代 | 存在约束=零第三方依赖(纯标准库) / md 单一真相源 / 有意剔除神经嵌入 / 不复制实现正文
+白箱三问：依据=每条给文件行级证据(§一) | 条件=先决已核对，未核对项显式标出 | 错后=索引若复制代码正文，
+          会造出「第二份真相」，破坏「md 可审计 + git 可 diff」这一存在理由，且代码改了索引不报错(静默漂移)
+裁决：ACCEPT 6 / DEFER 2 / REJECT 2
+依据：条件证据见 §一，非相似度
+缺失维度：观测位置之外的「索引粒度」——文件级 / 符号级 / 段落级三者未定义，本计划定为「符号级(代码) + 章节级(文档)」
+验证路径：R0 收口基线 → R1 ref 协议+回读 → R2 文档索引 → R3 增量+漂移巡检 → R4 互链 → R5 规范化产出
+关注信号：`index_code` 全仓 0 测试；`index_dir` 静默截断；代码节点恒定被判 BLINDSPOT（§二）
+```
+
+---
+
+## 一、现状核对（事实层）
+
+### 1.1 已具备（不要重复造）
+
+| 能力 | 证据 |
+|---|---|
+| 条件代码图模块已存在，AST 抽注释/接口 | `md_cg/codeindex.py:1-13`（设计声明）、`:53-75`（`extract`）、`:78-88`（`render`）、`:91-95`（`node_id`）、`:98-118`（`index_dir`） |
+| MCP 已接线 | `md_cg/mcp_server.py:1492-1516`（`cg(op=index_code)`），op 声明在 `:531-532`、`:545-546`、`:616-618` |
+| ref 字段**真的落盘**（不是被 kwargs 吞掉） | `mcp_server.py:1509` 传 `code_ref={path,name,kind,lineno,end}` → `md_cg/mdcg.py:388`（`**extra`）→ `:452`（`fm.update(extra)`） |
+| ref 字段**能解析回来** | `md_cg/nodefile.py:51`（值一律 `json.dumps`）→ `:73`（`json.loads`），嵌套 dict 保真 |
+| ref 字段**能返回给调用方** | `mcp_server.py:730-734`（`_node_view` 返回整个 `frontmatter`） |
+| 已有 op 注册表与权限校验 | `md_cg/tokens.py:56-59`（`ALL_OPS`，含 `index_code`）+ `test_p21_tokens.py` |
+| 增量 watermark 机制有现成范式 | `md_cg/sources.py:219-253`（`_sources.json`：`{source_key:{t,seq,count}}`）、`:257-334`（`ingest` 增量+去重+幂等） |
+| 自愈只修派生物、逐条留痕的纪律已定 | `md_cg/sustain.py:12-14`（诊断只读）、`:277-302`（`_audit` + 幂等修复 + 失败不拖垮进程） |
+| 「非 CCG 正文」有两种既有豁免范式 | `mdcg.py:513-519`（目标节点**按 CCG 格式渲染**以避开 BLINDSPOT）、`mdcos.py:313-316`（`ccg_exempt` legacy 记忆 → DEFER） |
+
+### 1.2 真实缺口（本计划要闭合的）
+
+| # | 缺口 | 证据（现状） | 严重度 |
+|---|---|---|---|
+| **A** | **文档索引完全不存在**——认知图索引不到 `docs/*.md` 的任何位置 | 全仓无 `.md` 索引模块；`sources.py` 只有 `JsonlSource`(`:49`)/`DSHSessionSource`(`:112`)，均吃会话流不吃文档 | 高（正是用户的核心诉求） |
+| **B** | **代码节点恒定被判 BLINDSPOT** | `codeindex.render`(`codeindex.py:80-88`) 只输出 `# path::name (kind, L..)` / `# sig` / `# 注释` / `# doc:`，**不含 CCG 5 要素标记**；而 `judge_qualification` 第一步就是 `ccg_completeness` 不全 → `BLINDSPOT`（`mdcg.py:709-714`），且该判定在**检索路径上逐条调用**（`mdcos.py:746`、`:869`） | **最高（存得进、判不了、白索引）** |
+| **C** | **只能索引，不能回读**——没有「按 ref 打开源文件正文」的 op | `mcp_server.py:1492-1516` 只写不读；无 ref 解析/定位入口 | 高 |
+| **D** | **无漂移/悬空检测**——源码改了、行号漂了，索引不知道 | 无 ref 校验代码；`sustain.diagnose`(`sustain.py:141-266`) 的巡检项里无 ref | 高（静默故障，正是方案自己警惕的那类） |
+| **E** | **只认 `.py`** | `codeindex.py:19` `SUFFIX = (".py",)`；本仓 `src/*.ts`、`test/*.ts`、`scripts/*.ps1`、`cordova/cordis*.yml` 全在索引外 | 中 |
+| **F** | **全量重扫 + 静默截断** | `codeindex.py:107-108`：达到 `max_files`/`max_items` **直接 return**，调用方 `mcp_server.py:1513` 只回 `indexed/error_count`，不报 `truncated` → 索引不全但不告警 | 中（静默不全） |
+| **G** | **零测试** | `index_code` 仅出现在 `tokens.py:59` 与 `mcp_server.py`（5 处）；`test_*.py` 中 **0 命中** | 中 |
+| **H** | **code 图与 doc 图不互链** | `links.py` 是蜂群信任（`links.py:1-20`），与代码/文档无关；代码节点 tags 仅 `["code","code:<kind>"]`(`mcp_server.py:1505`)，无指向文档的边 | 中（「互链」是索引的价值上限） |
+| **I** | **工程规范化的三份索引文件缺位** | `docs/` 30 份含方案/评分/工具表，但**无模块索引、无功能矩阵、无文件清单**；33 个 MCP 工具的 `inputSchema`(`mcp_server.py:96-690`) 无 timeout/执行语义；无跨进程可读的 `status.json` | 中（= 复核表 #12/#8 本体） |
+
+### 1.3 已核对但**尚未核实**的点（诚实登记，不当作事实）
+
+1. ~~`cg.add` 未显式设 `role`（`mcp_server.py:1503-1511`），代码/文档节点会落到哪个 role 档、是否进正排——**未验证**，R1 必须实测。~~
+   → **已实测（R1）**：代码节点 frontmatter **不带 `role` 字段**（`index_code` 未传），但检索/资格判定不依赖 `role`——实测 `op=read` 能命中并按 CCG 完整度判 **ACCEPT**（`tags=["code","code:<kind>"]`、`verification_basis` 落盘）。故 `role` 缺口不影响 R1 目标，留待 R5（FEATURE_MATRIX）统一裁定标签体系。
+2. `index_dir` 的 `condition_space.observation_position = path.split("/")[0]`(`mcp_server.py:1506-1507`) 生成的桶分布是否健康（对齐 `routing` 分区健康度自检）——**未验证**。
+3. ~~文档节点的层与密级（`knowledge` vs `contextual`、`public` vs 继承目录）——**未裁定**，R2 前定。~~
+   → **已裁定（R2）**：layer 默认 `knowledge`（与代码节点同层，保证进默认召回；`contextual` 表示情境绑定会过期，会让文档掉出默认召回）；密级**默认 `internal` 且显式写入 frontmatter**（不依赖节点默认值——审计时看不出意图），路径段命中私有提示词时**再保守降为 `private`**（只可能更严，宁可漏召回不可泄漏）。实测 `internal:3 / private:1`。详见 §十三-3。
+
+---
+
+## 二、为什么必须先修 B（避免把预算花在错误的地方）
+
+当前 `index_code` 的产出**在检索路径上是残废的**：
+
+```
+judge_qualification(mdcg.py:709-714)
+  第 1 步：ccg_completeness(content) 不全  →  直接返回 BLINDSPOT
+           ↑ codeindex.render 不产 CCG 标记（codeindex.py:80-88）
+           ↑ 第 3 步「verification_basis 缺失 → DEFER」根本走不到，
+             尽管 mcp_server.py:1508 已正确填了 verification_basis="compiler"
+```
+
+同仓已有两个正确范式可抄：目标节点**按 CCG 格式渲染**（`mdcg.py:513-519`，注释直写「保证 judge_qualification 能给出 ACCEPT 而非 BLINDSPOT」）、legacy 记忆走 `ccg_exempt`（`mdcos.py:313-316`）。
+
+**结论**：索引层的第一个 PR 不是「加更多后缀」，而是**让渲染产物符合 CCG 5 要素**。否则索引量涨 10 倍，可用性仍是 0。
+
+---
+
+## 三、目标（可验收的三句话）
+
+1. **回得去**：任何一条被检索到的节点，都能给出行级可定位的位置——
+   代码 → `<path>:<lineno>-<end>`；文档 → `<path>#<heading-path>:<lineno>-<end>`。
+2. **找得到**：`.py` / `.md` 全量可索引（`.ts` 为弱提取器），不漏召回，且索引结果能回答「这条功能在文档里怎么写的 / 对应哪段代码」。
+3. **守得住**：索引是**派生物**——可删可重建；源文件变更后能被巡检发现（漂移/悬空），且修复不改源文件、逐条留痕。
+
+---
+
+## 四、设计：统一 ref 协议
+
+沿用 `code_ref` 的形状，扩成 `ref` 协议，作为 frontmatter 一等字段（`nodefile` 已支持任意 JSON 值，无需改格式层）。
+
+```jsonc
+// 代码节点
+"code_ref": {"path":"md_cg/mdcg.py","name":"MdCG.add","kind":"def",
+             "lineno":383,"end":462,"lang":"py","hash":"9f2c1ab3de44"}
+
+// 文档节点
+"doc_ref":  {"path":"docs/认知图_MD目录方案_v0.1.md","heading":"9. 分阶段实施（稳健）",
+             "heading_path":["9. 分阶段实施（稳健）"],"level":2,
+             "lineno":491,"end":513,"anchor":"9-分阶段实施稳健","hash":"41ab77c0e1d9"}
+```
+
+**不变量（写进代码注释与测试）**
+- 正文**永不复制实现/全文**——只存「索引块 + ref 指路」（对齐 `codeindex.py:4-6` 的既有纪律）。
+- `hash` = 被引用行的 sha1 前 12 位，用于漂移判定（不是内容寻址，是变更探测）。
+- 索引是派生物：`_refindex.json` 丢了/坏了，能从源文件全量重建。
+- 源文件**只读**：索引一轮后源文件 mtime 全不变（对齐 P0 的 mtime 只读断言）。
+
+**CCG 渲染模板（修 B 的关键）**
+
+代码节点（`功能名/子功能/执行/验证方式/不适用条件` 五个必需标记齐 → `complete=True`）：
+
+```
+# 功能名：{name}（{kind}）
+# 生效条件：大域={top_dir}；检索「{name}」或「{path}」
+# 子功能：{所属模块/类} · {docstring 首段≤120字}
+# 执行：{sig}
+# 验证方式：compiler（AST 已解析，非人工声明）
+# 不适用条件：其它大域的同名符号
+```
+
+文档节点：
+
+```
+# 功能名：{heading}
+# 生效条件：文档={rel_path}；检索「{heading}」或正文关键词
+# 子功能：{父 heading 路径}
+# 执行：{首段摘要≤200字}
+# 验证方式：data（原始文档为准）
+# 不适用条件：其它文档的同名标题
+```
+
+> 取舍：docstring/首段进 `子功能` 行而不另起 `# doc:` 行，是为了让**单条节点的全部可检索信息都在 CCG 结构内**，避免出现「检索能命中、判定看不见」的字段。
+
+---
+
+## 五、模块改动表
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `md_cg/refindex.py` | **新增** | ref 协议常量 + 提取器注册表 + 统一 `index_dir` 调度 + `_refindex.json` 增量 + `check_refs()` 漂移巡检 + `read_ref()` 回读 |
+| `md_cg/docindex.py` | **新增** | `.md` 章节切块：ATX 标题栈、heading_path、行号区间、首段摘要、anchor |
+| `md_cg/codeindex.py` | **改造** | ①`render()` 改产 CCG 5 要素（修 B）②后缀注册化（`.py` 走 AST、`.ts/.js` 走弱提取器）③`index_dir` 返回 `truncated` 与 `files_scanned`（修 F）④`node_id` 保持稳定（重复索引幂等） |
+| `md_cg/mcp_server.py` | **扩** | 新增 `op=ref`（`action=read\|check\|stat`，兼回读与巡检）；`op=index_code` 保留为别名并透传 `truncated`；`op=index_doc`；op 枚举与 `:542-546` 同步 |
+| `md_cg/tokens.py` | **改** | `ALL_OPS`(`:56-59`) 加 `ref` / `index_doc`（漏改会被权限层直接拒），`test_p21_tokens.py` 同步 |
+| `md_cg/sustain.py` | **扩** | `diagnose` 增巡检项 `ref_stale` / `ref_dangling`，`heal` 动作为「重建索引」（派生物，符合现有自愈边界 `:12-14`） |
+| `md_cg/mdcos.py` | **扩** | 检索结果带 `ref` 与 `ref_kind`（读侧不改召回逻辑，只加字段） |
+| `md_cg/test_p26_refindex.py` | **新增** | 见 §七 |
+
+---
+
+## 六、分阶段实施
+
+| 阶段 | 做什么 | 验证 | 状态 |
+|---|---|---|---|
+| **R0** | ✅ **已完成**（§十一 取证纪录）：全量 28 用例基线取证 + 修 4 条缺陷（`corpus.reset_root` 全量 rmtree / 3 处编码） | 28/28 全绿；P0 25/25、P1 38/38、P11 27/27、P12 32/32 | ✅ |
+| **R1** | ✅ **已完成**（§十二 取证纪录）：`codeindex.render` 改产 CCG 6 行、`EXTRACTORS` 后缀注册化（AST 精确 / TS-JS 弱提取）、`op=ref` 回读 + 漂移检测、`truncated`/`skipped_suffixes` 显式上报；实测 §1.3-1（role 档位） | ✅ 代码节点判定 **ACCEPT**（不再 BLINDSPOT）；`op=ref` 回读文本与源区间**逐字一致**、`hash_match` 检出漂移 | ✅ |
+| **R2** | ✅ **已完成**（§十三 取证纪录）：`docindex.py`（章节切块 + CCG 渲染 + `doc_ref`）+ `op=index_doc`；裁 §1.3-3（层/密级） | ✅ `docs/` 全部 md（实测 **19/19**，非静默跳过）切块可定位；`docs/认知图_MD目录方案_v0.1.md` 的 §9 表被判 **ACCEPT** 且给出行号 `L491-L516` | ✅ |
+| **R3** | ✅ **已完成**（§十四 取证纪录）：`_refindex.json` 增量（抄 `sources.Ingestor` 范式）+ `check_refs` 漂移巡检 + `truncated` 显式上报 + 接入 `sustain.diagnose` | ✅ 改源文件一行 → `ref check` 报 stale（重建后消除）；删源 → dangling；`max_files` 触发时 `truncated=true` 且写进水位；`diagnose` 报 `ref_stale`、`heal` 的 `rebuild_refs` 修复 | ✅ |
+| **R4** | 修 H：code↔doc 互链（文档中出现的符号名/路径 → 建边指向 code 节点；反向亦然） | 「某功能」检索能同时给出代码位置与文档位置 | ⬜ |
+| **R5** | 修 I（工程规范化产出，见 §九） | 三份索引文件可由 `index_ref` **自动生成**，非手写 | ⬜ |
+| DEFER | `.ps1/.vbs/.yml` 提取器；跨副本身份下的 ref 可见性 | 先决：R4 完成且互链被实际使用 | ⬜ |
+
+---
+
+## 七、验收（`test_p26_refindex.py`，对齐既有 `test_pNN` 脚本式 `check()` 风格）
+
+1. **ref 落盘**：代码/文档节点的 `frontmatter.code_ref`/`doc_ref` 五字段完整，且 `loads` 往返不丢（`nodefile.py:73`）。
+2. **CCG 合规（修 B 的守门断言）**：`ccg_completeness(content)["complete"] is True`；`judge_qualification(...)["state"] != BLINDSPOT`。
+3. **回读一致**：`read_ref(node_id)` 返回的区间文本与该文件当前内容**逐字相同**（非「看起来对」）。
+4. **漂移检测**：在目标文件插入 1 行 → `ref check` 报 `stale`；删除该符号 → 报 `dangling`；两者都不抛异常、都不改源文件。
+5. **只读契约**：索引一轮前后，被索引的 `.py`/`.md` **mtime 全不变**、源文件 hash 不变。
+6. **幂等**：同一目录索引两次 → 节点数不变、`node_id` 稳定、`_refindex.json` 不膨胀。
+7. **不复制正文**：代码节点 content 内「函数体语句」0 命中（如断言不含 `return ` 之外的可执行行）；content 长度 ≤ 阈值。
+8. **截断诚实**：`max_files=1` 时 `truncated is True` 且给出建议值。
+9. **文档切块**：heading_path 与行号可定位；正文含 `---` 分隔线不污染 frontmatter（`nodefile.py:19-23` 的既有纪律不回归）。
+10. **权限**：`op=ref` 走 `tokens` 校验；无权限 actor 读取越权层的 ref 应被拒。
+11. **新 op 注册**：`tokens.ALL_OPS` 与 `mcp_server` 的 op 枚举一致（防漏改）。
+
+---
+
+## 八、风险与代价
+
+| 风险 | 后果 | 处理 |
+|---|---|---|
+| `.md` 切块过细 | 30 份文档切出上千节点，污染正排、拖慢检索 | 只切 `level<=3`；正文 <200 字的 section 合并进父节点；先跑一次统计再定阈值 |
+| 行号漂移 | ref 指向错误代码（**静默**） | `hash` + `check_refs` 巡检 + 挂 `sustain.diagnose`；文档不承诺「永久有效」，只承诺「可检出」 |
+| 双份真相 | 索引与源文件各自演化 | 索引是派生物、可重建；doc 索引**不存全文** |
+| `.ts` 无 AST | 质量劣于 `.py` | 标准库无 TS parser → v0.1 用「行首 regex + 上邻注释」**弱提取器**，代码里显式标注「弱」，不冒充 AST |
+| 密级泄漏 | 私有文档被索引进公开层 | 显式声明 `sensitivity`，不依赖默认值；越权写入由 `security` 事前拦截（`sources.py:296-307` 已有同款范式） |
+| 索引自身成单点 | `_refindex.json` 损坏导致增量失效 | 降为纯派生物，可全量重建（对齐 `_index.json` 的既有裁定） |
+
+---
+
+## 九、对复核表 #12 / #8 的正面回答（DEFER → ACCEPT）
+
+复核表 #12 的先决是「**先说清缺哪一份索引**」。答案：
+
+| #12 提的三份文件 | 对应本计划 | 关键增量 |
+|---|---|---|
+| `DOCUMENTATION_INDEX`（文档索引） | **R2 `docindex.py` + R5 产出** | 不是手写目录，而是**认知图可检索的 doc 节点**（带 heading_path + 行号） |
+| `FEATURE_MATRIX`（功能矩阵） | **R5 产出** | 矩阵由 `index_ref` 自动生成：`工具 × op × 实现文件:行 × 测试文件`，并**校验「每个 op 都能找到测试」**（`index_code` 的 0 覆盖正是这条能抓出来的） |
+| `FILE_INVENTORY`（文件清单) | **R5 产出（自动生成）** | 由索引自动产出而非手写——这才能避免「清单与代码脱节」这一常规失败 |
+
+复核表 #8（manifest：timeout / protocol / 执行语义）同样可转 ACCEPT，且**用协议原生字段而非自造**：
+MCP 规范本身有 `annotations`（`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`）——这恰好是「执行语义分类」；
+md_cg 侧再补 `timeout_ms` 与 `needs_clearance` 两个扩展字段。裁剪到 R5，随三份索引文件一起产出。
+
+---
+
+## 十、诚实边界
+
+1. **本计划是「可索引」，不是「可理解」**：doc/code 索引仍是**确定性静态索引**，不含语义蕴含；跨表述的「这段代码其实实现了那段文档的意思」不解决（与 `memory_score.md:36` 「有意剔除神经嵌入」一致）。
+2. **索引质量上限 = 源文件注释质量**：白箱路线的固有代价。没有 docstring 的函数只能索引到签名。
+3. **`hash` 不是内容寻址**：只做变更探测，不保证「内容相同即同节点」。
+4. ~~R0 有一个待闭环疑点~~ → **已在 §十一 闭环**。「`test_p1` EXIT 1 且输出仅 165 字节」的根因与 `test_p0` 同一类：受管环境下 `os.remove` 被环境 shim 接管，
+   删除量越阈即中断进程；且失败形态是**静默截断 + 非零退出**，不是一条 FAIL。现已改为不清空目录（原子覆盖 + 等号守门），并全量复跑验证。
+5. **当前工作区未提交**：`docs/认知图_MD目录方案_v0.1.md`、`bench_p0.py`、`census.py`、`test_p0.py`、`test_p1.py` 已改，`md_cg/corpus.py` 未跟踪——R0 应先收口提交，再动索引层。
+
+---
+
+## 十一、R0 取证纪录（已完成 · 2026-09-10）
+
+### 11.1 基线复跑结果（修前 vs 修后）
+
+| 用例 | 修前 | 修后 | 说明 |
+|---|---|---|---|
+| `test_p0` | ❌ EXIT 1，输出 **443 字节**，**无任何 FAIL 项** | ✅ **25/25** | 死在第一条断言之前 |
+| `test_p1` | ✅ EXIT 0（偶发 ❌ EXIT 1 / 165 字节） | ✅ **38/38** | 新增守门断言 1 条 |
+| `test_p11_consistency` | ❌ EXIT 1，输出 725 字节 | ✅ **27/27** | **此前从未真正执行过** |
+| `test_p12_metacognition` | ❌ EXIT 1，输出 725 字节 | ✅ **32/32** | **此前从未真正执行过** |
+| 全量 28 个用例 | 非零退出 2 个 | ✅ **非零退出 0 个** | — |
+
+### 11.2 缺陷 1（已修 · 严重）：测试「重跑 ≡ 首跑」的前提是脆的，且失败不可见
+
+**现象**：`test_p0` 输出仅 443 字节：
+```
+[风险1] 分桶键退化 …
+[safe-delete][SAFE_DELETE_BULK_CONFIRM_REQUIRED] {"count":722,"threshold":500,"scope":"turn", …}
+```
+**根因链（闭合）**：`test_p0.py:68` → `corpus.reset_root(CONC_ROOT)` → `shutil.rmtree(722 文件)`
+→ 环境 shim（`sitecustomize._safe_remove`）逐个接管删除 → 累计 722 > 阈值 500 → 拒绝并中断进程。
+
+**铁证**：`_md_cg_p0_conc` 实测 **722 文件**，与报错的 `"count":722` 完全吻合；
+`_md_cg_p0` 实测 **0 文件**——说明第一个 `reset_root(ROOT)` 已清空+重建成功，死在第二个；
+`_md_cg_p1` 实测 **350 文件**（< 500）故通过——**只差 150 就到阈值**，这正是历史上「P1 EXIT 1 / 165 字节」的同源形态。
+
+**关键点：文档早已裁决过**。`docs/认知图_MD目录方案_v0.1.md:365-367` 原文：
+> 幂等性：迁移按 node id 原子覆盖写，可反复执行，**不需要先清空目录**。（这不只是便利：清空目录依赖 `rmtree`，
+> 在有安全策略的环境下会被拦截，而"必须先删除才能重跑"的迁移脚本本身就是个脆弱设计。）
+
+而同一份文档 `:350` 又写「测试前 `corpus.reset_root(root)` 清空」，`corpus.py:84-88` 实现的正是清空版——
+**实现踩中了文档自己警告的坑，且文档内部自相矛盾**。
+
+**修法**（按文档已裁决的设计修实现，非新发明）：`reset_root` 默认**不删目录**，只保证存在；
+重跑不变性改由两个可观测事实守住——① 写入侧同 id 原子覆盖（`seed()` 固定 id）；
+② **等号**断言（`test_p0`「索引节点数 == 语料期望数」由无害升级为守门者；
+`test_p1` 新增「knowledge 层 == 336 + 5」守门断言，实测通过）。
+
+### 11.3 缺陷 2（已修）：两个用例因 stdout 编码**从未真正跑过**
+
+`test_p11_consistency.py` / `test_p12_metacognition.py` 缺 `sys.stdout.reconfigure(encoding="utf-8")`。
+Windows 默认 gbk 控制台下打印「d²D/dt²」的 `²`(U+00B2) 直接 `UnicodeEncodeError`，
+**崩在第一条断言之前**，输出只剩 725 字节。仓库其实已有该约定（`test_p0.py:246-249` 的注释甚至
+预言了「只落盘 444 字节」这一失败形态），这两个用例只是漏抄了。**修后 P11 27/27、P12 32/32。**
+
+### 11.4 缺陷 3/4（已修）：读子进程输出未指定 encoding
+
+- `md_cg/audit.py:167-169`（`_verify_code` 的「实测」路径）：`text=True` 退回 locale(gbk) → 被测命令
+  只要输出非 gbk 字节，读取线程即抛 `UnicodeDecodeError` → `p.stdout/p.stderr` 可能为空 →
+  `:174` 的失败证据丢失，「实测失败」退化成**一句没有依据的 REJECT**。
+- `md_cg/test_p22_theory.py:156-159`（CLI 子进程）：同类隐患。
+
+两处均补 `encoding="utf-8", errors="replace"`，对齐 `whitebox.py:93-97` 的正确写法。
+
+### 11.5 环境事实（不修，但必须记录）
+
+装探针抓现场（`subprocess.Popen.__init__` 打点）确认：**受管环境下 `os.remove` 每次都要 spawn 外部进程**
+（`node.exe safe-delete-bulk-guard.cjs` → 判定 → `genie-trash/win32-x64.exe` → 移动；
+其间还会经 `platform.machine()` → `platform.win32_ver()` → `subprocess.check_output('ver')` 再 spawn 一次）。
+
+后果三条，均记入工程规范化的前提：
+1. **删除 ≠ 真删**，而是移入回收站；批量删除有 500 阈值门。
+2. `fsutil.ShardedLog.clear`(`fsutil.py:249`) 逐文件 `os.remove` 是**性能热点**（`rebuild_index` 每次都调）。
+3. `test_p1` 输出尾部那条 `UnicodeDecodeError … _readerthread` 异常**来自环境 shim 自身**
+   （守护线程抛出，不影响退出码，但污染输出、会让 CI 误判）。**仓库侧无法修**，只能记录。
+
+**已验证非仓库问题**：全仓 `platform.*` 使用数 = **0**，该 spawn 由环境 shim 发起。
+
+---
+
+## 十二、R1 取证纪录（已完成 · 2026-09-10）
+
+### 12.1 交付物与改动清单
+
+| 文件 | 改动 | 对应计划项 |
+|---|---|---|
+| `md_cg/codeindex.py` | `render()` 由「非 CCG 注释行」改为输出 **CCG 6 行**；`_walk_defs()` 按源码顺序并携带父级类名；新增 `EXTRACTORS` 后缀注册表（`.py`→AST 精确 / `.ts·.tsx·.js·.mjs·.cjs`→弱提取）；`region_hash()` 收敛为**唯一实现**；`index_dir` 返回 `(items, errors, stats)`（含 `truncated`/`skipped_suffixes`）；无提取器后缀**显式 `raise ValueError`** | 修 B、修 E(部分) |
+| `md_cg/mcp_server.py` | `op=index_code` 透传 stats、落 `verification_basis`/`code_ref`（含 `lang`/`precise`/`hash`/`root`）；新增 `_ref_call` 回读源区间 + `hash_match` 漂移检测；op 枚举与描述加入 `ref`，新增 `ref`/`root` 参数 | 修 C |
+| `md_cg/tokens.py` | `ALL_OPS` 收录 `ref` | §七-11（防漏改） |
+| `md_cg/test_p26_refindex.py` | 新增验收用例（47 断言，全绿） | §七 |
+
+**未改动**：`mdcg.py`（`add` 的 `**extra` 已能承载 `code_ref`，无需改签名）、`nodefile.py`（CCG 判定逻辑本就正确，问题在渲染侧）。
+
+### 12.2 关键缺陷与修法：所有代码节点「恒定 BLINDSPOT」
+
+**现象**：改造前 `index_code` 索引出的代码节点**存得进、判不了、检索不到**——`judge_qualification` 第一条 `ccg_completeness` 即判 BLINDSPOT。
+
+**根因（闭合）**：旧 `render()` 只产 `# path::name` / `# sig` 等**非 CCG 行**，不含「功能名 / 生效条件 / 子功能 / 执行 / 验证方式 / 不适用条件」5 要素中任何一项 → `nodefile.CCG_REQUIRED` 缺项 → `complete=False` → BLINDSPOT。
+即：**渲染层不产 CCG，却要求判定层按 CCG 判**——两侧契约错配。
+
+**修法**：`render()` 产出完整 CCG 6 行（5 要素 + `# 位置`），`verification_basis` 显式落 `frontmatter`（`.py`→`compiler`、弱提取→`other`），使节点在「CCG 完整 + 基底已声明」下判 **ACCEPT**。
+
+**守门断言**（`test_p26` §4/§5）：`ccg_completeness(render(item))["complete"] is True`；`op=read` 真实检索链路命中且 `state == "ACCEPT"`（Python 与 JS 各一例）。
+
+### 12.3 `op=ref` 回读：索引侧与回读侧**共用同一哈希实现**
+
+- `codeindex.region_hash(lines, lineno, end)` 为唯一实现；索引侧写入 `code_ref.hash`，回读侧 `_ref_call` 重算并比对 → `hash_match`。
+- **实测**：未改动 → `hash_match=True`/`stale=False`；改源（保持行数不变只换实现）→ `hash_match=False`/`stale=True`；**重跑 `index_code` → 漂移消除**（可恢复）。
+- 边界**均显式报错，不静默读错位置**：缺 `root` → `ref 未记录 root…`；非代码节点 → `该节点没有 code_ref…`；节点不存在 → `节点不存在：…`。
+- **只读契约**：索引一轮前后被索引源文件 **mtime 全不变**（§七-5）。
+
+### 12.4 「不静默」三处落地（修 E 部分）
+
+| 旧行为 | 新行为 | 断言 |
+|---|---|---|
+| `max_files` 触发时静默返回不完整结果 | `truncated=True` + `truncated_reason`（如 `files=1>=max_files=1`）+ `note` 警告 | §九 |
+| 扫到无提取器后缀静默丢弃 | `stats.skipped_suffixes` 显式列出（实测 `['.txt']`） | §二 |
+| 语法错误文件被吞 | 进 `errors`（实测 `bad.py: bad.py:1: invalid syntax`） | §十 |
+
+### 12.5 §七 验收对照
+
+| 验收项 | 状态 | 说明 |
+|---|---|---|
+| 1 ref 落盘（`code_ref` 字段完整） | ✅ | 9 字段（path/name/kind/lineno/end/lang/precise/hash/root） |
+| 2 CCG 合规（`complete is True`、非 BLINDSPOT） | ✅ | 实测 ACCEPT |
+| 3 回读逐字一致 | ✅ | 文本含 `def compute_energy` 与实现行 |
+| 4 漂移检测 | ⚠️ 部分 | `hash_match` 漂移 ✅；`ref check` CLI 报 `stale`/`dangling` 属 **R3** |
+| 5 只读契约（mtime 不变） | ✅ | — |
+| 6 幂等（节点数不变、id 稳定） | ✅ | 12 == 12；`_refindex.json` 属 **R3** |
+| 7 不复制正文 | ✅ | content 不含函数体语句 |
+| 8 截断诚实 | ✅ | — |
+| 9 文档切块 | ⏭️ | 属 **R2**（`docindex.py`） |
+| 10 权限（`op=ref` 走 `tokens`） | ✅ | `ops_allow` 未含 `ref` 即被 `require_op` 拒 |
+| 11 新 op 注册一致 | ✅ | `ALL_OPS` 含 `ref`/`index_code` |
+
+### 12.6 回归
+
+全量 **29 个用例模块**（R0 的 28 + 新增 `test_p26_refindex`）**非零退出 0 个**；`test_p26_refindex` **47/47** 全绿。
+
+---
+
+## 十三、R2 取证纪录（已完成 · 2026-09-10）
+
+### 13.1 交付物与改动清单
+
+| 文件 | 改动 | 对应计划项 |
+|---|---|---|
+| `md_cg/docindex.py` | **新增**：`.md` 章节切块（ATX 标题栈 + `heading_path` + 行号区间 + `anchor` + 首段摘要）；`render()` 产 **CCG 7 行**（5 要素 + 验证方式 + 位置）；`doc_ref` 11 字段；`_region_hash` 委托 `codeindex.region_hash`（**唯一实现**）；`index_dir(root, patterns, ...)` 返回 `(items, errors, stats)`（含 `truncated`/`truncated_reason`/`skipped_suffixes`）；无提取器后缀**显式 `raise ValueError`** | 修 A、修 C(文档侧) |
+| `md_cg/mcp_server.py` | 新增 `op=index_doc` 分支（逐条 `cg.add(..., layer=, tags=["doc","doc:md","level:<n>"], verification_basis="data", sensitivity=, doc_ref=)`）；`_ref_call` 的 `ref_kind` 扩为 `code_ref`/`doc_ref`；op 枚举与描述加入 `index_doc`；新增 `sensitivity` 参数 | 修 C |
+| `md_cg/tokens.py` | `ALL_OPS` 收录 `index_doc`（`... "index_code","index_doc","ref","theory","link"`） | §七-11（防漏改） |
+| `md_cg/test_p27_docindex.py` | **新增** 验收用例（**49 断言，全绿**） | §七 |
+
+**未改动**：`mdcg.py`（`add` 的 `**extra` 已能承载 `doc_ref`，与 `code_ref` 同路径）、`nodefile.py`（CCG 判定逻辑本就正确，问题在渲染侧）、`mdcos.py`（检索侧无需改——文档节点与代码节点走同一判定路径）。
+
+### 13.2 §七-9 文档切块：三条硬约束的落地与实测
+
+md 不是代码，切块风险集中在「把不该当标题的当标题」。三处均实测守门：
+
+| 硬约束 | 若不处理 | 处理与实测 |
+|---|---|---|
+| **围栏代码块内 `#` 非标题** | `docs/` 里大量 python/shell 片段带 `#` 注释 → 一节被切成假标题、行号错位 | `_headings()` 带围栏跟踪（``` / ~~~ 状态机）。实测：含假标题的样例仍只切出 `['9. 分阶段实施', '代码示例', '总览']`，**假标题零泄漏**，且父节区间**未被假标题截断** |
+| **开头 YAML frontmatter 不当正文** | 切块起点落在 `---` 里，首节点区间从第 1 行开始 | `_body_start()` 跳过 frontmatter。实测：`总览` 节点 `lineno=6`（跳过 YAML） |
+| **正文 `---` 不污染 frontmatter** | 文档正文分隔线被 `nodefile` 当 frontmatter 边界 → `doc_ref` 读不回 | 校验 `doc_ref` 字段可正常 `loads` 往返（`['总览','9. 分阶段实施']`），与 `nodefile.py:19-23` 既有纪律一致、不回归 |
+
+**层级与合并**：只切 `level<=3`（实测条目层级 `[1,2,2]`）；直接正文 <200 字且无子节的小节点**合并进父节摘要**（实测「表格与正文说明。」与围栏代码片段均并入父节，**不丢内容**），避免「一行小标题」也成节点（计划 §八 风险项 1）。
+
+### 13.3 §1.3-3 裁定：层与密级（详见 §1.3-3 的落地）
+
+- **layer = `knowledge`（默认）**：文档是可回读、可漂移检测的**参照知识**，与代码节点同层，保证进默认召回；`contextual` 意为情境绑定、会过期，用在此处会让文档掉出默认召回。实测 guide 节点 `layer=knowledge`。
+- **sensitivity = `internal`（默认）+ 显式写入 frontmatter**：不依赖节点默认值（`mdcos` 读隔离取的是 `fm.sensitivity`；不显式写=靠默认兜底，审计看不出意图）。实测 guide 节点 frontmatter 密级显式为 `internal`。
+- **私有路径段 → 保守降 `private`**：`PRIVATE_HINTS=("private","secret","internal","未公开","私有","内部")` 命中路径段即降级；**只可能更严，不更松**。实测 `guide/`（internal 3）+ `private/`（private 1）→ 分布 `{'internal':3,'private':1}`。
+- **可显式覆盖**：`op=index_doc` 传 `sensitivity="public"` 可整批覆盖（实测 4 节点全 `public`），覆盖后 frontmatter 同步。
+
+### 13.4 `doc_ref` 回读与漂移（与 `code_ref` 共用唯一哈希实现）
+
+- `doc_ref` 落 **11 字段**：`path/heading/heading_path/level/lineno/end/anchor/hash/lang/precise/root`。
+- `op=ref` 回读：索引侧与回读侧**共用 `codeindex.region_hash`**（`docindex._region_hash` 只是委托，杜绝两套实现漂移）。实测未改动 → `hash_match=True`；改文档一段 → `hash_match=False`（**stale 可检出**）；**重跑 `index_doc` → 漂移消除**（派生物可重建）。
+- **只读契约**：索引一轮前后被索引 `.md` 源文件不被触碰（测试断言通过）。
+- **边界显式报错、不静默**：无提取器后缀 `raise ValueError`；`max_files` 触发时 `truncated=True` + `truncated_reason="files=1>=max_files=1"` + `note` 警告。
+
+### 13.5 §七 验收对照
+
+| 验收项 | 状态 | 说明 |
+|---|---|---|
+| 1 ref 落盘（`doc_ref` 字段完整） | ✅ | 11 字段完整、`loads` 往返不丢 |
+| 2 CCG 合规（`complete is True`、非 BLINDSPOT） | ✅ | 文档节点实测 `ACCEPT` |
+| 3 回读逐字一致 | ✅ | 回读文本 = 源章节（含标题与表格行） |
+| 4 漂移检测 | ⚠️ 部分 | `hash_match` 漂移 ✅ + 重跑消除 ✅；`ref check` CLI/`_refindex.json` 报 `stale`/`dangling` 属 **R3** |
+| 5 只读契约（mtime 不变） | ✅ | — |
+| 6 幂等（节点数不变、id 稳定） | ✅ | `304 == 304`；id 集合稳定（按 id 原子覆盖，不清目录） |
+| 7 不复制正文 | ✅ | 不逐字复制整节；「执行」栏摘要封顶 ≤200 字 |
+| 8 截断诚实 | ✅ | — |
+| **9 文档切块** | ✅ | 三硬约束全过（§13.2）；§9 真实章节行号 `491 == 491` |
+| 10 权限（`op=ref` 走 `tokens`） | ✅ | R1 已覆盖，文档节点同路径 |
+| 11 新 op 注册一致 | ✅ | `ALL_OPS` 含 `index_doc`；工具 op 枚举 == `ALL_OPS`（`only-schema=[] only-ops=[]`） |
+
+### 13.6 回归
+
+全量 **30 个用例模块**（R1 的 29 + 新增 `test_p27_docindex`）**非零退出 0 个**；`test_p27_docindex` **49/49** 全绿。
+
+### 13.7 诚实边界（R2 新增）
+
+1. **计数口径**：计划 §六 R2 目标原写「`docs/` 30 份」——那是把 `docs/` 下非 md 也计入的早期估计；**实际 md 文件 19 份**，R2 实测 `files=19/19`（无静默跳过）。后续阶段一律以「按后缀注册表实际匹配数」为准，不再用估计值。
+2. **文档索引仍是确定性的位置索引**，不含语义：能回答「这段写在哪个文档哪一节」，不能回答「这段文档说的是哪段代码」（后者属 R4 互链，且仍不做语义蕴含）。
+3. **`doc_ref` 不承诺永久有效**，只承诺「可检出」（`hash` 变更探测）。
+
+---
+
+## 十四、R3 取证纪录（已完成 · 2026-09-10）
+
+### 14.1 交付物与改动清单
+
+| 文件 | 改动 | 对应计划项 |
+|---|---|---|
+| `md_cg/refindex.py` | **新增**：统一 ref 协议（`REF_KEYS` / `registry()` / `kind_of_path()` / `extract()`，无提取器后缀**显式 `raise`**）；`Ledger` 索引水位（`_refindex.json`，**键 = 源文件绝对路径**，逐文件记 `(size, mtime)` + 节点区间 + **源大域 `root`**）；`index_dir()` 统一调度（`fresh`/`on_file` 钩子 + 增量跳过 + 截断留痕 + `prune`/`reconcile` 对账）；`probe_ref()`/`read_ref()` 回读；`check_refs()` 漂移·悬空巡检；`rebuild()` 修复动作 | 修 D、修 F |
+| `md_cg/codeindex.py` / `md_cg/docindex.py` | `index_dir` 加 `fresh`/`on_file` 钩子与 `skipped_unchanged` 计数（默认 `None` → 与改造前**逐字一致**） | 修 F |
+| `md_cg/mcp_server.py` | `op=index_code`/`index_doc` 改走 `refindex.index_dir` + `refindex.add_items`（**落盘唯一实现**）；新增 `incremental`/`max_items` 参数（传 `sensitivity` 时自动退回全量）；`_ref_call` 重写为 `action=read\|check\|stat`，**未知 action `raise`**；`read` 与检索结果带 `ref`/`ref_kind` | 修 D、修 F |
+| `md_cg/sustain.py` | `diagnose` 增 `ref_stale`/`ref_dangling`/`ref_check_truncated` 巡检项与 `ref_checked`/`ref_stale`/`ref_dangling` stats；`heal` 增 `rebuild_refs` 动作（派生物，符合既有自愈边界） | 修 D 接入 |
+| `md_cg/test_p28_refcheck.py` | **新增** 验收用例（**45 断言，全绿**） | §七 |
+
+### 14.2 三个真实缺陷（首轮实测 39 通过 / 6 失败 → 修后 45/0）
+
+首轮失败不是断言太严，而是**实现确实错**，逐条留证：
+
+1. **巡检把一切都误判成 `dangling`（严重）**：`Ledger.record()` 没记源大域，`check_refs` 拿 `ledger.root`（= 认知图根）去拼 `root/rel`；而源在别处（如临时目录 / 任意被索引的大域），于是**文件永远找不到**。实测：改源一行后 `stale=[]`、`dangling=[alpha.py,beta.py,...]`，`sustain.diagnose` 因此报 `ref_dangling` 而非 `ref_stale`。
+   → 逐文件记 `root`，巡检用**每个源文件自己的 root**；且键改绝对路径。
+2. **水位不会遗忘死根**：键若按 `rel`（或虽按绝对路径但从不清理），源大域整个搬迁/删除后条目永久残留。因 `node_id` 与绝对路径无关，`nodes` 过滤挡不住这些幽灵条目，巡检会报**永不消失的 dangling**（`heal` 也治不好，因为条目不在任何会被重建的 root 下）。实测：连跑两次用例 → 水位 `files=4`（含上一轮已删临时目录的 2 条），`重跑后 dangling 消除` 失败。
+   → 新增 `prune()`（剪掉源大域已不存在的条目，真悬空由节点自带 ref 兜底）+ `reconcile(root, kind, seen)`（一次**完整**索引后，本 root 下没扫到的旧条目剪掉）。**截断的索引不对账**——没扫完 ≠ 剩下的都消失了。
+3. **落盘字节抖动**：`updated_at`/`ts` 用 `time.time()` 全精度浮点，`float` 最短 repr 的小数位长度会变 → 重跑 3 次体积 `1156 → 1157`，「不膨胀」判据假失败。→ 时间戳压到 **1 位小数**（`_now()`），体积稳定（实测 `1504 → 1504`）。
+
+### 14.3 增量（修 F）：未变文件不重切
+
+- `_refindex.json` 按 `(size, mtime)` 双等判「未变」，`incremental=True` 时**不读盘**直接跳过，计入 `skipped_unchanged`。
+- 实测：首轮全量 `indexed=6 / files=2`；第二轮 `incremental=true` → `skipped_unchanged=2 / indexed=0`，**节点数不变（幂等）**；不传 `incremental` 时 `skipped_unchanged=0`（默认仍全量，保证不漏召回）；两轮 `id` 集合稳定。
+- 水位键 = **源文件绝对路径**：一份认知图可索引多个大域，只按 `rel` 记会在 `alpha.py` 这类同名文件上互相覆盖（静默丢水位）。
+
+### 14.4 漂移 / 悬空（修 D）：唯一判定实现
+
+- 回读与巡检**共用 `probe_ref` / `codeindex.region_hash`**，杜绝「回读说没漂、巡检说有漂」。`stale` 判据是**内容哈希**，不是 mtime——只 `touch` 不改内容，报 `ok` 才对（段⑧ 首版用例正是写入了与索引**相同**的正文，属用例缺陷，已改为第二个真实漂移变体）。
+- 实测：改源一行（`lineno 5..7` 区间）→ `check` `ok=false`、`stale=[alpha.py ×2]`；重跑 `index_code` → `stale=[]`；删 `beta.py` → `dangling=[beta.py ×2]`；恢复源并重建 → `dangling=[]`。
+- **只读契约**：巡检前后被索引源文件 `mtime` 不变；`heal` 也不修改源文件（源里仍是改后的正文）。
+- **快路径**：ledger 判「未变」的文件不读盘直接判 ok；变了的才读一次按记录区间重算哈希。ledger 覆盖不到的节点再回退逐节点探测（`only_tagged=True` 只扫带 `code`/`doc` 标签者）。
+
+### 14.5 截断不静默 + 接入 sustain
+
+- `max_files=1` → `truncated=true`、`truncated_reason="files=1>=max_files=1"`、`note` 带 ⚠；并写进水位 `last_index.truncated=true`，重跑全量后回 `false`（`action=stat` 可见）。
+- `sustain.diagnose`：改源后 `issues` 含 `ref_stale`、`stats.ref_stale=2` 且带 `ref_checked`；`heal` 动作含 `rebuild_refs`（实测 `['rebuild_refs','flush_index']`），heal 后 `ref_stale` 消除、源文件未被修改。
+- 巡检超过 `max_nodes` 时报 `ref_check_truncated`（覆盖缺口显式说出，而非静默截断）。
+
+### 14.6 §七 验收对照
+
+| 验收项 | 状态 | 说明 |
+|---|---|---|
+| 1 ref 落盘字段完整 | ✅ | `code_ref` 9 字段 / `doc_ref` 11 字段，注册表覆盖两类 |
+| 2 CCG 合规（非 BLINDSPOT） | ✅ | 由 `index_code`/`index_doc` 产出的节点实测 `ACCEPT`（R1/R2 已覆盖） |
+| 3 回读逐字一致 | ✅ | 回读文本 = 源区间，`hash_match=true` |
+| **4 漂移检测** | ✅ | `ref check` 报 `stale`；重建后消除；纯 mtime 变更**不**误报（§14.4） |
+| **5 悬空检测** | ✅ | 删源报 `dangling`；恢复重建后消除；死根条目被 `prune` |
+| 6 只读契约（mtime 不变） | ✅ | 巡检与 heal 均不改源文件 |
+| 7 幂等（节点数不变、id 稳定） | ✅ | 增量/全量重跑节点数与 id 集合均稳定 |
+| **8 截断诚实** | ✅ | `truncated` + `truncated_reason` + 写进水位 `last_index` |
+| 9 增量不重切 | ✅ | `skipped_unchanged=2 / indexed=0` |
+| 10 权限（`op=ref` 走 `tokens`） | ✅ | `ALL_OPS` 仍收录 `ref`/`index_code`；未知 action 不静默成功 |
+| 11 派生物不膨胀 | ✅ | `_refindex.json` `< 20KB`；重跑 3 次字节数不变；`files` 无幽灵条目 |
+
+### 14.7 回归
+
+全量 **31 个用例模块**（R2 的 30 + 新增 `test_p28_refcheck`）**非零退出 0 个**；`test_p28_refcheck` **45/45** 全绿；`test_p26_refindex` 47/47、`test_p27_docindex` 49/49 无回归；`refindex.py` 改动文件 lint 0 错误。
+
+### 14.8 诚实边界（R3 新增）
+
+1. **`stale` 只承诺「可检出」，不承诺「自动定位到改了哪一行」**：报的是区间哈希不匹配 + 原区间坐标，不做行级 diff。
+2. **水位是派生物缓存，可随时删除**：`prune`/`reconcile` 让它有界，但语义上它只是提速；删掉后巡检退回逐节点探测，结论不变。
+3. **多根同名文件**：键为绝对路径，同名文件分属不同大域**互不覆盖**；但同一文件被两个大域同时索引时，`nodes` 会指向同一组 id，最后写入者胜（与索引自身语义一致）。
+4. **`max_files` 截断时不对账**（§14.2-2），因此截断轮次后水位会短暂保留未扫文件的旧条目——这是**保守**选择：宁可多留，不可误删。
+
+---
+
+*计划生成：2026-09-10 · 证据：§一 全部为源码行级核对结果 · 未核对项已单列 §1.3 / §十 · §十一 为 R0 实测取证 · §十二 为 R1 实测取证 · §十三 为 R2 实测取证 · §十四 为 R3 实测取证*

package/docs//350/256/244/347/237/245/345/233/276/344/275/234/344/270/272/350/256/260/345/277/206/346/223/215/344/275/234/347/263/273/347/273/237_/350/257/204/344/274/260/344/270/216/350/267/257/347/272/277_v0.1.md

@@ -1,6 +1,6 @@
 # 认知图作为「记忆操作系统」· 现状评估与路线
 
-> 对象：`dsh-memory/llm-adapter-poc/md_cg/`（codebuddy 实现，基于《认知图_MD目录方案_v0.1》）
+> 对象：`dsh-memory/md_cg/`（codebuddy 实现，基于《认知图_MD目录方案_v0.1》）
 > 目标：评估它离「记忆操作系统（memory OS）」还差什么，给出路线。
 > 2026-09-08 · dsh 端独立验证
 
@@ -69,7 +69,7 @@ tags / spatial / temporal / edges / state_attributes(含 CCG comment 5 要素)
 2. **与灵枢/AEIS 未统一** —— 认知图（md_cg）与 AEIS 记忆（sqlite）**并行两套**。OS 的前提是**单一权威存储**。
 3. **进程/权限模型缺失** —— 多 agent 并发写、租户隔离、访问控制都还没有（文件锁只解决了互斥，没解决"谁可以写什么"）。
 
-> 另：`llm-adapter-poc/` 目录混入数百个 `diag-*/verify-*/analyze-*` 一次性脚本——**引擎需要从工作区里提取干净**，否则无法作为 OS 长期维护。
+> 另：md_cg 已从 `llm-adapter-poc/` 实验工作区提取到工作区顶层 `md_cg/`（2026-09-09），一次性脚本留在原目录待清理。
 
 ---