@a9i5k4/dsh-auto-memory 3.0.1 → 3.1.0

package/docs/internal/ROADMAP.md

@@ -1,106 +0,0 @@
-# 主线路线图（2026-09-14 定稿）
-
-> 唯一"看这里"的文件：回答「千头万绪怎么理」。事项明细在 `TODO-BACKLOG.md`，本文件只讲**主线、依赖、顺序、判据**。
-> 用户 2026-09-14 亲述 9 项（QQ 记录）+ 群友脱敏记忆文件报的 3 条工具缺陷，已全部归位到下面四条主线。
-> **可视化孪生**：`TODO-GRAPH.html`（同一批事项的图，用户直接看那张；**改排期时两边必须同步**）。
-
-## 0 一句话主脉
-
-所有事项其实在回答**同一个问题**：**记忆从产生到使用，中间哪一步会出错？** 把这条链路摊开，就是六步：
-
-| 步骤 | 出错会怎样 | 对应事项 |
-|---|---|---|
-| ① 产生（反思/沉淀） | 产生**错误记忆** | B1 晋升标准（8 号）、A1 纠错 |
-| ② 存储（文件/索引） | 写坏、超容量、改一下全库重排 | A5 文件卫生（群友报 3 条）、A1 块级缓存 |
-| ③ 选取（检索） | 选错/漏选/被旧记忆带偏 | A3 分级精确检索、A6 语义框架（9 号）、A4 会话检索 |
-| ④ 注入（进上下文） | 把错的灌进去，**一路走错** | A2 注入上限 + 排除来源（4 号前半） |
-| ⑤ 晋升（长期化） | 不可控、不直观、串项目 | B2 skill hand-off（8 号）、B3 可读性（5 号）、B4 晋升开关（3 号） |
-| ⑥ 呈现（给人看） | 看不见进展、开关点不动 | C2 graph 集成（1 号目标）、C1 接续开关（1 号）、C3 模型选择（2 号） |
-
-**排序原则**：先做「哪一步最痛」+「哪一步是别人的前置」。据此得出下面四条主线的优先级。
-
-## 1 四条主线
-
-> ⚠️ **编号口径（防混淆）**：本条线里的 `A/B/C/D + 数字`（如 A1、C2）是**主线条目号**，与 `TODO-BACKLOG.md` 历史分区名 `§A/§B/§C/§D`（那 A=阻塞在用户决策、B=下一版三点、C=冷启动、D=分发门面）**无关**。**唯一权威编号是看板号 `P0-①…/P1-⑤…/P2-⑦…`**，每条主线条目后面都标了对应的看板号，两边以看板号对齐。
-
-### A 线｜记忆的正确性（进得对、出得准、错得掉）★最痛
-- **A1 错误记忆的废弃与修改**：改正 = 写新记录声明 `supersedes` + 旧记录标 `supersededBy` + 检索过滤；配套**块级向量缓存**（改一条只嵌一条，不再整库重排）。← 3 号/4 号诉求 + 图片里"语义模型需要编号、随便增删会乱、每次都要重新构建"的正解
-- **A2 注入上限 + 来源排除**：给注入设压缩上限，并能把某条来源整个排除（坏记忆不再被反复灌进去）。← 4 号前半（含"旧记忆怎么废弃、怎么改"）
-- **A3 检索的精确与分级**：Tier-0 目录 → L0 摘要 → 原文，逐层缩窄 + 仲裁规则。← P0-③
-- **A4 会话检索可用**：51 个阻塞文件（已取证，四组处方，等拍板施工）。← P0-①
-- **A4b 跨会话 / 跨 Agent 检索**（**本会话主线，勿再漏**）：让"我记不清哪版改了什么"真正可查——覆盖 DSH 自身会话历史 + 其它 Agent 的记忆/会话（Claude Code / Codex / WorkBuddy / ZCode）。**路径已选 C（分期版 A）**：先把插件自己承诺的能力做实，再扩到外部 Agent 源。**调研与成本已实测**：DSH 191 个/320MB、Codex 17/45.8MB、WorkBuddy 89/155MB、ZCode 3/80MB（合计约 600MB）；DSH 321MB 压缩 → 解压约 0.67GB → 可索引正文约 0.35GB（压缩比 2.1x、正文占 52%）；解码 11MB 文本 0.7s → 全量扫描约 1 分钟 CPU。**技术结论**：FTS5/BM25 词法为主干 + 可选本地小嵌入做混合（RRF 融合）+ **轮次级（round）分块** + 增量后台索引；LongMemEval-S 实证 BM25-only R@5 86.2% → 混合 95.2% → 纯向量 96.6%。**容错纪律**：逐文件跳过 + 计数 + quarantine，**不得 fail-closed**（这正是本机检索被 51 个文件压死的教训）。落盘=`CROSS-SESSION-SEARCH-RESEARCH.md` + `CROSS-SESSION-SEARCH-PATH-DECISION.md`。**待拍板**：是否开工、先覆盖哪几个源。← P2-⑦
-- **A5 记忆文件卫生**：空标题碎片 / 超容量拒写 / 账本被快照段落污染（群友报 3 条；**本机只复现 0 处**，须先查证再修）。
-- **A6 语义框架与评估基准**：把检索/语义这条按**规范 RAG 框架**做一遍审计（视频=10 种 RAG 策略），产出"我们的策略清单 + 应加未加 + 评估基准"。← 9 号
-
-### B 线｜记忆的结构（procedural memory 重构）★多个事项的共同前置
-- **B1 晋升标准重做**：不只"次数沉淀"，**长时攻关/突破也晋升**为长期 skill 记忆。← 8 号
-- **B2 skill 之间的 hand-off**："用完这个常遇到那个" → 两个紧密联系的 skill 可互相写交接。← 8 号
-- **B3 技能可读性**："我都不知道是啥技能" → 晋升后要有看得懂的说明。← 5 号
-- **B4 晋升开关**：项目记忆 → 全局记忆的晋升可开可关、可手动管理。← 3 号
-- **结论**：**3 / 5 / 8 号全部锁在 B 线之后**（用户自己的规划也是如此："得在我重过完 procedural memory 部分以后再进行"）。B 线是第二批的地基。
-
-### C 线｜界面与可见性（白板 / 看板 / graph）
-- **C1 白板「接续」开关互锁 + 取消强制接续**：现在"接续"开了之后"强制接续"点不动、要关只能整个白板关掉；且强制接续会让主力 agent 用贵模型（成本诉求）。← 1 号，**功能 bug，可插队先修**
-- **C2 graph 集成两个验收目标**：①**不启动 agent 也能单独看到项目总体进展**；②进展**同步注入 agent**，多轮压缩后仍准确掌握。← 1 号目标
-- **C3 设置里 sub agent 模型/思考强度选不动**：能读出、选不动、估计也用不上。← 2 号，**功能 bug，可插队先修**
-- **C4 手机端首次启动指引太大且关不掉**：远期随 UI 调整。← 6 号
-- **C5 日历换开源方案**：调研公开开源日历组件替换自研。← 7 号
-
-### D 线｜工程质量与验收
-- **D1 能力可达性验收**：每条对外承诺都要有"默认配置下可达"的证明。← P1-⑤
-- **D2 OpenViking 式补全返工**：`l0-index` 接线、Tier 分级、L0 补 `layer/status`。← P0-②
-- **D3 群反馈闭环**：已有（@现有问题 / 日报自动销账），只需持续喂。
-
-## 2 推荐执行顺序
-
-**第一批（工程优先，都在"记忆正确性"，一次重启内可交付）**
-1. C1 + C3（两个功能 bug，不依赖任何东西，感知强、成本低）
-2. A4 会话检索解锁（等拍板 → 施工 → 全量复验 → 一次重启）
-3. A1 + A2（错误记忆废弃/修改 + 注入上限/排除）← **用户最痛，且 B4 依赖它**
-
-**第二批（检索质量）**
-4. A3 + D2（分级精确检索 + OpenViking 补全）
-5. A6 语义框架审计（用规范 RAG 策略清单审 A1/A3 的实现）
-6. A5 记忆文件卫生（先查证 3 条，能复现的进本批，不能复现的记档）
-7. D1 验收标准返工
-
-**第三批（结构）**
-8. B1–B4 procedural memory 重构（连带解锁 3 / 5 / 8 号）
-9. C2 graph 集成（把进展可视化 + 注入 agent）
-
-**最后**
-10. C4 / C5 + 界面重构与美化
-
-## 3 每条主线的完成判据（可验，不看感觉）
-
-- A1：改一条记忆后，**向量文件不是整体覆写**（只有新增块被编码），且被 supersede 的旧记忆**不再出现在检索结果里**，审计链仍可查。
-- A2：注入量可设上限；被排除的来源在后续注入中**0 次出现**。
-- A3：同一问题在"目录→L0→原文"三层各能命中，且分层仲裁有明确规则（笔记>日志、被更正项过滤、provenance 可见）。
-- A4：51 个文件全部可读 + 索引建立 + `[记忆检索|sessions]` 真出结果。
-- A5：三条各自"能复现 → 修复 → 加回归断言"，不能复现也要留下"查过、证据在此"。
-- A6：产出一张《我们的检索策略 vs 规范框架》对照表 + 缺失项清单 + 评估基准与当前得分。
-- B1/B2：晋升记录里能看到"因攻关而晋升"与"skill 互链"两类真实样本。
-- B4：晋升开关默认关（或按用户设定），关闭后项目记忆**不再自动写入**全局记忆。
-- C2：不启动 agent 即可打开图看到最新进展；同一条进展在 agent 压缩后的上下文里能被读到。
-- D1：把现有对外承诺逐条跑一遍，缺证据的补测试或改文案。
-
-## 4 我先需要你拍板的 3 件事
-
-1. **A4 的施工口径**：C+B（就地修复 51 个 + 索引器加跳过保险）/ 只 B / 只 A / D / E。
-2. **4 号里「压缩上限 + 排除用户提示」具体指什么**——是指注入量上限（条数/字符），还是指压缩蒸馏时的取舍规则？我按"注入上限 + 可排除来源"理解并入了 A2，但需要你一句话确认。
-3. **A1 的授权边界**：AI 可以**直接改**记忆文件，还是只能给出"建议修改"由你确认？（图片里你说"下个版本看看能不能让 AI 去修改记忆"——这条决定 A1 的交互设计。）
-
-## 5 本路线图与本会话既有结论的衔接（防脱节，2026-09-14 补）
-
-> 这份文件是**追加**在既有工作之上的，不是重来。以下既定结论全部保留、未被本表覆盖：
-
-| 既有结论 | 出处 | 在本表中的位置 |
-| --- | --- | --- |
-| 会话检索"从没真正开过"（四条硬证据）+ 51 个文件四组构成 + 禁删行（seq 必须等于行序号）+ 真白名单 15 项 | `SESSION-FILE-REPAIR-PROTOCOL.md`、`ACCEPTANCE-20260914.md` 附录 | **A4 / P0-①**（等口径） |
-| 跨会话 / 跨 Agent 检索：路径 C（分期版 A）+ 体量实测 + 成本模型 + LongMemEval 证据 | `CROSS-SESSION-SEARCH-RESEARCH.md`、`-PATH-DECISION.md` | **A4b / P2-⑦** |
-| 三层记忆的**设计意图**（上层指引"要不要用"、逐层下探、上层出来即缩窄搜索空间）+ 现状三缺（无状态 / 无层级归属 / 无递进闸门） | 用户澄清，项目笔记 | **A3 / P0-③** 的目标形态 |
-| 记忆增删 × 索引重排的机制（miv 全量哈希、worker 全量重嵌、块级 ID 已内容寻址却未用作缓存键）+ 方案（块级缓存 / supersede / 差量 / fail-open） | `MEMORY-MUTATION-AND-INDEX-DESIGN.md` | **A1 + A2 / P0-④ 及附** |
-| 白板图参照物 = **`miuzel/dsh-graph`**（不是 DSH-Plan-Graph）+ 用户已定"combine 进自己白板"+ 已有 P0→P3 预研与 15 个拍板点 | `WB-GRAPH-DECISIONS-20260914.md`、4 份 `WB-GRAPH-*` | **C2 / P1-⑥** |
-| 验收基线：npm 2.5.2 / REL=main=tag=55c3deb / pre `1c06c46` / 71 套件全绿 / m73 flake 已修 | `ACCEPTANCE-20260914.md` | **D1 / P1-⑤** 的起点 |
-| 两个界面功能 bug 来自群反馈（接续开关互锁、sub agent 模型选不动） | QQ 群记录（用户转发） | **C1 / P0-A、C3 / P0-B** |
-| 过渡投递管道 `TODO-GRAPH.html`（不投入打磨，白板上线后退役） | 用户口径 | C2 的前身，不另立条目 |

package/docs/internal/RUN-P0-NIGHTLY.md

@@ -1,227 +0,0 @@
-# RUN-P0-NIGHTLY · 过夜施工运行日志
-
-> **这是什么**：KICKOFF §6.2 要求的持续追加运行日志。压缩会吃掉思考过程，但吃不掉写进文件的结论。
-> **读法**：接续/被压缩后，先读本文件恢复进度，再继续施工。
-> **纪律**：客观陈述（第三人称中性句式），只留可复用的事实/决策/路径，不写思考腔。
-
----
-
-## [00:20] 接续仪式 + 环境确认
-
-- 目标：接续上一窗口（已按接续键），恢复上下文并按 KICKOFF 开工。
-- 做了：
-  - 读 `docs/internal/KICKOFF-P0.md`（254 行，第一份指令）。
-  - 按 §2 找接续转写包：`~/.dsh/memory/workspaces/--D--dsh-auto-memory--/handoff/prev-session-session--160615.md`（75497 字节，2026-09-15 00:06:15，最新一份）。
-  - 读 `MASTER-PLAN-3.0.md`（§0.5 v2 修订 + §0–§3.5）与 `reviews/ROUND3-REVIEW-INTEGRATION-20260914.md`（230 行，全部三处我方错误 + 六处设计修正 + 断言编号）。
-- 结果：确认工作区 `main` 分支、110 项未提交改动（含约 98 个用户工作状态文件）；全量基线待复测。
-- 卡住：无。
-- 下一步：跑红证明 → 修 C8。
-
-## [00:26] 第一步 · C8 红证明复现（修复前）
-
-- 目标：按 KICKOFF §3.1 先确认缺陷真实存在（不是推测）。
-- 命令：`node tools/_redproof/red-proof-phase0-t01.mjs`
-- 结果：**0 通过 / 4 报红，exit 1**。实测四条全红：
-  - `superseded 条目不出现在 Tier-1 注入行` RED
-  - `retracted 条目不出现在 Tier-1 注入行` RED
-  - `非 current 正文不出现在最终文本` RED
-  - `Tier-1 条数 = current 命中数(2) —— 实际 4` RED
-- 判读：契约 I5（`THREE-LAYER-CONTRACT.md:183`）在**注入侧**从未实现；检索侧（C2）早已过滤。
-- 根因（读码确认）：`lib/tier-layer-inject-pre.js:buildTier1SectionPre` 把 `h.status` 当**展示字段**渲染进 `- [layer/status]` 前缀，**从不做准入判断**。
-- 卡住：无。
-- 下一步：在装配器入口（闸门之前）加 current 过滤。
-
-## [00:35] 第一步 · C8 修复完成（注入侧 I5 状态过滤）
-
-- 目标：让非 current 条目在注入侧被挡下，并让红证明转绿。
-- 改了：
-  - `lib/tier-layer-inject-pre.js:filterCurrentHitsPre`（**新增导出**）—— 复用检索侧唯一权威
-    `import { isCurrentPre } from './l0-extract-pre.js'`（**import 而非复制**：复制会让两侧漂移）。
-  - `lib/tier-layer-inject-pre.js:composeTieredInjectionPre` —— 在**闸门之前**过滤（顺序关键：
-    放闸门后会让"全是 superseded"仍下探并渲染空段）；新增 `status-filtered` 降级项；
-    返回体新增 `hits`（过滤账：kept/dropped/total/current/droppedCount/droppedIds）。
-  - `tests/smoke/smoke-test-c5-tier-inject-pre.mjs:127/133/137` —— **改掉锁死错误现状的断言**，
-    并附注释说明原断言违反 I5、证据是红证明 4 报红。原 `lines[2].includes('0.55')` 用的是被挡下的
-    superseded 条目，改为**真正乱序输入**独立验证降序。
-- 结果：
-  - `red-proof-phase0-t01.mjs` ⇒ **4 通过 / 0 报红，exit 0**。
-  - `smoke-test-c5-tier-inject-pre.mjs` ⇒ pass=90 fail=0。
-  - `smoke-test-three-layer-pre.mjs` ⇒ pass=122 fail=0（无连带破坏）。
-- 卡住：无。
-- 下一步：把红证明移进 `tests/smoke/` 成为正式套件。
-
-## [00:45] 第一步 · 红证明入正式套件 + 演示变红
-
-- 目标：KICKOFF §3.1 第 3/4 条 —— 转绿后移入 `tests/smoke/`，并遵守
-  「新增守卫必须演示变红后再按字节还原」纪律。
-- 改了：新增 `tests/smoke/smoke-test-i5-status-filter-pre.mjs`（7 组 44 断言）。
-  保留原红证明 4 条判据，另补：取值域（缺失/空放行、未知值 fail closed）、
-  与检索侧同函数逐值对照、过滤在闸门之前、挡下不静默且**不回显被挡条目正文与 id**、
-  接线可达性、以及「开关不能撤掉共同保护」（过滤在 `enabled` 开关**之前**执行）。
-- **定向变异验证**：把 `isCurrentPre(h)` 改成 `true` ⇒ 套件 **12 条报红**；
-  随后按字节还原，SHA256 `A1C0CF8A9630C4677764EB5CBA4138046A49D2063303C06921F8EEB620591CA3`
-  前后一致（`RESTORED_BYTE_EXACT=True`）。
-- 结果：新套件 pass=44 fail=0。
-- 卡住：无。
-- 下一步：跑全量回归确认基线（预期 80 套件）。
-
-## [01:05] 全量回归（C8 修复后）
-
-- 命令：`node tools/run-smoke.mjs`
-- 结果：**PASS 80 / FAIL 0 / TIMEOUT 0，total 160.1s，exit 0**。
-- 判读：套件数 79 → **80**（新增 `smoke-test-i5-status-filter-pre.mjs`），符合 KICKOFF §3.1 第 4 条预期。
-- 卡住：无。
-- 下一步：第二步 T0-2 版本校验。
-
-## [01:25] 第二步 · T0-2 版本校验完成
-
-- 目标：命中投影复用**不得只凭时间**（旧 `lib/index.js:3894` 只查 `Date.now()-at<30min`，
-  且身份取不到时 **fail open**）。
-- 改了：
-  - `lib/tier-layer-inject-pre.js:selectReusableTierHitsPre`（新增）+ `describeReuseReasonPre`
-    + `TIER_HITS_REUSE_REASONS_PRE_V1` —— 五道门：时间 / 会话 / 工作区 / **版本（contextVersion + miv）** /
-    观测身份。凡不能证明同版同源 ⇒ fail closed 不复用；原因码全部有可读中文。
-  - `lib/activation-host-pre.js:recordTierGateHits` —— 投影补 `contextVersion / miv / observationId /
-    requestKey / workspaceKey`（T0-2 要求携带版本四元组）。
-  - `lib/index.js:buildTierLayerInjection` —— 删掉旧的 `fresh` / `sameSession` 判定，改调版本门；
-    不复用时追加**可见**降级行（I7），并把复用账写进 `tier0Meta.reuse`。
-  - `lib/index.js:tierCurrentMivPre`（新增）—— 当前 miv 的**零重读**实现：只用 `sourceFingerprint`
-    （`size:mtimeMs`）判变化，**不调 `CorpusRegistry.get()`**（后者在指纹变化时会整体重读重建语料，
-    不能放在每轮热路径上）；60 秒缓存，异常一律返回 null（下游 fail closed）。
-  - `lib/activation-inbox-pre.js:makeFakeActivationRequestPre` —— fixture 支持 `status` 与 `requestKey`。
-- 结果：新增 `tests/smoke/smoke-test-t0-2-version-gate-pre.mjs` **pass=68 fail=0**。
-  含核心场景「A 快照产生候选、B 快照准备输出 ⇒ 必须不复用（混装即失败）」。
-- **定向变异验证**：把三道版本门改成恒假 ⇒ 套件 **8 条报红**；按字节还原后 SHA256 前后一致。
-- 首跑踩坑（已留痕在测试注释）：两条接线断言**假红** —— 正则命中了注释里刻意保留的旧实现片段。
-  修正方式：先剥注释再匹配（本文件成为"源码接线守卫 ≠ 行为断言"纪律的又一实例）。
-- 卡住：无。
-- 下一步：第三步 T0-3 预算单一口径。
-
-## [01:55] 第三步 · T0-3 预算单一口径完成（模块层 + 接线）
-
-- 目标：把注入预算改成**分项账本**（v2 §3.3 选 (ii)），消灭两处实测缺陷。
-- 改了：
-  - **新增 `lib/memory-envelope-pre.js`**：`composeMemoryEnvelopePre` + `describeEnvelopeCharsPre`。
-    三条不变式各有能红断言：E1 `chars.total === text.length`（逐字节）、
-    E2 分项之和 = 总计（**不允许未计费尾巴**）、E3 分项上限是硬约束且**裁剪永远可见**。
-    `rules` 不参与裁剪（显式传上限也会被忽略并留痕）；`over-budget-total` 如实记录代价
-    （v2 要求"不许用记账写法掩盖"）。
-  - `lib/tier-layer-inject-pre.js:composeTieredInjectionPre` —— 修总长门两处：降级行**先计入 head
-    长度**再裁、裁完**真正回写** headParts、head 自身超预算时输出 `headOverBudgetChars` 显式超额行；
-    新增 `textChars / maxTotalChars / claimedTotalChars / headOverBudgetChars` 四个可审计字段。
-    第一版实现漏了回写（降级行没进文本），靠 `claimed === len` 自检抓到 —— 已写进代码注释。
-  - `lib/index.js:renderMemoryDynamic` —— 从 `lines[] + join('\n')` 改为**边推边归位**的 `segs[]`，
-    交给分项账本计量与序列化；删掉 35% 封顶的 `catalogCost` 与注水的 `used`；
-    目录层按**实际注入全文长度**计入 `memoryReferences`；`otherDynamicBudgetChars` 按 v2
-    "未配置时以 `Bm` 作派生初值、不另设魔数"实现；账本挂 `state.envelopeMeta`；
-    超限降级行附在快照尾部（不静默）。
-    **字节等价**：`join('\n')` ≡「首段无前缀 + 其余各加 `\n`」拼接；`neutralizePromptTemplateVars`
-    改为逐段施加（`{{`→`｛｛` 是 1:1 等长替换，逐段与整篇结果相同）。
-- 结果：新增 `tests/smoke/smoke-test-t0-3-budget-ledger-pre.mjs` **pass=64 fail=0**；
-  `smoke-test-c5-tier-inject-pre.mjs` 90/90（旧的总长门断言由红转绿）。
-- 连带修正（两条，非行为回归，已留注释）：
-  - `smoke-test-i5-status-filter-pre.mjs` 的接线断言原写死**单行**调用文本，T0-3 给该调用补了
-    `extraDegradations` 并改多行 ⇒ 改为断言**参数语义**（hits 确实作为实参传入）。
-  - `smoke-test-t0-3-budget-ledger-pre.mjs` 的 `envelope.chars.total` 断言改为 `envelope.chars`
-    （`total` 在同一表达式里，断言更贴实现）。
-- **连带回归（我引入的，已修）**：
-  1. `error: runtime B survived dispose`（`smoke-test-context-observer.mjs` P3f）——
-     我在 `buildTierLayerInjection` 里对 `runtimeFor(agent)` 取值；该方法底层
-     `SessionRuntimeStore.get()` **找不到时会新建并重新登记**，于是在 `await` 之后
-     **复活了已 dispose 的 runtime**。这正是本项目硬纪律写死的那条坑。
-     修法：新增**只读**的 `MemoryEngine.peekRuntime` / `SessionRuntimeStore.peek`（绝不创建），
-     注入路径改用它。
-  2. `ReferenceError: composeMemoryEnvelopePre is not defined`（`smoke-test-handoff-pre.mjs` G4）——
-     `renderMemoryDynamic` 现在依赖分项账本模块，而该套件用 `new Function` **抽源码跑**，
-     作用域里没有这个符号。修法：把 `lib/memory-envelope-pre.js` 源码一并注入（剥 `export `）。
-     这不是"测试迁就实现"——抽取式测试本来就要显式提供该函数依赖的全部模块级符号。
-  3. `Error: unbalanced: renderMemoryDynamic(context) {` —— 我在注释里写了裸 ASCII **双花括号**，
-     而该套件的 `extractFn` 靠**花括号配平**切函数体。修法：注释改为文字描述
-     （不写裸双花括号），并把这条坑写进注释本身。
-- 卡住：无。
-- 下一步：第三步完成后跑全量；然后第四步（写入门 + 白板最小适配边界）。
-
-## [02:05] 第四步 · 写入门 + 白板最小适配边界完成（T0-8 / T0-8B / T0-8C）
-
-- 目标：把 `WB-FORMAT-CONVENTION.md` §4 的写入门与 §5 的人机分区**真正实现**
-  （事故根因是"规范已批准、代码从未实现"：实际 `PLAN.md` 一个锚点、一个分区标记都没有）。
-- **边界（总纲 §0.5 / ROUND3 §3.1 定案）**：3.0 主体拥有共同提交与保护入口；白板线拥有白板格式及适配器。
-- 改了：
-  - **新增 `lib/memory-mutation-pre.js`**：`validateMutationBoundaryPre`（**只收规范化投影**
-    `{beforeIds, afterIds, protectedRegions, afterProtectedRegions, archivedIds}`，**零白板格式知识**）
-    + `validateProjectionPairPre` + `mutationRefusalTextPre` + `protectedRegionDigestPre`。
-    三条**无条件**保护：**M1** 丢卡（消失必须显式归档，否则拒写并报差异清单）/ **M2** 用户区
-    （摘要逐字节比对；**省略 afterProtectedRegions = fail closed**）/ **M3** 重复 id。
-  - **新增 `lib/wb-contract-pre.js`**：`parseWhiteboardPre`（锚点 / 卡片 / 人机分区 / 状态解析）
-    + `computeWhiteboardCardIdPre`（A8 预授权默认值：`mem_` + sha256(wsKey+NUL+页路径+NUL+标题) 前 32 位）
-    + `extractProtectedRegionsPre` + `toMutationProjectionPre`（唯一桥）
-    + **同模块内置判据门** `checkHandoffCriteriaPre`（H1–H4/S1–S4）/ `checkPlanCriteriaPre`
-    （P-H1/P-H2/P-S1）+ `criteriaRefusalTextPre`（格式只维护一份）。
-  - `lib/index.js`：新增 `checkMutationPre`（**判据门在前、保护门在后**，顺序有意为之：
-     质量门可退、保护门不可退）；`writePlanSnapshot` / `writeHandoffLedger` 各加 `opts` 并接入；
-     水位骨架降级路径（A6 预授权默认值 = **照写 + 警示行**）走 `skipCriteria:true`，
-     **只跳判据门、遇保护门拒绝时绝不绕过**；工具层对两类拒绝都返回**原始可执行文案**；
-     新增配置 `criteriaGate: true`。
-- 结果：新增 `tests/smoke/smoke-test-t0-8-mutation-gate-pre.mjs` **pass=110 fail=0**。
-  含 T0-8B（三条写入路径都不能绕过共同保护，源码接线守卫）、T0-8C（**关掉质量门后仍拒绝丢卡**）、
-  以及"判据不能张冠李戴"的反证（把账本判据套给 PLAN 会误拒 ⇒ 证明归属必须分开）。
-- **定向变异验证**：把 M1/M2 改成恒通过（＝回到"写入门从未实现"的旧行为）⇒ **15 条报红**；
-  按字节还原后 SHA256 前后一致。
-- 连带修正（签名扩展，非行为回归）：`smoke-test-handoff-pre.mjs` 与 `smoke-test-p7-write-fix-pre.mjs`
-  用**签名字符串**抽取函数 ⇒ 同步为 `(projectDir, content, opts)`；并给假引擎补
-  `checkMutationPre` 恒过桩（门本身由 T0-8 套件专测，接线由 T0-8B 锁）。
-- 中途一次**操作失误**（已留痕）：变异演示脚本里第二处替换目标写错了文件，
-  脚本以 `!!! MUT2 NOT APPLIED` 退出并留下一个未还原的 `.bak-mut`。已立即还原两文件并按 SHA256
-  确认无残留，随后重做变异演示（这次先在 `memory-mutation-pre.js` 内精确定位字符串）。
-- 卡住：无。
-- 下一步：第五步 P6A。
-
-## [02:40] 第五步 · P6A 注入表达与节奏完成
-
-- 目标：修**用户最痛的病**——「规矩不在场 / 规矩被降格为"只是参考"」。
-- 改了：
-  - **新增 `lib/rules-layer-pre.js`**：`extractRulesLayerPre`（两级判定：结构化前缀=高置信 /
-    约束语汇=中置信）+ `renderRulesSectionPre` + `splitMemoryEntriesPre` + `ruleSummaryPre`。
-    **遵守 v2 的真源纪律**：规则真源＝**既有用户级记忆**里的类型化规则，**不新增 `RULES.md`**。
-    **遵守 T7-4 的 v2 修订**：含「必须」但带引用/历史语境（`据文档写着` / `曾经` / `已取消`…）
-    **不得自动升级为规则**，只产生「待确认候选」——GPT 给的两个反例已写成断言。
-  - `lib/index.js`：`DEFAULT_PROMPT_LAYERS` 新增 `snapshotRulesTitle` / `snapshotRulesGuide`
-    （**约束语**措辞，与参考段的"参考"语义**不同**）；新增 `renderRulesOnlySnapshotPre`；
-    `renderMemoryDynamic` 把规则段以 `rules` 分项**排在最前**（在开场白/状态行之后、一切参考内容之前）；
-    新增配置 `rulesLayeringMode: 'off'`（**默认关** = 新旧并存 + 一键回退）。
-  - **节奏三处**（ROUND3 §3.3 Q3c，逐条落实）：
-    ① `snapshotMinGapRounds` 默认 **5 → 1**；
-    ② **新增 `parseGapRoundsPre`** 修零值解析（旧 `Number(v) || 5` 让 **0 无法表达**）；
-    ③ **节流分支不再跳过整份快照** —— 改为 `return rulesOnlyText + renderReflectionRequest()`，
-       即"**先提供规则段，再对参考内容应用 gap**"。
-- 结果：新增 `tests/smoke/smoke-test-p6a-rules-layer-pre.mjs` **pass=94 fail=0**。
-  含 T7-1（连续 6 轮规则都在 —— 在**能测的范围内**测注入函数返回值，并如实标注"模型真收到"需 U6）、
-  T7-3（规则与参考引导语**必须不同**）、T7-4 修订（两个反例 + 反面：真规则仍要认）、
-  T7-6（前缀字节稳定；**不冒充**缓存命中）、T7-7（规则以 `rules` 分项进账本 + 代码里不存在对 rules 的裁剪）。
-- **首跑抓到一个真实实现缺陷**：`ruleSummaryPre` 最初直接用 `firstLine`，而既有记忆条目结构是
-  「锚点 → `## 日期` → 正文」⇒ 规则行被渲染成 `- ## 2026-08-14`（**规则内容全丢，只剩日期**）。
-  修法：新增 `ruleSummaryPre` 跳过日期小节标题与锚点行。
-- **定向变异验证**：三点变异（取消引用语境降级 / 引导语改回"只是参考" / 摘要退回读首行）
-  ⇒ **11 条报红**；按字节还原后 SHA256 前后一致。
-  期间发现断言不够健壮（`candidates[0].confidence` 在变异后会抛 TypeError 让套件崩掉、
-  只剩一条红报告）⇒ 改为防御式取值，让"能红"不退化成"能崩"。
-- 卡住：无。
-- 下一步：全量回归 + 收尾汇报。
-
-## [03:00] 全量回归 + 字节卫生 + 收尾
-
-- 命令：`node tools/run-smoke.mjs`
-- 结果：**PASS 84 / FAIL 0 / TIMEOUT 0，total 154.0s，exit 0**。
-  套件数 79 → **84**（新增 i5 / t0-2 / t0-3 / t0-8 / p6a 五个套件）。
-- 守卫：`node artifacts/verify-todo-graph.mjs` exit 0（47 卡）；
-  `smoke-test-doc-code-consistency-pre.mjs` 44/0；`red-proof-phase0-t01.mjs` 4/4 绿。
-- **字节卫生事故与修复**：`tests/smoke/smoke-test-handoff-pre.mjs` 在编辑后变成 **CRLF**
-  （KICKOFF §8 第 6 条要求 `lib/*-pre.js` 与测试为 LF）⇒ 已逐字节转回 LF（315 bareLF / 0 CRLF）
-  并复跑套件（53/0）确认内容未损。
-  全仓复核：`lib/index.js` CRLF ✓、新模块（memory-envelope / memory-mutation / wb-contract /
-  rules-layer）均为 LF ✓、新测试均 LF ✓、**全部改动文件无 BOM** ✓。
-  （备注：本仓换行实际是**混合**的——`lib/index.js`、`lib/client.js`、`activation-*`、
-  `context-*` 等为 CRLF，`handoff-anchor-pre.js`、`tier-layer-inject-pre.js` 等为 LF；
-  纪律的实质是"**不改变既有文件的换行形态**"，本次未对任何既有文件改换行。）
-- 卡住：无。
-- 下一步：按 KICKOFF §7 输出完整汇报（含"最值得让 GPT 审的三个点"）。

package/docs/internal/S10-CONSTRUCTION-HANDOFF-20260917.md

@@ -1,185 +0,0 @@
-# 施工交接 · S10 四缺口全量改（2026-09-17 02:3x）
-
-> **给谁看**：压缩后的下一个窗口（我），以及用户本人。
-> **状态**：**未开工**。用户已拍板「四个缺口全量改」，但决定**先推送一次文档更新，明天再改代码**。
-> **2026-09-17 回读校正**：本文 18 处行号写于 3.0 发版**之前**，已有漂移（±5 行不等），且**缺口 1 的前提被 3.0 默认值翻转改写了**。
-> 以 `S10-GAP-INVENTORY-20260917.md`（同日实测复核版）为准；本文保留作为原始施工语境。
-> **上游依据**：`ROADMAP-20260917-WEEK.md` §3.5（技术版，带行号）· `S10-GAPS-PLAIN-20260917.md`（大白话版）。
-
----
-
-## 一、用户已拍板的决定（不要重开议题）
-
-| # | 决定 | 原话/口径 |
-|---|---|---|
-| 1 | **四个缺口全量改**（不是"标注未实现"，是真做） | 「我决定了，四个缺口都全量改」 |
-| 2 | **缺口 4 的第⑤类（矛盾检测）走「主代理每轮收尾写记忆时顺带做」** | 「不是 subagent 的自动沉淀，是每轮对话的收尾写记忆的时候可以更新白板状态」 |
-| 3 | 该时机下 **LLM 介入是合法的** | 用户自己推断，**已核实成立**（见 §四） |
-| 4 | **先推送一次文档更新，明天再改代码** | 「我压缩之后先推送一次更新，明天再改剩下的」 |
-| 5 | 图片等前端重构后再改 | 前轮已定 |
-
----
-
-## 二、四个缺口 + 现状（全部已代码核实）
-
-### 缺口 1（P0）· 锚点写入被 `boardMode` 门控，默认不生效
-
-> ### ⚠️ 前提已修正（2026-09-17 回读核实，v3.0.0 发版时翻转）
-> 本节原写「默认值 `boardMode:'legacy'`⇒整条链默认不启动」。**该症状已在 v3.0.0 消失**：
-> - `lib/index.js:221` 现为 `boardMode: 'graph'`（3.0 默认值翻转，随发版一起出去）
-> - `lib/index.js:312` 现为 `handoffEnabled: true`
-> ⇒ **默认配置下锚点写入、sidecar、tag 地图、expand/trace 工具全部已激活。**
-> **但「格式契约耦合渲染开关」这个根缺陷仍在**：只要用户手动切回 legacy，锚点写入立刻停摆。
-> 所以结论从「P0 默认不生效」下调为 **P1 耦合缺陷**（仍要做，但不再是发版阻断项）。
-
-- ~~默认值 `boardMode: 'legacy'` —— `lib/index.js:219`~~（已被 3.0 默认翻转覆盖）
-- 锚点写入仍被门控：当前行号 `:1993`（PLAN）、`:2037`（账本）；sidecar 早退 `:2081`
-- ⇒ **仅 legacy 档下 S10.1「页面即语料」整条链不启动**（graph 档正常）
-
-**改法（用户已认可方向）**：**把锚点写入与 `boardMode` 解耦**。
-理由：锚点是**记录格式**，看板是**显示样式**，本不该耦合。**不要改默认值**（会牵动老用户）。
-⚠️ 实施注意：解耦后需确认 sidecar 写入口径 —— `writeSidecarEntryPre` 的早退（`:2076`）与锚点写入是两件事，**要分别判断**是否都该解耦。
-
-### 缺口 2（P0）· 白板进「注入」但不进「检索」
-
-- 注入 ✅ `index.js:4701` `add('whiteboard', s.planText, s.planPath)` → Tier-0 目录（五来源之一，有保底配额）
-- 检索 ❌ `pushL0` 四来源（`:5505-5508`）与 `semSources` 四来源（`:5704-5707`）**均无白板**
-- **⇒ 白板每轮被注入，但 `memory_recall` 搜不到**
-
-**改法**：两处各补一条白板来源。`p.planPath` 变量**已存在**（`:4701` 在用）。
-⚠️ 注意配额：`tier0-catalog-pre.js` 的 `floorLayers=['whiteboard','user']` 是 Tier-0 侧的；**L0 检索侧是否需要同类保护要一并判断**，否则白板可能又被 `project` 挤掉。
-
-### 缺口 3 · 索引派生（S10.2）——**不是没做，是没输出成契约那一行**
-
-契约要的那行（`WB-FORMAT-CONVENTION.md:44`）：
-```
-- [卡片标题](<页面路径>#mem_<32hex>) — 一句话摘要 · layer=whiteboard · status=current · 2026-09-14
-```
-
-**已有的家底（关键！别重复造）**：
-- `rebuildSidecarIndexPre`（`wb-sidecar-pre.js:363`）**真在派生索引**，产出 `entries` + `by_tag` + `by_cue` + `versions`
-- 每条 entry 已有 `id`（`mem_`+sha256 前 32 位，`:78-83`）、`source`（页面路径）、`title`、`section`、`preview`（前 120 字）、`tags`、`cues`、`kind`、`mtime`、`ts`
-- **锚点 id 与 sidecar id 同源**：`applyAnchorsPre:501` 调的就是 `wbEntryIdPre`
-- `renderCatalogLinePre`（`tier0-catalog-pre.js:316`）已在渲染 `标题 · 摘要 · layer · status · 日期`
-
-**缺的只有**：① 没拼成契约那一行的字面格式 ② entry 无 `status` 字段 ③ entry 无 `layer` 字段
-
-**改法（已定的设计）**：**不做成独立文件**（那会新增状态源，违反 S10.4「不建状态机」）。
-改为：**同一次派生、两种渲染** —— 让 `renderCatalogLinePre`（或新增同源渲染函数）在有页面路径时输出**带链接形态**。
-⇒ 契约 §8 验收项「派生出 index 与 Tier-0 条目一致」**天然成立**，因为就是同一份数据。
-
-### 缺口 4 · lint（S10.3）——五类，前四类纯函数、第五类走纪律
-
-契约清单（`WB-FORMAT-CONVENTION.md:80-93`）：
-
-| 类 | 内容 | 难度 | 做法 |
-|---|---|---|---|
-| ① | 孤立条目（无入站引用） | ★ 低 | 扫全部卡正文，找是否引用过其 id/标题 |
-| ② | 陈旧（`status≠current`，或超阈值仍 current） | ★ 极低 | 状态 + 日期比较 |
-| ③ | 被提及却无独立卡 | ★★ 中 | **判据模糊，需先定阈值/词典** |
-| ④ | 缺交叉引用 | ★★ 中 | **"相关"判据要先定** |
-| ⑤ | 矛盾检测 | ★★★ | **需 LLM → 走 §四 的纪律方案** |
-
-**形态（硬约束）**：`lintWhiteboardPre(entries) → 问题清单`，**只读、只报告、绝不写盘**。
-契约 §6 尾注：「任何自动修正都会把白板变成状态机（违反边界）」。
-
----
-
-## 三、缺口 4⑤ 的纪律方案（用户的核心思路）
-
-### 结论：**合法**，且比"造一条 LLM 通路"便宜一个量级
-
-三条理由（已核实）：
-1. **契约只禁"自动路径"**：§6 原文「需要 LLM 的一类（**必须手动触发，不进自动路径**）」。而「每轮收尾主代理写记忆」**不是自动路径** —— 是主代理在环的有意识判断，与人工触发同性质。
-2. **工具通道现成**：`memory_note_pre(kind=plan)` 就是写白板的口子（`index.js:543` 的 `snapshotPlanTitle` 已告知模型"内容过时可用它重写"），且**过判据门 + 保护门**（`:1939`/`:2020`），丢卡会被拦。
-3. **白板本就是"模型维护区"**：契约 §5 人机分区已规定模型写哪段。
-
-### 但**必须先解决的前提**（实测）
-
-**当前 `GUIDANCE` 对白板零覆盖** —— 逐字扫过：
-```
-白板 no   PLAN no   kind=plan no   handoff no   账本 no
-```
-`GUIDANCE`（`index.js:143`，**845 字符 ≈ 423 token**）是每轮注入的记忆纪律，**详列了各 memory_* 工具，唯独没提白板**。
-⇒ **模型被明确要求"做记忆"，但从未被要求"维护白板"。这才是白板腐烂的真因 —— 不是模型偷懒，是纪律里没这条。**
-
-### 所以要做的：「扩写 `GUIDANCE`」（用户说的"固化文档"）
-
-**零新增管线** —— 它本来就每轮注入，加几十字符即可。
-
-### 三条设计要点（**必须守住**）
-
-**① 写成「条件触发」，不是「每轮都做」**
-否则每轮改白板 → 噪声 + token 浪费。
-措辞方向：「**当本轮产生与白板既有结论冲突的信息、或完成了白板上的目标时**，用 `memory_note_pre(kind=plan)` 更新」。
-
-**② 必须写明「只报告、不自动删」**
-契约 §6 尾注为硬纪律。否则模型会把"清理白板"理解成"删卡片" → 违反 §4 写入门（会被拒，但模型会反复试）。
-
-**③ 白板关闭时不得有副作用**
-`handoffEnabled=false` 时白板不读不写（`:3581`、`:3615` 已有解耦处理）。
-纪律里须说明「白板未启用时跳过」，否则模型会去找不存在的 PLAN.md。
-
-### 已纠正的数字误记
-
-用户说的「默认 10000」**不是注入预算**：
-- `SECTION_ORDER = 10000`（`index.js:137`）是**注入顺序** —— 末尾注入，让模型最后读到、遵循度高
-- 真实注入预算是 `injectBudgetChars = 8000`（本机配置实测）
-- **但用户直觉指对了位置**：那个"最后读到"的位置，正是放纪律最合适的地方
-
----
-
-## 四、明天动手顺序（5 步，已排定）
-
-| 步 | 缺口 | 难度 | 备注 |
-|---|---|---|---|
-| 1 | **缺口 2** 白板进检索 | ★ 很低 | 补两行，变量现成，收益最大 |
-| 2 | **缺口 1** 锚点解耦 | ★★ 低 | 拿掉 `boardMode` 壳，**要跑回归** |
-| 3 | **缺口 3** 索引派生 | ★ 低 | 纯函数，同源两渲染 |
-| 4 | **缺口 4①②④** lint | ★★ 中低 | 只读纯函数；③ 判据待定 |
-| 5 | **缺口 4⑤ + 白板纪律** | ★★ 低 | 扩写 `GUIDANCE`；依赖前几步（纪律要能引用索引/lint 判据） |
-
-**顺序理由**：⑤ 放最后，因为它要在纪律里引用前面做出来的东西。
-
----
-
-## 五、实施纪律（沿用本仓既有传统）
-
-1. **改前备份**：`*.bak-YYYYMMDD-<tag>`
-2. **改后 `node --check`**（`lib/index.js` 是 CRLF 大文件，注意 edit 的 `replace_all` 命中计数）
-3. **跑全量回归**：基线 **PASS 105 / FAIL 0 / TIMEOUT 0（160.5s）**（`node tools/run-smoke.mjs`）
-4. **写新套件**：每个缺口配可失败断言；**变异演示**要真红（把机制改回旧行为，测试必须失败）
-5. **无 BOM**；大文件分块写
-6. **代码留 pre 线**，未获明确同意不 commit/push
-7. **host 代码改完只告知用户自行重启**，严禁 Stop/Start-Process
-
-### ⚠️ 本轮要新增的纪律（前几轮踩出来的）
-- **引用行号前必须回读确认**（本次曾把 `:2062` 误记 `:2361`）
-- **workflow 脚本先自查变量定义与 `return`**（本次 7 个 agent 白跑）
-- **契约文档措辞像"已完成说明"，引用前必须 grep 真实调用链** —— 有调用点才算已实现
-
----
-
-## 六、本轮已完成、可安全推送的部分（纯文档）
-
-| 文件 | 内容 |
-|---|---|
-| `README.md` / `README.zh-CN.md` | 顶部按钮行换 for-the-badge 徽章；新增 5 个技术段（三层下探 / Karpathy 模块 / 唤起度 / 三级部署 / 交接工程）；含「⚠️ 实现边界」如实标注 |
-| `docs/USER-GUIDE.zh-CN.md` / `.en.md` | 顶部徽章 + 返回链接；版本号 `2.2.7+`→`3.0+`；新增 §13「3.0 底层重建」5 小节 |
-| `docs/internal/ROADMAP-20260917-WEEK.md` | 新增 §3.5 缺口审计（技术版） |
-| `docs/internal/S10-GAPS-PLAIN-20260917.md` | 缺口大白话版（本文档的上游） |
-| 本文档 | 施工交接 |
-
-**推送注意**：
-- 当前 `package.json` 版本 = **2.5.2**，pre 线 HEAD = `746a4ae`，工作区 **247 项改动**（其中 201 未跟踪）
-- 远端 `main` = `43c5492`（本轮礼节性 merge 后的位置）
-- **推送策略已由用户裁定**：远端 merge 属礼节性，最终以**本机版本强制覆盖**
-- 推送前须确认：**README 图片引用未动**（用户指示等前端重构）
-
----
-
-## 七、未决 / 待用户拍板
-
-1. **lint 第③类（被提及却无独立卡）的判据** —— 「什么算概念」「几次算反复」需用户定；判据不清会是误报源。
-2. **lint 第④类（缺交叉引用）的"相关"判据** —— 同上。
-3. **白板纪律的具体措辞** —— 待我出草案（明天第 5 步）。