@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/docs/GBrain/345/217/257/345/200/237/351/211/264/347/202/271_/347/201/265/346/236/242/350/220/275/347/202/271/344/272/244/346/216/245_20260919.md

@@ -0,0 +1,169 @@
+# GBrain 可借鉴点 · 灵枢大脑改进交接文档
+
+> 交接方：CodeBuddy 端 · 接收方：**CodeBuddy 端后续施工轮次 / 其他端**
+> 交接时间：2026-09-19 · 依据：荣指令「GBrain 记忆机制学习报告也可以列新任务来补充功能了」
+> 素材：`docs/GBrain记忆机制学习报告_供CodeBuddy端_20260914.md`（自包含报告）· 源项目 gbrain（MIT，TypeScript/bun，30.1k★，本地参考克隆）
+> **本轮范围声明（重要）**：本文件**只出任务清单、不改代码**。四条任务的代码实施另立施工轮次，沿用 Pi 交接「先文档后施工」的既有节奏。
+
+---
+
+## 0. 一句话交接
+
+gbrain 把**「记忆如何变化」做成了数据模型的一等公民**——冻结的动词线缆协议、事实有效期双时间戳、巩固指针、能力探测降级；本文件将其 §10 四条可借鉴点逐项映射到灵枢大脑（`md_cg`）的落点，每项带 gbrain 源码证据、**本轮实测的灵枢现状基线**、建议落点与可裁决验收口径；并附「不学什么」反面清单（§4）与既有工作线边界（§5）。
+
+**本文件与 Pi 交接的分工**：Pi 交接（`docs/Pi可学习优点_灵枢大脑改进交接_20260915.md`）解决的是**运行时与上下文工程**（fork/钩子/瘦身/状态机/两段式/不变量巡检/组装细节）；本文件解决的是**记忆数据模型与接口契约**（协议冻结/有效期语义/巩固字段/能力降级）。两者无重叠面，可并行施工。
+
+## 1. 版本与落点纪律（⚠️ 防版本不一致，先读）
+
+| 仓 | 角色 | 本次改动落点 |
+|---|---|---|
+| `dsh-memory/` | **大脑 · 唯一主线** | ✅ **本文件全部改进落这里**（`md_cg/` 为主） |
+| `AEIS/` | 身体仓：记忆真源数据 + 可视化管线 | ❌ 不改代码 |
+| gbrain 源码克隆 | **只读参考件**（MIT，思想可吸收） | ❌ 不引入其运行时、不引依赖 |
+
+- 记忆真源 = md 文件（纯 md，主链路零 SQLite、零外部依赖）；`md_cg` 经 `--root`/`MDCG_ROOT`/datapath 访问，**不得**在 `md_cg` 内硬编码本机路径。
+- **gbrain 的存储形态不学**：其真源是 Markdown、派生索引在 PGLite（嵌入式 Postgres/WASM）。灵枢主链路**零 SQLite**是既有架构决定，只吸收其**数据模型与契约设计**，不引入任何 DB 依赖。
+- 改动后必须跑全量回归（`python -m md_cg.test_pXX` 形式）；测试只能模块方式跑，直接 `pytest md_cg/` 会崩（相对导入，已知缺陷）。
+- **引用纪律（内容政策）**：本文件所有 gbrain 侧证据一律以「**仓名 + 报告锚点行号**」引用（如「报告 §2 冻结政策」），**不写本机克隆绝对路径**；报告头部现有的本机路径不复制。
+
+> **完成度判据（沿用 Pi 交接 §3 纪律，同为本文件的硬约束）**：各项「落地状态」是**手工标注、无机械守卫**，历史上必滞后于代码（Pi 交接已实证：① ② ④ ⑥ 已入库而文档长期漏标，曾据「未标」误判未落地）。
+> **判断某项是否完成，请以认知图落地记录 + `git log` 提交取证为准**，本文件标注只作索引——与「手写行号必腐化」同构：无守卫的手工标注必漂移。
+> **本文件四条初始状态一律为「未开工」，依上纪律，动工前请先重新取证而非信任此标注。**
+
+## 2. gbrain 素材位置（查证入口）
+
+| 内容 | 位置（仓内可见） |
+|---|---|
+| 学习报告（主素材，自包含、逐条带源码锚点） | `docs/GBrain记忆机制学习报告_供CodeBuddy端_20260914.md` |
+| 四条可借鉴点原文 | 同上 **§10**（行号见 §3 各条「证据行」） |
+| 七动词协议与冻结政策 | 同上 §1–§2（对应 gbrain 仓 `gbrain/docs/protocol/MEMORY_VERBS_v1.md`、`gbrain/src/mcp/surface.ts`） |
+| 数据模型逐字段解剖 | 同上 §3（对应 gbrain 仓 `gbrain/src/core/migrate.ts:2395` 起建表语句） |
+| 能力探测两级降级 | 同上 §6（对应 gbrain 仓 `gbrain/src/core/capability.ts`） |
+| 巩固 / dream cycle | 同上 §7 |
+| 反面素材（治理/多 agent/哲学） | 同上 §4、§5、§8、§9 |
+| 动手验证清单（6 条复核路径） | 同上 §11 |
+
+## 3. 可借鉴点清单（按建议优先级排序）
+
+> 每条五段式：**gbrain 机制** → **灵枢现状**（2026-09-19 实测取证）→ **建议落点** → **验收** → **落地状态**。
+
+### ②★P0 事实有效期进入查询语义（highest：字段与判定已在，只差消费）
+
+- **gbrain 机制**：`facts` 表把「记忆的后半生」做成一等公民——`valid_from / valid_until / expired_at` 三戳表达有效期，「过期」由查询侧判定，不是人工清理任务（报告 §3 生命周期行、§10 第 2 条）。配套 `superseded_by BIGINT REFERENCES facts(id)` 自引用链：**纠错不是删除**。
+- **灵枢现状**（实测取证，逐条可复核）：
+  - 字段**已在**：`valid_from` / `valid_until` —— `md_cg/nodefile.py:122-123`（`VALID_FROM_FIELD` / `VALID_UNTIL_FIELD`，注释自陈「`valid_until` 既有（已被 scrub 的过期消费面使用）；`valid_from` 本轮补齐」）+ `md_cg/trust.py:61-62`（`FROM_FIELD` / `UNTIL_FIELD`）。
+  - **`expired_at` 在灵枢零命中**（全仓唯一命中即本报告自身）——灵枢以 `valid_until` + 验证态 `expired` 表达过期，**不设第三戳**。故本条的灵枢形态是「**双时间戳 + 状态**」，与 gbrain 的「双时间戳 + 过期戳」是**同构不同形**（差异如实列出，不视为缺陷）。
+  - 判定函数**已在**：`md_cg/trust.py:225-242` `validity(fm, now)` → `unknown / not_yet / active / expired` 四态。
+  - 消费面**只在治理/展示侧**：`trust.patrol`（`trust.py:500-524` 巡检粗判 expired/not_yet 清单出报表）、`md_cg/statushdr.py:77`（状态头展示）、`md_cg/coldverify.py:148`（冷启动复核转 expired 态）。
+  - **检索面零处理（关键缺口）**：`mdcg.search` / `mdcos.search_rrf` / `mdcos.recall` / `mdcg._candidates` / `mdcos._candidates` **均无 `validity` 调用**——`_candidates` 的过滤维度现有 layer / session / branch / roles，**没有有效期**。即：**过期节点仍会作为正常候选参与召回**。
+- **建议落点**：`md_cg/mdcos.py` 的 `_candidates`（一处过滤全链路生效，与既有 `session=` / `branch=` 过滤同构——该位置已被 Pi④ 验证为「改一处、search/search_rrf/recall 三签名透传」的正确落点）；`mdcg._candidates` 同步（子类覆盖，历史教训：首轮漏改被测试抓住）。**处置语义建议先出裁决再动手**：`expired` 与 `not_yet` 是否同等对待（gbrain 的三戳里 `expired_at` 与 `valid_until` 可分离，灵枢无第三戳 → 需明确「未生效」与「已过期」是否同为不可召回）。参数建议 **opt-in 开关注入**（对齐 `session=`/`branch=` 的「一处过滤全链路生效」与仓内「默认零回归」惯例）。
+- **验收**：① 断言 `validity=expired` 节点**不入候选池**（口径同 Pi④ 分支过滤：以「nid 不在命中集」为准，而非「结果为空」）；② `not_yet` 处置按裁决断言；③ `active` / `unknown` 节点召回**逐位不变**（零回归）；④ 全量回归零新增失败。
+- **落地状态（2026-09-19）：未开工** · 资格裁决=**ACCEPT**（依据：字段在+判定在+查询面缺位，「已有的判定函数无人消费」是确定性缺口，非相似度推断）。
+
+### ③★P0 巩固结果显式化与可追溯（second：已有归并，缺「可被查询看见」）
+
+- **gbrain 机制**：夜间 dream cycle 做「事实抽取 → 引用修复 → **合并** → 嵌入去重」，合并动作在 `facts` 上留下 `consolidated_at / consolidated_into BIGINT`——**合并可追溯**，且是**结果节点上的显式指针**（报告 §3 巩固行、§7）。
+- **灵枢现状**（实测取证）：
+  - `consolidated_at` / `consolidated_into` **全仓零命中**（唯一命中即本报告自身）。
+  - 归并机制**已在**：`md_cg/consolidate.py:1217` `induce_memories`（聚类归纳）+ `:1153` `_link_concept`（建**概念节点** + `edges` 成员边）+ `:1200` `_concept_payload`；`:799` `promote_memories`（三门槛层级提升）+ `:871` `rollback_promotion`（可回滚）；`contextualize_*` 语境化归位。入口 `md_cg/mcp_server.py:2201` 分派 `_consolidate_call`，action 枚举 `promote / promote_rollback / promote_history / induce / contextualize / contextualize_rollback / contextualize_history`。
+  - 另有**分支级**合并：`md_cg/branches.py` 的 `merge`（逐节点按 `branched_from` 溯源回写，`relation=merged_from`）——**是分支级而非节点级**，与本条目标不同层。
+  - **关键取证（决定落点）**：`md_cg/mdcg.py:2079-2080` 注释自陈「S3 图扩散激活……**为何：edges 一直只被写入、检索从不使用（审计偏差 1）**」→ **归并产生的成员边在检索面长期不可达**，即「合并可追溯」在**查询侧实际不成立**。
+- **建议落点**：**优先补读侧可达**（概念节点 ↔ 成员边的检索消费，S3 图扩散已部分在做——先确认其覆盖面是否已包含 `_link_concept` 产出的边类型）；**其次**再评估是否需要在结果节点落 `consolidated_into` 式显式指针字段——**须先答「字段 vs 边」的单一真源问题**（两者并存即双真源，违反仓内「真源唯一」纪律，可能反被判 REJECT）。gbrain 的字段指针形态与其 DB 行模型绑定，灵枢用结构化边表达同一语义**已是对等设计**，不可照搬字段。
+- **验收**：① 对既有 `induce` 产出的概念节点，断言「成员节点可经该边被检索/追溯到达」（口径可裁决、可复跑）；② 若新增字段，须断言与边**同源**（无第二真源）；③ 归并可回滚（`promote_rollback` 既有能力不得退化）；④ 全量回归零新增失败。
+- **落地状态（2026-09-19）：未开工** · 资格裁决=**ACCEPT，但落点与 gbrain 不同形**（依据：归并机制已在、边已写入、读侧不消费——缺口位置已由代码注释自证）。
+- **与缺口矩阵的关系**：本条与 `docs/theory/理论_机制_代码_实验_缺口矩阵_v0.1.md` **#27（P-T-92 睡眠整理/联想保留 → `consolidate.promote` 三门槛，状态 🟡「机制在，本仓无治理前后数字」）** 同一工作面——**标关系、不另立**：#27 管「整理是否有效」的度量，本条管「整理结果是否可见可追溯」。
+
+### ①P1 记忆动词协议冻结与 conformance 认证（third：有工具面、无契约承诺）
+
+- **gbrain 机制**：七动词 `recall / remember / entity / synthesize / forget` + `context_pack / delta` 构成**线缆协议**，与实现分离；冻结政策三条——① 字段名与语义**永久冻结**（不删/不改名/不改型）；② 新字段新动词**只增不破坏**（v1 客户端必须忽略未知字段）；③ `protocol_version` 只在破坏性变更时递增且政策预期「never」；枚举值属契约。任何实现同一协议者可经 `gbrain protocol conformance --target <endpoint>` **认证**（报告 §1–§2、§10 第 1 条）。另设 surface 阶梯 `verbs ⊆ starter(~27) ⊆ full`，monotonic 由测试钉死，**fail-closed**（隐藏操作被点名也返回 `unknown_tool`）。
+- **灵枢现状**（实测取证，**含对报告表述的修正**）：
+  - `MEMORY_VERBS` **全仓零命中** → 「记忆动词契约」概念确为空白。
+  - **修正报告的「无冻结承诺」更精确表述**：`PROTOCOL_VERSION` 存在但**语义不同**——`md_cg/mcp_server.py:48` 与 `md_cg/whitebox.py:51` 是 **MCP 传输协议版本**（JSON-RPC 侧），`md_cg/theory.py:38` 是**理论版本**（3.4）；三者**均非「记忆工具面契约版本」**。故本条缺口不是「没有版本号」，而是「**没有以工具面为对象的契约版本**」。
+  - 工具面**形态已在**：`mcp_server.py:499` `KERNEL_TOOLS`（2 基元 `cg`/`stg`）+ `:907` `ALL_TOOLS = KERNEL_TOOLS + TOOLS`（+31 细粒度）=33；`:908` `SURFACE = env MDCG_MCP_SURFACE`（默认 kernel）；`:912 tools_for_surface()` 经 `tool_face.slim_tools` 投影；`MDCG_TOOL_FACE=full` 关闭投影。
+  - **已有的守卫是「投影一致性」而非「跨版本只增」**：Pi① 已落地 `md_cg/tool_face.py`（投影真源）+ `md_cg/test_tool_face.py`（23 断言，含**工具名/参数名/顺序/required/类型/枚举值集逐位不变**）+ `cg(op=help)` 按需取回。该断言保证「瘦身前后契约不变」（**同一版本内**），**不含**「版本 A 的消费方在版本 B 下仍可用」的跨版本断言。
+  - **Pi⑤ 的 `conformance.py` 与本条要求同名不同物（必须区分，防误判已完成）**：`md_cg/conformance.py` 自陈为「**数据健康不变量断言集**」（答「数据是否失真」：混层比例/重复度/字段覆盖率/闸门分布），挂 `sustain._tick_conformance` 6h 节奏、超阈值**告警不自动改数据**；而 gbrain 的 conformance 是「**协议一致性认证**」（答「外部实现是否合规」）。**两者同名不同物，不得因前者存在而判本条已完成。**
+  - surface 阶梯**有形态差异**：灵枢 `SURFACE` 是**进程级 env**（部署时定档），gbrain 是**每客户端天花板**（服务端解析 `min(ceiling, client_row ?? default)`，可逐客户端收窄）。差异如实列出。
+- **建议落点**：`md_cg/` 新增**工具面契约真源**（建议形态：把 `KERNEL_TOOLS` + `op` 枚举 + 参数名/类型/枚举值集导出为**可版本化的契约清单**，与既有 `tool_face.py` 投影真源**共源不复制**）+ 契约断言集（跨版本只增：既有项不得消失/改名/改型；新增项允许；`op` 枚举只增）；`cg(op=help)` 出口可附契约版本。**⚠️ 前置裁决（不可跳过）**：先划定「冻结面」边界——冻结 **kernel 2 基元**（对外承诺面）还是含 full 31 工具（兼容/调试面）？**建议只冻结 kernel**：full 面在 Pi① 中已定位为「兼容与调试」，冻结它会锁死后续瘦身空间（与 Pi① 的投影层方向冲突）。此项须使用者裁决后再动工。
+- **验收**：① 契约清单可由管线生成（**禁止手工维护**——与「手写行号必腐化」同构）；② 断言「删除/改名任一冻结项」在测试中**必红**（反向注入探针，参考 cogmap 的单引号静默漏报守卫做法：正向与恢复双向断言）；③ 新增项不触发红灯（只增语义正确）；④ 既有 `test_tool_face` 23 断言与 MCP 回归零变化。
+- **落地状态（2026-09-19）：未开工** · 资格裁决=**ACCEPT**（依据：三端已是事实独立消费方，而现有守卫只覆盖同版本投影一致性；缺失维度=冻结面边界）。
+
+### ④P2 能力探测降级（fourth：裁决为 DEFER，先取证再动工）
+
+- **gbrain 机制**：`gbrain/src/core/capability.ts` 探测 embeddings 可用性 → `search: 'semantic' | 'keyword-only'`；无 key 时 **BM25 关键词检索完全可用**，加 OpenAI/Voyage key 升级语义检索（混合向量+关键词）。「keyless 先行、按需升级」是其 30k★ 体验的一部分（报告 §0、§6、§10 第 4 条）。
+- **灵枢现状**（实测取证）：
+  - `bm25` **全仓零命中**（区分大小写检索确认）——灵枢**没有 BM25**，其词法侧是 char-bigram 主链路 + 独立的中英归一原子 + Jaccard 路（`md_cg/semantic/REPRODUCE.md` 双语双路裁定）。
+  - 所有相关开关都是**部署期 env**，不是运行期探测：`MDCG_SEMANTIC`（`md_cg/mdcg.py:221-232` `semantic_on()`，注释「默认关闭零回归」）、`MDCG_EN_ATOMS`（`mdcg.py:235-301`，默认 `"0"`）、`MDCG_TOOL_FACE`、`MDCG_MCP_SURFACE`、`MDCG_S7_FRESHNESS`。
+  - **灵枢天然零依赖**（无 `requirements.txt` / `pyproject.toml`，主链路纯标准库）→ 「无 API key 完全可用」是**结构性的**，比 gbrain 的「keyless 先行」更彻底：gbrain 无 key 需**退**到 BM25，灵枢**根本不存在该调用**。
+  - **降级先例已在（但非探测）**：`mdcg.py:254` 注释「semantic 模块缺失时**静默降级**（不阻断主链路）」；`hive/exec.py` 有**零依赖探测**先例（PNG IHDR / JPEG SOF 读尺寸，不读像素）。
+- **建议落点**：**先取证，暂无落点**。真正可迁移的不是「检索降级」（无靶：问题本体是 gbrain 的 embedding 依赖），而是「**能力差异应自动判定而非部署期人工配置**」——即在**多端部署面**把 `MDCG_SEMANTIC` / `MDCG_EN_ATOMS` 一类开关改为「能力自动判定 + 显式覆盖」。但此改动的前提是：存在**真实受损场景**（使用者或某端因不知要开开关而实际损失召回）。
+- **验收（DEFER 的解除条件）**：先取证「semantic 路默认关闭导致的可感知召回损失」是否有实例（对齐 Pi⑦「取证结论：默认路径结构性已满足，未做无靶改动」的先例）。**有实例** → 落点=开关改能力自适应，验收=断言「能力可用且未显式覆盖时自动启用 + 显式 override 优先 + 能力探测失败静默降级不阻断」（须保持零依赖）；**无实例** → 本条结案为「**结构性已满足，不学**」，并把它写进 §4 反面清单的姊妹条（避免后续重复立项）。
+- **落地状态（2026-09-19）：未开工** · 资格裁决=**DEFER**（依据：capability.ts 解决的是灵枢不存在的问题本体；缺失维度=条件边界「谁是受损者」未取证；**不得为对齐外部做无靶改动**）。
+
+## 4. 反面清单（不学什么）
+
+> 素材来源：报告 §4（治理例外清单）、§5（HTTP/MCP 治理）、§8（多 agent 与信任边界）、§9（哲学对照表）。
+
+| 对方做法 | 为什么不学 | 灵枢对应原则 |
+|---|---|---|
+| **DB-only by design**：凭证 / `mcp_request_log` / 任务队列 / `raw_data` / `dream_verdicts`（30 天 TTL）/ withdrawal ledger / durable receipts / outbox 均只落 DB，不进 Markdown | 灵枢**真源唯一且是 md 文件**——主链路零 SQLite、派生索引可随时重建是架构决定；一旦开设「DB-only 例外清单」，例外会随需求扩张并最终使 md 真源名存实亡 | 真源唯一 · 派生可重建 · 主链路零外部依赖 |
+| **「DB-only for now」偷懒路径**（gbrain 用 CI 门程序化拦截「新增派生表持用户知识却不 FS-first」） | ——**这条不是不学，是学做法**：其价值在「**把偷懒路径做成机器红灯**」而非「人工评审记得拦」 | 与 `scripts/cogmap_sync.py check`（手写行号禁令 / 文件链接守卫）、`scripts/verify_discipline.py`（声明出口 strict）同构——**门禁化是仓内既有方针**，本条作为正面做法单列 |
+| **ambient writeback**（对话随口陈述自动写回知识库；默认关闭，公司脑永不开启） | 灵枢写路径已有三道闸（六要素校验 DEFER → 审核队列 / 冲突拦截 / REJECT 负记忆）；自动写回会让「未发现拒绝理由」冒充「确认适用」——灵枢已明确 REJECT 过同类设计 | 未验证不写入 · 写入须过闸门 · 判定归使用者 |
+| **队列 TTL 自动放行**（`dream_verdicts` 30 天过期即视为通过） | 灵枢已在审核队列议题上**显式 REJECT 过该候选**（理由：TTL 放行=「未发现拒绝理由冒充确认适用」）；裁决必须显式发生（`cg(op=review, decision, reason)`），不设静默过期 | 裁决显式化 · 未验证不固化 |
+| **信任外推**（哲学=「仓库即大脑，真源/备份/验证都推给用户自管」） | 灵枢的定位是**治理内置**（五层 + 条件论 + 白箱化）：结构强制可复算、revision 乐观并发、权限按 op 分档、审计留痕——把验证责任外推给使用者与「白箱化」方向直接冲突 | 治理内置 · 结构强制可复算 · 可审计 |
+| **单智能体笔记本定位**（gbrain 作者自述：单写入者假设，无多 agent 并发语义） | 灵枢是**蜂群互联**形态（hive Rust 并发调度 + `session`/`writer` 归属 + `branches` 实验分支隔离 + 互维心跳）；引入单写入者假设会击穿既有的归属与隔离语义 | 多会话归属 · 分支隔离 · 蜂群并发 |
+| **PGLite（嵌入式 Postgres/WASM）作为派生索引底座** | 灵枢主链路零依赖（无 `requirements.txt` / `pyproject.toml`）；为对齐其检索形态而引入 DB 运行时，会同时牺牲「零配置可跑」与「派生可重建」两条既有资产 | 零依赖 · 零配置可用 |
+| **BM25 词法引擎**（gbrain 无 key 时的检索引擎） | 灵枢词法侧已是 char-bigram 主链路 + 中英归一原子 + Jaccard 路（双语双路已裁定），加 BM25 属**同层第二实现**（对照 §3④：`bm25` 全仓零命中，问题本体不存在） | 单一真源 · 不设同层重复实现 |
+
+## 5. 与既有工作线的边界（防撞车）
+
+| 既有工作线 | 关系 | 处置 |
+|---|---|---|
+| **Pi 交接七项**（`docs/Pi可学习优点_灵枢大脑改进交接_20260915.md`） | 运行时/上下文工程面（fork、writepipe 钩子、工具瘦身、状态机、两段式、conformance 巡检、上下文组装），与本文件四条**无重叠** | 并行安全；**唯一接壤处**=本文件 §3① 与 Pi①（`tool_face` 投影）/ Pi⑤（`conformance.py`）——已在 §3① 显式区分「投影一致性守卫」与「协议一致性认证」，动工前**必须**先读那两处，避免误判已有 |
+| **缺口矩阵 `#27`（P-T-92 睡眠整理/联想保留）** | 与本文件 §3③ 同一工作面（`consolidate.promote` 三门槛） | **标关系、不另立**：矩阵管「整理有效性的度量」，本文件管「整理结果的可见与可追溯」 |
+| **缺口矩阵 §2-6（`mdcg.search` 重复实现清理）** | 与本文件 §3② 可能落在**同一函数面**（检索入口过滤） | ② 动工前先查该项是否已施工，避免双改冲突 |
+| **rust 只读检索核心（`rust/`，mdcgr 评测器）** | §3② 的有效期过滤若落在**读侧默认行为**，可能触发 py↔rust 镜像义务（既有口径：py 改动须确认是否落在 rust 已对齐的读侧默认行为域） | ② 施工前**必须**评估镜像义务；若默认开启则须同步 rust，否则 rust 侧召回口径与 python 漂移 |
+| **bench 口径（bench6 / LoCoMo 500）** | §3② 改动会改变召回集 | 若为 **opt-in 默认关闭**，bench 零漂移（对齐仓内既有惯例）；若转默认，须复跑并如实更新 README 对外数字（**数字未达标不动对外声明**） |
+| **在途未提交改动**（`README.md`、`docs/mdcg/功能调用映射表_v0.1.md`、`scripts/cogmap_sync.py`） | 与本文件无交集 | 施工轮次须与此三件隔离，避免混淆提交 |
+
+## 6. 建议施工顺序
+
+> 每步统一节奏：**实现 → 全量回归（模块方式）→ 灵枢归档（第 16 条）→ 看板/文档同步**。前置裁决未完成**不得**动工。
+
+1. **② 有效期进查询语义（P0，先裁后动）**
+   - 1a. **前置裁决**：`expired` 与 `not_yet` 是否同为用户不可召回？（建议：同为不可召回，但须 `unknown` 保持原样——否则旧库无时间戳节点会被静默排除）
+   - 1b. 落点实现：`mdcos._candidates` 一处过滤（与 `session=` / `branch=` 同构）+ `mdcg._candidates` 同步；**默认 opt-in**
+   - 1c. 回归 + 断言（§3② 验收四条）
+   - 1d. **rust 镜像义务评估** → 若涉默认行为则同步
+   - 1e. 归档 + 更新本文件落地状态
+2. **③ 巩固结果读侧可达（P0）**
+   - 先核 S3 图扩散对 `_link_concept` 边类型的覆盖面 → 补齐读侧可达 → 再评估是否需要显式指针字段（须过「单一真源」裁决）
+3. **① 工具面契约冻结（P1，须使用者裁决冻结面）**
+   - 划冻结面（建议仅 kernel 2 基元 + op 枚举）→ 契约清单管线化（禁手工）→ 只增断言 + 反向注入探针
+4. **④ 能力自适应（P2，先取证）**
+   - 取证受损场景 → 有则改「能力自动判定 + 显式覆盖」；无则结案「结构性已满足，不学」并回写 §4
+
+## 7. 快速上手（施工前一分钟自检）
+
+```bash
+# 0) 先读形态模板与素材（防版本不一致、防重新发明范式）
+#    docs/Pi可学习优点_灵枢大脑改进交接_20260915.md  §3 五段式 / §4 反面清单
+#    docs/GBrain记忆机制学习报告_供CodeBuddy端_20260914.md  §10 四条原文
+
+# 1) 复核四条现状基线（本文件 §3 各条「灵枢现状」的来源命令）
+#    grep 手法：搜索范围限定 md_cg/，逐条核对下列符号是否仍如本文件所述
+#      §3①  MEMORY_VERBS / PROTOCOL_VERSION / KERNEL_TOOLS / ALL_TOOLS / tools_for_surface
+#      §3②  valid_from / valid_until / trust.validity / _candidates 的过滤维度
+#      §3③  consolidated_at / consolidated_into / induce_memories / _link_concept
+#      §3④  bm25 / MDCG_SEMANTIC / MDCG_EN_ATOMS
+
+# 2) 回归（模块方式，勿用 pytest md_cg/）
+python -m md_cg.test_p2_mcp
+python -m md_cg.test_p33
+# …按改动面选套件；改动后须跑全量
+
+# 3) 收尾（第 16 条）：提炼核心修改 → cg(op=write) → cg(op=read) 读回确认
+```
+
+---
+
+**交接摘要**：四条任务中 **②③ 为 P0 且证据充分**（确定性缺口，非相似度推断），**① 为 P1 但须先裁冻结面**，**④ 已裁 DEFER**（先取证，不得为对齐外部做无靶改动）。四条**均为未开工**——依 §1 完成度判据，动工前请重新取证而非信任本文件标注。

package/docs/Pi/345/217/257/345/255/246/344/271/240/344/274/230/347/202/271_/347/201/265/346/236/242/345/244/247/350/204/221/346/224/271/350/277/233/344/272/244/346/216/245_20260915.md

@@ -0,0 +1,144 @@
+# Pi 可学习优点 · 灵枢大脑改进交接文档
+
+> 交接方：ZCode 端 · 接收方：**CodeBuddy 端**
+> 交接时间：2026-09-15 · 依据：荣指令「整理完整的 Pi 可学习优点文档，交接 CodeBuddy 处理，避免灵枢大脑版本不一致」
+> 素材：`agi-architectures/pi/`（浅克隆，MIT 许可，代码思想可吸收）· 三轮源码深读结论（状态管理/会话持久化/压缩、扩展机制、上下文工程、协议哲学）
+
+---
+
+## 0. 一句话交接
+
+pi（Pi Agent Harness，105k★）把**事件溯源、显式状态机、渐进披露、可逆压缩、钩子化扩展**做到了 coding agent 领域的标杆；本文档将其七项可学习优点逐项映射到灵枢大脑（`md_cg`）的改进落点，每项带 pi 源码证据、灵枢现状基线、建议落点与验收口径。
+
+## 1. 版本与落点纪律（⚠️ 防版本不一致，先读）
+
+| 仓 | 角色 | 本次改动落点 |
+|---|---|---|
+| `dsh-memory/` | **大脑 · 唯一主线**（荣 2026-09-14 裁定：中文编译器并入大脑作核心架构） | ✅ **本文件全部改进落这里**（`md_cg/` 为主） |
+| `AEIS/` | 身体仓：记忆真源数据（`data/mdcg/`）+ `tools/coggraph/` 可视化管线 | ❌ 不改代码；数据真源对管线**只读** |
+| `protocol-compiler/` | 已冻结（世界模型测试地点，荣 2026-09-14 裁定） | ❌ 不动 |
+
+- 记忆真源 = `AEIS/data/mdcg/`（11,195 节点，纯 md，主链路零 SQLite）；`md_cg` 通过路径锚（`data/paths.json`）访问，**不要**在 md_cg 内硬编码本机路径（沿用 `--root`/`MDCG_ROOT`/datapath 约定）。
+- coggraph 可视化管线（DSH→CodeBuddy 另一份交接 `AEIS/docs/知识图谱项目_交接文档_20260914.md`）与本文件**并行不冲突**：那边管可视化与语义层，本文件管写入纪律与运行时。两者都遵守「管线只读真源、产物不入库」。
+- 改动后必须跑全量回归（`python -m md_cg.test_pXX` 形式，60+ 套件）不回退；测试只能模块方式跑，直接 `pytest md_cg/` 会崩（相对导入，已知 P2 缺陷）。
+
+## 2. pi 素材位置（查证入口）
+
+| 内容 | 路径（相对 `agi-architectures/pi/`） |
+|---|---|
+| 状态机/会话/存储 | `packages/agent/src/harness/session/`、`runtime/`、`drive/` |
+| 压缩 | `packages/agent/src/harness/compaction/compaction.ts`（865 行） |
+| 扩展机制 | `packages/coding-agent/docs/extensions.md`（API 全典）、`src/core/extensions/` |
+| 上下文组装 | `packages/coding-agent/src/core/system-prompt.ts`、`skills.ts`、`tools/` |
+| 安全立场 | `packages/coding-agent/docs/security.md` |
+
+## 3. 可学习优点清单（按建议优先级排序）
+
+> **完成度判据（2026-09-16 补正）**：各项的「落地状态」是**手工标注、无机械守卫**，历史上多次滞后于代码（① ② ④ ⑥ 已入库而本文件长期漏标）。**判断某项是否完成，请以认知图落地记录 + `git log` 提交取证为准**，本文件的标注只作索引——与「手写行号必腐化」同构：无守卫的手工标注必漂移。此纪律已由实证触发：本轮曾据「本文件未标落地状态」误判 ① 未落地，被使用者纠正。
+
+### ④★P0 记忆演化 fork（最高价值——条件论反事实的实验场）
+
+- **pi 机制**：会话是 entry 树，任意历史节点可 fork；两种 scope（`branch` 只拷贝某分支路径 / `tree` 拷全树），运行态一律不复制（`session/types.ts:562-602`、`jsonl/repo.ts:146-196`、`fork-policy.ts:56-63`）；被放弃旁支由 branch_summary 归档（2048 token 定长摘要，`branch-summarization.ts:87-118,274`），切回时提供上下文。
+- **灵枢现状**：认知图是**单一演化线**（`_evolution/ledger.md` 2,650 行账本），没有假设分支。条件论的「负条件/反事实显式化」在记忆层没有实验场。
+- **建议落点**：`md_cg/mdcg.py` 新增 fork 层（节点 frontmatter 加 `branch_id`/`branched_from`；派生索引记分支 tip），`stg.py` 支持分支时间线；新增 `branch_summary` 节点类型（复用 `NEG_MEMORY_MARKS` 式的必填 MARKS 模式）。语义：大规模改写/遗忘策略变更前先 fork 推演，验证通过合并回主支（合并=按 `derived_from` 溯源回写），失败归档 branch_summary 教训节点。
+- **验收**：fork→改写→合并后主支节点 `derived_from` 链完整可回溯；放弃分支不污染主支检索（召回主支时 branch 节点零命中）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `419305c`）。落点 `md_cg/branches.py`（新，分支真源）+ `md_cg/test_branches.py`（新）+ `mdcg.py`/`mdcos.py`/`mcp_server.py` 接线。语义：`BRANCH_MARKS` 教训必填 + 命名守卫；`fork`（副本 nid=`<主支>@<bid>`，layer/tags/importance/cs 继承旧 fm，`derived_from=[主支]`/`relation=split_from`，fm 落 `branch_id`/`branched_from`/`branch_note`）；`rewrite` 为**分支改写的唯一正路**——关键机制发现：`add` 是**全量重建 fm**（非增量更新），裸 add 改写分支节点不重传 `branch_id` 会让副本在索引退化成主支、实验内容泄漏进主支检索，故 `rewrite` 强制归属/血缘从旧 fm 继承、同名 extra 键剥离、override 快照留痕；`merge` 分支级合并（逐节点按 `branched_from` 溯源回写，主支缺失 `skipped` 不炸）；`discard`（require_admin→MARKS 校验→`branch_summary_<bid>` 教训节点入 knowledge→文件 `os.replace` 移冷区 `_branches/<bid>/`→索引摘除→audit）；`list_branches`。检索**一处过滤全链路生效**（`mdcg.search/_stage/_scan_nodes` 与 `mdcos._candidates` 加 `branch=None`：分支节点仅主支+本 branch 可见，与 session 过滤正交）；`mdcos` insight 增六分支 act。
+  **偏离建议**：实现落**新模块** `branches.py` 而非文档建议的内联进 `mdcg.py`（`stg.py` 分支时间线未做）。**边界（如实）**：分支节点**不出库**（冷区 `_branches/` 在 root 下 LAYERS 外、索引隐身——永不删除但检索不可见）；`merge` 是分支级而非节点级。验收：`test_branches` **41/41** 全绿（含主支零污染，断言口径=分支 nid 不在命中集而非结果为空）、回归 10 套件 292 断言全绿、cogmap check 绿、lint 0。
+
+### ⑥★P0 写入路径钩子化（闸门即扩展）
+
+- **pi 机制**：全生命周期事件总线，每个钩子可改变行为——`before_agent_start` 改提示词、`context` 每次 LLM 调用前改消息、`tool_call` 阻断/改参、`session_before_compact` 整体替换压缩（`docs/extensions.md:277-349,452-475,780-848`）。闸门/路径保护/审批全是以扩展形态叠加的，核心没有硬编码策略。
+- **灵枢现状**：写入侧闸门族已经是管线形态——role 作用域闸（`mcp_server.py:1434`）→ 冲突闸（:1656）→ 审核闸（:1707）→ 校验闸（:1715）→ 主动遗忘闸门（`forgetting.assess` 三问四态）→ writelimit（写侧限流+同构聚合，`writelimit.py`）→ canonical 语义归一（`semantic/canonical.py`）。**次序与启停硬编码在 write 路径里**，加一道闸要改核心代码。
+- **建议落点**：`md_cg/mcp_server.py` 写路径重构为拦截器链：`before_write(ctx) -> verdict`（可 ACCEPT/MERGE/DROP/DEFER/改写）与 `after_write(ctx)` 两个挂载点，现有六道闸全部改注册为拦截器（行为不变，回归护航），token 角色校验保留在链首**不可卸载**（见 §4 反面清单——不学 pi 的全权信任）。
+- **验收**：全部既有写入测试（`test_md_writepath.py`/`test_writelimit.py`/`test_verify_answer.py` 等）零改动通过；新增/移除一个拦截器不改核心文件。
+- **落地状态（2026-09-15 · CodeBuddy 端）：✅ 已落地**（commit `419305c`）。落点 `md_cg/writepipe.py`（新，拦截器链真源）：write 分支原 128 行硬编码流程重构为链式——`register_before`/`unregister` 即插即拔、**链尾 executor 常驻**（保证「链上无拦截器也能落盘」）、`after` 观测者、REWRITE 语义（拦截器可改写内容后交下游）；`mcp_server.py` 的 op=write 收敛为**一行分发**。
+  **权限闸保持库层不可绕过**（刻意的不对称）：「卸掉链上全部拦截器」≠ 取得写权限，token 角色校验不因闸门可组合化而下放——对齐 §4 反面清单「不学 pi 的全权信任」。验收：`test_writepipe` **18/18** 全绿 + 全部既有写入测试**零改动通过**（writepath 52 / writelimit 全过 / verify_answer 31 / identity 14 / conformance 26 / p2_mcp 63）。
+
+### ①P1 上下文经济学：工具面与纪律的分层驻留
+
+- **pi 机制**：system prompt 约 150 词骨架（`system-prompt.ts:127-144`）；工具只以**一行 snippet** 常驻系统提示，完整描述只进 API tools 字段（`system-prompt.ts:82-84`）；8 个内建工具默认只激活 4 个（`agent-session.ts:2831-2834`）；skills 只驻留「name+description+path」三元组 XML 索引，正文由 agent 任务匹配时自己 read（`skills.ts:355-383`）。
+- **灵枢现状**：MCP 工具（cg/stg）的 op 参数空间全量 schema 常驻；16 条工作纪律全文常驻 AGENTS.md。
+- **建议落点**：`md_cg/mcp_server.py` 工具 schema 瘦身（一行职责+`docs/工具详细说明.md` 按需引用）；纪律/技能分层（索引常驻、正文文件化按需读）；评估工具子集按 profile 启停（对齐已有 `tools: 'core'|'brain'|'all'` 三档，做到档内再分层）。
+- **验收**：瘦身前后工具描述 token 数对比产物（目标 ≥50% 削减）；检索/写入功能回归零变化。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `c789e95`，同批含「索引幽灵条目根因修复」）。落点 `md_cg/tool_face.py`（新，**投影真源**）+ `md_cg/test_tool_face.py`（新）+ `mcp_server.tools_for_surface` 返回 slim 投影（开关 `MDCG_TOOL_FACE=full` 回到真源）+ cg 新增 **op=help**（`tokens.ALL_OPS` 同步登记）。
+  **信息守恒的结构性保证（本项能减 token 而不减能力的原因）**：被投影掉的原文**不复制、不搬运**，`cg(op=help, query=…)` **从真源即时渲染取回**——不存在第二真源、零漂移面。这是「瘦身」与「信息丢失」的分界线。**偏离建议**：文档建议的「纪律/技能分层驻留」「按 profile 分层启停」两项本轮**未做**（本轮只落工具面投影层）。**顺带修正**：补齐 6 个「op 枚举里有、说明段缺失」的真源文档段（session/ingest/export/maintain/consolidate/insight）——分层后这些会真丢能力，属实测发现的既有缺口。
+  验收：注入面 kernel **20878→8330 字符（−60.10%）**、full31 20347→15221（−25.19%）、all 33 工具 41225→23507（−42.98%）；`test_tool_face` **23 断言**全绿（削减≥50% + 工具名/参数名/顺序/required/类型/枚举值集**逐位不变** + 外置参数经 op=help **逐字**取回 + op 枚举每项都有说明段 + 开关与幂等 + 真源 schema 零改动）；MCP 回归 63/63；72 套件全量回归除 2 个 pre-existing 失败外全绿。
+
+### ②P1 记忆节点显式生命周期状态机
+
+- **pi 机制**：运行操作 = 13 叶子显式状态机（`session/types.ts:315-329`），drive 循环按 `at` 分发；一轮无任何进展抛 `SessionInvariantError`（`drive.ts:101-104`）——非法迁移在结构上不可能。
+- **灵枢现状**：节点生命周期状态**散落**：writelimit 的 `tidy:converged` 标记、forgetting 的 importance 降权、`_evolution/ledger.md` 账本、`protect` 的 protected 标记——没有一个统一状态字段，迁移合法性无校验。
+- **建议落点**：`nodefile.py` frontmatter 新增 `state` 字段（建议集：`active → converged → demoted → archived`，受保护节点单独豁免），`mdcg.py` 写入时校验迁移合法性（非法迁移拒绝，负路由）；存量节点默认 `active`，一次性回填。
+- **验收**：非法迁移用例被拒且回归零变化；`_index.json` 索引快照带 state（免读文件可查）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `2ebf8f0`）。落点 `md_cg/lifecycle.py`（新，**状态机唯一真源**）+ `md_cg/test_lifecycle.py`（新）。`STATES` = `active → converged → demoted → archived`；`TRANSITIONS` 合法迁移表（逐级降级/回升，**拒跳级**）；`check()` 纯函数裁决（`code ∈ ok/noop/unknown_state/illegal_transition/protected`）；`stamp()` 就地推进（复用供需等字段的**同批落盘收口点**，免重复写盘）；`set_state()` 单点推进 + `_lifecycle.jsonl` 审计；`backfill()` 存量回填（dry-run/apply 幂等）。
+  **偏离建议（字段名，重要）**：新增字段取 **`lifecycle_state`** 而非文档建议的 `state`——`state` 已被认知图**裁决四态**（ACCEPT/REJECT/DEFER/BLINDSPOT）占用，复用会让「资格裁决态」与「生命周期态」两个正交轴撞进同一字段（真源节点 fm 现同时带 `state` 与 `lifecycle_state`，可实证两轴并置）。**边界（如实）**：本项落地**不含** Ghidra G3 所设想的 `unanalyzed` 取值——状态集仅四项，分析覆盖度不进生命周期轴（G3 改由 conformance 派生判据承载，见 ⑤ 落地状态）。
+
+### ③P2 写入两段式提交（intent/结果对账）
+
+- **pi 机制**：工具调用先持久化 intent+参数（status=effect_pending）再执行，完成后原子写结果；崩溃后 `replay:"safe"` 工具重放，否则合成 interrupted 结果——消息永不缺失（`drive/tools.ts:187-227,515-540`）。
+- **灵枢现状**：`_audit.jsonl` 已是追加式操作日志（coggraph 会话串链的数据源），但只有 op=add 事后记录，**没有写入意图的先行持久化**，崩溃时无法区分「写了没落盘」。
+- **建议落点**：`md_cg` 写路径在闸门通过后先落 `_audit.jsonl` intent 事件（含 content_hash），写入完成落 outcome 事件；启动时对账（有 intent 无 outcome 的写入做 content_hash 校验补账）。工具幂等声明可后置（md_cg 写入天然可重放：同 hash 幂等）。
+- **验收**：kill -9 模拟半途写入后重启，对账报告正确补账/标记；`test_lock.py` 回归通过。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**。`md_cg/twophase.py`（新，两段式真源）+ 两条真实落盘路径接线（`writepipe.py`：链尾执行器 / `_gate_gated` 替代落盘路径各自 begin→commit）+ 库层门面（`mdcg.reconcile_writes` / `pending_writes`）+ MCP 启动自动对账（`mcp_server.py`，失败不阻塞启动但必须 stderr 上报）。**偏离建议**：账本落**独立文件** `_write_2pc.jsonl` 而非本文档建议的 `_audit.jsonl`——理由见 `twophase.py` docstring（`_audit.jsonl` 已被当作单一语义流消费，混入三类事件会扰动既有断言口径；本仓已有 `protect.py/_protected_audit.jsonl` 独立审计惯例）。**边界（如实）**：对账只做「补账 / 如实标记」，**不重放写入**；`append_jsonl` 在 Windows 非原子（对账是增益、不是「保证不丢」）；`_gate_audit` 的 REJECT 负记忆与各闸 propose（无落盘动作）不在覆盖面内。验收：`python -m md_cg.test_twophase` 10 组 35 项全绿 + 全量回归零新增失败。
+
+### ⑤P2 conformance：数据健康不变量的周期巡检
+
+- **pi 机制**：`session/testing/conformance/`（storage 920 行 + session-repo 1185 行）把存储承诺写成断言：事务原子提交、seq 严格递增、非法写被拒且状态完全不变、close/reopen 状态保持、重放确定性。
+- **灵枢现状**：机制测试 60+ 套件很强；但**数据健康不变量**没有周期断言。2026-09-15 审计（灵枢 node_26b0973a）发现的存量问题：knowledge 层索引节点混层 57.9%、role 存量 99.99% 为空、evidence_count 仅 6 条、精确重复 90 条、闸门 DROP/DEFER=0、召回率 7%——全靠人肉审计发现。
+- **建议落点**：`md_cg/census.py` 产品化：把审计脚本（临时位置 `Temp/audit_write_effect.py`，可向 ZCode 端索取）改写为断言集（混层比例阈值/重复度阈值/字段覆盖率下限/闸门四态分布），挂 `sustain` 周期巡检；超阈值告警不自动改数据（治理另走 tidy/merge，永不删除）。
+- **验收**：census 断言集可一键复跑；对当前真源产出首份基线报告（以上数字应复现）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**。`md_cg/conformance.py`（新，断言集真源）+ `md_cg/test_conformance.py`（53 断言自测）+ `sustain._tick_conformance` 挂点（复用 6h tidy 节奏，不新开周期）+ `.github/workflows/conformance-check.yml`。
+  **偏离建议**：①**不改造 `census.py`** 而新建 `conformance.py`——census 是**节点清单工具**（`by_keys`/`report`，答「有多少、在哪」），conformance 是**不变量断言集**（答「是否失真」），职责不同；且 census 已有 `test_census_prune` 既有口径，改其语义会牵连回归。②G3 `unanalyzed` 用**派生判据**（`evidence_count==0 ∧ basis 空 ∧ state 空`）而非字段级占位——生命周期是单向降级轴、与分析覆盖正交，塞同字段即破坏正交性；且 `verification_basis` 已有 `other` 逃逸口（真源 273 条在用），「分析过但无法归类」有归宿。③基线报告落**真源库同级私有目录**（`AEIS/data/conformance_baseline_mdcg.json`）、不入公开仓——基线是环境特定运维产物，随库增长变动，入库即制造虚假同步义务。
+  **口径更正（关键，9-15 审计数字的复现前提）**：审计的「role 99.99% 为空」「evidence_count 仅 6 条」是 **knowledge 层分母**；全库分母会把 99.991% 的空缺摊薄成「role 2.13%、evidence 12 条」，把严重空缺伪装成「还行」。故断言集**判据一律取 knowledge 层口径**、全库口径仅作对照。据此：role[knowledge]=0.009%（↔ 99.991% 空，与审计逐位吻合）、evidence[knowledge]=0.054%（↔ knowledge 层 6 条，吻合）。
+  **首份基线（2026-09-16，真源 nodes=11666）**：混层 6505/11113=**58.5%**（审计 57.9%，差=期间库增长）；`dir_mismatch=0`、`path_missing=0`、悬空边 0（不变量全绿）；重复 content_hash **93 组/186 节点**（审计 90 条）；闸门 decisions **142**（accept 115 / reject 21 / edit 6）、inbox_pending 0；触达率 **8.7%**（审计 7%；源为滚动追加日志，差异未逐条复算，故**不纳入基线不劣化比对**——日志轮转会误报）；G3 unanalyzed 派生 **4619（39.6%）**。
+  **G1 新发现（正交性审计的增量产出）**：①边类型空间**不封闭**——`above/counterpart/generalizes/instance_of` **未声明已用**（读侧退化 `chain.DEFAULT_EDGE_WEIGHT=0.50`，不炸但权重失真）、另有 8 个声明未用（`applies_to/parent_of/spatial_*` 等）；②**96.9%（5543/5719）的边用 legacy `type` 键**而非规范 `relation_type`——取证更正：`subgraph.children_index:122`/`parents_index:162` 已含 `or e.get("type")` 容错，**读侧不忽略**（`normalize_edge` docstring 称「会被静默忽略」属**文档滞后于代码**，已登记 `DOC_CODE_DRIFT`）；故该项判 **WARN 非 FAIL**（不冒充硬失败），仅以「不劣化」为判据；③`role` 与 `tag_prefix` **无模块级真源**（自由文本/命名约定）→ 标 `None`→BLINDSPOT，不冒充封闭；④`hierarchical` 同名反义（md_cg=本节点是子 / 白箱源库=source 是父）已登记为方向口径分歧；`part_of/parent_of/contains` 已核对**逐字对称、无分歧**（防止被反复误报）。
+  **验收证据**：`python -m md_cg.test_conformance` **53/53 全绿**（对照 test_p27【9】教训：自测**自备 tempfile 合成库**，外部 clone 下集成段自动 SKIP，不依赖仓外目录）；**回归 16 套件零失败**（conformance/census_prune/p14_sustain/sustain_mutual/p30/p41/p2_mcp 64/cond_match 17/p33 58/p36 34/p37 42/sem_noise 7/writepipe 18/branches 41/identity 14/autonomy 10，墙钟 3.6s）；lint 0。
+
+### ⑦P3 上下文组装工程细节（零散但便宜）
+
+pi 的细节清单（出处省略，均可直接对照源码）：错误/中止的 assistant 消息不入上下文；read 截断 2000 行/50KB 附续读提示；bash 大输出全量落盘临时文件+消息保尾部；图片自动缩 2000px、token 估算按 4800 字符/张；AGENTS.md 祖先链发现+worktree 防重复；**system prompt 不持久化，会话恢复时实时重建**（配置变更自动反映到旧会话）。
+灵枢对应落点：`stg.py`/recall 组装路径与 `compact_context`；「错误消息不入上下文」与「大输出落盘保尾」两条最值得先做。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 六条全落地 + 一条取证后判定「结构性已满足」**（改动面：`hive/exec.py`、`hive/test_exec_tools.py`、`md_cg/mcp_server.py`、`md_cg/test_read_clip.py`、`scripts/render_discipline.py`、`scripts/verify_discipline.py`、`scripts/test_injection_chain.py`、`docs/discipline/harnesses.yaml`、`.github/workflows/discipline-check.yml`）。
+  | pi 细节 | 灵枢落点 | 与 pi 的偏离 |
+  |---|---|---|
+  | 错误/中止 assistant 消息不入上下文 | `exec.py` 空轮护栏：`content` 与 `tool_calls` **双空** → 记日志 + `progress(error)` + `error` 终态，不再冒充有效终答（旧行为曾产出 `ok=true` + 空 content 的假成功） | 判据取「双空」而非「有 error 字段」——错误轮本身可能带有效 content（工具失败但模型给了说明），一律丢弃会**丢真信息** |
+  | read 截断 2000 行/50KB 附续读提示 | `mcp_server.py` `_clip_text` 双阈值（`READ_MAX_LINES`/`READ_MAX_BYTES`）+ `offset`/`next_offset` 续读；截断时**显式**返回 `truncated/total_lines/total_bytes/note`，未截断路径零新增键（旧调用方无感） | 阈值同 pi；**不静默**——「截了多少、从哪续」是返回体必带字段，不靠模型猜 |
+  | bash 大输出全量落盘 + 消息保尾 | `exec.py` 工具回喂面：全量落 `tool_<i>_<j>.json`，回喂消息保**头+尾**并插「中间省略」提示（对齐 `_dump_step`+`_render` 既有形态） | 保留头部（错误常在首屏），pi 只保尾 |
+  | 图片自动缩 2000px、4800 字符/张 | `exec.py` context_files 面：零依赖探测尺寸（PNG IHDR / JPEG SOF，不读像素内容）；超阈值按需处理并反馈「是否已压缩」；token 折算 `IMAGE_CHARS_PER=4800` | **不主动缩图**（处置由调用方决定、结果如实回报），不做隐式重编码 |
+  | AGENTS.md 祖先链发现 + worktree 防重复 | `render_discipline.py`（`_walk_ancestors` + `discover_injection_chain`）/`verify_discipline.py`（`check_injection_matrix`）/`harnesses.yaml`（`injection:` 声明段 + 每 target `slot:`） | 见下方「⑤ 关键取舍」 |
+  | system prompt 不持久化、恢复时重建 | `exec.py` `resolve_system_prompt`：`system_prompt_from` 声明后**每次执行重建**（rust 侧 claimed 重投的崩溃恢复窗口也覆盖），缺文件 **fail-closed**（明确失败优于静默沿用旧提示词） | **取证结论：默认路径结构性已满足**——hive 每次 spawn 由调用方重建 `system_prompt`，`spec.json` 是**任务证据**而非 pi 所指「持久化会话状态」，故不存在 pi 那个缺陷本体；仅补一条显式重建通道，未做无靶改动 |
+  **⑤ 关键取舍（防重复的真实落点）**：去重落在**目录层**——走祖先链按物理目录身份（realpath+normcase）折叠别名拼写，使 worktree/junction/大小写别名下同一份件只查一次。**反面已实证**：按「git 仓身份 + 仓内相对路径」做键**会错**——worktree 与其主仓的 `AGENTS.md` 是同相对路径但**物理不同的两个文件**（各自 checkout 一份），折叠即把真实重复注入源静默藏起；故此类同仓不同物理文件只**标注**（`wt_dups`）不折叠。判据分两档：**硬失败**（`path_dup` 同物理文件被两个 target 写；`root_shadow` 仓根遮蔽本地私有件 → 后者使本地纪律注入失效）与**发现面报告**（祖先链同槽位命中：仓内判定同源指纹、仓外属宿主侧事实，本仓不裁决但不得假定不存在）；每个 file target 必须声明 `slot` 且产物名在其槽位清单内（否则遮蔽判定失真），有守卫。
+  **验收证据**：`hive/test_exec_tools.py` **47/47**、`md_cg/test_read_clip.py` **14/14**、`scripts/test_injection_chain.py` **35/35**（含 junction 别名折叠实证、`path_dup`/`root_shadow` 两硬判据的**正向与恢复双向**断言、防重复反面对照）；`scripts/run_tests.py` 新增 `scripts` 组（scripts/ 非包 → 直跑）；`verify_discipline.py` 注入面全绿；CI `discipline-check.yml` 增挂注入面自检步（Linux 下 junction 项自动 SKIP，属环境差异非失败）。
+
+## 4. 反面清单（不学什么，与灵枢哲学冲突）
+
+| pi 做法 | 为什么不学 | 灵枢对应原则 |
+|---|---|---|
+| 无 sandbox/无审批，扩展以用户全权运行（security.md:35 自述有意设计，隔离外包 OS/容器） | 信任必须**结构强制且可复算**，不能靠文档告诫+一道 project trust | 位置效应、写权限互斥、凭据六角色（designer/reflection/verifier/recorder/output/sustain/guest） |
+| No MCP 立场（CLI+README 替代协议） | 灵枢保持双形态接口：MCP 服务 MCP 阵营（资格闸服务端强制），CLI 形态补「md 目录直改设防」后再开；协议哲学见荣 2026-09-15 纲领（唯一协议=智能论，字节层放开） | 智能论=唯一行为协议 |
+| 子进程模型（OASIS 式批处理/每工具一进程） | md_cg 主链路常驻+Rust `--serve` 检索形态已占优 | 记忆真源唯一+多端共享 |
+| 会话即全部记忆（无跨会话沉淀） | pi 的 session 文件就是它的全部记忆；灵枢的认知图蒸馏（16 条闭环）是**灵枢独有的维度**，绝不为对齐 pi 而弱化 | 记忆闭环（第 16 条） |
+
+## 5. 与既有工作线的边界（防撞车）
+
+- **writelimit.py（已落地 2026-09-15）**：contextual 层写侧限流+同构聚合+读侧 tidy——不要重做；③/⑤ 与它互补（两段式对账、census 断言）。
+- **coggraph 交接（DSH→CodeBuddy，另一份文档）**：可视化管线/语义层/命名治理归那边；本文件的 ①④⑥ 改 `md_cg` 核心不碰 `tools/coggraph/`。
+- **审计遗留五项**（role 回填/evidence 补齐/精确重复 90/闸门加严/召回 7%）：⑤ 的 census 会持续暴露它们；修复动作（回填/合并）另立子步，先断言后治理。
+
+## 6. 建议施工顺序
+
+1. **⑥ 钩子化**（先改结构，后续一切闸门策略都挂上去）→ 2. **④ fork**（条件论落地最大增量）→ 3. **① 描述瘦身**（立即降 token，独立可并行）→ 4. **② 状态机** → 5. **③ 两段式** → 6. **⑤ census** → 7. **⑦ 细节**。
+每步：实现 → 全量回归 → 灵枢归档（16 条四要素）→ 看板/文档同步。
+
+> **进度（2026-09-16 取证核）**：第 **1–6 步均已落地**——⑥④ 见 `419305c`、③ 见 `4201238`、① 见 `c789e95`、② 见 `2ebf8f0`、⑤ 见 `8fffc24`；**仅剩第 7 步 ⑦ 未开工**。落点与验收数字见 §3 各项「落地状态」。
+
+## 7. 快速上手（CodeBuddy 5 分钟）
+
+```bash
+# 1. 读本文档 §1 落点纪律 + §4 反面清单
+# 2. 查证 pi 源码（任选两条路径核对本文档行号引用）：
+#    agi-architectures/pi/packages/agent/src/harness/session/types.ts:315
+#    agi-architectures/pi/packages/coding-agent/docs/extensions.md:277
+# 3. 确认灵枢基线：python -m md_cg.test_p0（及全量 test_pXX 回归绿）
+# 4. §6 第 1–6 步（⑥④①②③⑤）已落地、仅 ⑦ 未开工——续做前先按 §3「完成度判据」取证
+```

package/docs/README.md

@@ -0,0 +1,111 @@
+# docs/ 目录索引
+
+> 按工程域分目录，与本仓 README「平台全景」五件套对应。新文档先归域、后登记到本页对应清单；跨域的横切件留顶层。改纪律真源路径前须核对引用面（AGENTS.md / 渲染管线 / md_cg 注释）。
+
+## 目录结构
+
+```
+docs/
+├── mdcg/      灵枢大脑 md_cg 工程（架构/工具表/发布/教程/护栏）
+├── swarm/     蜂群运行时 swarm/
+├── hive/      蜂巢并发引擎 hive/
+├── world_model/  世界模型神经网络底层架构（hex 系列台账）
+├── theory/    智能论与白箱智能理论（跨工程）
+├── eval/      评测与第三方验证报告
+├── plans/     项目计划 / 交接文档 / 实验规格（跨工程）
+├── discipline/  工作纪律渲染管线（模板 / harness 矩阵）
+├── promo/     宣传物料
+├── experiments/ 实验区（gitignored，可重跑再生产物）
+└── 工作纪律_认知图条目_v1.1.json   ← 全局真源（横切面，不属单一工程）
+```
+
+## mdcg/ · 灵枢大脑 md_cg 工程
+
+| 文档 | 内容 |
+|---|---|
+| [README 详细版](mdcg/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 |
+| [发布说明 v0.3.0](mdcg/release_v0.3.0.md) / [v0.4.5](mdcg/release_v0.4.5.md) | 各版变更 / 升级指引 |
+| [工具表 v0.3.0](mdcg/tool_table_v0.3.0.md) | MCP 工具清单 |
+| [功能调用映射表 v0.1](mdcg/功能调用映射表_v0.1.md) | 功能 → 源码行号（管线生成，勿手写行号） |
+| [灵枢 MCP 工具总表 v3.4](mdcg/灵枢MCP工具总表_v3.4.md) | 工具参数与调用规范 |
+| [灵枢 82 工具迁移映射 v0.1](mdcg/灵枢82工具_功能整理与迁移映射_v0.1.md) | 功能整理与迁移对照 |
+| [灵枢自我层定义](mdcg/灵枢_自我层定义.md) | 自我层行为规范（test_p16 行号级引用） |
+| [三层拆分规划 v0.1](mdcg/灵枢三层拆分规划_v0.1.md) | 架构分层规划 |
+| [记忆操作系统 MdCGOS 与 MCP 接入 v0.1](mdcg/记忆操作系统_MdCGOS与MCP接入_v0.1.md) | 核心架构设计 |
+| [认知图 MD 目录方案 v0.1](mdcg/认知图_MD目录方案_v0.1.md) | 目录方案（test_p27 验收对象） |
+| [认知图索引与工程规范化计划 v0.1](mdcg/认知图_索引与工程规范化_计划_v0.1.md) | 索引工程化 |
+| [认知图条件空间合成与生效条件口径 v0.1](mdcg/认知图_条件空间合成与生效条件口径_v0.1.md) | 条件论口径 |
+| [认知图 G4-G8 缺口裁定单 v0.1](mdcg/认知图_G4-G8缺口裁定单_v0.1.md) | 缺口裁决留痕 |
+| [认知图作为记忆操作系统：评估与路线 v0.1](mdcg/认知图作为记忆操作系统_评估与路线_v0.1.md) | 路线图 |
+| [主代理子代理记忆架构设计](mdcg/主代理子代理记忆架构设计.md) | 多代理记忆分工 |
+| [子代理配置标准 v0.5](mdcg/子代理配置标准_v0.5.md) | 运行时角色拓扑·六位（§8：副代理=设计者视角）/ 统一执行默认（§0）/ 派发 / 确定性执行（§7）/ 复用 / 产出物生命周期（§5.4） |
+| [单元自我锚点·系统提示词标准 v0.3](mdcg/单元自我锚点_系统提示词标准_v0.3.md) | 提示词锚点标准 |
+| [令牌与角色权职分离 v0.1](mdcg/令牌与角色权职分离_v0.1.md) | 权限模型 |
+| [缺口单 P0 收口 v0.1](mdcg/缺口单_P0收口_v0.1.md) | P0 缺口清单 |
+| [源码级架构审计：GPT 批评对照 v1.0](mdcg/源码级架构审计_GPT批评对照_v1.0.md) | 外部审计取证 |
+| [护栏宪章 v2.0](mdcg/guardrail-charter.md) | 对外部智能体与人类的行为边界 |
+| [memory_score](mdcg/memory_score.html)（[png](mdcg/memory_score.png)） · [memory-assessment](mdcg/memory-assessment.html) · [教学教程](mdcg/lingshu_tutorial.html) | 评分 / 评估 / 教程 |
+
+## swarm/ · 蜂群运行时
+
+| 文档 | 内容 |
+|---|---|
+| [功能说明 v0.6](swarm/蜂群多智能体_功能说明_v0.6.md) | .pbc 确定性实例 + Gossip/WAL/信任聚合 |
+| [使用报告 2026-09-13](swarm/蜂群多智能体_使用报告_20260913.md) | 实测记录 |
+| [蜂群互联 v0.1](swarm/蜂群互联_v0.1.md) | 多蜂群互联协议 |
+| [蜂群盲区标记 v1.0](swarm/蜂群盲区标记_v1.0.md) | 盲区协同标记 |
+| [蜂群同错检测实验协议 v0.1](swarm/蜂群同错检测实验协议_v0.1.md) | 同错检测实验设计 |
+
+## hive/ · 蜂巢并发引擎
+
+| 文档 | 内容 |
+|---|---|
+| [蜂巢工作记忆·项目计划](hive/蜂巢工作记忆_项目计划.md) | hive 工作记忆规划 |
+
+## world_model/ · 世界模型神经网络底层架构
+
+| 文档 | 内容 |
+|---|---|
+| [世界模型·神经网络底层架构 v1.0](world_model/世界模型_神经网络底层架构_v1.0.md) | hex 系列工程成果台账（11 件组件 / 反传语义 / Rust 后端 / 认知图对接面 / 验证基线与红线） |
+
+## theory/ · 智能论理论
+
+| 文档 | 内容 |
+|---|---|
+| [白箱智能是什么？](theory/白箱智能是什么？.md) | 教学一 |
+| [智能的认知过程](theory/智能的认知过程.md) | 教学二 |
+| [智能的公理化基石](theory/智能的公理化基石.md) | 教学三 |
+| [信息差为什么必然存在且自然扩大](theory/信息差为什么必然存在且自然扩大.md) | 教学四 |
+| [白箱智能系列·第五篇：让 AI 真正装上记忆](theory/白箱智能系列·第五篇：让AI真正装上记忆.md) | 系列续篇 |
+| [智能论 3.4](theory/智能论3.4.md) | 理论主文档 |
+| [并发必然性理论 v0.2](theory/并发必然性理论_v0.2.md) | 并发架构的必然性论证 |
+| [单线程与注意力集中 v1.0](theory/单线程与注意力集中_无争议理论文档_v1.0.md) | 无争议理论文档（含验证留痕表） |
+| [概念分层对齐表 v0.1](theory/概念分层对齐表_v0.1.md) | 概念层级对齐 |
+| [认知代理与收敛结构·条件论重构 v0.1](theory/认知代理与收敛结构_条件论重构_v0.1.md) | 条件论 |
+| [理论·机制·代码·实验·缺口矩阵 v0.1](theory/理论_机制_代码_实验_缺口矩阵_v0.1.md) | 全景矩阵 |
+| [理论仓拆分与白箱知识库内迁 v0.1](theory/理论仓拆分与白箱知识库内迁_v0.1.md) | 拆分方案 |
+
+## eval/ · 评测与第三方验证
+
+| 文档 | 内容 |
+|---|---|
+| [AGI 七维评分报告 v1.0](eval/AGI七维评分报告_md_cg_v1.0.md) / [v2.0](eval/AGI七维评分报告_md_cg_v2.0.md) | 逐维得分 / 诚实边界 |
+| [第三方复评·统一评分 v7](eval/第三方验证报告_灵枢_vs_dejavu_统一评分_v7.md) | 七轮对照：灵枢 9.258 / deja-vu 9.119 |
+| [第三方验证·LoCoMo 独立复现](eval/第三方验证报告_LoCoMo_灵枢_.md)（[png](eval/第三方验证报告_LoCoMo_灵枢_.png)） | 独立评测全流程复现 |
+| [六家横评 100 题中英双查 v1.0](eval/横评_六家100题中英双查_v1.0.md) | 六家同口径对照 |
+| [实验方案·学习闭环 AB 与横评 v1.0](eval/实验方案_学习闭环AB与横评_v1.0.md) | 实验设计 |
+
+## plans/ · 项目计划 / 交接 / 规格
+
+| 文档 | 内容 |
+|---|---|
+| [命名治理·项目计划](plans/命名治理_项目计划.md) | 命名规范治理 |
+| [知识图谱项目·交接文档 2026-09-14](plans/知识图谱项目_交接文档_20260914.md) | 项目交接 |
+| [GridWorld 最小闭环规格 v0.1](plans/GridWorld最小闭环规格_v0.1.md) | 实验规格 |
+
+## 归域规则（新文档放哪）
+
+1. **工程文档** → 对应工程域（`mdcg/`、`swarm/`、`hive/`、`world_model/`；rust / compiler 有专属文档时新增同目录）。
+2. **跨工程理论** → `theory/`；**评测 / 第三方报告** → `eval/`；**计划 / 交接 / 规格** → `plans/`。
+3. **横切全局件**（工作纪律真源等）→ 留顶层，移动前必须核对引用面并全量重写。
+4. 入域后在本页对应清单登记一行；`discipline/`、`experiments/`、`promo/` 既有惯例不变。