dsh-vibe-math 2.3.12 → 2.3.14

package/{RELEASE-NOTES-2.3.9.md → docs/release-notes/RELEASE-NOTES-2.3.9.md}

@@ -1,70 +1,70 @@
-# dsh-vibe-math 2.3.9 — v4 架构图重绘为 SVG（零依赖生成器 + README 展示）
-
-> 上一版：2.3.8。本版把 v4 的架构图从"matplotlib 生成的位图"换成**零依赖 Node 生成的 SVG**，
-> 与 v5 同一套版式语言，并把它纳入随包发布（README 里的图在 GitHub 与 npm 上都能正常显示）。
-> 无代码行为变更，四套预设字节未变。
-
----
-
-## 1. 为什么换
-
-| | 旧（`框架图-v4.png` + `generate_framework_diagram_v4.py`） | 新（`框架图-v4.svg` + `generate_framework_diagram_v4.mjs`） |
-|---|---|---|
-| 生成方式 | Python + matplotlib | **纯 Node，零依赖**（本仓库运行时自带 Node） |
-| 产物 | 位图，缩放糊、无法 diff | 纯文本 SVG，任意缩放、可评审、diff 友好 |
-| 信息量 | 5 个方框 + 若干小字 | 分带：定论门槛 / 常驻层 / 框架六面 / 数据面 / 哲学红线 + 图例 |
-| 版式校验 | 无（只能靠眼睛） | 生成时**估算文字宽度**，任何一行溢出容器即 WARN + 退出码 1 |
-| 随包发布 | 否（npm 上 README 图裂） | **是**（`files` 收录，GitHub 与 npm 均可显示） |
-
-旧文件已删除（需要时可从 git 历史取）；`README.md` 的图源链接与说明同步更新，
-`docs/generate_framework_diagram_v5.mjs` 头部注释里的"v2/v3/v4 用 matplotlib"也改成"v2/v3"。
-
-## 2. 新图覆盖的内容（全部与实现逐项核对过）
-
-- **定论门槛**：全体一致为真（全 1）/ 一致为假（全 0）→ 写入 `Verified/`；
-  **没有** forced / flat / 近共识收口；分歧 → 公开辩论重评；仍未全票 → 留库 + 平均概率 + 辩论录。
-- **常驻层**：`continuable` 持久会话、独立上下文、自主方向、只写自己的库 / 跨读他人库（只读）、
-  唤醒 = `subagents.sendMessage`、一轮 = 一次完整思考；起始 brainstorm 产出各自方向；全票"已解决"才停。
-- **框架六面**（逐条对齐代码/规格）：
-  - 消息总线·邮件箱：`vibe_v4_message(to|all)` → 入目标邮箱 → 空闲则唤醒；常驻之间不直接互调；
-  - 会议 / 辩论：`vibe_v4_meeting(agenda)` → 全体发言 → `Shared/meetings/<id>.md` → 广播结论；
-    看门狗防死锁；与验证**互斥**（排队，不抢占）；
-  - 任务板（只搬运）：提议/认领写在回执里 → `Shared/taskboard.md`；框架不决定谁做什么；
-  - 共识验证（全票）：回执字段 `propose_verify` → FIFO 排队 → 独立初评（互不可见）→ 公开辩论重评
-    （最多 `verdictMaxRounds` 轮，默认 3）；
-  - 上下文 / compact：`contextPct ≥ compactThreshold`（默认 66）触发 DSH `/compact`，
-    `compactAfterRounds` 默认 8，压缩后重申核心规则；
-  - 活性 / 并发 / 恢复：`activityTimeoutMs` 心跳、`maxParallel` 并发闸、停滞 `stallAutoMeetingMs`
-    （默认 6 min）自动开会、`resume` 用 `residents.json` + `progress.md` 重种化。
-- **回执字段**（**按代码里真正的解析字段列**，不是照抄记忆）：
-  `summary / solved / input / vote / propose_verify / propose_task / claim_task / task_done / voteSolved / formal / contextPct`。
-  （核对时发现我第一版图里写了 `reject_assign` 与 `vote_solved` —— 前者是 **v5** 的字段、后者是拼错的
-  驼峰名，v4 实际是 `voteSolved`；已改正。）
-- **数据面**（真实路径核对过）：
-  `Progress/<r-id>/progress.md`、`Propos/<r-id>/<p-id>.md`、`Methods/<r-id>/<m-id>.md`、
-  `Subproblems/<r-id>/<s-id>.md`（每条记录必填 价值程度 / 动机用途计划 / 自身概率估计）；
-  `Shared/meetings|debates`、`Shared/taskboard.md`、`Shared/meetings/brainstorm.md`、
-  `Verified/命题|问题/<id>.md`、`Problems/<id>.md`；
-  `State/residents.json`、`mailboxes.json`、`taskboard.json`、`decisions.json`、`session.json`、
-  `settings.json`、`formal.json`；`fileOwner` 写锁 / `projectLock` / `processEpoch` / `abort → resume`。
-- **哲学红线**：框架绝不指派 / 定论必须全体一致 / 只有 `Verified/` 绝对可信 / 常驻不直接互调 /
-  人工干预不改变自组织。
-
-## 3. 验收
-
-| 项 | 结果 |
-|---|---|
-| 生成器 | `node docs/generate_framework_diagram_v4.mjs` → `示例图/框架图-v4.svg`（23501 字节），**0 条溢出告警** |
-| 渲染校验 | 无头 Chrome 截图 1760×1300 逐带人工核对（无重叠、无截断；左侧控制通道不穿过常驻） |
-| 全量并行回归 | 23/23 |
-| 静态守卫 | invariants 157/0（self-probe 5/5）、traceability 94/0、v5-integrity clean、persona-surface 197/0 |
-| closing verification | 18/18（含"包内所有声明文件存在"） |
-| 发布产物自证 | registry 取回 tarball 比对 sha1 + 包内跑随包套件（见发布记录） |
-
-## 4. 升级
-
-```
-npm i dsh-vibe-math@latest
-```
-
-无迁移。README 里的 v4 图现在读 `示例图/框架图-v4.svg`。
+# dsh-vibe-math 2.3.9 — v4 架构图重绘为 SVG（零依赖生成器 + README 展示）
+
+> 上一版：2.3.8。本版把 v4 的架构图从"matplotlib 生成的位图"换成**零依赖 Node 生成的 SVG**，
+> 与 v5 同一套版式语言，并把它纳入随包发布（README 里的图在 GitHub 与 npm 上都能正常显示）。
+> 无代码行为变更，四套预设字节未变。
+
+---
+
+## 1. 为什么换
+
+| | 旧（`框架图-v4.png` + `generate_framework_diagram_v4.py`） | 新（`框架图-v4.svg` + `generate_framework_diagram_v4.mjs`） |
+|---|---|---|
+| 生成方式 | Python + matplotlib | **纯 Node，零依赖**（本仓库运行时自带 Node） |
+| 产物 | 位图，缩放糊、无法 diff | 纯文本 SVG，任意缩放、可评审、diff 友好 |
+| 信息量 | 5 个方框 + 若干小字 | 分带：定论门槛 / 常驻层 / 框架六面 / 数据面 / 哲学红线 + 图例 |
+| 版式校验 | 无（只能靠眼睛） | 生成时**估算文字宽度**，任何一行溢出容器即 WARN + 退出码 1 |
+| 随包发布 | 否（npm 上 README 图裂） | **是**（`files` 收录，GitHub 与 npm 均可显示） |
+
+旧文件已删除（需要时可从 git 历史取）；`README.md` 的图源链接与说明同步更新，
+`docs/generate_framework_diagram_v5.mjs` 头部注释里的"v2/v3/v4 用 matplotlib"也改成"v2/v3"。
+
+## 2. 新图覆盖的内容（全部与实现逐项核对过）
+
+- **定论门槛**：全体一致为真（全 1）/ 一致为假（全 0）→ 写入 `Verified/`；
+  **没有** forced / flat / 近共识收口；分歧 → 公开辩论重评；仍未全票 → 留库 + 平均概率 + 辩论录。
+- **常驻层**：`continuable` 持久会话、独立上下文、自主方向、只写自己的库 / 跨读他人库（只读）、
+  唤醒 = `subagents.sendMessage`、一轮 = 一次完整思考；起始 brainstorm 产出各自方向；全票"已解决"才停。
+- **框架六面**（逐条对齐代码/规格）：
+  - 消息总线·邮件箱：`vibe_v4_message(to|all)` → 入目标邮箱 → 空闲则唤醒；常驻之间不直接互调；
+  - 会议 / 辩论：`vibe_v4_meeting(agenda)` → 全体发言 → `Shared/meetings/<id>.md` → 广播结论；
+    看门狗防死锁；与验证**互斥**（排队，不抢占）；
+  - 任务板（只搬运）：提议/认领写在回执里 → `Shared/taskboard.md`；框架不决定谁做什么；
+  - 共识验证（全票）：回执字段 `propose_verify` → FIFO 排队 → 独立初评（互不可见）→ 公开辩论重评
+    （最多 `verdictMaxRounds` 轮，默认 3）；
+  - 上下文 / compact：`contextPct ≥ compactThreshold`（默认 66）触发 DSH `/compact`，
+    `compactAfterRounds` 默认 8，压缩后重申核心规则；
+  - 活性 / 并发 / 恢复：`activityTimeoutMs` 心跳、`maxParallel` 并发闸、停滞 `stallAutoMeetingMs`
+    （默认 6 min）自动开会、`resume` 用 `residents.json` + `progress.md` 重种化。
+- **回执字段**（**按代码里真正的解析字段列**，不是照抄记忆）：
+  `summary / solved / input / vote / propose_verify / propose_task / claim_task / task_done / voteSolved / formal / contextPct`。
+  （核对时发现我第一版图里写了 `reject_assign` 与 `vote_solved` —— 前者是 **v5** 的字段、后者是拼错的
+  驼峰名，v4 实际是 `voteSolved`；已改正。）
+- **数据面**（真实路径核对过）：
+  `Progress/<r-id>/progress.md`、`Propos/<r-id>/<p-id>.md`、`Methods/<r-id>/<m-id>.md`、
+  `Subproblems/<r-id>/<s-id>.md`（每条记录必填 价值程度 / 动机用途计划 / 自身概率估计）；
+  `Shared/meetings|debates`、`Shared/taskboard.md`、`Shared/meetings/brainstorm.md`、
+  `Verified/命题|问题/<id>.md`、`Problems/<id>.md`；
+  `State/residents.json`、`mailboxes.json`、`taskboard.json`、`decisions.json`、`session.json`、
+  `settings.json`、`formal.json`；`fileOwner` 写锁 / `projectLock` / `processEpoch` / `abort → resume`。
+- **哲学红线**：框架绝不指派 / 定论必须全体一致 / 只有 `Verified/` 绝对可信 / 常驻不直接互调 /
+  人工干预不改变自组织。
+
+## 3. 验收
+
+| 项 | 结果 |
+|---|---|
+| 生成器 | `node docs/generate_framework_diagram_v4.mjs` → `示例图/框架图-v4.svg`（23501 字节），**0 条溢出告警** |
+| 渲染校验 | 无头 Chrome 截图 1760×1300 逐带人工核对（无重叠、无截断；左侧控制通道不穿过常驻） |
+| 全量并行回归 | 23/23 |
+| 静态守卫 | invariants 157/0（self-probe 5/5）、traceability 94/0、v5-integrity clean、persona-surface 197/0 |
+| closing verification | 18/18（含"包内所有声明文件存在"） |
+| 发布产物自证 | registry 取回 tarball 比对 sha1 + 包内跑随包套件（见发布记录） |
+
+## 4. 升级
+
+```
+npm i dsh-vibe-math@latest
+```
+
+无迁移。README 里的 v4 图现在读 `示例图/框架图-v4.svg`。

package/docs/test-timing.md

@@ -8,15 +8,15 @@
 ## 1. 怎么跑（并行是默认）
 
 ```bash
-node run-tests.mjs                     # 全部 *.test.mjs，并行（并发 = min(4, CPU 核数)）
-node run-tests.mjs --only formal       # 只跑名字含 formal 的套件
-node run-tests.mjs --concurrency=6     # 手动指定并发
-node audit-formal-sensitivity.mjs      # 49 条不变式探针，并行（--concurrency=N / --only=<preset> / --list）
-node audit-persona-sensitivity.mjs     # 11 条提示词面探针（串行，本身只要几秒）
-node audit-prompt-invariants.mjs       # 静态：四套的提示词/工具面不变式 + 扫描器自检（< 0.1s）
-node audit-prompt-invariants.mjs --self-probe   # 证明上面那 157 条不变式真的会变红（5 个自探针）
-node audit-spec-traceability.mjs       # 静态：规格/README ↔ 代码可追溯（< 0.1s）
-node audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 + 扫描器解析级自检（≈0.5 s）
+node tests/run-tests.mjs                     # 全部 *.test.mjs（在 tests/ 下），并行（并发 = min(4, CPU 核数)；命令都从**仓库根**执行）
+node tests/run-tests.mjs --only formal       # 只跑名字含 formal 的套件
+node tests/run-tests.mjs --concurrency=6     # 手动指定并发
+node tests/audit-formal-sensitivity.mjs      # 49 条不变式探针，并行（--concurrency=N / --only=<preset> / --list）
+node tests/audit-persona-sensitivity.mjs     # 11 条提示词面探针（串行，本身只要几秒）
+node tests/audit-prompt-invariants.mjs       # 静态：四套的提示词/工具面不变式 + 扫描器自检（< 0.1s）
+node tests/audit-prompt-invariants.mjs --self-probe   # 证明上面那 157 条不变式真的会变红（5 个自探针）
+node tests/audit-spec-traceability.mjs       # 静态：规格/README ↔ 代码可追溯（< 0.1s）
+node tests/audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 + 扫描器解析级自检（≈0.5 s）
 ```
 
 两个并行 runner 都会打印**每项耗时 + 汇总（wall / sum / speed-up / 最慢几项）**。跑完请读这几行。
@@ -25,14 +25,15 @@ node audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 +
 
 | 脚本 | 串行（sum） | 并行（wall） | 实测输出 |
 |---|---|---|---|
-| `run-tests.mjs`（23 个套件） | 221.5 s | **111.5 s**（并发 4，speed-up x1.99） | 关键路径 = `e2e-v4-fixes` 98.1 s |
+| `tests/run-tests.mjs`（26 个套件） | 225.8 s | **109.7 s**（并发 4，speed-up x2.06） | 关键路径 = `e2e-v4-fixes` 95.9 s |
+| `tests/audit-installer-policy.test.mjs` | ≈ 1 s | — | 在临时 DSH_HOME 里驱动真实安装器（复制 4 套预设 × 2 个版本） |
 | `audit-formal-sensitivity.mjs`（49 探针） | 612.0 s | **154.6 s**（并发 4，speed-up x3.96） | 关键路径 = 12 个 v2 探针（每个 ≈32 s） |
 | `audit-persona-sensitivity.mjs`（11 探针） | ≈ 5 s | — | 本身很快，不需要并行 |
 | `audit-prompt-invariants.mjs`（157 条，含 X5–X8b 扫描器自检） | 0.4 s | — | 静态 |
 | `audit-prompt-invariants.mjs --self-probe`（5 探针） | 1.5 s | — | 每个探针 = 一次自我重跑（0.3 s） |
 | `audit-spec-traceability.mjs`（94 条） | 0.3 s | — | 静态 |
 | `audit-v5-integrity.mjs` | ≈ 0.5 s | — | 静态审计（含扫描器自检） |
-| `prompt-v5-integrity.test.mjs` | 1.6 s | — | 虚拟时钟下生成 v5 语料（语料字节稳定） |
+| `prompt-v5-integrity.test.mjs` | 1.6 s | — | 虚拟时钟下生成 v5 语料（语料字节稳定；**stdout 里的会议成员顺序仍是运行间随机的**，只有落盘语料是逐字节确定的） |
 
 > 优化前：全量回归 ≈ 5.5 min（串行，`formal-verify-v2` 单独 186 s）；
 > 探针脚本 ≈ **38 min**（49 条串行，其中 12 条 × `formal-verify-v2` 162 s）。
@@ -49,7 +50,7 @@ node audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 +
 | `e2e-d9-d13.test.mjs` | ≈ 13 s | |
 | `e2e-v3.test.mjs` | ≈ 12 s | |
 | `formal-verify-v3.test.mjs` | ≈ 12 s | |
-| 其余 16 个 | ≤ 6 s | 其中 8 个 < 1 s |
+| 其余 19 个 | ≤ 6 s | 其中 12 个 < 1 s |
 
 ## 3. 已经做过的优化（别再重复踩）
 
@@ -90,12 +91,12 @@ node audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 +
 
 | 目的 | 跑什么 | 预期 |
 |---|---|---|
-| 改了某个架构的插件 | `node run-tests.mjs --only <vN>` + `node audit-formal-sensitivity.mjs --only=vN` | 30 s – 2 min |
-| 改了提示词/人设 | `node run-tests.mjs --only persona --only prompt` + `node audit-persona-sensitivity.mjs` | ≈ 15 s |
-| **改了任何工具的参数 schema / 参数处理** | `node audit-prompt-invariants.mjs --self-probe` + `node run-tests.mjs --only formal` | ≈ 40 s（v2 套件占大头） |
-| 改了共享契约 / 发版前 | `node run-tests.mjs` + `node audit-formal-sensitivity.mjs` + `node audit-persona-sensitivity.mjs` + `node audit-prompt-invariants.mjs --self-probe` + `node audit-spec-traceability.mjs` + `node audit-v5-integrity.mjs` | ≈ 4.5 min |
-| 只想快速看提示词/文档有没有漂移 | `node audit-prompt-invariants.mjs && node audit-spec-traceability.mjs` | **< 0.5 s** |
-| 只想知道"快不快" | `node run-tests.mjs --json` | 读 `wallSeconds` / `slowest` |
+| 改了某个架构的插件 | `node tests/run-tests.mjs --only <vN>` + `node tests/audit-formal-sensitivity.mjs --only=vN` | 30 s – 2 min |
+| 改了提示词/人设 | `node tests/run-tests.mjs --only persona --only prompt` + `node tests/audit-persona-sensitivity.mjs` | ≈ 15 s |
+| **改了任何工具的参数 schema / 参数处理** | `node tests/audit-prompt-invariants.mjs --self-probe` + `node tests/run-tests.mjs --only formal` | ≈ 40 s（v2 套件占大头） |
+| 改了共享契约 / 发版前 | `node tests/run-tests.mjs` + `node tests/audit-formal-sensitivity.mjs` + `node tests/audit-persona-sensitivity.mjs` + `node tests/audit-prompt-invariants.mjs --self-probe` + `node tests/audit-spec-traceability.mjs` + `node tests/audit-v5-integrity.mjs` | ≈ 4.5 min |
+| 只想快速看提示词/文档有没有漂移 | `node tests/audit-prompt-invariants.mjs && node tests/audit-spec-traceability.mjs` | **< 0.5 s** |
+| 只想知道"快不快" | `node tests/run-tests.mjs --json` | 读 `wallSeconds` / `slowest` |
 
 **每次跑完都要看那几行 timing**：如果某个套件突然比基线慢很多，先怀疑新增的固定等待，
 再怀疑它是否在等一个永远不会发生的条件（这正是 v2 套件 186 s 的成因）。

package/installer.js

@@ -1,5 +1,5 @@
 // dsh-vibe-math merged bundle installer — VERSIONED AUTO-UPDATE.
-// When this bundle is installed (e.g. `dsh plugin add dsh-vibe-math` or from the
+// When this bundle is installed (e.g. `dsh plugin --profile <name> add dsh-vibe-math`, or from the
 // dsh-market), this plugin copies ALL FOUR agent presets out of the package into
 // the DSH preset root, so the user immediately gets four presets in the picker:
 //   vibe-math-v2/  (probability-driven architecture)
@@ -16,16 +16,21 @@
 //  ships v2/v3/v4/v5.)
 //
 // UPDATE POLICY (state recorded in <presetRoot>/.vibe-math-installed.json):
-//   - baseline (no state file — e.g. upgrading from an installer that predates
-//     this mechanism): every existing owned file is refreshed to the current
-//     package version and recorded as package-owned (user policy: auto-update
-//     old installs; any manual edits made before this baseline are overwritten
-//     once — from then on edits are protected).
-//   - upgrade (recorded version != current package.json version): every owned
-//     file that is byte-identical to the previously installed copy (i.e. NOT
-//     user-edited since) is overwritten with the new version; user-edited files
-//     are preserved and reported via the logger.
-//   - same version: no-op (idempotent). Missing files are ALWAYS restored.
+//   - FORCE-REPLACE ON VERSION CHANGE. When the recorded version differs from this package's
+//     version — or there is no record at all (an install made by an older installer) — every
+//     managed file is overwritten with the shipped bytes. This is deliberately NOT conditional on
+//     the file being unmodified. Two reasons:
+//       · a preset assembled from two different versions (the old policy updated a file's
+//         neighbours and kept the file the user had touched) is exactly the state that fails to
+//         mount or misbehaves subtly, and the user has no way to see that from the outside;
+//       · editing a shipped preset in place is not the supported way to customize one — DSH
+//         provides a real one (copy the preset: the picker's copy action, or a new directory
+//         under <presetRoot>), which leaves the managed set updatable.
+//   - Nothing is destroyed silently: before a file whose bytes are not what the installer last
+//     wrote is replaced, the user's copy is kept under
+//     <presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file> and named in the log.
+//   - same version: no-op (idempotent) — restarting DSH never rewrites a file or churns the
+//     preset's generation stamp. Missing files are ALWAYS restored, at any version.
 //   - force a full refresh at any time: delete the preset dirs and restart DSH.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync, rmdirSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -36,7 +41,10 @@ import { fileURLToPath } from 'node:url'
 
 export const name = 'vibe-math-preset-installer'
 
-const PRESETS = [
+// Exported so the shipped policy suite can prove the managed list still covers what each preset
+// needs at runtime (a file present in the preset directory but missing here is copied by nobody,
+// and the installed preset then cannot mount).
+export const PRESETS = [
   {
     src: 'vibe-math-v2',
     dst: 'vibe-math-v2',
@@ -62,9 +70,34 @@ const PRESETS = [
 ]
 
 const STATE_FILE = '.vibe-math-installed.json'
+// where a replaced user edit is preserved; a leading dot keeps DSH's preset discovery from ever
+// treating it as a preset directory (ids must match [a-z0-9][a-z0-9-]*)
+const BACKUP_DIR = '.vibe-math-backup'
 
 function sha256(buf) { return createHash('sha256').update(buf).digest('hex') }
 
+/**
+ * Preserve one file that is about to be replaced by the shipped version, under
+ * `<presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file>`.
+ *
+ * Returns `'written'` (a copy was made now), `'kept'` (a copy for this version was already there —
+ * the earliest edit is the one worth keeping, and a re-run must not overwrite it with an
+ * already-replaced file) or `'failed'`. A caller must not report `'kept'` as a failure: the user's
+ * bytes are preserved, just from an earlier run.
+ */
+function backupReplacedFile(presetRoot, fromVersion, presetDir, fileName, buf) {
+  try {
+    const dir = join(presetRoot, BACKUP_DIR, String(fromVersion || 'unversioned'), presetDir)
+    const dst = join(dir, fileName)
+    if (existsSync(dst)) return 'kept' // the earliest copy for this version is the one worth keeping
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(dst, buf)
+    return 'written'
+  } catch (e) {
+    return 'failed' // a backup failure must never stop the update; it is reported by the caller
+  }
+}
+
 function readState(path) {
   try {
     const raw = readFileSync(path, 'utf8')
@@ -350,11 +383,35 @@ export async function apply(ctx) {
     const state = readState(stateFile)
     const prevFiles = (state && state.files) || {}
     const isUpgrade = state !== null && pkgVersion !== '' && state.version !== pkgVersion
-    const isBaseline = state === null // no recorded history → refresh everything (user policy: auto-update old installs)
+    const isBaseline = state === null // no recorded history → refresh everything
+    // A version change (or a first sighting) REPLACES the managed files; only a same-version boot
+    // leaves the working tree alone. See UPDATE POLICY at the top of this file.
+    const refresh = isBaseline || isUpgrade
+    const fromVersion = (state && state.version) || '(unversioned)'
+    if (pkgVersion === '') {
+      // Without a version there is nothing to compare against, so this run must NOT replace
+      // anything (a wrong guess would overwrite files for no reason); it still restores missing
+      // ones and keeps the previously recorded version, so the next readable run reports the
+      // right "from" version.
+      logger?.warn?.('[dsh-vibe-math] 读不到本包版本（package.json 缺失或损坏）：本次不做版本比对，只补回缺失的 preset 文件。')
+    }
+    // A recorded version NEWER than this package means this run replaces preset bytes BACKWARDS.
+    // The policy still does it — "the preset directory equals the installed package" is the whole
+    // point — but a silent downgrade (an old bundle still installed in the profile while the presets
+    // were synced from a newer one) is exactly the surprise worth naming.
+    if (isUpgrade) {
+      const recorded = parseSemver(fromVersion)
+      const installed = parseSemver(pkgVersion)
+      if (recorded !== null && installed !== null && compareSemver(recorded, installed) > 0) {
+        logger?.warn?.('[dsh-vibe-math] 记录里的版本（' + fromVersion + '）比本包版本（' + pkgVersion + '）新，本次会把 preset 换回旧字节。' +
+          '若这不是你想要的，请先升级 profile 里的依赖：dsh plugin --profile <name> add dsh-vibe-math@latest，再重启 DSH。')
+      }
+    }
 
     const nextFiles = {}
     let installed = 0, updated = 0, kept = 0
-    const keptList = []
+    const replacedEdits = []
+    const backupFailures = []
 
     for (const p of PRESETS) {
       const srcDir = join(here, p.src)
@@ -375,32 +432,33 @@ export async function apply(ctx) {
           nextFiles[key] = { hash: curHash, provenance: 'package' }
           continue
         }
-        const destHash = sha256(readFileSync(d))
-        if (isBaseline) {
-          // no recorded history: refresh to the current package (one-time; edits
-          // made before this mechanism are overwritten, later edits are protected)
-          if (destHash === curHash) { nextFiles[key] = { hash: curHash, provenance: 'package' } }
-          else { writeFileSync(d, cur); updated += 1; nextFiles[key] = { hash: curHash, provenance: 'package' } }
-          continue
-        }
+        const destBuf = readFileSync(d)
+        const destHash = sha256(destBuf)
         const prev = prevFiles[key]
         const prevRec = (prev && typeof prev === 'object') ? prev : { hash: prev, provenance: 'package' }
-        const prevProv = (prevRec.provenance === 'user') ? 'user' : 'package' // 未知来源按包文件处理
-        if (prevProv === 'package' && destHash === prevRec.hash) {
-          // 包文件且未被改动 → 可安全升级（内容相同则跳过写入）
-          if (destHash !== curHash) { writeFileSync(d, cur); updated += 1 }
+        if (destHash === curHash) {
+          // already the shipped bytes: never rewrite, so the file's mtime (which keys the preset's
+          // DSH generation) stays put
           nextFiles[key] = { hash: curHash, provenance: 'package' }
-        } else if (prevProv === 'user') {
-          // 用户持有 → 永不覆盖
-          kept += 1
-          if (isUpgrade) keptList.push(key + ' (用户持有)')
-          nextFiles[key] = { hash: destHash, provenance: 'user' }
-        } else {
-          // 包文件但自上次安装后已被用户改动
+          continue
+        }
+        if (!refresh) {
+          // same version: nothing is being updated, so a file that differs from the package is left
+          // exactly as it is. The recorded hash stays "what this installer last wrote" (or unknown),
+          // so the drift is still recognised — and backed up — at the next version change.
           kept += 1
-          if (isUpgrade) keptList.push(key + ' (已修改)')
-          nextFiles[key] = { hash: destHash, provenance: 'user' }
+          nextFiles[key] = typeof prevRec.hash === 'string' ? { hash: prevRec.hash, provenance: 'package' } : { provenance: 'package' }
+          continue
+        }
+        // replacing: preserve the user's bytes when they are not what this installer last wrote
+        // (a legacy state without a hash cannot tell, so it backs the file up rather than risk it)
+        if (typeof prevRec.hash !== 'string' || destHash !== prevRec.hash) {
+          if (backupReplacedFile(presetRoot, fromVersion, p.dst, f, destBuf) === 'failed') backupFailures.push(key)
+          replacedEdits.push(key)
         }
+        writeFileSync(d, cur)
+        updated += 1
+        nextFiles[key] = { hash: curHash, provenance: 'package' }
       }
     }
 
@@ -434,22 +492,38 @@ export async function apply(ctx) {
       if (dirEmpty && existsSync(dir)) { try { rmdirSync(dir); removedDirs.push(dir) } catch (e) {} }
     }
 
-    writeState(stateFile, { version: pkgVersion, files: nextFiles, updatedAt: Date.now() })
+    writeState(stateFile, { version: pkgVersion || (state && state.version) || '', files: nextFiles, updatedAt: Date.now() })
 
     if (removedFiles > 0 || removedDirs.length > 0) {
       logger?.info?.('[dsh-vibe-math] preset cleanup: removed ' + removedFiles + ' file(s) from ' + removedDirs.length + ' stale preset dir(s) (' + removedDirs.map(d => d.split(/[\\/]/).pop()).join(', ') + ') that are no longer shipped.')
     }
 
     if (isUpgrade) {
-      logger?.info?.('[dsh-vibe-math] preset auto-update: version ' + (state.version || '(none)') + ' → ' + pkgVersion +
-        ' — 新增 ' + installed + ' 个文件，更新 ' + updated + ' 个文件' +
-        (kept > 0 ? '，保留 ' + kept + ' 个未覆盖文件（' + keptList.join('; ') + '）' : '') +
-        '。新版本 preset 将在新会话生效。')
+      logger?.info?.('[dsh-vibe-math] preset auto-update: version ' + fromVersion + ' → ' + pkgVersion +
+        ' — 新增 ' + installed + ' 个文件，更新 ' + updated + ' 个文件。' +
+        (replacedEdits.length > 0
+          ? '其中 ' + replacedEdits.length + ' 个文件与上一次安装的字节不同（被改过），已按版本一致化覆盖' +
+            (backupFailures.length === 0
+              ? '，原文备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion)) + '：' + replacedEdits.join(', ')
+              : '；这 ' + backupFailures.length + ' 个文件**备份失败**（原文未保留）：' + backupFailures.join(', ')) +
+            '。要自定义 preset，请复制一份而不是改这几个文件——被管理的文件在下一次版本变更时一定会被替换。'
+          : '') +
+        '新版本 preset 将在新会话生效。')
     } else if (isBaseline) {
       logger?.info?.('[dsh-vibe-math] preset baseline: refreshed ' + (installed + updated) + ' file(s) to v' + pkgVersion +
-        ' — 已启用自动更新（后续版本升级将自动替换未被手动修改的 preset 文件）。')
+        (replacedEdits.length > 0
+          ? '，其中 ' + replacedEdits.length + ' 个原有文件与随包版本不同' +
+            (backupFailures.length === 0 ? '，原文已备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion))
+              : '，但有 ' + backupFailures.length + ' 个备份失败（原文未保留）：' + backupFailures.join(', '))
+          : '') +
+        ' — 已启用版本化自动更新（后续版本变更会直接替换被管理的 preset 文件）。')
     } else if (installed > 0) {
       logger?.info?.('[dsh-vibe-math] restored ' + installed + ' missing preset file(s)')
+    } else if (kept > 0) {
+      // same version, and some managed file on disk differs from the package: reported, never
+      // rewritten mid-version (it is replaced, with a backup, at the next version change)
+      logger?.info?.('[dsh-vibe-math] preset files untouched (v' + pkgVersion + ' unchanged): ' + kept +
+        ' file(s) differ from the shipped copy; they will be replaced on the next version change (原件会先备份)')
     }
     await checkHostCapabilities(ctx, logger)
   } catch (err) {