dsh-plugin-guide 0.3.27 → 0.3.29

package/references/official-docs/docs/persistence-changes/2026-10-07-title-reasoning-effort.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-07-title-reasoning-effort
+
+[English](2026-10-07-title-reasoning-effort.md) | 中文
+
+## 概述
+
+记录辅助会话标题请求选择的具体推理强度。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-07-title-reasoning-effort
+baseline: false
+changes:
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-05-working-directory-attribution"
+    after: "b33545b3244861bcbf73b407d24b53402710f5acacab7ae939537e5504a68dc6"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+新增 reasoningEffort 字段为可选。现有 V4 记录仍有效，继续保留其未记录强度的事实。路由提供可选推理强度时，已准备的标题请求写入解析后的强度；无需提升 Session 格式版本。
+
+<a id="verification"></a>
+## 验证
+
+LLM、适配器、标题提供方与回放的定向测试通过：50 个文件、1960 个测试。session-title-after-turn SDK 快照通过，记录从默认 high 的路由中选出的 low 强度。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/README.i18n.yaml

@@ -18,11 +18,11 @@
   en: 6cd0f79a9455bdf2
   zh: a5978b7834c0802b
 /persistence-type-change-records/compatibility-rules:
-  en: 7d5ce8c14e387922
-  zh: 9106c78283ad932c
+  en: 218b28a5096b5e7d
+  zh: 5b987c852e204893
 /persistence-type-change-records/history-and-limitations:
-  en: 10a426d36c41548b
-  zh: ef03b693d9d9be26
+  en: 705a215ce0dd5d82
+  zh: a3b3e46231dae6ce
 /persistence-type-change-records/dev-note:
   en: 5de1d6304e00c58f
   zh: 8d8225361cfa29e5

package/references/official-docs/docs/persistence-changes/README.md

@@ -46,25 +46,27 @@ The [record template](../../.agents/skills/dsh-doc/templates/persistence-change.
 <a id="compatibility-rules"></a>
 ## Compatibility rules
 
-Every detected structural change requires an acknowledgement. Record creation and update infer the minimum decision from these fixed rules; an explicit `--decision` is a checked assertion. The rules apply to the complete change, so an allowed change cannot hide a simultaneous breaking change.
+Every detected structural change requires an acknowledgement. Keep the Session version when older readers preserve the required meaning of accepted data, safely ignore optional features while retaining opaque records, or refuse unsupported required data before execution, mutation, or recovery truncation. New readers must preserve historical meaning and readability. Bump only when unsafe interpretation cannot be prevented by an effective discriminator. Unknown fields or values count only when existing readers actually handle them safely; type differences alone cannot establish that behavior. See the [reader-compatibility decision](../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md).
 
-| Detected change | Minimum decision |
+| Detected change | Recording requirement |
 |---|---|
 | Add an optional event-body property, including its complete subtree | `same-version` |
 | Make a required event-body property optional | `same-version` |
 | Add an ordinary event type | `same-version` |
-| Add a higher numeric `data.version` to an ordinary event while retaining every old payload alternative unchanged | `same-version` |
+| Add a higher numeric `data.version` to an ordinary event while retaining every old payload alternative under the existing compatibility rules | `same-version` |
 | Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | `same-version` |
-| Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
-| Change the Session header or event envelope | `version-bump` |
+| Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | Compatibility review for `same-version`, or explicit `version-bump` |
+| Change the Session header or event envelope | Compatibility review for `same-version`; a header version change requires `version-bump` |
 
-A finalized checkpoint protects the accepted baseline without replacing these compatibility rules. At V4, optional additions, ordinary events, and qualified attribution additions can receive new same-version records. Breaking differences require a higher writer version and an acknowledgement containing its own header increase. The accepted V4 record cannot be updated to reuse its original 3→4 transition.
+The classifier identifies established same-version cases and changes requiring compatibility review; it cannot decide semantic safety. The latter require an explicit `--decision same-version` when recording or updating without a version increase. The acknowledgement’s Compatibility section explains actual reader behavior in both directions, and Verification records the executed checks. Review the complete transition, including simultaneous changes. An explicit `version-bump` instead requires its own increasing `SessionHeader.version` transition; a same-version decision cannot waive a header version change. Finalized records remain immutable, so a later record cannot reuse the accepted 3→4 transition.
 
-An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided all existing alternatives remain structurally unchanged. The reader must retain support for the old payloads; adding variants at an existing version, dropping old versions, and changing the Session header or envelope remain breaking. Older readers may reject the new payload version. The [catalog acknowledgement](2026-09-20-unknown-child-catalog.md) records one such transition.
+The CLI requires that explicit choice before generating a flagged same-version record. CI reads the recorded `decision: same-version` and accepts it when the ordinary history, schema, and header-version constraints hold, whether the record was generated or edited manually. Verification cannot establish how the record was authored or whether a human reviewed it. Reviewers compare base and head inventories with [`persistence-review`](../cookbook/reviewing-persistence-type-changes.md#generate); `--check` validates current-tree consistency and cannot reveal a transition already covered by an acknowledgement.
 
-The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated breaking changes remain strict. Multiple context-form alternatives with the same wire kind form one group.
+An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided every existing alternative remains readable under the established same-version rules above. Optional property additions and required-to-optional changes may accompany the new version; each retained alternative is compared separately. Other payload changes require compatibility review. Older readers may reject the new payload version. The [catalog acknowledgement](2026-09-20-unknown-child-catalog.md) records one such transition.
 
-A same-version explanation states how old records remain readable and how older readers handle new records. Optional additions explain why older readers can ignore them without changing replay; a new payload version records the older-reader rejection. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated structural changes require compatibility review. Multiple context-form alternatives with the same wire kind form one group.
+
+Every same-version explanation states how old records remain readable and how older readers handle new records, including established cases that need no explicit CLI decision. A feature absent from a log must retain the old behavior; dispensable features must be safe to ignore; required features need an effective refusal signal. Unsupported-feature refusal must not become corruption recovery or tail truncation. For required-to-optional changes, explain how readers handle an absent value. Reviewers assess behavior and evidence; the checker validates the declaration and type classification. A version-bump record follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
 
 When a reader rejects a JSON property by name, declare the property as optional `never` and mark it with argument-free `@persistenceReserved`. The extractor retains the forbidden field, so allowing a JSON value later requires an existing-field type change. Required or JSON-valued properties cannot carry this marker. Unmarked optional `never` and `undefined` properties retain their existing omission behavior.
 
@@ -75,7 +77,7 @@ One baseline records the complete initial inventory. Later records use their pre
 
 Accepted records describe historical transitions; preserve their machine declarations and schema snapshots when adding a successor. An unaccepted terminal record can be refreshed explicitly; the command rejects baselines, records with dependants, and checkpoint-locked records before producing artifacts. Verification checks retained checkpoint hashes; it does not prove that the checkpoints and their authority record were never edited together. No Git ref, remote service, or released checkout supplies the baseline.
 
-Digests describe declared persistence types, not runtime validation or behavior. Ordinary comments, source locations, alias names, and harmless declaration reordering do not affect them. Compatibility annotations are recorded policy data and do affect digests. Unannotated version-1 snapshots retain their original normalization, fingerprints, and strict classification; policy-bearing graphs use a separate fingerprint domain. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as `unknown` expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The [decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) records these trade-offs.
+Digests describe declared persistence types, not runtime validation or behavior. Ordinary comments, source locations, alias names, and harmless declaration reordering do not affect them. Compatibility annotations are recorded policy data and do affect digests. Unannotated version-1 snapshots retain their original normalization and fingerprints; policy-bearing graphs use a separate fingerprint domain. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as `unknown` expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The [decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) records these trade-offs.
 
 <a id="dev-note"></a>
 ## Dev Note

package/references/official-docs/docs/persistence-changes/README.zh.md

@@ -46,25 +46,27 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 <a id="compatibility-rules"></a>
 ## 兼容性规则
 
-每个检测到的结构变更都需要确认。创建和更新记录依据这些固定规则推断最低决策；显式 `--decision` 是受检查的断言。规则应用于整个变更，因此允许的变更不能掩盖同时发生的破坏性变更。
+每个检测到的结构变更都需要确认。当旧读取器保留所接受数据的必要含义、安全忽略可选功能并保留不透明记录，或在执行、修改及恢复截断前拒绝不受支持的必要数据时，可以保留 Session 版本。新读取器必须保留历史含义和可读性。只有有效判别信息无法阻止不安全解释时，才提升版本。未知字段或值只有在已有读取器实际安全处理它们时才有效；类型差异本身无法证明这种行为。参见[读取器兼容性决策](../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.zh.md)。
 
-| 检测到的变更 | 最低决策要求 |
+| 检测到的变更 | 记录要求 |
 |---|---|
 | 添加可选事件体属性，包括其完整子树 | `same-version` |
 | 将必选事件体属性改为可选 | `same-version` |
 | 添加普通事件类型 | `same-version` |
-| 为普通事件增加更高的数字 `data.version`，并原样保留所有旧载荷分支 | `same-version` |
+| 为普通事件增加更高的数字 `data.version`，并按现有兼容性规则保留所有旧载荷分支 | `same-version` |
 | 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | `same-version` |
-| 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
-| 更改会话头或事件封装 | `version-bump` |
+| 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `same-version` 需兼容性评审，或显式 `version-bump` |
+| 更改会话头或事件封装 | `same-version` 需兼容性评审；头版本变化要求 `version-bump` |
 
-定稿检查点保护已接受基线，不替换这些兼容性规则。在 V4 中，可选新增、普通事件及符合条件的归属 kind 新增可以使用新的同版本记录。破坏性差异要求更高的写入器版本，以及包含自身头版本递增的确认记录。不能更新已接受 V4 记录以复用其原有 3→4 转换。
+分类器识别已明确允许的同版本情形及需要兼容性评审的变更，不能判定语义安全性。后者在不升版本的记录或更新操作中要求显式提供 `--decision same-version`。确认记录的兼容性部分说明两个方向上的实际读取器行为，验证部分记录已执行的检查。评审覆盖整个转换，包括同时发生的其他变更。显式 `version-bump` 则要求自身包含 `SessionHeader.version` 递增转换；同版本决策不能豁免头版本变化。定稿记录保持不可变，因此后续记录不能复用已接受的 3→4 转换。
 
-普通事件可增加具有必选、非负整数 `data.version` 的载荷分支，新版本必须高于所有已有载荷版本，且所有已有分支结构保持不变。读取器必须保留旧载荷支持；在已有版本中增加分支、移除旧版本，以及修改 Session header 或事件封装仍属于破坏性变更。旧读取器可能拒绝新载荷版本。[Catalog 确认记录](2026-09-20-unknown-child-catalog.zh.md) 记录了此类演进。
+CLI 在生成被标记的同版本记录前要求该显式选择。CI 读取所记录的 `decision: same-version`；只要通常的历史、schema 与头版本约束成立，无论记录由工具生成还是手工编辑，都会接受。验证无法确定记录的编写方式，也无法证明人类已评审。评审者使用 [`persistence-review`](../cookbook/reviewing-persistence-type-changes.zh.md#generate) 比较 base 与 head 清单；`--check` 验证当前目录一致性，无法显示已被确认记录覆盖的转换。
 
-提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
+普通事件可增加具有必选、非负整数 `data.version` 的载荷分支，新版本必须高于所有已有载荷版本，且所有已有分支按上述明确允许的同版本规则保持可读。可选属性新增和必选改可选可以与新版本一同引入；每个保留分支均独立比较。其他载荷变更需要兼容性评审。旧读取器可能拒绝新载荷版本。[Catalog 确认记录](2026-09-20-unknown-child-catalog.zh.md)记录了此类演进。
 
-同版本说明须解释旧记录如何保持可读，以及旧读取器如何处理新记录。可选新增须说明旧读取器为何可以忽略它而不改变回放；新增载荷版本须记录旧读取器的拒绝行为。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关结构变更需要兼容性评审。同一 wire kind 的多个上下文形式分支归为一组。
+
+每项同版本说明都须解释旧记录如何保持可读，以及旧读取器如何处理新记录，包括无需显式 CLI 决策的明确允许情形。日志未使用某功能时必须保留旧行为；可舍弃功能必须能安全忽略；必要功能需要有效的拒绝信号。不受支持功能的拒绝不能变成损坏恢复或尾部截断。对于必选改可选的变更，说明读取器如何处理缺失值。审阅者判断行为和证据；检查器校验声明及类型分类。升版本记录遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
 
 当读取器按属性名拒绝 JSON 字段时，将该属性声明为可选 `never`，并添加无参数的 `@persistenceReserved` 标记。提取器保留这一禁止字段，因此后续允许 JSON 值属于已有字段类型变更。必选属性或允许 JSON 值的属性不能携带该标记。未标记的可选 `never` 和 `undefined` 属性保留现有省略行为。
 
@@ -75,7 +77,7 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 
 已接受记录描述历史转换；添加后继时须保留其机器声明和 schema 快照。尚未接受的末端记录可以显式刷新；命令在生成产物前拒绝基线、被依赖的记录和被检查点锁定的记录。验证检查所保留检查点的哈希，但不证明检查点及其真源记录从未被一起修改。基线不依赖 Git 引用、远端服务或已发布版本的检出目录。
 
-摘要描述声明的持久化类型，不描述运行时验证或行为。普通注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。兼容性标记是记录的策略数据，会影响摘要。不带标记的版本 1 快照保留原有规范化、指纹和严格分类；包含策略的图使用独立的指纹域。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。`unknown` 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。[决策记录](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)说明这些取舍。
+摘要描述声明的持久化类型，不描述运行时验证或行为。普通注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。兼容性标记是记录的策略数据，会影响摘要。不带标记的版本 1 快照保留原有规范化和指纹；包含策略的图使用独立的指纹域。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。`unknown` 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。[决策记录](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)说明这些取舍。
 
 <a id="dev-note"></a>
 ## 开发备注

package/references/official-docs/docs/persistence-changes/historical-formats/README.i18n.yaml

@@ -15,8 +15,8 @@
   en: 14c57f30e676f6e3
   zh: b1a0ccf26fab3727
 /session-persistence-formats/format-references:
-  en: b19e6cfc84bfc46d
-  zh: 5b1d86bcdab672ca
+  en: 553fd4963cf19abe
+  zh: 7ca3cd5d0a88d35a
 /session-persistence-formats/scope-and-evidence:
   en: b220062139ddac1e
   zh: 7c4c0efe05dafa9c

package/references/official-docs/docs/persistence-changes/historical-formats/README.md

@@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant.
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 590 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 63 / 597 |
 
 <!-- persistence-format-index:end -->
 

package/references/official-docs/docs/persistence-changes/historical-formats/README.zh.md

@@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 590 |
+| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 63 / 597 |
 
 <!-- persistence-format-index:end -->
 

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.2.i18n.yaml

@@ -21,8 +21,8 @@
   en: af9cea43334ee692
   zh: c6c8bd0d6a17718a
 /persistence-release-dsh-v0-0-1-rc-2/structural-changes:
-  en: bdf6c95697ae5816
-  zh: 0332dec60181ab4a
+  en: 7cd96972b43b0cb0
+  zh: 7e61c1098f402657
 /persistence-release-dsh-v0-0-1-rc-2/verification:
   en: 8ccca317964523b1
   zh: 2c8b3e70a3320778

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.2.md

@@ -191,58 +191,58 @@ changes:
 
 <!-- persistence-release-changes:start -->
 
-Detected 45 changed roots and 48 structural differences. The minimum below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
+Detected 45 changed roots and 48 structural differences. The review requirement below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
 
-| Path | Change | Current minimum |
+| Path | Change | Review requirement |
 |---|---|---|
-| `SessionEventEnvelope` | `union-variants-changed` | `version-bump` |
-| `event:agent-preset/selected.ignorable` | `optional-property-added` | `version-bump` |
-| `event:agent/inbox/spliced.data.inserted[].source` | `union-variants-changed` | `version-bump` |
-| `event:agent/inbox/spliced.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/asked.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/decided.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/policy.ignorable` | `optional-property-added` | `version-bump` |
-| `event:assistant/chunk.ignorable` | `optional-property-added` | `version-bump` |
-| `event:assistant/message.ignorable` | `optional-property-added` | `version-bump` |
-| `event:command/done.ignorable` | `optional-property-added` | `version-bump` |
-| `event:command/run.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/prune.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/summary.ignorable` | `optional-property-added` | `version-bump` |
-| `event:feedback/record.ignorable` | `optional-property-added` | `version-bump` |
-| `event:goal/change.ignorable` | `optional-property-added` | `version-bump` |
-| `event:hook/invoked.ignorable` | `optional-property-added` | `version-bump` |
-| `event:hook/result.ignorable` | `optional-property-added` | `version-bump` |
-| `event:llm/retry.ignorable` | `optional-property-added` | `version-bump` |
-| `event:llm/retry-started.ignorable` | `optional-property-added` | `version-bump` |
-| `event:permission/preset.ignorable` | `optional-property-added` | `version-bump` |
-| `event:plan/mode.ignorable` | `optional-property-added` | `version-bump` |
-| `event:request/context.ignorable` | `optional-property-added` | `version-bump` |
-| `event:request/header.ignorable` | `optional-property-added` | `version-bump` |
-| `event:sandbox/mode.ignorable` | `optional-property-added` | `version-bump` |
-| `event:schedule/change` | `root-added` | `same-version` |
-| `event:session/end-seed.ignorable` | `optional-property-added` | `version-bump` |
-| `event:session/title.ignorable` | `optional-property-added` | `version-bump` |
-| `event:session/title-llm-request.data.messages[].source` | `union-variants-changed` | `version-bump` |
-| `event:session/title-llm-request.ignorable` | `optional-property-added` | `version-bump` |
-| `event:step/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:step/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:subagent/descriptor.ignorable` | `optional-property-added` | `version-bump` |
-| `event:todo/write.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool-workflow/agent-end` | `root-added` | `same-version` |
-| `event:tool-workflow/agent-start` | `root-added` | `same-version` |
-| `event:tool-workflow/run-end` | `root-added` | `same-version` |
-| `event:tool-workflow/run-start` | `root-added` | `same-version` |
-| `event:tool/call.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/code-dispatch.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/code-dispatch-start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/result.ignorable` | `optional-property-added` | `version-bump` |
-| `event:turn/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:turn/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:user/message.data.source` | `union-variants-changed` | `version-bump` |
-| `event:user/message.ignorable` | `optional-property-added` | `version-bump` |
-| `event:web/deepseek-search-llm-request.ignorable` | `optional-property-added` | `version-bump` |
+| `SessionEventEnvelope` | `union-variants-changed` | `review-required` |
+| `event:agent-preset/selected.ignorable` | `optional-property-added` | `review-required` |
+| `event:agent/inbox/spliced.data.inserted[].source` | `union-variants-changed` | `review-required` |
+| `event:agent/inbox/spliced.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/asked.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/decided.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/policy.ignorable` | `optional-property-added` | `review-required` |
+| `event:assistant/chunk.ignorable` | `optional-property-added` | `review-required` |
+| `event:assistant/message.ignorable` | `optional-property-added` | `review-required` |
+| `event:command/done.ignorable` | `optional-property-added` | `review-required` |
+| `event:command/run.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/prune.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/summary.ignorable` | `optional-property-added` | `review-required` |
+| `event:feedback/record.ignorable` | `optional-property-added` | `review-required` |
+| `event:goal/change.ignorable` | `optional-property-added` | `review-required` |
+| `event:hook/invoked.ignorable` | `optional-property-added` | `review-required` |
+| `event:hook/result.ignorable` | `optional-property-added` | `review-required` |
+| `event:llm/retry.ignorable` | `optional-property-added` | `review-required` |
+| `event:llm/retry-started.ignorable` | `optional-property-added` | `review-required` |
+| `event:permission/preset.ignorable` | `optional-property-added` | `review-required` |
+| `event:plan/mode.ignorable` | `optional-property-added` | `review-required` |
+| `event:request/context.ignorable` | `optional-property-added` | `review-required` |
+| `event:request/header.ignorable` | `optional-property-added` | `review-required` |
+| `event:sandbox/mode.ignorable` | `optional-property-added` | `review-required` |
+| `event:schedule/change` | `root-added` | `not-required` |
+| `event:session/end-seed.ignorable` | `optional-property-added` | `review-required` |
+| `event:session/title.ignorable` | `optional-property-added` | `review-required` |
+| `event:session/title-llm-request.data.messages[].source` | `union-variants-changed` | `review-required` |
+| `event:session/title-llm-request.ignorable` | `optional-property-added` | `review-required` |
+| `event:step/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:step/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:subagent/descriptor.ignorable` | `optional-property-added` | `review-required` |
+| `event:todo/write.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool-workflow/agent-end` | `root-added` | `not-required` |
+| `event:tool-workflow/agent-start` | `root-added` | `not-required` |
+| `event:tool-workflow/run-end` | `root-added` | `not-required` |
+| `event:tool-workflow/run-start` | `root-added` | `not-required` |
+| `event:tool/call.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/code-dispatch.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/code-dispatch-start.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/result.ignorable` | `optional-property-added` | `review-required` |
+| `event:turn/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:turn/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:user/message.data.source` | `union-variants-changed` | `review-required` |
+| `event:user/message.ignorable` | `optional-property-added` | `review-required` |
+| `event:web/deepseek-search-llm-request.ignorable` | `optional-property-added` | `review-required` |
 
 <!-- persistence-release-changes:end -->
 

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.2.zh.md

@@ -191,58 +191,58 @@ changes:
 
 <!-- persistence-release-changes:start -->
 
-检测到 45 个根类型变化、48 项结构差异。下表的最低要求按当前规则计算，只用于比较；不表示旧版本曾遵守这些规则，也不证明迁移或运行时兼容性。
+检测到 45 个根类型变化、48 项结构差异。下表的审查要求按当前规则计算，只用于比较；不表示旧版本曾遵守这些规则，也不证明迁移或运行时兼容性。
 
-| 路径 | 变化 | 当前最低要求 |
+| 路径 | 变化 | 审查要求 |
 |---|---|---|
-| `SessionEventEnvelope` | `union-variants-changed` | `version-bump` |
-| `event:agent-preset/selected.ignorable` | `optional-property-added` | `version-bump` |
-| `event:agent/inbox/spliced.data.inserted[].source` | `union-variants-changed` | `version-bump` |
-| `event:agent/inbox/spliced.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/asked.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/decided.ignorable` | `optional-property-added` | `version-bump` |
-| `event:approval/policy.ignorable` | `optional-property-added` | `version-bump` |
-| `event:assistant/chunk.ignorable` | `optional-property-added` | `version-bump` |
-| `event:assistant/message.ignorable` | `optional-property-added` | `version-bump` |
-| `event:command/done.ignorable` | `optional-property-added` | `version-bump` |
-| `event:command/run.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/prune.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:compact/summary.ignorable` | `optional-property-added` | `version-bump` |
-| `event:feedback/record.ignorable` | `optional-property-added` | `version-bump` |
-| `event:goal/change.ignorable` | `optional-property-added` | `version-bump` |
-| `event:hook/invoked.ignorable` | `optional-property-added` | `version-bump` |
-| `event:hook/result.ignorable` | `optional-property-added` | `version-bump` |
-| `event:llm/retry.ignorable` | `optional-property-added` | `version-bump` |
-| `event:llm/retry-started.ignorable` | `optional-property-added` | `version-bump` |
-| `event:permission/preset.ignorable` | `optional-property-added` | `version-bump` |
-| `event:plan/mode.ignorable` | `optional-property-added` | `version-bump` |
-| `event:request/context.ignorable` | `optional-property-added` | `version-bump` |
-| `event:request/header.ignorable` | `optional-property-added` | `version-bump` |
-| `event:sandbox/mode.ignorable` | `optional-property-added` | `version-bump` |
-| `event:schedule/change` | `root-added` | `same-version` |
-| `event:session/end-seed.ignorable` | `optional-property-added` | `version-bump` |
-| `event:session/title.ignorable` | `optional-property-added` | `version-bump` |
-| `event:session/title-llm-request.data.messages[].source` | `union-variants-changed` | `version-bump` |
-| `event:session/title-llm-request.ignorable` | `optional-property-added` | `version-bump` |
-| `event:step/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:step/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:subagent/descriptor.ignorable` | `optional-property-added` | `version-bump` |
-| `event:todo/write.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool-workflow/agent-end` | `root-added` | `same-version` |
-| `event:tool-workflow/agent-start` | `root-added` | `same-version` |
-| `event:tool-workflow/run-end` | `root-added` | `same-version` |
-| `event:tool-workflow/run-start` | `root-added` | `same-version` |
-| `event:tool/call.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/code-dispatch.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/code-dispatch-start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:tool/result.ignorable` | `optional-property-added` | `version-bump` |
-| `event:turn/end.ignorable` | `optional-property-added` | `version-bump` |
-| `event:turn/start.ignorable` | `optional-property-added` | `version-bump` |
-| `event:user/message.data.source` | `union-variants-changed` | `version-bump` |
-| `event:user/message.ignorable` | `optional-property-added` | `version-bump` |
-| `event:web/deepseek-search-llm-request.ignorable` | `optional-property-added` | `version-bump` |
+| `SessionEventEnvelope` | `union-variants-changed` | `review-required` |
+| `event:agent-preset/selected.ignorable` | `optional-property-added` | `review-required` |
+| `event:agent/inbox/spliced.data.inserted[].source` | `union-variants-changed` | `review-required` |
+| `event:agent/inbox/spliced.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/asked.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/decided.ignorable` | `optional-property-added` | `review-required` |
+| `event:approval/policy.ignorable` | `optional-property-added` | `review-required` |
+| `event:assistant/chunk.ignorable` | `optional-property-added` | `review-required` |
+| `event:assistant/message.ignorable` | `optional-property-added` | `review-required` |
+| `event:command/done.ignorable` | `optional-property-added` | `review-required` |
+| `event:command/run.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/prune.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:compact/summary.ignorable` | `optional-property-added` | `review-required` |
+| `event:feedback/record.ignorable` | `optional-property-added` | `review-required` |
+| `event:goal/change.ignorable` | `optional-property-added` | `review-required` |
+| `event:hook/invoked.ignorable` | `optional-property-added` | `review-required` |
+| `event:hook/result.ignorable` | `optional-property-added` | `review-required` |
+| `event:llm/retry.ignorable` | `optional-property-added` | `review-required` |
+| `event:llm/retry-started.ignorable` | `optional-property-added` | `review-required` |
+| `event:permission/preset.ignorable` | `optional-property-added` | `review-required` |
+| `event:plan/mode.ignorable` | `optional-property-added` | `review-required` |
+| `event:request/context.ignorable` | `optional-property-added` | `review-required` |
+| `event:request/header.ignorable` | `optional-property-added` | `review-required` |
+| `event:sandbox/mode.ignorable` | `optional-property-added` | `review-required` |
+| `event:schedule/change` | `root-added` | `not-required` |
+| `event:session/end-seed.ignorable` | `optional-property-added` | `review-required` |
+| `event:session/title.ignorable` | `optional-property-added` | `review-required` |
+| `event:session/title-llm-request.data.messages[].source` | `union-variants-changed` | `review-required` |
+| `event:session/title-llm-request.ignorable` | `optional-property-added` | `review-required` |
+| `event:step/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:step/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:subagent/descriptor.ignorable` | `optional-property-added` | `review-required` |
+| `event:todo/write.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool-workflow/agent-end` | `root-added` | `not-required` |
+| `event:tool-workflow/agent-start` | `root-added` | `not-required` |
+| `event:tool-workflow/run-end` | `root-added` | `not-required` |
+| `event:tool-workflow/run-start` | `root-added` | `not-required` |
+| `event:tool/call.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/code-dispatch.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/code-dispatch-start.ignorable` | `optional-property-added` | `review-required` |
+| `event:tool/result.ignorable` | `optional-property-added` | `review-required` |
+| `event:turn/end.ignorable` | `optional-property-added` | `review-required` |
+| `event:turn/start.ignorable` | `optional-property-added` | `review-required` |
+| `event:user/message.data.source` | `union-variants-changed` | `review-required` |
+| `event:user/message.ignorable` | `optional-property-added` | `review-required` |
+| `event:web/deepseek-search-llm-request.ignorable` | `optional-property-added` | `review-required` |
 
 <!-- persistence-release-changes:end -->
 

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.3.i18n.yaml

@@ -21,8 +21,8 @@
   en: af9cea43334ee692
   zh: c6c8bd0d6a17718a
 /persistence-release-dsh-v0-0-1-rc-3/structural-changes:
-  en: b4ded7b41999584d
-  zh: 49c3f355a5559cbd
+  en: 0fd2841ea23b8cd6
+  zh: 1138a25ac478eaa8
 /persistence-release-dsh-v0-0-1-rc-3/verification:
   en: 8ccca317964523b1
   zh: 2c8b3e70a3320778

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.3.md

@@ -92,22 +92,22 @@ changes:
 
 <!-- persistence-release-changes:start -->
 
-Detected 12 changed roots and 12 structural differences. The minimum below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
+Detected 12 changed roots and 12 structural differences. The review requirement below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
 
-| Path | Change | Current minimum |
+| Path | Change | Review requirement |
 |---|---|---|
-| `event:agent/inbox/spliced.data.inserted[].source.kind` | `type-changed` | `version-bump` |
-| `event:compact/end` | `root-removed` | `version-bump` |
-| `event:compact/prune` | `root-removed` | `version-bump` |
-| `event:compact/start` | `root-removed` | `version-bump` |
-| `event:compact/summary` | `root-removed` | `version-bump` |
-| `event:compaction/end` | `root-added` | `same-version` |
-| `event:compaction/prune` | `root-added` | `same-version` |
-| `event:compaction/start` | `root-added` | `same-version` |
-| `event:compaction/summary` | `root-added` | `same-version` |
-| `event:hook/invoked.data.dialect` | `type-changed` | `version-bump` |
-| `event:session/title-llm-request.data.messages[].source.kind` | `type-changed` | `version-bump` |
-| `event:user/message.data.source.kind` | `type-changed` | `version-bump` |
+| `event:agent/inbox/spliced.data.inserted[].source.kind` | `type-changed` | `review-required` |
+| `event:compact/end` | `root-removed` | `review-required` |
+| `event:compact/prune` | `root-removed` | `review-required` |
+| `event:compact/start` | `root-removed` | `review-required` |
+| `event:compact/summary` | `root-removed` | `review-required` |
+| `event:compaction/end` | `root-added` | `not-required` |
+| `event:compaction/prune` | `root-added` | `not-required` |
+| `event:compaction/start` | `root-added` | `not-required` |
+| `event:compaction/summary` | `root-added` | `not-required` |
+| `event:hook/invoked.data.dialect` | `type-changed` | `review-required` |
+| `event:session/title-llm-request.data.messages[].source.kind` | `type-changed` | `review-required` |
+| `event:user/message.data.source.kind` | `type-changed` | `review-required` |
 
 <!-- persistence-release-changes:end -->
 

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.0.1-rc.3.zh.md

@@ -92,22 +92,22 @@ changes:
 
 <!-- persistence-release-changes:start -->
 
-检测到 12 个根类型变化、12 项结构差异。下表的最低要求按当前规则计算，只用于比较；不表示旧版本曾遵守这些规则，也不证明迁移或运行时兼容性。
+检测到 12 个根类型变化、12 项结构差异。下表的审查要求按当前规则计算，只用于比较；不表示旧版本曾遵守这些规则，也不证明迁移或运行时兼容性。
 
-| 路径 | 变化 | 当前最低要求 |
+| 路径 | 变化 | 审查要求 |
 |---|---|---|
-| `event:agent/inbox/spliced.data.inserted[].source.kind` | `type-changed` | `version-bump` |
-| `event:compact/end` | `root-removed` | `version-bump` |
-| `event:compact/prune` | `root-removed` | `version-bump` |
-| `event:compact/start` | `root-removed` | `version-bump` |
-| `event:compact/summary` | `root-removed` | `version-bump` |
-| `event:compaction/end` | `root-added` | `same-version` |
-| `event:compaction/prune` | `root-added` | `same-version` |
-| `event:compaction/start` | `root-added` | `same-version` |
-| `event:compaction/summary` | `root-added` | `same-version` |
-| `event:hook/invoked.data.dialect` | `type-changed` | `version-bump` |
-| `event:session/title-llm-request.data.messages[].source.kind` | `type-changed` | `version-bump` |
-| `event:user/message.data.source.kind` | `type-changed` | `version-bump` |
+| `event:agent/inbox/spliced.data.inserted[].source.kind` | `type-changed` | `review-required` |
+| `event:compact/end` | `root-removed` | `review-required` |
+| `event:compact/prune` | `root-removed` | `review-required` |
+| `event:compact/start` | `root-removed` | `review-required` |
+| `event:compact/summary` | `root-removed` | `review-required` |
+| `event:compaction/end` | `root-added` | `not-required` |
+| `event:compaction/prune` | `root-added` | `not-required` |
+| `event:compaction/start` | `root-added` | `not-required` |
+| `event:compaction/summary` | `root-added` | `not-required` |
+| `event:hook/invoked.data.dialect` | `type-changed` | `review-required` |
+| `event:session/title-llm-request.data.messages[].source.kind` | `type-changed` | `review-required` |
+| `event:user/message.data.source.kind` | `type-changed` | `review-required` |
 
 <!-- persistence-release-changes:end -->
 

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.1.0-rc.7.i18n.yaml

@@ -21,8 +21,8 @@
   en: af9cea43334ee692
   zh: c6c8bd0d6a17718a
 /persistence-release-dsh-v0-1-0-rc-7/structural-changes:
-  en: 5178d26722926711
-  zh: bfe39111dd34ff48
+  en: 1a08248deb5e841c
+  zh: b5dd3c2ac161a100
 /persistence-release-dsh-v0-1-0-rc-7/verification:
   en: 8ccca317964523b1
   zh: 2c8b3e70a3320778

package/references/official-docs/docs/persistence-changes/releases/dsh-v0.1.0-rc.7.md

@@ -59,11 +59,11 @@ changes:
 
 <!-- persistence-release-changes:start -->
 
-Detected 1 changed root and 1 structural difference. The minimum below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
+Detected 1 changed root and 1 structural difference. The review requirement below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.
 
-| Path | Change | Current minimum |
+| Path | Change | Review requirement |
 |---|---|---|
-| `event:assistant/chunk.data.chunk.replayState` | `type-changed` | `version-bump` |
+| `event:assistant/chunk.data.chunk.replayState` | `type-changed` | `review-required` |
 
 <!-- persistence-release-changes:end -->