@furongjun1999/dsh-memory 0.4.11 → 0.5.1

package/docs/mdcg//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

@@ -1,588 +1,588 @@
-# 认知图 · 索引与工程规范化 计划 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/mdcg/认知图_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()` 回读 + **节点级对账** `prune_orphans()`（过期代）/ `prune_dangling()`（悬空）（R3.1）+ `skip_dirs` 透传（R3.2） |
-| `md_cg/docindex.py` | **新增** | `.md` 章节切块：ATX 标题栈、heading_path、行号区间、首段摘要、anchor；`skip_dirs` 追加排除（R3.2，复用 `codeindex.skip_matcher`） |
-| `md_cg/codeindex.py` | **改造** | ①`render()` 改产 CCG 5 要素（修 B）②后缀注册化（`.py` 走 AST、`.ts/.js` 走弱提取器）③`index_dir` 返回 `truncated` 与 `files_scanned`（修 F）④`node_id` 保持稳定（重复索引幂等）⑤`skip_matcher()` + `skip_dirs`（R3.2，两条链路的唯一实现） |
-| `md_cg/mcp_server.py` | **扩** | 新增 `op=ref`（`action=read\|check\|stat\|prune`，兼回读 / 巡检 / 清退）；`op=index_code` 保留为别名并透传 `truncated`；`op=index_doc`；op 枚举与 `:542-546` 同步；`index_code`/`index_doc` 索引后自动节点级对账（`prune` 默认开、`prune_dry_run` 可预演，R3.1）；`skip_dirs` 透传 + `skipped_dirs` 回报（R3.2） |
-| `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/mdcg/认知图_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` 修复 | ✅ |
-| **R3.1** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：节点级对账——`prune_orphans`（改标题产生的过期代）+ `prune_dangling`（源已删的悬空节点），接入 `index_code`/`index_doc` 与 `op=ref action=prune` | ✅ P27 §10/§10b 全绿；真实现场悬空 **20 → 0**（`LIVE_HITS=0`/`TRASH_HITS=20`）；受影响面 7 模块 6 绿 1 环境红 | ✅ |
-| **R3.2** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：索引器**追加排除** `skip_dirs`（`index_code`/`index_doc`）——把 `.gitignore` 已忽略却物理留存的实验产物挡在门外，替代「调大 `max_files`」这一掩盖手段 | ✅ P27 **75/0** 全绿（§9 由 `500/2388` 红转 `30/30`）；新增 §9b 验证匹配口径 / 只增不减 / 可审计；受影响面 10 模块全绿 | ✅ |
-| **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/mdcg/认知图_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/mdcg/认知图_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），因此截断轮次后水位会短暂保留未扫文件的旧条目——这是**保守**选择：宁可多留，不可误删。
-
----
-
-## 十五、R3.1 / R3.2 取证纪录（已完成 · 2026-09-12）：节点级对账 + 索引追加排除
-
-> **为什么单开一节而不并进 R3**：R3 只做了**水位层**对账（`Ledger.reconcile`/`prune` 剪的是 `_refindex.json` 的水位条目），
-> **节点层**两类残留无人处置——`node_id = sha1(相对路径 + "#" + heading_path)`，文档标题一变整篇 id 全量重算，
-> 于是同 path 的旧代节点与新代节点并存（一份文档召回两份）；源文件一删，节点永久 `dangling`。
-> §十四 验收项 5 的原话是「删源报 `dangling`」——**悬空当时只承诺「可检出」，本节补上「可处置」**。
-
-### 15.1 交付物与改动清单
-
-| 文件 | 动作 | 职责 |
-|---|---|---|
-| `md_cg/refindex.py` | **扩** | 节点级对账节：`_norm_root`/`_same_root`/`_norm_rel`（大域与路径归一）+ `_forget_many`（逐条软删、受保护拦下、缺 `forget` 能力显式报错）+ `prune_orphans`（清退同 root+path 的过期代）+ `prune_dangling`（清退悬空） |
-| `md_cg/mcp_server.py` | **扩** | `op=ref` 增 `action=prune`/`prune_dangling`；`index_code`/`index_doc` 返回前接 `_prune_after_index`（读 `prune` 默认 True、`prune_dry_run` 预演）；schema 增 `prune`/`prune_dry_run`/`roots` |
-| `md_cg/test_p27_docindex.py` | **扩** | 新增【10】节点级对账、【10b】悬空清退；`cg` 由 `MdCG` 改 `MdCGOS`（对齐生产路径） |
-
-### 15.2 两个真实缺陷（首轮实测暴露，逐条留证）
-
-1. **对账静默假成功（严重）**：`cg.index['nodes']` 是 `mdcg._scan_nodes()` 产出的**元数据快照**（path/layer/tags/importance/edges…），**不含 `ref`**——`ref` 只写在节点 frontmatter 里。首版直接对索引条目调 `ref_of()`，**恒返回 `('', None)`**，于是「清退了 0 条」却报 `ok=True`。实测 `prune_orphans count=0`、`prune_dangling candidates=0`。
-   → 改为 `node = cg.get(nid)` 取回节点再 `ref_of(node)`，并加 `doc`/`code` 标签预筛（与 `check_refs` 同口径，免得为全库每条记忆都读一次盘）。
-2. **`forget` 能力分层被忽略**：`forget` 属 **`MdCGOS` 层**（保护裁决 + 回收站 + 删除清单），基础层 `MdCG` 没有任何删除原语。首版测试用 `MdCG(ROOT)`，实测 `'MdCG' object has no attribute 'forget'`。
-   → ①`_forget_many` 缺能力时**显式返回错误、不静默跳过**（文案点名「生产路径是 MdCGOS，测试请用 MdCGOS」）；②测试改 `MdCGOS` 构造。
-   → 与 P43 的教训同构：**双实现类（`MdCG`/`MdCGOS`）必须双路覆盖**，只测一条路径等于留静默盲区。
-
-### 15.3 三条保守约束（宁可不删，不可误删）
-
-- **只清「本次真正重切过」的文件**：`prune_orphans` 的判定范围限于 `items` 里的 path；增量索引跳过的未变文件不进判定——否则会把完好节点整片误删。
-- **截断轮次不清退**：没扫完 ≠ 剩下的都过期。`_prune_after_index` 见 `truncated=True` 直接返回，不算、不删。
-- **探测失败不算悬空**：`probe_ref` 抛异常即跳过，不把「读不到」当成「源已删」。
-
-### 15.4 真实现场处置（`AEIS/data/mdcg`）
-
-常驻 MCP 进程加载的仍是旧代码（`op=ref` 只认 `read|check|stat`），故按**工作纪律第7条**走等价兜底：python 直调同一模块（身份从 CodeBuddy `mcp.json` 读取，不落盘、不回显令牌）。
-
-| 步骤 | 命令 | 实测 |
-|---|---|---|
-| 巡检 | `op=ref action=check max_nodes=20000` | `checked=5456`、`dangling=20`、`stale=42`、`truncated=false` |
-| 预演 | `action=prune_dangling dry_run=true` | `scanned=10136`、`candidates=20`、`count=20` |
-| 清退 | `action=prune_dangling`（designer 身份，`can_admin=true`） | `count=20`，全部软删进 `trash/` |
-| 复核 | 同 `dry_run` 再跑 + 落盘核对 | `candidates=0`；20 个 `node_id` **`LIVE_HITS=0` / `TRASH_HITS=20`**；`trash/` 与 `_deletions.jsonl` 均 36 条 |
-
-悬空来源单一：4 个已删的临时脚本（`_tmp_v3check.py`×2、`cmp_rows.py`×4、`dump_rows.py`×2、`vision.py`×12），非业务记忆，清退无信息损失且可 `op=restore` 回滚。
-
-### 15.5 诚实边界（R3.1 新增）
-
-1. **对账是 O(带标签节点数) 次读盘**：`ref` 不在索引快照里，只能逐节点 `cg.get()`。每次 `index_code`/`index_doc` 都会带上这一遍开销（本仓 ~500 节点级、现场 10k 节点级；后者秒级但非零成本）。若成热点，正解是把 `ref` 摘要进 `_scan_nodes` 快照，而非放松判定。
-2. **只处置「孤儿」与「悬空」，不处置 `stale`**：漂移（源已改）用重建解决（重跑索引或 `sustain.heal`），不靠清退——删掉再索引等于绕远路。
-3. **`stale` 与「孤儿」判据不同**：孤儿靠 `node_id` 重算比对（结构性），不看内容哈希；内容已变但 id 未变的节点不属孤儿。
-4. **本仓 `test_p27` §9 的计数断言曾在本机为红**（`files=500/2388`，唯一失败项，非 R3.1 改动引起）：`.gitignore` 已整目录忽略的 `docs/experiments/`（实测 2358 个 md 于 `docs/experiments/md-cg-gate-probe/`）物理仍在盘上，把 `docs/` 从 30 个 md 撑到 2388，越过 `max_files=500`。**处置口径已裁定并落地 → 见 §15.7（R3.2）**：给索引器加**追加排除**，而非调大上限。裁后 §9 由 `500/2388` 转为 `30/30` 全绿。
-
-### 15.6 回归（R3.1）
-
-受影响面 7 模块：`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p28_refcheck` 45/0、`test_p2_mcp` 63/0 **全绿**；`test_p27_docindex` **68/1**（当时唯一红项为 §15.5-4 的环境事实，非代码缺陷）。
-
-### 15.7 R3.2：`skip_dirs` 追加排除（原 §15.5-4 的裁定落地）
-
-**问题**：索引的「扫描范围」只有**下限**（`SKIP_DIRS` 硬编码）没有**上限**——`.gitignore` 已整目录忽略的实验产物物理仍留在盘上，就照样被扫。本仓 `docs/` 真实内容 30 个 md，被 `docs/experiments/` 的 2358 个撑到 2388，直接压爆 `max_files=500`。此前唯一的应对是「调大 `max_files`」，那是**掩盖**：上限调到 2500，下次再多一批产物同样爆。
-
-**交付物**：
-
-| 文件 | 动作 | 职责 |
-|---|---|---|
-| `md_cg/codeindex.py` | **扩** | `skip_matcher(skip_dirs)` → `(hit, rules)`；`index_dir(..., skip_dirs=None)` 在 `os.walk` 处**追加**剪枝；`stats` 增 `skip_dirs`（规则回显）/ `skipped_dirs`（实际排掉的目录） |
-| `md_cg/docindex.py` | **扩** | 同签名同语义，复用 `codeindex.skip_matcher`（**唯一实现**，避免两条链路口径漂移） |
-| `md_cg/refindex.py` | **扩** | `index_dir(..., skip_dirs=None)` 透传给底层 |
-| `md_cg/mcp_server.py` | **扩** | `index_code`/`index_doc` 透传 `skip_dirs`；`_skip_dirs_report()` 把「排掉了什么」压成 `skipped_dirs` / `skipped_dirs_count` / `skip_dirs` 回报；schema 增 `skip_dirs` |
-| `md_cg/test_p27_docindex.py` | **扩** | §9 改用 `skip_dirs=["experiments"]`；新增 §9b 专测匹配口径 / 只增不减 / 可审计 |
-
-**三条设计裁定**：
-
-1. **只增不减**：`skip_dirs` 在 `SKIP_DIRS` **同一处**生效，调用方只能追加，**不能关掉** `.git`/`.venv`/`node_modules` 这类内置保护——否则一次参数写错就能把版本库元数据索引进认知图。
-2. **排除不许静默**（与「截断不许静默」同一纪律）：命中目录写进 `stats["skipped_dirs"]`（就地追加、不依赖末尾汇总，所以**截断提前 return 时也带得走**），MCP 层再压成可读回报。调用方据此能把「源文件真的少了」与「被规则排掉了」区分开。
-3. **两类匹配口径可混用**：含 `/` 按**相对 root 的路径**（`docs/experiments` 只排这一处）；不含 `/` 按**目录名**（`experiments` 排任意层级同名目录）。反斜杠 / 首尾斜杠先归一——否则「规则传了却不生效」又是一次静默失配。默认 `None` 时 `hit is None`、走原路径，**行为与改造前逐字一致**（同 `fresh`/`on_file` 纪律）。
-
-**实测**（`test_p27` §9 / §9b）：
-- 本仓 `docs/`：`files=30/30`、`truncated=false`，`skipped_dirs=['experiments']`（此前 `files=500/2388` 已截断）。
-- 合成树（`keep.md` + 两层 `experiments/*` + `sub/experiments/y.md` + `node_modules/pkg/n.md`）：不给规则 → `files=4`「内置排除照旧」；`skip_dirs=["experiments"]` → `files=1` 且 `skipped=['docs/experiments','sub/experiments']`（**同时证明 `node_modules` 仍被排，即只增不减**）；`skip_dirs=["docs/experiments"]` → `files=2` 只排这一处；`skip_dirs=["docs\\experiments\\"]` → `files=2`（归一后仍生效）。
-
-### 15.8 诚实边界（R3.2 新增）
-
-1. **按路径的规则不跨 root**：`docs/experiments` 是「相对本次 root」的路径，换个 root 就不再匹配；跨仓复用规则要用不含 `/` 的目录名形式。
-2. **同名目录一网打尽**：`skip_dirs=["experiments"]` 会排掉**任意层级**的同名目录。这正是它对 `2_ai` 那种多子项目树好用的原因，但也意味着「只想排一处」必须写全路径。
-3. **排除只影响扫描，不清理既有节点**：已在库、但本次被排掉的目录里的节点**不会**因此消失（`prune_orphans` 的判定范围限于本次真正重切过的 path，见 §15.3-1）。若要清掉，需先不带 `skip_dirs` 跑一次让它们成为孤儿，或直接 `prune_dangling`。
-4. **`max_files` 仍是安全上限而非目标值**：`skip_dirs` 解决「噪声挤占额度」，不解决「真实内容超过 500」——真超了应当**调大 `max_files`**（那是真实内容），而不是继续加排除。
-
-### 15.9 回归（R3.2）
-
-受影响面 10 模块**全绿**：`test_p2_mcp` 63/0、`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p27_docindex` **75/0**、`test_p28_refcheck` 45/0、`test_p29_session_ingest_export` 48/0、`test_p30_maintain` 55/0、`test_p32_backfill` 58/0。改动文件 lint 0 错误。
-
----
-
-*计划生成：2026-09-10 · 证据：§一 全部为源码行级核对结果 · 未核对项已单列 §1.3 / §十 · §十一 为 R0 实测取证 · §十二 为 R1 实测取证 · §十三 为 R2 实测取证 · §十四 为 R3 实测取证 · §十五 为 R3.1 / R3.2 实测取证*
+# 认知图 · 索引与工程规范化 计划 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/mdcg/认知图_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()` 回读 + **节点级对账** `prune_orphans()`（过期代）/ `prune_dangling()`（悬空）（R3.1）+ `skip_dirs` 透传（R3.2） |
+| `md_cg/docindex.py` | **新增** | `.md` 章节切块：ATX 标题栈、heading_path、行号区间、首段摘要、anchor；`skip_dirs` 追加排除（R3.2，复用 `codeindex.skip_matcher`） |
+| `md_cg/codeindex.py` | **改造** | ①`render()` 改产 CCG 5 要素（修 B）②后缀注册化（`.py` 走 AST、`.ts/.js` 走弱提取器）③`index_dir` 返回 `truncated` 与 `files_scanned`（修 F）④`node_id` 保持稳定（重复索引幂等）⑤`skip_matcher()` + `skip_dirs`（R3.2，两条链路的唯一实现） |
+| `md_cg/mcp_server.py` | **扩** | 新增 `op=ref`（`action=read\|check\|stat\|prune`，兼回读 / 巡检 / 清退）；`op=index_code` 保留为别名并透传 `truncated`；`op=index_doc`；op 枚举与 `:542-546` 同步；`index_code`/`index_doc` 索引后自动节点级对账（`prune` 默认开、`prune_dry_run` 可预演，R3.1）；`skip_dirs` 透传 + `skipped_dirs` 回报（R3.2） |
+| `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/mdcg/认知图_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` 修复 | ✅ |
+| **R3.1** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：节点级对账——`prune_orphans`（改标题产生的过期代）+ `prune_dangling`（源已删的悬空节点），接入 `index_code`/`index_doc` 与 `op=ref action=prune` | ✅ P27 §10/§10b 全绿；真实现场悬空 **20 → 0**（`LIVE_HITS=0`/`TRASH_HITS=20`）；受影响面 7 模块 6 绿 1 环境红 | ✅ |
+| **R3.2** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：索引器**追加排除** `skip_dirs`（`index_code`/`index_doc`）——把 `.gitignore` 已忽略却物理留存的实验产物挡在门外，替代「调大 `max_files`」这一掩盖手段 | ✅ P27 **75/0** 全绿（§9 由 `500/2388` 红转 `30/30`）；新增 §9b 验证匹配口径 / 只增不减 / 可审计；受影响面 10 模块全绿 | ✅ |
+| **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/mdcg/认知图_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/mdcg/认知图_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），因此截断轮次后水位会短暂保留未扫文件的旧条目——这是**保守**选择：宁可多留，不可误删。
+
+---
+
+## 十五、R3.1 / R3.2 取证纪录（已完成 · 2026-09-12）：节点级对账 + 索引追加排除
+
+> **为什么单开一节而不并进 R3**：R3 只做了**水位层**对账（`Ledger.reconcile`/`prune` 剪的是 `_refindex.json` 的水位条目），
+> **节点层**两类残留无人处置——`node_id = sha1(相对路径 + "#" + heading_path)`，文档标题一变整篇 id 全量重算，
+> 于是同 path 的旧代节点与新代节点并存（一份文档召回两份）；源文件一删，节点永久 `dangling`。
+> §十四 验收项 5 的原话是「删源报 `dangling`」——**悬空当时只承诺「可检出」，本节补上「可处置」**。
+
+### 15.1 交付物与改动清单
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `md_cg/refindex.py` | **扩** | 节点级对账节：`_norm_root`/`_same_root`/`_norm_rel`（大域与路径归一）+ `_forget_many`（逐条软删、受保护拦下、缺 `forget` 能力显式报错）+ `prune_orphans`（清退同 root+path 的过期代）+ `prune_dangling`（清退悬空） |
+| `md_cg/mcp_server.py` | **扩** | `op=ref` 增 `action=prune`/`prune_dangling`；`index_code`/`index_doc` 返回前接 `_prune_after_index`（读 `prune` 默认 True、`prune_dry_run` 预演）；schema 增 `prune`/`prune_dry_run`/`roots` |
+| `md_cg/test_p27_docindex.py` | **扩** | 新增【10】节点级对账、【10b】悬空清退；`cg` 由 `MdCG` 改 `MdCGOS`（对齐生产路径） |
+
+### 15.2 两个真实缺陷（首轮实测暴露，逐条留证）
+
+1. **对账静默假成功（严重）**：`cg.index['nodes']` 是 `mdcg._scan_nodes()` 产出的**元数据快照**（path/layer/tags/importance/edges…），**不含 `ref`**——`ref` 只写在节点 frontmatter 里。首版直接对索引条目调 `ref_of()`，**恒返回 `('', None)`**，于是「清退了 0 条」却报 `ok=True`。实测 `prune_orphans count=0`、`prune_dangling candidates=0`。
+   → 改为 `node = cg.get(nid)` 取回节点再 `ref_of(node)`，并加 `doc`/`code` 标签预筛（与 `check_refs` 同口径，免得为全库每条记忆都读一次盘）。
+2. **`forget` 能力分层被忽略**：`forget` 属 **`MdCGOS` 层**（保护裁决 + 回收站 + 删除清单），基础层 `MdCG` 没有任何删除原语。首版测试用 `MdCG(ROOT)`，实测 `'MdCG' object has no attribute 'forget'`。
+   → ①`_forget_many` 缺能力时**显式返回错误、不静默跳过**（文案点名「生产路径是 MdCGOS，测试请用 MdCGOS」）；②测试改 `MdCGOS` 构造。
+   → 与 P43 的教训同构：**双实现类（`MdCG`/`MdCGOS`）必须双路覆盖**，只测一条路径等于留静默盲区。
+
+### 15.3 三条保守约束（宁可不删，不可误删）
+
+- **只清「本次真正重切过」的文件**：`prune_orphans` 的判定范围限于 `items` 里的 path；增量索引跳过的未变文件不进判定——否则会把完好节点整片误删。
+- **截断轮次不清退**：没扫完 ≠ 剩下的都过期。`_prune_after_index` 见 `truncated=True` 直接返回，不算、不删。
+- **探测失败不算悬空**：`probe_ref` 抛异常即跳过，不把「读不到」当成「源已删」。
+
+### 15.4 真实现场处置（`AEIS/data/mdcg`）
+
+常驻 MCP 进程加载的仍是旧代码（`op=ref` 只认 `read|check|stat`），故按**工作纪律第7条**走等价兜底：python 直调同一模块（身份从 CodeBuddy `mcp.json` 读取，不落盘、不回显令牌）。
+
+| 步骤 | 命令 | 实测 |
+|---|---|---|
+| 巡检 | `op=ref action=check max_nodes=20000` | `checked=5456`、`dangling=20`、`stale=42`、`truncated=false` |
+| 预演 | `action=prune_dangling dry_run=true` | `scanned=10136`、`candidates=20`、`count=20` |
+| 清退 | `action=prune_dangling`（designer 身份，`can_admin=true`） | `count=20`，全部软删进 `trash/` |
+| 复核 | 同 `dry_run` 再跑 + 落盘核对 | `candidates=0`；20 个 `node_id` **`LIVE_HITS=0` / `TRASH_HITS=20`**；`trash/` 与 `_deletions.jsonl` 均 36 条 |
+
+悬空来源单一：4 个已删的临时脚本（`_tmp_v3check.py`×2、`cmp_rows.py`×4、`dump_rows.py`×2、`vision.py`×12），非业务记忆，清退无信息损失且可 `op=restore` 回滚。
+
+### 15.5 诚实边界（R3.1 新增）
+
+1. **对账是 O(带标签节点数) 次读盘**：`ref` 不在索引快照里，只能逐节点 `cg.get()`。每次 `index_code`/`index_doc` 都会带上这一遍开销（本仓 ~500 节点级、现场 10k 节点级；后者秒级但非零成本）。若成热点，正解是把 `ref` 摘要进 `_scan_nodes` 快照，而非放松判定。
+2. **只处置「孤儿」与「悬空」，不处置 `stale`**：漂移（源已改）用重建解决（重跑索引或 `sustain.heal`），不靠清退——删掉再索引等于绕远路。
+3. **`stale` 与「孤儿」判据不同**：孤儿靠 `node_id` 重算比对（结构性），不看内容哈希；内容已变但 id 未变的节点不属孤儿。
+4. **本仓 `test_p27` §9 的计数断言曾在本机为红**（`files=500/2388`，唯一失败项，非 R3.1 改动引起）：`.gitignore` 已整目录忽略的 `docs/experiments/`（实测 2358 个 md 于 `docs/experiments/md-cg-gate-probe/`）物理仍在盘上，把 `docs/` 从 30 个 md 撑到 2388，越过 `max_files=500`。**处置口径已裁定并落地 → 见 §15.7（R3.2）**：给索引器加**追加排除**，而非调大上限。裁后 §9 由 `500/2388` 转为 `30/30` 全绿。
+
+### 15.6 回归（R3.1）
+
+受影响面 7 模块：`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p28_refcheck` 45/0、`test_p2_mcp` 63/0 **全绿**；`test_p27_docindex` **68/1**（当时唯一红项为 §15.5-4 的环境事实，非代码缺陷）。
+
+### 15.7 R3.2：`skip_dirs` 追加排除（原 §15.5-4 的裁定落地）
+
+**问题**：索引的「扫描范围」只有**下限**（`SKIP_DIRS` 硬编码）没有**上限**——`.gitignore` 已整目录忽略的实验产物物理仍留在盘上，就照样被扫。本仓 `docs/` 真实内容 30 个 md，被 `docs/experiments/` 的 2358 个撑到 2388，直接压爆 `max_files=500`。此前唯一的应对是「调大 `max_files`」，那是**掩盖**：上限调到 2500，下次再多一批产物同样爆。
+
+**交付物**：
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `md_cg/codeindex.py` | **扩** | `skip_matcher(skip_dirs)` → `(hit, rules)`；`index_dir(..., skip_dirs=None)` 在 `os.walk` 处**追加**剪枝；`stats` 增 `skip_dirs`（规则回显）/ `skipped_dirs`（实际排掉的目录） |
+| `md_cg/docindex.py` | **扩** | 同签名同语义，复用 `codeindex.skip_matcher`（**唯一实现**，避免两条链路口径漂移） |
+| `md_cg/refindex.py` | **扩** | `index_dir(..., skip_dirs=None)` 透传给底层 |
+| `md_cg/mcp_server.py` | **扩** | `index_code`/`index_doc` 透传 `skip_dirs`；`_skip_dirs_report()` 把「排掉了什么」压成 `skipped_dirs` / `skipped_dirs_count` / `skip_dirs` 回报；schema 增 `skip_dirs` |
+| `md_cg/test_p27_docindex.py` | **扩** | §9 改用 `skip_dirs=["experiments"]`；新增 §9b 专测匹配口径 / 只增不减 / 可审计 |
+
+**三条设计裁定**：
+
+1. **只增不减**：`skip_dirs` 在 `SKIP_DIRS` **同一处**生效，调用方只能追加，**不能关掉** `.git`/`.venv`/`node_modules` 这类内置保护——否则一次参数写错就能把版本库元数据索引进认知图。
+2. **排除不许静默**（与「截断不许静默」同一纪律）：命中目录写进 `stats["skipped_dirs"]`（就地追加、不依赖末尾汇总，所以**截断提前 return 时也带得走**），MCP 层再压成可读回报。调用方据此能把「源文件真的少了」与「被规则排掉了」区分开。
+3. **两类匹配口径可混用**：含 `/` 按**相对 root 的路径**（`docs/experiments` 只排这一处）；不含 `/` 按**目录名**（`experiments` 排任意层级同名目录）。反斜杠 / 首尾斜杠先归一——否则「规则传了却不生效」又是一次静默失配。默认 `None` 时 `hit is None`、走原路径，**行为与改造前逐字一致**（同 `fresh`/`on_file` 纪律）。
+
+**实测**（`test_p27` §9 / §9b）：
+- 本仓 `docs/`：`files=30/30`、`truncated=false`，`skipped_dirs=['experiments']`（此前 `files=500/2388` 已截断）。
+- 合成树（`keep.md` + 两层 `experiments/*` + `sub/experiments/y.md` + `node_modules/pkg/n.md`）：不给规则 → `files=4`「内置排除照旧」；`skip_dirs=["experiments"]` → `files=1` 且 `skipped=['docs/experiments','sub/experiments']`（**同时证明 `node_modules` 仍被排，即只增不减**）；`skip_dirs=["docs/experiments"]` → `files=2` 只排这一处；`skip_dirs=["docs\\experiments\\"]` → `files=2`（归一后仍生效）。
+
+### 15.8 诚实边界（R3.2 新增）
+
+1. **按路径的规则不跨 root**：`docs/experiments` 是「相对本次 root」的路径，换个 root 就不再匹配；跨仓复用规则要用不含 `/` 的目录名形式。
+2. **同名目录一网打尽**：`skip_dirs=["experiments"]` 会排掉**任意层级**的同名目录。这正是它对 `2_ai` 那种多子项目树好用的原因，但也意味着「只想排一处」必须写全路径。
+3. **排除只影响扫描，不清理既有节点**：已在库、但本次被排掉的目录里的节点**不会**因此消失（`prune_orphans` 的判定范围限于本次真正重切过的 path，见 §15.3-1）。若要清掉，需先不带 `skip_dirs` 跑一次让它们成为孤儿，或直接 `prune_dangling`。
+4. **`max_files` 仍是安全上限而非目标值**：`skip_dirs` 解决「噪声挤占额度」，不解决「真实内容超过 500」——真超了应当**调大 `max_files`**（那是真实内容），而不是继续加排除。
+
+### 15.9 回归（R3.2）
+
+受影响面 10 模块**全绿**：`test_p2_mcp` 63/0、`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p27_docindex` **75/0**、`test_p28_refcheck` 45/0、`test_p29_session_ingest_export` 48/0、`test_p30_maintain` 55/0、`test_p32_backfill` 58/0。改动文件 lint 0 错误。
+
+---
+
+*计划生成：2026-09-10 · 证据：§一 全部为源码行级核对结果 · 未核对项已单列 §1.3 / §十 · §十一 为 R0 实测取证 · §十二 为 R1 实测取证 · §十三 为 R2 实测取证 · §十四 为 R3 实测取证 · §十五 为 R3.1 / R3.2 实测取证*