release-skill 0.1.4 → 0.1.6

package/bin/release-skill.mjs

@@ -23,12 +23,32 @@ try {
 }
 
 if (!bundleExists) {
+  // Fail closed with static text only: never interpolate bundlePath (or any
+  // other machine-specific value) so a copied/installed launcher cannot leak
+  // absolute paths, usernames, or host layout on stdout/stderr. This branch
+  // is self-contained by design — it must not import src/* or rely on the
+  // missing bundle's redaction helpers.
   console.error(
-    `Error: release-skill bundle not found at:\n  ${bundlePath}\n` +
-    `The bundle is required for installed-plugin execution.\n` +
-    `Reinstall the plugin or run 'node scripts/build-bundle.mjs' in the source checkout.`,
+    `Error: release-skill bundle not found (release-skill.bundle.mjs).\n` +
+    `The self-contained bundle is required for installed-plugin execution.\n` +
+    `Reinstall the plugin, or run 'node scripts/build-bundle.mjs' in a source checkout to rebuild it.`,
   );
   process.exit(1);
 }
 
-await import(bundlePath);
+// The bundle owns the command lifecycle: its entry awaits command completion
+// and exits with the real business exit code (success, business errors,
+// handled async rejections, unknown commands). The launcher only guards the
+// load itself: if the bundle cannot be evaluated (corrupt or incompatible
+// build), fail closed with static text only — module-load failures carry
+// absolute paths in their messages, so the failure is never interpolated.
+try {
+  await import(bundlePath);
+} catch {
+  console.error(
+    `Error: release-skill bundle failed to load (release-skill.bundle.mjs).\n` +
+    `The self-contained bundle is required for installed-plugin execution.\n` +
+    `Reinstall the plugin, or run 'node scripts/build-bundle.mjs' in a source checkout to rebuild it.`,
+  );
+  process.exit(1);
+}

package/native/safe-write/binding.gyp

@@ -24,7 +24,8 @@
             "xcode_settings": {
               "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
               "CLANG_CXX_LANGUAGE_STANDARD": "c++20",
-              "MACOSX_DEPLOYMENT_TARGET": "11.0"
+              "MACOSX_DEPLOYMENT_TARGET": "11.0",
+              "GCC_GENERATE_DEBUGGING_SYMBOLS": "NO"
             }
           }
         ],

package/native/safe-write/prebuilds.json

@@ -3,7 +3,7 @@
   "prebuilds": {
     "darwin-arm64": {
       "path": "prebuilds/darwin-arm64/safe_write.node",
-      "sha256": "a0e39732c359f3faa23715e6d17d8bc5fec5c5b86e0390220e1beb9f5def2d2e",
+      "sha256": "f5ffc367a1c49fed812dc430246cd8b07fb722653cc9738acabcedb17d6bab67",
       "exports": [
         "openRoot",
         "openDir",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
   "scripts": {
     "build": "node --check src/**/*.mjs && node scripts/build-bundle.mjs",
     "test": "node --test test/*.test.mjs",
-    "test:no-dogfood": "node --test $(ls test/*.test.mjs | grep -v -E 'dogfood|artifacts-safe-fs-native-seam')",
+    "test:no-dogfood": "node --test $(ls test/*.test.mjs | grep -v -E 'dogfood|artifacts-safe-fs-native-seam|setup-live-samples')",
     "typecheck": "node --check src/**/*.mjs bin/*.mjs",
     "sync:skills": "node scripts/sync-skills.mjs",
     "sync:skills:check": "node scripts/sync-skills.mjs --check",

package/references/.render-manifest.json

@@ -10,8 +10,8 @@
       "bytes": 7770
     },
     "02-project-config.md": {
-      "digest": "6c8d6262e5fe9c034ad961b01b8fed684adb6272a7ce4c0e4dd87bfb061519ac",
-      "bytes": 7017
+      "digest": "837f1643245f544011eddf336f31718fc05a1fe7dd4f181f627168a8ffcec183",
+      "bytes": 16501
     },
     "03-readme-quality.md": {
       "digest": "d74e41052592443ebbd450d0ace5f9b9b19c7a94db50f952b17c1c5a4c5dc230",
@@ -22,8 +22,8 @@
       "bytes": 4682
     },
     "05-evidence-and-errors.md": {
-      "digest": "63987751b6d3a74f02033d4e23daa1f3c30d299827de9d8242b425887607b2ac",
-      "bytes": 6658
+      "digest": "244cd989dc86031e69fbdce8ec299359c3495c4f4dad4c903b119ef0e7a39569",
+      "bytes": 8260
     },
     "06-adapter-contract.md": {
       "digest": "f727bfbdcd2bd6f95edc144a4fd61732ecaac2a49ffda296dbf6923f14a0c2f1",

package/references/02-project-config.md

@@ -49,6 +49,19 @@ releaseUnits:               # 发布单元数组，至少 1 个
     previousPublicBaseline: # 必填；每个 unit 独立声明
       mode: none            # none | bound
       # bound 时还必须提供 repo/ref/commit，可选 tree/manifestDigest
+    releaseDocuments:       # 可选；结构化双语发布文档刷新，缺省保持既有行为
+      notesSource: <string> # 说明源相对路径，仅允许 {version} 占位符与 .yaml/.yml/.json 后缀
+      locales: [<string>]   # 非空唯一语种数组，如 [en, zh-CN]
+      changelogs:           # 非空数组
+        - path: <string>
+          locale: <string>
+      readmes:              # 非空数组
+        - path: <string>
+          locale: <string>
+          regions: [<string>]  # 非空唯一受管区域 id
+          versionMarkers:      # 可选；id 唯一
+            - id: <string>
+              pattern: <string> # 含 {version} 占位符的精确标记模式
 
 verificationGates:         # 可选；定义会进入冻结计划摘要
   - id: <stable-id>
@@ -113,6 +126,17 @@ human-owned 权威源，然后重新 prepare、审阅并 approve；后续环节
 
 已有公开仓不得使用 `mode: none` 伪装成首次发布。示例中的 commit 只是校准时点证据；每轮 production prepare 都必须在线重观测。
 
+### 3.3 发布文档刷新（releaseDocuments）
+
+`releaseUnits[].releaseDocuments` 可选；未配置时保持既有行为。配置后，一份结构化说明源确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目；区域外字节、旧版本条目、前言、链接定义和人工说明逐字保留。核心命令不联网、不调用大模型、不自动翻译。
+
+- `notesSource` 与各目标路径均为发布单元根相对安全路径，不得为绝对路径，不得包含 `..`、反斜杠、空段或 NUL；`notesSource` 只允许 `{version}` 占位符与 `.yaml`、`.yml`、`.json` 后缀。
+- `locales` 非空且唯一；每个目标语种必须属于 `locales`，目标规范路径不得重复或发生大小写/Unicode 碰撞。
+- 说明源的 `version` 必须与 `version.source` 解析结果精确一致，`date` 为 `YYYY-MM-DD`；每个配置语种恰好出现一次，`summary` 和变更项去除首尾空白后非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。重复键、YAML alias/anchor、合并键、自定义标签、未知字段、缺少或多余语种、语种回退均失败关闭。
+- README 受管区域以 `<!-- release-skill:managed:start id=<region> -->` 与对应结束标记做字节偏移替换；版本标记必须唯一匹配且只替换机器值，零次或多次匹配拒绝写入。CHANGELOG 当前版本受管条目由含 `baseline` 摘要的注释包围，基线不符、非受管同版本条目或标记损坏返回冲突。
+- `docs refresh --unit <id>` 默认只读演练，输出逐文件相对路径、语种、新旧摘要和 `refreshDigest`；写入必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交。该授权只覆盖声明的本地文档目标，不包含 hook、提交、推送、发布或安装。
+- `prepare` 在 hook、基线、快照、远端检查和计划冻结前执行同一只读规划器：`clean` 继续，`changes` 以 `RELEASE_DOCS_STALE` 失败关闭并给出精确演练/写入参数。`prepare`、`publish`、`reconcile` 永不隐式刷新文档；刷新后重新 prepare 会自然改变快照、workspace digest 与 plan digest，使旧批准失效。
+
 ---
 
 ## 4. Hooks 参数约束

package/references/05-evidence-and-errors.md

@@ -21,6 +21,11 @@
 | `POST_PUBLISH_VERIFY_FAILED` | 发布后验证未通过 | 安装测试失败、泄漏审计未通过、provenance 验证失败 | 检查失败原因，可能需要人工干预 |
 | `SETUP_DIGEST_MISMATCH` | setup 事实或答案已漂移 | dry-run 后 README/package/manifest/remote/answers 发生变化，或确认摘要错误 | 重新运行 setup dry-run、审阅并确认新摘要 |
 | `CONFIG_EXISTS` | setup 目标配置已经存在 | 写入模式试图创建已有 `.release-skill/project.yaml` | 不覆盖；运行 assess 并人工增量编辑 |
+| `RELEASE_DOCS_INVALID` | 发布文档配置或说明数据语义非法 | `releaseDocuments` 配置不合规、说明源含重复键/alias/未知字段、版本漂移 | 修正配置或说明源后重新演练 |
+| `RELEASE_DOCS_TRANSLATION_MISSING` | 说明源缺少或多余配置语种 | `locales` 声明多个语种但说明源只含其一 | 补齐全部配置语种，禁止语种回退 |
+| `RELEASE_DOCS_CONFLICT` | 目标文档存在人工冲突 | 非受管同版本 CHANGELOG 条目、受管标记缺失/重复/损坏、版本标记非唯一 | 人工修复目标并保留人工修改后重新演练 |
+| `RELEASE_DOCS_REFRESH_STALE` | 写入确认绑定的候选已变化 | 演练后说明源或目标发生变化，仍用旧 `refreshDigest` 写入 | 重新演练取得新的 `refreshDigest` 并重新确认 |
+| `RELEASE_DOCS_STALE` | prepare 检测到发布文档未刷新 | 说明源已更新但 README/CHANGELOG 受管内容未同步 | `docs refresh` 演练 → 确认写入 → 审阅提交 → 重新 prepare |
 
 ---
 

package/schemas/.render-manifest.json

@@ -2,8 +2,8 @@
   "source": "schemas",
   "files": {
     "approval-record.schema.json": {
-      "digest": "38df0f095cc4b5be650a04513f8ea10cef5a6c3d0780ab38b0c5ee559d6ac7a5",
-      "bytes": 2611
+      "digest": "2ddac883435110e2c036cfadb00ce0c4d347a97d674b2c4ea9fcda3d72f81b8b",
+      "bytes": 3135
     },
     "artifact-lock.schema.json": {
       "digest": "6a5f4c826540b849571f173118bcbd778dfaceb4133034036ae565c3e9e353e5",
@@ -14,24 +14,24 @@
       "bytes": 1546
     },
     "artifact-policy.schema.json": {
-      "digest": "fa28b3856f2ed48b666458120c9b9d84d42c9ebfbec13bc866e8d71ecef6dea7",
-      "bytes": 2117
+      "digest": "86c9cab024ebe9c7f8ec3358fcc12d05b8ed246ab59da2b0acc6a517f31274ea",
+      "bytes": 2488
     },
     "evidence-event.schema.json": {
       "digest": "b7e14522a5aba818cab191545f23d2323be0e4c80566e9d3e4da576103a00490",
       "bytes": 2390
     },
     "release-plan.schema.json": {
-      "digest": "3647a554d7f8b1041078301b4de06c9aade0e1083ba8f6492cf4d3a825ea40ef",
-      "bytes": 4084
+      "digest": "13baa16d9a762cc04c7f28fc9d31ed81d381008c71eb044f4e97de252b4cc324",
+      "bytes": 22942
     },
     "release-project.schema.json": {
-      "digest": "6ae488bbad12563323892cc65f236a0ca3443aa6c0f4a17d69095a5c1af2574e",
-      "bytes": 6218
+      "digest": "4e46d6b1956a14d01471e7cf1cde3c0a6971c4f8844603fedd2a52f3535a43b6",
+      "bytes": 24167
     },
     "release-run.schema.json": {
-      "digest": "eeb16507f0d852ed1c53b0fbeeeda0ab1c15abea63554d6f4c127f75ca1dc673",
-      "bytes": 4037
+      "digest": "74f087f8815f00997c6ad3bac033660b9b69de226a6f5c48a96194dba0fa872c",
+      "bytes": 8917
     }
   }
 }

package/schemas/release-project.schema.json

@@ -200,6 +200,12 @@
                 },
                 "smokeExpectedJson": {
                   "type": "object"
+                },
+                "timeoutMs": {
+                  "type": "integer",
+                  "minimum": 30000,
+                  "maximum": 900000,
+                  "description": "Timeout in milliseconds for plugin marketplace install commands. Only valid for claude-plugin and codex-plugin distributions."
                 }
               },
               "allOf": [
@@ -219,6 +225,23 @@
                     ]
                   }
                 },
+                {
+                  "if": {
+                    "required": [
+                      "timeoutMs"
+                    ]
+                  },
+                  "then": {
+                    "properties": {
+                      "type": {
+                        "enum": [
+                          "claude-plugin",
+                          "codex-plugin"
+                        ]
+                      }
+                    }
+                  }
+                },
                 {
                   "if": {
                     "properties": {
@@ -422,6 +445,9 @@
                 }
               ]
             }
+          },
+          "releaseDocuments": {
+            "$ref": "#/definitions/releaseDocuments"
           }
         },
         "allOf": [
@@ -611,6 +637,121 @@
         }
       }
     },
+    "releaseDocuments": {
+      "type": "object",
+      "description": "Optional configuration-driven multilingual release-document refresh for one release unit. Absence preserves legacy behaviour. Lexical layer only; runtime path, locale-membership and collision checks apply additionally.",
+      "required": [
+        "notesSource",
+        "locales",
+        "changelogs",
+        "readmes"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "notesSource": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$)(?!.*\\{(?!version\\}))(?!.*(?<!\\{version)\\}).+\\.(?:yaml|yml|json)$"
+        },
+        "locales": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+          }
+        },
+        "changelogs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsChangelog"
+          }
+        },
+        "readmes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsReadme"
+          }
+        }
+      }
+    },
+    "releaseDocumentsChangelog": {
+      "type": "object",
+      "required": [
+        "path",
+        "locale"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+        },
+        "locale": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+        }
+      }
+    },
+    "releaseDocumentsReadme": {
+      "type": "object",
+      "required": [
+        "path",
+        "locale",
+        "regions"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+        },
+        "locale": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+        },
+        "regions": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          }
+        },
+        "versionMarkers": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/releaseDocumentsVersionMarker"
+          }
+        }
+      }
+    },
+    "releaseDocumentsVersionMarker": {
+      "type": "object",
+      "required": [
+        "id",
+        "pattern"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "verificationGate": {
       "type": "object",
       "required": [

package/scripts/build-bundle.mjs

@@ -28,7 +28,14 @@ const OUTFILE = join(PKG_ROOT, 'bin', 'release-skill.bundle.mjs');
 // Banner: compute PKG_ROOT deterministically from the bundle's own path.
 // No env-var override — callers cannot hijack schema/native resolution.
 // Uses import.meta.url only — process.argv[1] is not a reliable resource root.
-const BANNER = `\
+//
+// The banner also injects the package identity (__bundlePkg) as a build-time
+// constant so the CLI --version probe carries no bundle-relative file
+// dependency: the Claude and Codex adapter closures ship the bundle at a
+// different depth with no package.json next to it, while the npm closure does.
+// Reading package.json here (build input) keeps the output deterministic.
+function buildBanner(pkgIdentity) {
+  return `\
 // --- release-skill bundle (deterministic build) ---
 // Compute package root from the bundle's own file location (import.meta.url).
 // The bundle lives at <PKG_ROOT>/bin/release-skill.bundle.mjs, so go up one level.
@@ -38,7 +45,10 @@ import { createRequire as __bundleCreateRequire } from 'node:module';
 const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(import.meta.url)), '..');
 // Provide a real require() for CJS packages bundled into ESM (e.g. yaml, ajv).
 const __bundleRealRequire = __bundleCreateRequire(import.meta.url);
+// Package identity injected at build time — closure-independent --version probe.
+const __bundlePkg = Object.freeze(${JSON.stringify(pkgIdentity)});
 `;
+}
 
 // Pattern to replace esbuild's broken __require shim with a real require().
 const REQUIRE_SHIM_PATTERN = /var __require = \/\* @__PURE__ \*\/ \(\(x\) => typeof require !== "undefined" \? require : typeof Proxy !== "undefined" \? new Proxy\(x, \{[\s\S]*?\}\) : x\)\(function\(x\) \{[\s\S]*?\}\);/;
@@ -55,6 +65,9 @@ async function buildBundle() {
     process.exit(1);
   }
 
+  const pkgJson = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf-8'));
+  const banner = buildBanner({ name: pkgJson.name, version: pkgJson.version });
+
   const result = await esbuild.build({
     entryPoints: [ENTRY],
     absWorkingDir: PKG_ROOT,
@@ -63,7 +76,7 @@ async function buildBundle() {
     platform: 'node',
     target: 'node22',
     outfile: OUTFILE,
-    banner: { js: BANNER },
+    banner: { js: banner },
     // External: Node.js builtins, native addon loader, and the native addon itself.
     external: [
       'node:*',

package/skills/release-help/SKILL.md

@@ -35,8 +35,24 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 发布文档刷新：默认只读演练
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
+# 摘要确认后的本地写入（三项绑定缺一不可）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 ```
 
+## 发布文档刷新（docs refresh）
+
+发布单元配置 `releaseDocuments` 后，一份结构化双语说明源可确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目。核心 CLI 不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、版本标记机器值和当前受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+
+- **配置**：`releaseDocuments.notesSource`（说明源路径，只允许 `{version}` 占位符与 `.yaml`/`.yml`/`.json` 后缀）、`locales`（如 `[en, zh-CN]`）、`changelogs`（path + locale）、`readmes`（path + locale + `regions` 受管区域 id + `versionMarkers` 版本标记模式）。版本标记模式必须与 README 现有唯一标记精确匹配，`{version}` 代表机器版本值，刷新只替换该值；零次或多次匹配失败关闭。
+- **说明源**：`version` 必须与单元版本精确一致，`date` 为 `YYYY-MM-DD`，每个配置语种恰好出现一次且 `summary`、变更项非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。YAML alias、重复键、未知字段和语种回退都失败关闭。
+- **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
+- **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
+
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 hook、Git 提交、push、publish 或安装的授权。写入后必须审阅、提交，再重新 prepare。
+
 ## 故障路由
 
 | 场景 | 处理 |
@@ -50,6 +66,11 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 | 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
 | assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |
+| RELEASE_DOCS_INVALID | 配置或说明源语义非法（重复键、alias、未知字段、版本漂移等）；修正配置或说明源后重新演练 |
+| RELEASE_DOCS_TRANSLATION_MISSING | 配置语种缺失或多余；补齐说明源语种，与 `releaseDocuments.locales` 完全一致，不得回退 |
+| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
+| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
+| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
 
 ## 后续引导
 

package/skills/release-prepare/SKILL.md

@@ -23,13 +23,16 @@ description: Freeze an immutable release plan with local configuration, document
 
 **不确定性停止**: 遇到无法确定的配置项或版本冲突时，Agent 必须停止并上报用户。
 
+**发布文档新鲜度门**: 配置了 `releaseDocuments` 的单元在 hook 授权门前先执行同一只读规划器：`clean` 继续；`changes` 抛 `RELEASE_DOCS_STALE`，详情列出相对路径、语种、`refreshDigest` 和精确演练/写入参数数组。prepare 只检查、不写工作树。正式 prepare 前先运行只读演练；有变化时向用户展示文件/语种/版本/`refreshDigest`，只有在用户明确授权"本地发布文档写入"后，才执行带 `--write --confirm-refresh <refreshDigest> --ack-local-document-write` 三项绑定的写入，随后运行聚焦校验，要求维护者审阅并提交刷新结果，再重新 prepare。该授权不扩展为 hook、提交、push 或 publish 授权。
+
 ## 正向执行路径
 
 1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
-2. 运行 `${CLI} prepare --root <path> --offline --json`
-3. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
-4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
-5. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
+2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
+3. 运行 `${CLI} prepare --root <path> --offline --json`
+4. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
+5. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
+6. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -48,6 +51,11 @@ prepare 后若人工继续修改 README 或任何源文件，应保留修改并
 ## 确定性脚本调用
 
 ```bash
+# 发布文档新鲜度：prepare 前只读演练（配置了 releaseDocuments 的单元）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
+# 仅在用户明确授权“本地发布文档写入”后执行（三项绑定缺一不可）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
@@ -59,8 +67,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 
 ## 执行顺序
 
-1. 校验配置 schema → 2. Hook 授权门 → 3. 运行 hooks → 4. 捕获 Git baseline →
-5. 逐 unit 观察前序公开基线 → 6. 生成快照/扫描/README → 7. 版本解析 → 8. 原子写入 plan
+1. 校验配置 schema → 2. 版本解析与发布文档新鲜度门（只读，RELEASE_DOCS_STALE）→
+3. Hook 授权门 → 4. 运行 hooks 并复检文档新鲜度 → 5. 捕获 Git baseline →
+6. 逐 unit 观察前序公开基线 → 7. 生成快照/扫描/README → 8. 原子写入 plan
 
 ## 故障路由
 
@@ -71,6 +80,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
+| RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
+| RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
 | CONFIG_INVALID | 检查 version.source 和 package.json |
 

package/skills/release-publish/SKILL.md

@@ -17,7 +17,9 @@ description: 从已批准且摘要确认的生产计划发布冻结 Git branch/t
 不得把沙箱通过描述成真实发布成功。
 
 只发布 `prepare --production` 封存的 Git object 和 npm tarball，不从活动工作区重新
-打包，不生成或覆盖 README。远端 branch/tag/Release/npm version 已存在、查询不确定、
+打包，不生成或覆盖 README，也永不隐式刷新工作树中的发布文档；
+遇到 `RELEASE_DOCS_STALE` 或文档陈旧只能回到 `docs refresh` → 人工审阅 → 提交 →
+重新 prepare。远端 branch/tag/Release/npm version 已存在、查询不确定、
 认证失败或摘要漂移时，在全局预检阶段停止并交给人工。禁止覆盖、删除和自动回滚；
 新建 ref 的 create-only CAS（`--force-with-lease=<ref>:`）只断言目标不存在，不授权覆盖。
 

package/skills/release-reconcile/SKILL.md

@@ -19,7 +19,7 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ## 职责与边界
 
-查询远端实际状态，对照冻结计划识别一致/不一致检查点。已成功的步骤幂等跳过，只重试安全且未完成的步骤。远端冲突时停止并要求人工决策。不删除远端资源。`--run` 必需；重试需 `--approval`。
+查询远端实际状态，对照冻结计划识别一致/不一致检查点。已成功的步骤幂等跳过，只重试安全且未完成的步骤。远端冲突时停止并要求人工决策。不删除远端资源。`--run` 必需；重试需 `--approval`。reconcile 永不隐式刷新工作树中的发布文档；陈旧文档只能回到 `docs refresh` → 人工审阅 → 提交 → 重新 prepare。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PUBLISHED` 确认。随后必须以 reconcile 返回的新 `runPath` 执行 verify；只有 verify 的 `VERIFIED` 才是完整终态。
 

package/skills-src/release-help/SKILL.md

@@ -35,8 +35,24 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 发布文档刷新：默认只读演练
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
+# 摘要确认后的本地写入（三项绑定缺一不可）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 ```
 
+## 发布文档刷新（docs refresh）
+
+发布单元配置 `releaseDocuments` 后，一份结构化双语说明源可确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目。核心 CLI 不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、版本标记机器值和当前受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+
+- **配置**：`releaseDocuments.notesSource`（说明源路径，只允许 `{version}` 占位符与 `.yaml`/`.yml`/`.json` 后缀）、`locales`（如 `[en, zh-CN]`）、`changelogs`（path + locale）、`readmes`（path + locale + `regions` 受管区域 id + `versionMarkers` 版本标记模式）。版本标记模式必须与 README 现有唯一标记精确匹配，`{version}` 代表机器版本值，刷新只替换该值；零次或多次匹配失败关闭。
+- **说明源**：`version` 必须与单元版本精确一致，`date` 为 `YYYY-MM-DD`，每个配置语种恰好出现一次且 `summary`、变更项非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。YAML alias、重复键、未知字段和语种回退都失败关闭。
+- **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
+- **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
+
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 hook、Git 提交、push、publish 或安装的授权。写入后必须审阅、提交，再重新 prepare。
+
 ## 故障路由
 
 | 场景 | 处理 |
@@ -50,6 +66,11 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 | 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
 | assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |
+| RELEASE_DOCS_INVALID | 配置或说明源语义非法（重复键、alias、未知字段、版本漂移等）；修正配置或说明源后重新演练 |
+| RELEASE_DOCS_TRANSLATION_MISSING | 配置语种缺失或多余；补齐说明源语种，与 `releaseDocuments.locales` 完全一致，不得回退 |
+| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
+| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
+| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
 
 ## 后续引导
 

package/skills-src/release-prepare/SKILL.md

@@ -23,13 +23,16 @@ description: Freeze an immutable release plan with local configuration, document
 
 **不确定性停止**: 遇到无法确定的配置项或版本冲突时，Agent 必须停止并上报用户。
 
+**发布文档新鲜度门**: 配置了 `releaseDocuments` 的单元在 hook 授权门前先执行同一只读规划器：`clean` 继续；`changes` 抛 `RELEASE_DOCS_STALE`，详情列出相对路径、语种、`refreshDigest` 和精确演练/写入参数数组。prepare 只检查、不写工作树。正式 prepare 前先运行只读演练；有变化时向用户展示文件/语种/版本/`refreshDigest`，只有在用户明确授权"本地发布文档写入"后，才执行带 `--write --confirm-refresh <refreshDigest> --ack-local-document-write` 三项绑定的写入，随后运行聚焦校验，要求维护者审阅并提交刷新结果，再重新 prepare。该授权不扩展为 hook、提交、push 或 publish 授权。
+
 ## 正向执行路径
 
 1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
-2. 运行 `${CLI} prepare --root <path> --offline --json`
-3. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
-4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
-5. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
+2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
+3. 运行 `${CLI} prepare --root <path> --offline --json`
+4. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
+5. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
+6. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -48,6 +51,11 @@ prepare 后若人工继续修改 README 或任何源文件，应保留修改并
 ## 确定性脚本调用
 
 ```bash
+# 发布文档新鲜度：prepare 前只读演练（配置了 releaseDocuments 的单元）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
+# 仅在用户明确授权“本地发布文档写入”后执行（三项绑定缺一不可）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
@@ -59,8 +67,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 
 ## 执行顺序
 
-1. 校验配置 schema → 2. Hook 授权门 → 3. 运行 hooks → 4. 捕获 Git baseline →
-5. 逐 unit 观察前序公开基线 → 6. 生成快照/扫描/README → 7. 版本解析 → 8. 原子写入 plan
+1. 校验配置 schema → 2. 版本解析与发布文档新鲜度门（只读，RELEASE_DOCS_STALE）→
+3. Hook 授权门 → 4. 运行 hooks 并复检文档新鲜度 → 5. 捕获 Git baseline →
+6. 逐 unit 观察前序公开基线 → 7. 生成快照/扫描/README → 8. 原子写入 plan
 
 ## 故障路由
 
@@ -71,6 +80,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
+| RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
+| RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
 | CONFIG_INVALID | 检查 version.source 和 package.json |