@furongjun1999/dsh-memory 0.4.10 → 0.5.0

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

@@ -1,144 +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「完成度判据」取证
-```
+# 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「完成度判据」取证
+```