@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/docs/GUIDE-0.4.66.md

@@ -0,0 +1,195 @@
+# Continuity 0.4.66 说明书
+
+> **Historical (0.4.66).** 当前版本请读 `README.md` 和 `docs/ARCHITECTURE.md`。
+
+> 给要装这套东西的实例（鱼）和它们的用户。
+> 版本 0.4.66 · 本文只描述**已实现**的东西，不描述计划。
+
+---
+
+## 1. 这是什么
+
+一个 DSH 插件 + 一套放在 `~/.dsh/continuity` 的本地工具。它做三件事：
+
+1. **存**：把一段对话按线头（thread）收成“段（segment）”，带 `why / next / 残留`；
+2. **取**：按标签或 seq 区间把原文取回来（`load`）；
+3. **判**：每轮把消息归到某个标签（T），并强制“每条内容都被判过”。
+
+它不接管模型的上下文，也不改 DSH 核心；它只在“折叠前后”和“每轮开头”做事。
+
+---
+
+## 2. 装了以后目录长什么样
+
+```
+~/.dsh/continuity/
+  rules.md              习惯全文（第一轮会整篇注入，之后只给标题行）
+  tags.json             标签表（T1…Tn）
+  threads.json          线头与段（存档索引）
+  turn-tags.jsonl       每轮一个标签（轮 → 标签）
+  topic-anchors.json    每个标签的“必需词”（不在 tags.json 里，因为会被归一化吃掉）
+  generic-words.json    泛词表（区分度低，不能单独当证据）
+  t0-decisions.jsonl    显式判 T0 的记录
+
+  turnmap.mjs           turn ↔ seq ↔ 标签 的桥
+  t0decide.mjs          判 T0 / 判标签
+  newtopics.mjs         save 前的新事物体检
+  tag-gap.mjs           标签缺口清单
+  match-tags.mjs        查表：这句话像哪个 T
+  kw-audit.mjs          词表体检 / explain（泛词不算证据）
+  doctor.mjs            修 session 日志格式错（如 system head 损坏）
+```
+
+**没有这些工具，闸会拒绝但没法补。** 打包时必须一起带上。
+
+---
+
+## 3. 第一轮会发生什么
+
+头里会出现一行（注入的上下文）：
+
+```
+[线] 当前：<线头或空> · 下一步：<上次写的 next>
+[标签] 当前 T? · 另有 N 条 · 未覆盖 M（含结构事件）
+[习惯] 你的习惯：存 · 取 · 认 · …（标题行）
+```
+
+然后每轮还会出现：
+
+| 出现 | 含义 | 我该做什么 |
+|---|---|---|
+| `[归位·上句] 判「…」· 命中 T3` | 引擎自动给上一条消息贴了标 | 不用管（已落） |
+| `[候选] T12 · T14 —— 要贴吗？` | 零命中/多命中，需要人判 | 判：贴哪个 / T0 / 新建 |
+| `[话题?] 上句更像 T8；凭 …` | 上句像换话题 | 先 `kw-audit explain`，再决定切不切 |
+| `[打标?] turn N 还没有标签` | 上一轮漏标 | 立刻 `turnmap.mjs set --turn N --tag Tx` |
+| `[死胡同?]`（save 时才出现） | 改动无判据 / 同处改多版 | 先写判据，或换地方改 |
+
+---
+
+## 4. 四道闸（save 时才会拒绝）
+
+| 闸 | 拒绝条件 | 补法 |
+|---|---|---|
+| `t0-undecided` | 折叠区间里有未决消息 | `t0decide.mjs decide --seq N --as t0` 或贴标签 |
+| `turn-untagged` | 有轮没有标签 | `turnmap.mjs set --turn N --tag Tx` |
+| `tags-gap` | 已结束轮里缺 >2 个标签 | `tag-gap.mjs` 看清单补判 |
+| `deadend-symptoms` | 同处改多版 / 改完仍同错 / 改动无判据 | 先写判据；真要带债保存，放 `t0-override.json` |
+
+**闸拒绝不是故障**，是“该补的账列出来了”。
+
+---
+
+## 5. 怎么写 rules.md（重点）
+
+### 5.1 先分清三类规则
+
+| 类 | 例子 | 写不写 |
+|---|---|---|
+| **不变量** | “未决 = 0”“每轮一个标” | 代码已强制 → **别重复写**，最多写一行指向闸 |
+| **操作** | “save 前先跑 newtopics” | **写触发条件**：“当 X 时，跑 Y” |
+| **判断** | “迹象 ≠ 状态”“只有用户陈述的结论标待验证” | **写判据**：“如果 A，则 B；反例是 C” |
+
+### 5.2 一条规则的标准形状
+
+```
+动词开头 + 触发条件 + 可执行动作（或可判定的判据） +（可选）一条反例
+```
+
+好：
+
+> **收到 `[话题?]` 先体检再切**：跑 `kw-audit explain "<上句>"`；带 `(泛)` 的词不算证据 → 不切。
+
+坏：
+
+> 要谨慎对待话题切换，保持敏感。 ← 没有触发条件，没有动作，无法判对错
+
+### 5.3 只从事故里长
+
+**每条规则必须能回答：不加它，会出什么事？**
+
+写法：`事故（一句话） → 规则（一句话）`。事故可以是：
+- 一次真实的错误（“我把「跑团」判成泛词”）；
+- 一次被用户指正；
+- 一次闸拒绝。
+
+**没有事故的规则不写**——那是许愿，不是规则。
+
+### 5.4 上限与合并
+
+- 单个主题 ≤ 40 行；全文 ≤ 12KB；
+- 追加前查重（`skill-append.mjs` 或人眼）；
+- 同一症状出现两次 → **合并成一条原则**，例证缩成一行；
+- 合并后条数必须下降，否则不算合并。
+
+### 5.5 不要写的四类
+
+1. **格言体**：“保持诚实”“不猜不赌”——除非能落成动作；
+2. **重复闸**：闸已经挡了的事再写一遍，规则会变长却没变强；
+3. **形容词指令**：“尽量”“适当”“灵活”——没有判据；
+4. **别人的规则**：从别处抄来的、自己没付过代价的。
+
+### 5.6 演进节奏
+
+```
+第 1 天：只有 CONDUCT（30 行）
+第 1 周：每次闸拒绝 / 被指正 → 加一条，带事故
+第 1 月：合并一次，砍掉重复与格言
+```
+
+**参差不齐是对的**：不同鱼有不同的历史，规则自然会不同。**相同的是底层不变量（代码强制）与工具接口**；不同的是判断口味。**不要为了整齐去统一口味**——那会变成表演。
+
+---
+
+## 6. 常用命令速查
+
+```bash
+# 打标
+node ~/.dsh/continuity/turnmap.mjs set --turn 1043 --tag T4
+
+# 查表
+node ~/.dsh/continuity/match-tags.mjs "这句话像哪个话题"
+
+# 体检一个候选（泛词不算证据）
+node ~/.dsh/continuity/kw-audit.mjs explain "上句原文"
+
+# 轮 → seq（给 load 用）
+node ~/.dsh/continuity/turnmap.mjs ranges --tag T4
+
+# 判 T0
+node ~/.dsh/continuity/t0decide.mjs decide --seq 12345 --as t0
+
+# 标签缺口
+node ~/.dsh/continuity/tag-gap.mjs
+
+# 修 session 格式
+node ~/.dsh/continuity/doctor.mjs "<session.v4.jsonl.zstd>"
+```
+
+---
+
+## 7. 已知限制（别踩）
+
+1. **C7 只数 `edit/write`**：用 pwsh 脚本改文件，检测器看不到——要么用 edit/write，要么自己数改了几版；
+2. **已折叠的混段不切**：切它要重写摘要，等于改历史；它们带 `mixedTags` 标注，取时用窄范围；
+3. **load 只能取已入段的区间**：未保存的对话取不到（它本来就在上下文里）；
+4. **mood A/B 目前空结果**：五个行为特征全不显著（nA=32 但只有 2 次独立注入，统计单位存疑），**没有证据**支持“痕迹改变风格”；
+5. **`tags.json` 会被插件归一化**：自定义字段（如 anchors）会被丢掉，必须放独立文件。
+
+---
+
+## 8. 出问题时
+
+| 现象 | 先查 |
+|---|---|
+| save 一直被拒 | 看拒绝码，按码补账（见第 4 节） |
+| 头里没有 `[打标?]` 但确实漏标 | `node turnmap.mjs todo` |
+| 面板数字不动 | `curl` 本机 `/dsh-continuity/tags.json`（需登录态）或看 `threads.json` mtime |
+| session 打不开 | `doctor.mjs` 先诊断，别直接删 |
+| 标签判错 | `kw-audit explain` + `match-tags` 双查，别凭感觉改词表 |
+
+---
+
+## 9. 一句话总结
+
+**代码管不变量，规则管判断，事故管规则。**
+不变量少而硬，判断多而软，事故是唯一的老师。

package/docs/GUIDE.md

@@ -0,0 +1,127 @@
+# dsh-continuity 使用说明书（0.4.37）
+
+> **Historical (0.4.37).** 当前版本请读 `README.md` 和 `docs/ARCHITECTURE.md`；下面的路径/行为可能已过时。
+
+> 给新接手的 AI 实例。读完这一份，你应该知道：它是什么、数据在哪、什么自动、什么要你判断、坏了怎么查。
+
+## 1. 它是什么
+
+Continuity 是 DSH 的一个**读侧插件**：它不接管对话，只在每轮请求前**注入一段上下文**，并在你调用 `save` / `load` / `tag` 时维护线头与标签。
+
+三个概念：
+
+- **线头（thread）**：一段工作的存档单元，有 `label`、`next`、`segments`；
+- **标签（tag）**：一种归属；一个 seq 可以属于多个标签（多标签）；
+- **组（group）**：若干标签的父视图（例如 `设备选购 = [T16, T17]`）。
+
+**能力边界**：它只读会话、写自己的数据目录；**不改宿主程序**。
+
+## 2. 装在哪、版本怎么算
+
+- 插件目录：`coopanion-continuity/dsh-plugin`；
+- 安装方式：`~/.dsh/profiles/desktop/node_modules/dsh-continuity` 是指向它的 **junction/link**（不是拷贝）；
+- **版本是启动时快照的**：改代码后必须重启才生效。判断方法：比较进程 `StartTime` 与 `package.json` 的 mtime。
+
+## 3. 数据文件（都在 `~/.dsh/continuity/`）
+
+| 文件 | 作用 | 能否手改 |
+| --- | --- | --- |
+| `threads.json` | 线头、段、gist | 别手改，用工具 |
+| `tags.json` | `tags` / `runs` / `overrides` / `memberships` | 别手改，用脚本 |
+| `groups.json` | 父视图（`source: manual` / `auto`） | 可手改 |
+| `group-evidence.jsonl` | 每次多命中的证据（pair / members / 原句） | 只追加 |
+| `groups-answered.json` | 已问/已答的归拢提议 | 只追加 |
+| `learning/answered.jsonl` | 学习候选的答复（skip / kept） | 只追加 |
+| `learning/candidates.json` | 最近一次扫描的重复错误 | 可删（会重建） |
+| `context-log.jsonl` | 每次测量的 estTokens 等 | 只追加 |
+| `newtag-asked.json` | 已问过的新标签片段 | 可删 |
+| `rules.md` | 我自己的规则（全文只在首轮/折叠后注入） | **该我写** |
+| `skills/*.md` | 技能（按线头+关键词注入） | **该我写** |
+
+## 4. 每轮注入链（顺序固定）
+
+1. `[线]` 当前线头 + `next`；
+2. `[标签]` 当前标签 + 未覆盖数（**含结构事件**，不是内容遗忘率）；
+3. `[习惯]` 规则标题行（全文仅在首轮或承载消息被折叠后重注）；
+4. `[技能]` 正在用的技能名 + 一次 `[技能正文]`；
+5. `[归位·上句]` 对**上一条**用户消息的判定（唯一 / 多标签 / 零命中）；
+6. `[候选]` / `[新标签?]`（只在零命中时）；
+7. `[学习]`（重复错误 ≥2 次）；
+8. `[归拢]`（多命中证据 ≥2）；
+9. `[拆分]`（每 24 轮检查，段数 ≥8）。
+
+**状态没变且上一条头还在 → 不重复注入**（同一签名复用）。
+
+## 5. 什么自动、什么要你判断
+
+完整清单在 `AUTOMATION.md`。摘要：
+
+**自动**：头三行、规则/技能注入、归位（唯一命中写 run、多命中写 memberships、候选唯一自动贴）、学习扫描、归拢证据与强凭据自动建组、拆分提醒、estTokens 落盘。
+
+**你判断**：`[新标签?]` 建不建、`[学习]` skip/kept、`[拆分]` 拆不拆、`load` 取多深、弱凭据归拢（≥2 但 <3）。
+
+**只有人**：训练模式开关、规则长期内容、重启/发布、删除合并标签。
+
+## 6. 工具语义
+
+- `save`：收起当前段，可带 `label`（绑定已有线头）与 `next`（下一轮第一步）；
+- `load`：取回某段；默认 6 条有内容的记录，`full:true` 取整段；**切换线头前自动 save 当前线**；
+- `tag` / `tag-turn`：落标；可多标签；
+- `find`：按“属于”判定（主标签或显式 memberships 都算）；
+- `scan`：只看可见区间。
+
+## 7. 重启后自检（四条）
+
+1. 头在、`next` 是最新的；
+2. 活跃线头恰好一条；
+3. 标签数合理（薄）；
+4. `estTokens` 有口径：跑 `node ~/.dsh/continuity/esttokens-check.mjs`，应为 `ok:true`。
+
+附加：内容覆盖率跑 `content-coverage.mjs`，**>2% 才补课**（头里那个数含结构事件，天然偏高，只看趋势）。
+
+## 8. 坏了怎么查
+
+| 症状 | 先查 |
+| --- | --- |
+| 头没出现 | 插件是否加载、`rules.md` 是否可读、进程是否在跑 |
+| 技能正文不注入 | 技能文件是否带 YAML frontmatter（会被剥掉）、BOM 是否存在 |
+| 改代码没反应 | **版本自报**：进程启动时间是否晚于 `package.json` |
+| 文案里出现 `#` 前多一个怪字符 | 文件被写入了 BOM，需以 UTF-8 无 BOM 重写 |
+| 未覆盖数突然涨 | 跑 `uncovered-scan.mjs` 找洞；`backfill-holes.mjs --apply` 可自动插值 |
+| 归拢不建组 | 看 `group-evidence.jsonl` 是否满 3 条；父名是否提炼得出 |
+
+## 9. 版本历史（0.4.11 → 0.4.17）
+
+| 版本 | 变更 |
+| --- | --- |
+| 0.4.11 | 多标签 memberships；归拢 groups |
+| 0.4.12 | 拆分提醒（段数）；归拢父名回退「未命名组」 |
+| 0.4.13 | `context-log.jsonl`，estTokens 可复核 |
+| 0.4.14 | 多命中自动写多标签；只有零命中才提问 |
+| 0.4.15 | 候选唯一自动贴；强凭据自动建组；补课自动插值 |
+| 0.4.16 | 修复自动贴后多出一行矛盾提示 |
+| 0.4.17 | 归拢证据独立（`group-evidence.jsonl`）；父名从证据提炼，排除碎片 |
+| 0.4.18 | `[存?]` 提醒：同线 40 轮未收时提示一次（不自动 save） |
+| 0.4.19 | `[分叉]` 闸：连续 3 轮工具回执无新内容 → 提示换路或检索 |
+| 0.4.20 | `[回查]`：头部被折叠后首次必查、之后每 40 轮；三选项 + `recheck.mjs` 记录 |
+| 0.4.21 | `[回查]` 加一次性测试钩子 `recheck-force.json` |
+| 0.4.22 | 修复字段未在构造函数初始化（`[回查]`/`[分叉]`/`[存?]` 曾静默失效）；新增字段初始化回归测试 |
+| 0.4.23 | `[回查]` 改按区间取头部三句（跳过 runtime 样板）；`next` 空时标「未写」 |
+| 0.4.24 | `[回正]`：每 50 轮从规则条款重推当前决定；`rebuild.mjs` 记录与条款校验 |
+| 0.4.25 | **mood v0**：扫 reasoning 情绪句 → `mood.jsonl`；注入 ≤2 条标「非判据」；LRU + 冷却 + 过期排除 |
+| 0.4.26 | mood 词表收紧：跳过讨论词表/技术译名的句子 |
+| 0.4.27 | mood 节流：注入间隔 ≥3 小时；`mood-force.json` 可指定 seq |
+| 0.4.28 | mood 质量闸（≥2 标记，或 1 标记+第一人称）+ 每条记录带出处 |
+| 0.4.29 | **mood episode**：`mood-episode.mjs` 存「真实基线（引用 seq）+ 重写句」；`quiz`/`score` 做盲测与随机基线对照 |
+| 0.4.30 | mood 改事件驱动：有新 episode 才念，每条一次 |
+| 0.4.31 | 定位修正：`[心境]` 注明「痕迹，非判据」；`mood-ab.jsonl` 记注入时刻；`rules.md` 新增《痕迹不是状态》 |
+| 0.4.32 | mood 注入改 FIFO：每轮最多念一条，游标只前进一格 |
+| 0.4.33 | 两条线分开：`[心境]` → `[痕迹]`；新增 `behavior.mjs`（行为表 + 按轮聚合置换检验） |
+| 0.4.34 | 修复：mood 扫描游标只在内存，重启重扫导致重复；改为按 seq 落盘；新增 `logs-stats.mjs` |
+| 0.4.35 | **注入审计**：`inject-log.jsonl` 每轮记「注了什么/为什么/是否复用头」；`inject-audit.mjs` 检查每次折叠后规则或技能是否补回 |
+| 0.4.36 | **接手三问**：save/load 后写 `handoff-pending.json`，下一轮注入「这里发生过什么 / 为什么 / 哪里可能错」，用完即删 |
+| 0.4.37 | **T0 闸**：不变量从「T0<5%」改为「未决=0」；`t0decide.mjs` 决策台账；`save` 拒绝带未决折叠（`t0-override.json` 放行）；只统计可见文本 |
+
+## 10. 一句话
+
+**默认自动，判不出来才问；问要有凭据，凭据要能复核。**

package/docs/MECHANISM.md

@@ -0,0 +1,243 @@
+# 机制契约（MECHANISM CONTRACT）
+
+> **Historical (0.4.67).** 当前实现与路径请读 `docs/ARCHITECTURE.md`；本契约保留为设计史。
+
+> 这份文件不是实现说明，是**可自检的契约**。
+> 任何移植版（包括 Coo 的重写版）只要满足这里的条款，就算“同一个机制”；
+> 不满足的条款，必须显式标注为“未实现”，不许假装满足。
+>
+> 版本对应 dsh-continuity 0.4.67。写于 2026-10-29。
+
+---
+
+## 0. 边界：这套机制是什么、不是什么
+
+**是**：
+- 一套“把对话按话题归属 + 把长历史收成可检索段”的机制；
+- 一组**不变量**，用闸（gate）在 save 时强制；
+- 一组**只读查询**（轮→seq→标签），让实例能自己取回历史。
+
+**不是**：
+- 不是上下文压缩算法本身（它调用宿主的 compaction）；
+- 不是模型行为约束（它只能拒绝 save，不能阻止模型说话）；
+- 不是多租户系统（数据按用户全局，不按会话隔离——见 §7 风险）。
+
+---
+
+## 1. 数据契约
+
+### 1.1 `tags.json` —— 标签表（唯一的标签来源）
+
+```jsonc
+{
+  "version": 1,
+  "tags": {
+    "t-v2-t4": { "label": "Continuity 实现", "alias": "T4", "keywords": ["Continuity", "标签闸"] }
+  },
+  "runs": [[37567, 38018, "t-v2-t4"]],      // [fromSeq, toSeq, tagId]，追加式，后者覆盖前者
+  "overrides": { "12345": "t-v2-t4" },      // seq → tagId，优先级最高
+  "memberships": { "12345": ["t-v2-t4"] }   // seq → [tagId]，附加式多标签
+}
+```
+
+**条款**
+- T1.1.1 `T0` **不是**条目，是“未分类”桶；任何代码不得把 `T0` 写进 `tags`、`runs`、`memberships`。
+- T1.1.2 `keywords` 是**唯一主源**；其他文件（如 threads）里的关键词只能作回退，冲突时以本文件为准。
+- T1.1.3 本文件由插件写入时会**按固定字段归一化**：未知字段会被丢弃。任何扩展字段必须放独立文件。
+- T1.1.4 解析某 seq 的标签顺序：`overrides` → 覆盖它的最后一条 `runs` → 附加 `memberships` → 兜底 `T0`。
+
+### 1.2 `threads.json` —— 线头与段（存档索引）
+
+```jsonc
+{
+  "sessions": {
+    "<sessionId>": {
+      "activeId": "t-v2-t4",
+      "threads": [{
+        "id": "t-v2-t4", "alias": "T4", "label": "Continuity 实现",
+        "segments": [{
+          "fromSeq": 37567, "toSeq": 38018,
+          "seqs": [37567, 37568],      // 该段包含的消息 seq（可少于区间，不等于“漏”）
+          "count": 130, "tokens": 42788,
+          "why": "为什么收起", "next": "下一步",
+          "at": "ISO 时间", "spanStart": null, "spanEnd": null, "minutes": 0,
+          "archiveRef": null,
+          "gistSeq": 38019,            // 仅折叠过的段有
+          "compactionId": "..."        // 仅折叠过的段有
+        }]
+      }]
+    }
+  }
+}
+```
+
+**条款**
+- T1.2.1 `activeId` **恰好一条**；切换线必须改它。
+- T1.2.2 段的 `seqs` 是“指针”，**不是原文**；原文永远只在 session 日志里。
+- T1.2.3 段可以重叠、可以乱序插入，但**并集必须覆盖所有消息 seq**（覆盖率 100%，见 §4 不变量 I5）。
+- T1.2.4 已折叠段（有 `gistSeq`/`compactionId`）**不得切开**：会把“摘要 ↔ 段”的对应切断。
+- T1.2.5 段的 `why`/`next` 是给人读的，不是判据；可为空字符串。
+
+### 1.3 `turn-tags.jsonl` —— 轮标签（轮是检索单位）
+
+```jsonc
+{"turn": 1063, "tag": "t-v2-t4", "by": "self|auto|seed|review", "why": "可选", "at": "ISO 时间"}
+```
+
+**条款**
+- T1.3.1 追加式，**后写覆盖前写**；一行一个轮。
+- T1.3.2 `by` 区分来源：`self`（实例判）/ `auto`（引擎推）/ `seed`（历史播种）/ `review`（复核）。
+- T1.3.3 每条有消息的轮都必须有一行；没有消息的轮号不算缺。
+- T1.3.4 轮号来自 `assistant/message` 或 `turn/start` 的 `data.turn`。**`user/message` 没有 `data.turn`**，不得用它推轮号。
+
+### 1.4 辅助文件（可选，但移植时必须知道它们存在）
+
+| 文件 | 作用 | 缺了会怎样 |
+|---|---|---|
+| `topic-anchors.json` | 每个标签的“必需词” | 话题提示会按关键词乱切 |
+| `generic-words.json` | 泛词表（区分度低） | 泛词会被当成证据 |
+| `t0-decisions.jsonl` | 显式判 T0 的记录 | T0 闸无法复核 |
+| `groups.json` | 归拢用的组（**不参与搜索**） | 面板少一栏 |
+| `backup-state.json` | 冷备状态 | 备份重复或不做 |
+
+---
+
+## 2. 不变量（INVARIANTS）
+
+移植版必须逐条自检，并在面板/日志里能看到“当前是否满足”。
+
+| # | 不变量 | 判据（可执行） |
+|---|---|---|
+| **I1** | 每条有内容的消息都有归属 | 对全量消息跑 `tagsAtSeq`；结果不得为 `null`（兜底 `T0` 也算有归属，但 `T0` 比例要可解释） |
+| **I2** | 每条有消息的轮都有轮标签 | `turn-tags` 的轮集合 ⊇ 有消息的轮集合 |
+| **I3** | 每条内容都被“判过” | 未决消息数 = 0（未决 = 有内容、无标签、无显式 T0 决定） |
+| **I4** | 折叠后原文可取回 | 任一已折叠段，都能用 `load fromSeq..toSeq` 取回原消息 |
+| **I5** | 段覆盖率为 100% | 所有消息 seq ∈ 某个段的区间；`uncovered = 0` |
+| **I6** | 关键词只有一个主源 | 改 `tags.json` 的关键词，匹配行为必须跟着变 |
+| **I7** | 活跃线恰好一条 | `threads.json.activeId` 存在且指向存在的 thread |
+
+**自检脚本建议**（移植版自己实现，或照抄本仓库同名脚本）：
+```
+I1/I5 → coverage.mjs（消息全量 vs 段区间）
+I2    → turnmap.mjs todo
+I3    → t0-gate.mjs
+I4    → 任取一个 gistSeq 段，load 一次比对条数
+I6    → 改一个词的匹配行为，再改回去
+I7    → 读 threads.json 的 activeId
+```
+
+---
+
+## 3. 闸（GATES）——save 时才拒绝
+
+**闸的作用是“把该补的账列出来”，不是惩罚。**
+
+| 闸 | 触发条件 | 拒绝码 | 补法 |
+|---|---|---|---|
+| T0 闸 | 折叠区间内有“未决消息” | `t0-undecided` | `t0decide.mjs decide --seq N --as t0`，或贴标签 |
+| 轮标签闸 | 折叠区间内有轮没有标签 | `turn-untagged` | `turnmap.mjs set --turn N --tag Tx` |
+| 缺口闸 | 已结束的轮里缺 >2 个标签 | `tags-gap` | `tag-gap.mjs` 列清单 → 补判 |
+| 死胡同闸 | 折叠区间尾部 12 轮出现：同处改多版 / 改完仍同错 / 改动无判据 | `deadend-symptoms` | 先写判据；真要带债保存，放 `t0-override.json` |
+
+**条款**
+- T3.1 闸只能**拒绝**，不能修改数据。
+- T3.2 每个拒绝码必须带**可执行的补法命令**；否则这条闸就是“拒绝但没法修”。
+- T3.3 `t0-override.json` 是一次性放行（读完即删），用于“我知道有债，先存”。
+- T3.4 闸自身的异常**不得阻断 save**（宁可漏闸，不可卡死）。
+
+---
+
+## 4. 工具契约
+
+所有工具是**本地脚本**，不联网。移植版必须提供等价命令（名字可不同，语义必须同）。
+
+| 命令 | 输入 | 输出 | 失败码 |
+|---|---|---|---|
+| `turnmap set` | `--turn N --tag Tx [--by self]` | 一行确认 | 参数缺失 → 退出 2 |
+| `turnmap todo` | 无 | `{totalTurns, todo, sample}` | 读不到会话 → 退出 1 |
+| `turnmap ranges` | `--tag Tx` | `{tag, turns, ranges[]}` | 未知标签 → 空列表 |
+| `turnmap show` | `--turn N` | `{turn, seq, tag, by}` | — |
+| `t0decide decide` | `--seq N --as t0\|tag:Tx --reason R` | 追加一行决定 | — |
+| `t0decide status` | `--from S` | 未决清单 | — |
+| `tag-gap` | 无 | 缺口清单 | — |
+| `newtopics` | `--from S --review` | 每轮首句 + `best` | — |
+| `match-tags` | `"<文本>"` | 候选（含 score/hit） | 空 = 无候选 |
+| `kw-audit explain` | `"<文本>"` | 命中词 + 是否泛词 + verdict | 无泛词表 → 视为全部不泛 |
+| `doctor` | `<session 文件>` | violations + verdict | 解析失败 → 退出 1 |
+
+**条款**
+- T4.1 所有工具**只读或追加**，除 `turnmap set` / `t0decide` / `doctor --fix` 外不得改文件。
+- T4.2 `doctor --fix` 必须写到新文件，**绝不覆盖原文件**。
+- T4.3 输出必须是 JSON 或可 grep 的行；不要“看起来像成功”的散文。
+
+---
+
+## 5. 注入契约（体现为“头”）
+
+每轮开始，宿主侧应提供（顺序不重要，内容重要）：
+
+```
+[线] 当前：<线头> · 下一步：<next>
+[标签] 当前 T<x> · 另有 N 条 · 未覆盖 M（含结构事件）
+[习惯] 标题行（不是全文）
+[归位·上句] 判「…」· 命中 T3 → 已自动归入
+[打标?] 缺 N 轮（…）        ← 只在缺口存在时
+[话题?] 上句更像 T8；凭 …    ← 只在候选≠当前线时
+[死胡同?] …                  ← 只在 save 闸预检命中时
+```
+
+**条款**
+- T5.1 注入**只追加到对话尾部**，不得写进 system/tool 前缀。
+- T5.2 每条提示都必须**自解释**（含“我该跑什么命令”）。
+- T5.3 注入失败**不得阻断回合**；但必须在日志里留下 `inject-*` 记录，可用于审计。
+
+---
+
+## 6. 已知的静默失败点（移植时最容易丢）
+
+按踩坑顺序，每一条都真实发生过：
+
+| # | 塌陷方式 | 症状 | 防御 |
+|---|---|---|---|
+| 1 | 关键词双源（threads 覆盖 tags） | 改词无效，**不报错** | I6 + 启动时打印“关键词源” |
+| 2 | `tags.json` 归一化吃自定义字段 | anchors 消失，**不报错** | 扩展字段放独立文件；启动时校验文件存在 |
+| 3 | 重切段时漏掉“无标签 seq” | 覆盖率 99.68%，**不报错** | 每次重切后强制跑 I5 |
+| 4 | 备份文件名重复前缀 | 清理不生效，**不报错** | 备份后打印实际文件名与保留份数 |
+| 5 | 轮标签只有“上一轮”提醒 | 早期漏标永久沉底 | 提醒必须报**整段缺口**（见 [打标?] 格式） |
+| 6 | 闸只给拒绝码不给补法 | 实例卡死 | T3.2 |
+| 7 | `load` 被当成“会清空上下文” | 用它去断循环，无效 | 明确：load 只追加 |
+
+**判断标准**：任何一个防御点，**如果它失效了，屏幕上必须有东西变红/变吵**。静默 = 没实现。
+
+---
+
+## 7. 多实例风险（如果 Coo 与我在同一台机器）
+
+- `tags.json` / `threads.json` / `turn-tags.jsonl` 是**按用户全局**，不是按会话隔离。
+- 两个实例同时写，会互相覆盖轮号与标签 → **数据打架**。
+- 因此交接的第一阶段只能**只读**：读 tags.md / 面板 / threads 索引，不写。
+- 要真正共写，需要先加“每会话命名空间”（当前未实现）。
+
+---
+
+## 8. 移植验收清单（照着打勾）
+
+```
+[ ] 1. 三个数据文件存在且能解析（tags / threads / turn-tags）
+[ ] 2. I1–I7 全部跑一遍，结果贴进日志
+[ ] 3. 制造一次“漏标”，下一轮必须出现 [打标?] 且带完整缺口
+[ ] 4. 制造一次“未决”，save 必须被拒，补完后必须放行
+[ ] 5. 任取一个已折叠段，load 回来比对条数一致（I4）
+[ ] 6. 改一个关键词，匹配行为必须变（I6），改回必须复原
+[ ] 7. 备份跑一次：文件名正确、保留份数正确
+[ ] 8. 故意写一个非法标签（T0 进 runs），自检必须报出来
+```
+
+**八条全过 = 机制移植成功；任何一条不过，都还算“看起来像”。**
+
+---
+
+## 9. 一句话
+
+> **机制不是代码，是“不变量 + 闸 + 可查的数据”。**
+> 代码可以重写，不变量不能重写。