release-skill 0.1.5 → 0.1.7

package/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/claude/schemas/release-project.schema.json

@@ -445,6 +445,9 @@
                 }
               ]
             }
+          },
+          "releaseDocuments": {
+            "$ref": "#/definitions/releaseDocuments"
           }
         },
         "allOf": [
@@ -634,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/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/codex/.codex-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "name": "release-skill",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
-    "name": "release-skill contributors"
+    "name": "广州市风荷科技有限公司"
   },
   "license": "MIT",
   "skills": "./skills/",
@@ -11,7 +11,7 @@
     "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": "release-skill",
+    "developerName": "ifoohoo",
     "category": "DevOps",
     "capabilities": [
       "Write",
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.5.",
+      "Prepare a release plan for version 0.1.7.",
       "Help me understand the release workflow."
     ]
   }