release-skill 0.1.7 → 0.1.8

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.7",
+      "version": "0.1.8",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.7.",
+      "Prepare a release plan for version 0.1.8.",
       "Help me understand the release workflow."
     ]
   }

package/.kimi-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "release-skill",
+  "version": "0.1.8",
+  "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
+  "author": {
+    "name": "广州市风荷科技有限公司"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ifoohoo/release-skill#readme",
+  "keywords": [
+    "release",
+    "publish",
+    "governance",
+    "skill",
+    "claude-code",
+    "codex",
+    "kimi-code"
+  ],
+  "skills": "./adapters/kimi/skills/",
+  "interface": {
+    "displayName": "Release Skill",
+    "shortDescription": "Safe preparation and frozen GitHub/npm publishing",
+    "longDescription": "Prepares byte-faithful public snapshots without rewriting project source files and publishes approved frozen GitHub/npm artifacts. Full happy end verification confirms consumer installation from frozen Git ref.",
+    "developerName": "ifoohoo",
+    "websiteURL": "https://github.com/ifoohoo/release-skill"
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.1.8 locale=en baseline=sha256:1e1a0af9d5807bceb7af1eae88b726f67e6811dba4db579fd625c07f3bdbca89 -->
+## [0.1.8] - 2026-07-23
+
+v0.1.8 adds Kimi Code as a first-class plugin host without rewriting the already-published v0.1.7 artifacts. Kimi delivery uses a generated self-contained adapter and a fail-closed, plan-bound manual installation attestation because Kimi Code has no scriptable non-interactive plugin installation interface. The npm package name (`release-skill`), publishing identity (`publisher: mzdbxqh`), public repository (`ifoohoo/release-skill`), and corporate maintainer remain unchanged.
+
+### Changed
+
+- **Kimi Code plugin delivery and verification**: v0.1.8 adds the root
+  `.kimi-plugin/plugin.json`, a generated self-contained `adapters/kimi/` bundle,
+  and public installation guidance. Because Kimi Code exposes no scriptable
+  non-interactive plugin installation interface, production publish emits a
+  version-pinned manual installation requirement and enters `PARTIAL`; an
+  isolated `KIMI_CODE_HOME` installation and a trusted attestation bound
+  independently to the frozen plan digest and payload digest are required before
+  `reconcile` can reach `PUBLISHED` and `verify` can reach `VERIFIED`.
+- **Immutable v0.1.7 history preserved**: the existing v0.1.7 Git tag,
+  GitHub Release, npm version, and public commit remain untouched. The v0.1.8
+  production plan binds the published v0.1.7 commit
+  `fe5897456d4166a2ec60e99405836b122562b80d` as its previous public baseline.
+<!-- release-skill:changelog:end version=0.1.8 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.1.7 locale=en baseline=sha256:e41fd6460f5bb63343547f04b08e2cfcdd8a64cb53806cbcf39870a2fe27b03e -->
 ## [0.1.7] - 2026-07-23
 

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.1.7 -->
+<!-- release-skill:release-version: 0.1.8 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -35,6 +35,77 @@ release-skill help
 
 You should see the version number and the list of available commands.
 
+## Install as a Kimi Code plugin
+
+Kimi Code is a supported plugin host alongside Claude Code and Codex. The
+Kimi Code plugin manifest lives at `.kimi-plugin/plugin.json`, mirroring
+`.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`, and the package
+ships `adapters/kimi/` next to `adapters/claude/` and `adapters/codex/`.
+
+Kimi Code has an interactive plugin marketplace but **no scriptable,
+non-interactive install API**. release-skill therefore models Kimi installation
+as a version-pinned **manual** install plus trusted observation/attestation:
+`publish`/`verify` never auto-install Kimi plugins. The closed loop is:
+
+1. `publish` performs the automated writes (Git branch/tag, npm, GitHub
+   Release), then reaches the `kimi-marketplace-install` checkpoint. Because
+   there is no scriptable install, that checkpoint **fails closed** and the run
+   lands in `PARTIAL` — the successful automated writes are NOT undone. The
+   checkpoint observation (and the requirement file below) gives the isolated
+   `KIMI_CODE_HOME`, the pinned install URL, and the attestation path.
+2. Read the requirement at
+   `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-manual-install.json`.
+3. Launch Kimi Code with that **isolated** home so the managed copy lands inside
+   it (do not use your ordinary `~/.kimi-code`):
+
+   ```
+   HOME=<kimiCodeHome> KIMI_CODE_HOME=<kimiCodeHome> kimi
+   ```
+
+   The plugin installs to `<kimiCodeHome>/plugins/managed/<plugin>/`.
+4. In that isolated session, install from the release tag pinned to the exact
+   version (never the bare repository URL, which installs the latest release or
+   default branch), confirm the trust prompt, then reload:
+
+   ```
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.1.8
+   /plugins reload
+   ```
+
+5. Write the attestation JSON to
+   `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-attestation.json`.
+   `planDigest` MUST be the frozen **plan** digest; `payloadDigest` MUST be the
+   frozen snapshot **payload** digest; `installPath` MUST be the isolated
+   managed directory above; `attestedAt` must not be in the future and
+   `expiresAt` must be within 24 hours of `attestedAt`. Example:
+
+```json
+{
+  "consumer": "kimi",
+  "plugin": "release-skill",
+  "version": "0.1.8",
+  "entrySkill": "release-help",
+  "repo": "ifoohoo/release-skill",
+  "ref": "release-skill-v0.1.8",
+  "installPath": "<kimiCodeHome>/plugins/managed/release-skill",
+  "planDigest": "<64-hex frozen plan digest>",
+  "payloadDigest": "<64-hex frozen snapshot payload digest>",
+  "attestedBy": "<person responsible>",
+  "attestedAt": "2026-07-23T00:00:00.000Z",
+  "expiresAt": "2026-07-23T12:00:00.000Z"
+}
+```
+
+6. Run `release-skill reconcile --run <publish-run>` (promotes `PARTIAL` →
+   `PUBLISHED`) and then `release-skill verify --run <reconcile-run>` (→
+   `VERIFIED`). Both read the attestation from the same plan-digest-keyed
+   directory, so their fresh run directories do not lose the proof.
+
+Installing into the ordinary `~/.kimi-code` is **not** acceptable proof: the
+attested `installPath` must resolve inside the requirement's isolated
+`KIMI_CODE_HOME` managed root, otherwise verification fails closed and the Kimi
+unit never reaches `VERIFIED`.
+
 ## Development Install (Local Checkout)
 
 For development or when working from source:
@@ -273,7 +344,7 @@ requirements.
 
 Use a `snapshot-verify` gate for checks that should run against a disposable
 writable copy of the frozen public snapshot. Use `consumer-verify` for commands
-that must run from an exact isolated npm/Claude/Codex installation root. Gate
+that must run from an exact isolated npm/Claude/Codex/Kimi Code installation root. Gate
 commands are executable arrays, not shell strings, and must declare unit,
 distribution when applicable, cwd, timeout, and environment allowlist.
 

package/INSTALL.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.1.7 -->
+<!-- release-skill:release-version: 0.1.8 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本
@@ -10,9 +10,7 @@
 
 ## 从 npm 安装（推荐）
 
-公开版本只有在不可变生产计划经过批准、发布并达到 `VERIFIED` 后才算完整。对于更新的
-源码检出，只有当 `npm view release-skill version` 返回该精确版本后才使用 npm 安装；
-在此之前请使用下文的源码检出方式。
+公开版本只有在不可变生产计划经过批准、发布并达到 `VERIFIED` 后才算完整。对于尚未公开发布的源码版本，只有当 `npm view release-skill version` 返回该精确版本后才使用 npm 安装；在此之前请使用下文的源码检出方式。
 
 ```bash
 npm install -g release-skill
@@ -34,6 +32,72 @@ release-skill help
 
 输出中应包含版本号和可用命令列表。
 
+## 安装为 Kimi Code 插件
+
+Kimi Code 是与 Claude Code 和 Codex 并列的受支持插件宿主。Kimi Code 插件
+清单位于 `.kimi-plugin/plugin.json`，与 `.claude-plugin/plugin.json`、
+`.codex-plugin/plugin.json` 对应；包内同时提供 `adapters/kimi/`，与
+`adapters/claude/`、`adapters/codex/` 并列。
+
+Kimi Code 有交互式插件市场，但**没有可脚本化的非交互安装接口**。因此
+release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观测/人工证明”：
+`publish`/`verify` 从不对 Kimi 执行自动安装。完整闭环如下：
+
+1. `publish` 先完成自动化写入（Git branch/tag、npm、GitHub Release），随后
+   到达 `kimi-marketplace-install` 检查点。由于没有可脚本化安装接口，该检查点
+   **失败关闭**，整个 run 落入 `PARTIAL`——已成功的自动化写入**不会**被撤销。
+   检查点输出（以及下面的 requirement 文件）会给出隔离的 `KIMI_CODE_HOME`、
+   钉死的安装 URL 与证明写入路径。
+2. 读取 requirement：
+   `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-manual-install.json`。
+3. 用该**隔离** home 启动 Kimi Code，使 managed 副本落在其中（不要使用你日常的
+   `~/.kimi-code`）：
+
+   ```
+   HOME=<kimiCodeHome> KIMI_CODE_HOME=<kimiCodeHome> kimi
+   ```
+
+   插件会安装到 `<kimiCodeHome>/plugins/managed/<plugin>/`。
+4. 在该隔离会话中，从钉死到精确版本的 release tag 安装（切勿使用裸仓库地址，
+   它会安装最新 release 或默认分支），确认信任提示后重新加载：
+
+   ```
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.1.8
+   /plugins reload
+   ```
+
+5. 把证明 JSON 写入
+   `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-attestation.json`。
+   `planDigest` 必须是冻结**计划**摘要；`payloadDigest` 必须是冻结快照**载荷**
+   摘要；`installPath` 必须是上面的隔离 managed 目录；`attestedAt` 不得为未来
+   时间，`expiresAt` 必须在 `attestedAt` 之后 24 小时内。示例：
+
+```json
+{
+  "consumer": "kimi",
+  "plugin": "release-skill",
+  "version": "0.1.8",
+  "entrySkill": "release-help",
+  "repo": "ifoohoo/release-skill",
+  "ref": "release-skill-v0.1.8",
+  "installPath": "<kimiCodeHome>/plugins/managed/release-skill",
+  "planDigest": "<64 位十六进制冻结计划摘要>",
+  "payloadDigest": "<64 位十六进制冻结快照载荷摘要>",
+  "attestedBy": "<责任人>",
+  "attestedAt": "2026-07-23T00:00:00.000Z",
+  "expiresAt": "2026-07-23T12:00:00.000Z"
+}
+```
+
+6. 运行 `release-skill reconcile --run <publish-run>`（把 `PARTIAL` 提升为
+   `PUBLISHED`），再运行 `release-skill verify --run <reconcile-run>`（→
+   `VERIFIED`）。两者都从同一个按计划摘要命名的目录读取证明，因此它们各自的
+   新 run 目录不会丢失该证明。
+
+把插件安装到日常的 `~/.kimi-code` **不**构成有效证明：证明中的 `installPath`
+必须解析到 requirement 给出的隔离 `KIMI_CODE_HOME` managed 根之内，否则验证
+失败关闭，Kimi 单元绝不进入 `VERIFIED`。
+
 ## 开发安装（本地源码）
 
 用于开发或尚未公开发布的源码候选：
@@ -51,8 +115,7 @@ CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
 "${CLI[@]}" help
 ```
 
-当 `npm view release-skill version` 已确认目标版本公开并安装后，等价的 npm 入口是
-`CLI=(release-skill)`。同一次运行不要混用 npm 与源码入口。
+当 `npm view release-skill version` 已确认目标版本公开并安装后，等价的 npm 入口是 `CLI=(release-skill)`。同一次运行不要混用 npm 与源码入口。
 
 ## 首次运行
 
@@ -62,8 +125,7 @@ CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
 "${CLI[@]}" help
 ```
 
-如果项目尚无 `.release-skill/project.yaml`，把完整只读报告写入临时文件，只查看其中
-确定性的 `compactSummary`（紧凑摘要）：
+如果项目尚无 `.release-skill/project.yaml`，把完整只读报告写入临时文件，只查看其中确定性的 `compactSummary`（紧凑摘要）：
 
 ```bash
 PROJECT=/path/to/your/project
@@ -77,9 +139,7 @@ printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
 ```
 
-紧凑摘要只是审阅视图，不是授权；`setupDigest` 仍绑定完整事实、候选和 answers。若
-`proposalConflicts` 非空，必须由人工修正冲突的仓库/映射权威事实后重跑 setup，不能
-猜测选边。没有冲突时，机械提取机器提案：
+紧凑摘要只是审阅视图，不是授权；`setupDigest` 仍绑定完整事实、候选和 answers。若 `proposalConflicts` 非空，必须由人工修正冲突的仓库/映射权威事实后重跑 setup，不能猜测选边。没有冲突时，机械提取机器提案：
 
 ```bash
 SETUP_SESSION='/上一步打印的会话目录绝对路径'
@@ -88,13 +148,13 @@ REPORT="$SETUP_SESSION/discovery.json"
 ANSWERS="$SETUP_SESSION/answers.json"
 BOUND_REPORT="$SETUP_SESSION/bound.json"
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+
 "${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
 printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
 ```
 
-人工只确认一次绑定摘要和精确摘要值，然后使用已确认字面量首次创建。结果必须是
-`CONFIG_CREATED`；第二次 setup 必须是 `ALREADY_CONFIGURED`，随后运行 assess。
+人工只确认一次绑定摘要和精确摘要值，然后使用已确认字面量首次创建。结果必须是 `CONFIG_CREATED`；第二次 setup 必须是 `ALREADY_CONFIGURED`，随后运行 assess。
 
 ```bash
 SETUP_SESSION=<上一步打印的会话目录绝对路径>
@@ -115,10 +175,7 @@ node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>
 node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
 ```
 
-解释器/包管理器间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除且默认不选。项目特有 hook/gate
-只能经人工审阅后增量注册：hook 编辑 `projectConfig.hooks`；gate 编辑
-`verificationGates` 并将同一 id 加入 `selectedGateIds`，然后重跑绑定 dry-run。人工文件使用 `mode: preserve`；显式跨单元共享源使用
-`sourceScope: workspace`。
+解释器/包管理器间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除且默认不选。项目特有 hook/gate 只能经人工审阅后增量注册：hook 编辑 `projectConfig.hooks`；gate 编辑 `verificationGates` 并将同一 id 加入 `selectedGateIds`，然后重跑绑定 dry-run。人工文件使用 `mode: preserve`；显式跨单元共享源使用 `sourceScope: workspace`。
 
 ### 进阶 schema 参考——不是首次运行主路径
 
@@ -160,17 +217,11 @@ node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})
 }
 ```
 
-这个外壳仅供参考。正常 setup 必须使用机器提案；只有确认不存在历史公开版本时才可
-使用 `mode: none`。人工增量加入 gate 时，其 id 必须与 `selectedGateIds` 精确一致，
-snapshot gate 及其依赖必须存在于 `publicFiles`。详见
-[README 首次接入章节](README.zh-CN.md#首次接入不加载完整报告的确定性流程)。
+这个外壳仅供参考。正常 setup 必须使用机器提案；只有确认不存在历史公开版本时才可使用 `mode: none`。
 
-已有配置永远不会被重新生成或覆盖。无法发现 GitHub/npm 渠道的项目返回
-`LOCAL_ONLY_DETECTED`，不会冒充生产就绪。
+已有配置永远不会被重新生成或覆盖。无法发现 GitHub/npm 渠道的项目返回 `LOCAL_ONLY_DETECTED`，不会冒充生产就绪。
 
-自动 create-once 写入使用 v0.1.3 随包提供、带摘要登记的 `darwin-arm64` 原生预构建。
-其他平台以 `SAFE_WRITE_UNAVAILABLE` 失败关闭；此时保留只读报告，由人工首次创建经审阅
-的文件，不得启用不安全的路径写入兜底。
+自动 create-once 写入使用 v0.1.3 随包提供、带摘要登记的 `darwin-arm64` 原生预构建。其他平台以 `SAFE_WRITE_UNAVAILABLE` 失败关闭；此时保留只读报告，由人工首次创建经审阅的文件，不得启用不安全的路径写入兜底。
 
 配置存在后，检查发布就绪度：
 
@@ -178,12 +229,9 @@ snapshot gate 及其依赖必须存在于 `publicFiles`。详见
 "${CLI[@]}" assess --root /path/to/your/project --offline --json
 ```
 
-该命令只读地检查项目结构、配置、文档和供应链；未显式传入 `--output` 时不写报告，
-也不运行项目 hook。
+该命令只读地检查项目结构、配置、文档和供应链；未显式传入 `--output` 时不写报告，也不运行项目 hook。
 
-`prepare` 不同：它在目标项目的 `.release-skill/` 下写入发布工件，并可能运行已配置
-hook。hook 是无沙箱的任意进程，可能写到项目外、访问凭据、使用网络或执行远端写入。
-授予 `--acknowledge-hook-side-effects` 前必须审阅可执行文件、参数和工作目录。
+`prepare` 不同：它在目标项目的 `.release-skill/` 下写入发布工件，并可能运行已配置 hook。hook 是无沙箱的任意进程，可能写到项目外、访问凭据、使用网络或执行远端写入。授予 `--acknowledge-hook-side-effects` 前必须审阅可执行文件、参数和工作目录。
 
 Git 仓库应保留人工配置，同时忽略生成的权威文件和证据：
 
@@ -236,8 +284,7 @@ releaseUnits:
 
 ### 进阶：hook（可选）
 
-hook 是可选的任意本地进程。prepare 使用 hook 时必须显式授予
-`--acknowledge-hook-side-effects`：
+hook 是可选的任意本地进程。prepare 使用 hook 时必须显式授予 `--acknowledge-hook-side-effects`：
 
 ```yaml
 hooks:
@@ -254,9 +301,7 @@ hooks:
 
 ### 进阶：验证 gate（可选）
 
-`snapshot-verify` 用于冻结公开快照的一次性可写副本；`consumer-verify` 用于精确且
-隔离安装后的 npm/Claude/Codex 根目录。gate 使用可执行文件数组而不是 shell 字符串，
-并声明 unit、必要时的 distribution、cwd、超时和环境变量白名单。
+`snapshot-verify` 用于冻结公开快照的一次性可写副本；`consumer-verify` 用于精确且隔离安装后的 npm/Claude/Codex/Kimi Code 根目录。gate 使用可执行文件数组而不是 shell 字符串，并声明 unit、必要时的 distribution、cwd、超时和环境变量白名单。
 
 ```yaml
 verificationGates:
@@ -269,21 +314,13 @@ verificationGates:
     envAllowlist: []
 ```
 
-这个自包含示例只读取已映射的公开文件。若替换成项目脚本，该脚本及全部依赖必须
-存在于冻结公开快照；gate 不能借用父工作空间中的测试、开发依赖或 `node_modules`。
+这个自包含示例只读取已映射的公开文件。若替换成项目脚本，该脚本及全部依赖必须存在于冻结公开快照；gate 不能借用父工作空间中的测试、开发依赖或 `node_modules`。
 
-当计划的当前阶段包含 gate 时，prepare 或 verify 必须传入
-`--acknowledge-gate-side-effects`。hook/gate 都是无网络沙箱的项目进程；
-release-skill 约束其输入与证据，但无法保证自定义命令不修改文件或不访问网络。
-禁止把 Git push、tag、默认分支修改、GitHub Release 或 npm publish 注册为
-hook/gate，它们只能由受控的计划动作完成。
+当计划的当前阶段包含 gate 时，prepare 或 verify 必须传入 `--acknowledge-gate-side-effects`。hook/gate 都是无网络沙箱的项目进程；release-skill 约束其输入与证据，但无法保证自定义命令不修改文件或不访问网络。禁止把 Git push、tag、默认分支修改、GitHub Release 或 npm publish 注册为 hook/gate，它们只能由受控的计划动作完成。
 
 ### 进阶：发布文档刷新（可选）
 
-发布单元可以声明 `releaseDocuments`，用一份结构化说明源确定性刷新 README 受管
-区域和 CHANGELOG 当前版本条目。该命令离线运行：不联网、不调用大模型、不自动
-翻译；只改写声明过的受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管
-条目，其他字节全部保留。`prepare` 只检查新鲜度，不写工作树。
+发布单元可以声明 `releaseDocuments`，用一份结构化说明源确定性刷新 README 受管区域和 CHANGELOG 当前版本条目。该命令离线运行：不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目，其他字节全部保留。`prepare` 只检查新鲜度，不写工作树。
 
 ```yaml
 # .release-skill/project.yaml 的发布单元片段
@@ -308,29 +345,6 @@ releaseUnits:
           regions: [latest-release]
 ```
 
-`notesSource` 和所有目标路径均相对发布单元根；`versionMarkers[].pattern` 必须与
-README 现有唯一版本标记精确匹配，刷新只替换机器版本值。说明源位于发布单元根
-下，`version` 必须与解析出的单元版本一致，每个配置语种恰好出现一次且 summary
-非空、至少一个变更类别有条目；YAML alias、重复键、未知字段和语种回退均失败
-关闭：
-
-```yaml
-# release-notes/0.1.6.yaml
-version: 0.1.6
-date: 2026-07-21
-locales:
-  en:
-    summary: Deterministic multilingual release-document refresh.
-    changes:
-      added:
-        - Refresh managed README regions and changelogs from one source.
-  zh-CN:
-    summary: 从同一说明源确定性刷新多语种发布文档。
-    changes:
-      added:
-        - 自动刷新 README 受管区域和 CHANGELOG。
-```
-
 先只读演练，确认后再带三项绑定写入：
 
 ```bash
@@ -339,12 +353,7 @@ locales:
   --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 ```
 
-`refreshDigest` 绑定规范说明对象、配置投影和按路径排序的逐文件新旧摘要，不绑定
-时间、绝对路径或展示文本。摘要不匹配以 `RELEASE_DOCS_REFRESH_STALE` 失败关闭且
-零写入；候选无变化时返回 `clean` 同样零写入。该授权只覆盖声明的本地文档目标，
-不是 hook、提交、push、publish 或安装的授权。`prepare` 报告 `RELEASE_DOCS_STALE`
-时，按“运行演练 → 审阅文件与语种 → 确认本地写入 → 审阅并提交 → 重新 prepare”
-恢复。完整契约见 README 的发布文档刷新章节。
+`refreshDigest` 绑定规范说明对象、配置投影和按路径排序的逐文件新旧摘要，不绑定时间、绝对路径或展示文本。摘要不匹配以 `RELEASE_DOCS_REFRESH_STALE` 失败关闭且零写入；候选无变化时返回 `clean` 同样零写入。该授权只覆盖声明的本地文档目标，不是 hook、提交、push、publish 或安装的授权。完整契约见 README 的发布文档刷新章节。
 
 ### 生产分支策略
 
@@ -352,12 +361,9 @@ locales:
 
 - `create-release-branch`：创建此前不存在且不可变的 release 分支；
 - `advance-existing-branch`：从精确绑定的公开基线用普通非 force push 快进已有分支；
-- `initialize-default-branch`：创建不存在的标准分支；只有同时审阅
-  `setAsDefaultBranch` 与 `expectedCurrentDefaultBranch` 后，计划才可增加显式默认分支动作。
+- `initialize-default-branch`：创建不存在的标准分支；只有同时审阅 `setAsDefaultBranch` 与 `expectedCurrentDefaultBranch` 后，计划才可增加显式默认分支动作。
 
-远端漂移、非快进或默认分支不符合预期时必须停止并由人工介入。所有策略都禁止覆盖
-远端历史。新建 ref 仅使用 `--force-with-lease=<ref>:` 作为“目标必须不存在”的原子
-断言；推进已有分支使用普通非 force push。
+远端漂移、非快进或默认分支不符合预期时必须停止并由人工介入。所有策略都禁止覆盖远端历史。新建 ref 仅使用 `--force-with-lease=<ref>:` 作为“目标必须不存在”的原子断言；推进已有分支使用普通非 force push。
 
 ```yaml
 # create-release-branch：目标分支必须不存在
@@ -393,34 +399,23 @@ production:
   expectedCurrentDefaultBranch: old-public-branch
 ```
 
-后两种策略必须在线执行 production prepare。任何不一致都应停止并审阅；只有检查
-真实远端状态后才能人工更新权威配置，禁止 force push 或弱化基线。
+后两种策略必须在线执行 production prepare。任何不一致都应停止并审阅；只有检查真实远端状态后才能人工更新权威配置，禁止 force push 或弱化基线。
 
 ## 保护人工维护内容
 
-README 文案、slogan、示例、排版及其他人工源文件始终是权威。release-skill 只按
-`publicFiles` 映射做快照，不重新生成或覆盖源 README。每次人工编辑后重新 prepare，
-并批准新的不可变计划；不得编辑冻结快照或复用旧批准绕过变化。
+README 文案、slogan、示例、排版及其他人工源文件始终是权威。release-skill 只按 `publicFiles` 映射做快照，不重新生成或覆盖源 README。每次人工编辑后重新 prepare，并批准新的不可变计划；不得编辑冻结快照或复用旧批准绕过变化。
 
 如果已有公开副本发生漂移，显式选择：
 
-- **merge（合并）**：比较真实远端内容，把接受的改动合并回人工源文件，然后把
-  `previousPublicBaseline` 绑定到精确不可变的 `repo`/`ref`/`commit`，再 prepare；
+- **merge（合并）**：比较真实远端内容，把接受的改动合并回人工源文件，然后把 `previousPublicBaseline` 绑定到精确不可变的 `repo`/`ref`/`commit`，再 prepare；
 - **adopt（采纳）**：接受远端为新的事实来源，先带回人工源文件，再更新同一基线绑定；
 - **reject（拒绝）**：停止并调查。不得改成 `mode: none` 绕过漂移或唯一性检查。
 
 ## 下一步
 
 - 阅读[完整中文 README](README.zh-CN.md)了解整个工作流。
-- 缺少配置时运行 `"${CLI[@]}" setup --root <your-project> --json`，在人工决策完成前
-  保持默认 dry-run。
+- 缺少配置时运行 `"${CLI[@]}" setup --root <your-project> --json`，在人工决策完成前保持默认 dry-run。
 - 运行 `"${CLI[@]}" assess --root <your-project> --offline` 检查发布就绪度。
-- 运行 `"${CLI[@]}" prepare --root <your-project> --offline` 生成发布计划；
-  release-skill 自身只做本地写入，但项目 hook 可能执行远端操作。
-- 生产前为每个 unit 配置 `previousPublicBaseline`。已有公开版本必须使用
-  `mode: bound`，绑定精确 `repo`、`ref` 和 `commit`，再运行
-  `"${CLI[@]}" prepare --root <your-project> --online --production`。默认观察器只证明
-  ref 到 commit 的映射，不下载远端内容；目标 branch/tag/Release/npm 唯一性由
-  publish 全局预检在任何 execute 前检查。
-- 生产命令只使用 `prepare --json` 返回的不可变 `planPath`，以及 `approve --json`
-  返回的不可变 `approvalPath`。可变的 latest 别名不能作为生产权威。
+- 运行 `"${CLI[@]}" prepare --root <your-project> --offline` 生成发布计划；release-skill 自身只做本地写入，但项目 hook 可能执行远端操作。
+- 生产前为每个 unit 配置 `previousPublicBaseline`。已有公开版本必须使用 `mode: bound`，绑定精确 `repo`、`ref` 和 `commit`，再运行 `"${CLI[@]}" prepare --root <your-project> --online --production`。
+- 生产命令只使用 `prepare --json` 返回的不可变 `planPath`，以及 `approve --json` 返回的不可变 `approvalPath`。