release-skill 0.2.8 → 0.2.9

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.2.8",
+      "version": "0.2.9",
       "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.2.8",
+  "version": "0.2.9",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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.2.8",
+  "version": "0.2.9",
   "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.2.8.",
+      "Prepare a release plan for version 0.2.9.",
       "Help me understand the release workflow."
     ]
   }

package/.kimi-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.2.9 locale=en baseline=sha256:22b3d94c5d99fca0e6016334a108e4be5f3419f45507fae795b4d0714ca7ad6d -->
+## [0.2.9] - 2026-07-31
+
+v0.2.9 makes missing expected public-surface configuration visible during assessment and preparation without blocking existing projects.
+
+### Added
+
+- **Adoption warning**: assess reports `PUBLIC_SURFACE_CONFIG_MISSING` for every release unit that has not configured `expectedPublicSurface`.
+
+### Changed
+
+- **Prepare visibility**: prepare records and returns the same non-blocking warning, and the CLI exposes it in both JSON and human-readable output.
+<!-- release-skill:changelog:end version=0.2.9 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.2.8 locale=en baseline=sha256:ad6e8910f1af206463b5decf134b82590787b77f5a88faca3d8985d3686b111b -->
 ## [0.2.8] - 2026-07-30
 

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.2.8 -->
+<!-- release-skill:release-version: 0.2.9 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -128,7 +128,7 @@ as a version-pinned **manual** install plus trusted observation/attestation:
    frozen version; otherwise do NOT issue an attestation.
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.8
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.9
    /plugins reload
    ```
 
@@ -140,7 +140,7 @@ as a version-pinned **manual** install plus trusted observation/attestation:
 ```json
 {
   "platform": "kimi",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "planDigest": "<64-hex frozen plan digest>",
   "result": "passed",
   "actor": "<person who confirmed>",
@@ -204,7 +204,7 @@ attestation (the same capability gap and closed loop as Kimi Code):
 ```json
 {
   "platform": "codebuddy",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "planDigest": "<64-hex frozen plan digest>",
   "result": "passed",
   "actor": "<person who confirmed>",

package/INSTALL.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.2.8 -->
+<!-- release-skill:release-version: 0.2.9 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本
@@ -112,7 +112,7 @@ release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观
    必须核实已安装插件清单版本等于冻结版本；否则**不得**出具证明。
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.8
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.9
    /plugins reload
    ```
 
@@ -124,7 +124,7 @@ release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观
 ```json
 {
   "platform": "kimi",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "planDigest": "<64 位十六进制冻结计划摘要>",
   "result": "passed",
   "actor": "<确认人>",
@@ -178,7 +178,7 @@ codebuddy CLI 可以添加市场并安装插件，但 **`plugin marketplace add`
 ```json
 {
   "platform": "codebuddy",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "planDigest": "<64 位十六进制冻结计划摘要>",
   "result": "passed",
   "actor": "<确认人>",

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.2.8 -->
+<!-- release-skill:release-version: 0.2.9 -->
 Release preparation for Claude Code, CodeBuddy, WorkBuddy, Codex, and Kimi Code, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -14,27 +14,21 @@ Setup surfaces only the deterministic `compactSummary` review view; the full
 report stays in a temporary session directory.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.8** (2026-07-30)
+**0.2.9** (2026-07-31)
 
-v0.2.8 adds a project-configurable expected public-surface gate so newly added or omitted release files cannot silently disappear from a frozen snapshot.
+v0.2.9 makes missing expected public-surface configuration visible during assessment and preparation without blocking existing projects.
 
 **Added**
 
-- **Expected public surface**: release units can declare physical scan roots with compact `include` and `exclude` globs instead of maintaining a second per-file checker.
-- **Exhaustive classification diagnostics**: prepare reports missing mappings, unexpected mappings, unclassified files, and files that ambiguously match both include and exclude rules.
+- **Adoption warning**: assess reports `PUBLIC_SURFACE_CONFIG_MISSING` for every release unit that has not configured `expectedPublicSurface`.
 
 **Changed**
 
-- **Post-build release gate**: prepare scans the actual workspace after build hooks and blocks before source-authority closure, baseline capture, snapshot construction, or plan creation.
-- **Bounded glob and path safety**: the built-in scanner supports `*`, `?`, and `**`, rejects overlapping or escaping scan roots, and keeps workspace control paths outside the project classification surface.
-
-**Fixed**
-
-- **Silent release-file omission**: a file classified for publication can no longer be absent from `publicFiles` while the release still reaches `PREPARED`.
+- **Prepare visibility**: prepare records and returns the same non-blocking warning, and the CLI exposes it in both JSON and human-readable output.
 <!-- release-skill:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** v0.2.8 is the current release (v0.2.2 previously held
+> **Current boundary:** v0.2.9 is the current release (v0.2.2 previously held
 > published status before the platform verification convergence fix was added).
 > v0.1.1 completed a real production release to GitHub and npm — the first
 > production-verified milestone — followed by
@@ -52,7 +46,7 @@ v0.2.8 adds a project-configurable expected public-surface gate so newly added o
 > publish global preflight.
 
 <!-- release-skill:capability:safe-first-command -->
-> **Production path verified since the v0.1.1 milestone; v0.2.8 is the current
+> **Production path verified since the v0.1.1 milestone; v0.2.9 is the current
 > release.** The npm-installed CLI is the supported user entry. Source checkout
 > is the development/contributor fallback.
 >

package/README.zh-CN.md

@@ -2,33 +2,27 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.2.8 -->
+<!-- release-skill:release-version: 0.2.9 -->
 面向 Claude Code、CodeBuddy、WorkBuddy、Codex 和 Kimi Code 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终发布的内容是什么。它不重新生成、也不回写项目源文件。`prepare` 把每个配置的公开文件复制到隔离快照并验证字节——先冻结并供人工审阅，再从同一份冻结产物发布。`setup` 只显示确定性的 `compactSummary` 审阅视图，完整报告保留在临时会话目录中。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.8** (2026-07-30)
+**0.2.9** (2026-07-31)
 
-v0.2.8 新增项目可配置的期望发布面门禁，防止新增或漏声明的发布文件静默消失在冻结快照之外。
+v0.2.9 会在评估和准备阶段提示缺少期望发布面配置，同时保持现有项目兼容，不立即阻断发布。
 
 **新增**
 
-- **期望发布面**：发布单元可以通过精简的 `include`、`exclude` glob 声明物理扫描根，无需再维护第二份逐文件检查器。
-- **穷举分类诊断**：prepare 会报告缺失映射、多余映射、未分类文件，以及同时命中包含和排除规则的歧义文件。
+- **采用提醒**：assess 会为每个尚未配置 `expectedPublicSurface` 的发布单元报告 `PUBLIC_SURFACE_CONFIG_MISSING`。
 
 **变更**
 
-- **构建后发布门禁**：prepare 在 build hook 后扫描真实工作区，并在源码权威闭集、基线捕获、快照构建和计划写入前阻断失败。
-- **有界 glob 与路径安全**：内建扫描器支持 `*`、`?`、`**`，拒绝重叠或逃逸的扫描根，并将工作区控制面排除在项目分类范围之外。
-
-**修复**
-
-- **发布文件静默漏项**：已归类为应发布的文件如果缺少 `publicFiles` 映射，发布将无法再进入 `PREPARED`。
+- **prepare 可见性**：prepare 会记录并返回同一条非阻断警告，CLI 的 JSON 与人类可读输出都会显示该提醒。
 <!-- release-skill:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.2.8 是当前发布版本（v0.2.2 曾处于已发布状态，后因平台验证收敛修复而更新）。
+> **当前边界：** v0.2.9 是当前发布版本（v0.2.2 曾处于已发布状态，后因平台验证收敛修复而更新）。
 > v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；"当前发布版本"与"首次生产验证里程碑"
@@ -41,7 +35,7 @@ v0.2.8 新增项目可配置的期望发布面门禁，防止新增或漏声明
 > 远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.2.8 是当前发布版本。**
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.2.9 是当前发布版本。**
 > npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**

package/adapters/claude/.claude-plugin/marketplace.json

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

package/adapters/claude/.claude-plugin/plugin.json

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

package/adapters/claude/bin/release-skill.bundle.mjs

@@ -9,7 +9,7 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 // 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({"name":"release-skill","version":"0.2.8"});
+const __bundlePkg = Object.freeze({"name":"release-skill","version":"0.2.9"});
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -21535,6 +21535,15 @@ import {
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
+function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? []).filter((unit) => !unit?.expectedPublicSurface).map((unit) => Object.freeze({
+      code: PUBLIC_SURFACE_CONFIG_MISSING,
+      unitId: unit.id,
+      message: `\u53D1\u5E03\u5355\u5143 "${unit.id}" \u672A\u914D\u7F6E expectedPublicSurface\uFF1B\u65B0\u589E\u6216\u6F0F\u914D\u6587\u4EF6\u4E0D\u4F1A\u88AB\u5206\u7C7B\u95E8\u7981\u53D1\u73B0\u3002\u8BF7\u5BA1\u9605\u9879\u76EE\u53D1\u5E03\u8FB9\u754C\u540E\uFF0C\u5728 .release-skill/project.yaml \u4E2D\u914D\u7F6E expectedPublicSurface.scanRoots\u3002`
+    }))
+  );
+}
 function toPosixPath(path3) {
   return path3.split(sep3).join("/");
 }
@@ -21911,14 +21920,16 @@ async function assertExpectedPublicSurface(options) {
     }
   );
 }
-var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS;
+var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS, PUBLIC_SURFACE_CONFIG_MISSING;
 var init_public_surface = __esm({
   "src/core/public-surface.mjs"() {
     init_errors();
     init_public_path();
     ROOT_CONTROL_DIRECTORIES = Object.freeze([".git", ".release-skill"]);
     UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+    PUBLIC_SURFACE_CONFIG_MISSING = "PUBLIC_SURFACE_CONFIG_MISSING";
     __name(compareStrings, "compareStrings");
+    __name(collectExpectedPublicSurfaceAdoptionWarnings, "collectExpectedPublicSurfaceAdoptionWarnings");
     __name(toPosixPath, "toPosixPath");
     __name(isContainedOrEqual, "isContainedOrEqual");
     __name(isWorkspaceControlPath, "isWorkspaceControlPath");
@@ -23138,6 +23149,16 @@ async function assessProject(options) {
   }
   const config = configResult.config;
   const topology = identifyTopology(config);
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: ".release-skill/project.yaml"
+    }));
+  }
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
   const manifestGaps = await checkPluginManifests(root, config);
@@ -23174,6 +23195,7 @@ var init_assess = __esm({
   async "src/commands/assess.mjs"() {
     await init_config();
     init_errors();
+    init_public_surface();
     execFile4 = promisify4(execFileCb4);
     Severity = Object.freeze({
       ERROR: "error",
@@ -81183,12 +81205,20 @@ async function prepareRelease(options) {
   try {
     await evidence.append({ phase: "config", status: "started" });
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
     await evidence.append({
       phase: "config",
       status: "completed",
       configPath: relative22(realRoot, configPath),
       configDigest
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: "public-surface-adoption",
+        status: "warning",
+        ...warning
+      });
+    }
     const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
@@ -82110,7 +82140,8 @@ To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (
     return {
       planPath: writtenPath,
       planDigest,
-      evidenceDir
+      evidenceDir,
+      warnings: adoptionWarnings
     };
   } catch (err) {
     await evidence.append({
@@ -90431,9 +90462,13 @@ if (command === "prepare") {
         ...plan,
         planPath: result.planPath,
         planDigest: result.planDigest,
-        evidenceDir: result.evidenceDir
+        evidenceDir: result.evidenceDir,
+        warnings: result.warnings
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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.2.8.",
+      "Prepare a release plan for version 0.2.9.",
       "Help me understand the release workflow."
     ]
   }

package/adapters/codex/bin/release-skill.bundle.mjs

@@ -9,7 +9,7 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 // 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({"name":"release-skill","version":"0.2.8"});
+const __bundlePkg = Object.freeze({"name":"release-skill","version":"0.2.9"});
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -21535,6 +21535,15 @@ import {
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
+function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? []).filter((unit) => !unit?.expectedPublicSurface).map((unit) => Object.freeze({
+      code: PUBLIC_SURFACE_CONFIG_MISSING,
+      unitId: unit.id,
+      message: `\u53D1\u5E03\u5355\u5143 "${unit.id}" \u672A\u914D\u7F6E expectedPublicSurface\uFF1B\u65B0\u589E\u6216\u6F0F\u914D\u6587\u4EF6\u4E0D\u4F1A\u88AB\u5206\u7C7B\u95E8\u7981\u53D1\u73B0\u3002\u8BF7\u5BA1\u9605\u9879\u76EE\u53D1\u5E03\u8FB9\u754C\u540E\uFF0C\u5728 .release-skill/project.yaml \u4E2D\u914D\u7F6E expectedPublicSurface.scanRoots\u3002`
+    }))
+  );
+}
 function toPosixPath(path3) {
   return path3.split(sep3).join("/");
 }
@@ -21911,14 +21920,16 @@ async function assertExpectedPublicSurface(options) {
     }
   );
 }
-var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS;
+var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS, PUBLIC_SURFACE_CONFIG_MISSING;
 var init_public_surface = __esm({
   "src/core/public-surface.mjs"() {
     init_errors();
     init_public_path();
     ROOT_CONTROL_DIRECTORIES = Object.freeze([".git", ".release-skill"]);
     UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+    PUBLIC_SURFACE_CONFIG_MISSING = "PUBLIC_SURFACE_CONFIG_MISSING";
     __name(compareStrings, "compareStrings");
+    __name(collectExpectedPublicSurfaceAdoptionWarnings, "collectExpectedPublicSurfaceAdoptionWarnings");
     __name(toPosixPath, "toPosixPath");
     __name(isContainedOrEqual, "isContainedOrEqual");
     __name(isWorkspaceControlPath, "isWorkspaceControlPath");
@@ -23138,6 +23149,16 @@ async function assessProject(options) {
   }
   const config = configResult.config;
   const topology = identifyTopology(config);
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: ".release-skill/project.yaml"
+    }));
+  }
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
   const manifestGaps = await checkPluginManifests(root, config);
@@ -23174,6 +23195,7 @@ var init_assess = __esm({
   async "src/commands/assess.mjs"() {
     await init_config();
     init_errors();
+    init_public_surface();
     execFile4 = promisify4(execFileCb4);
     Severity = Object.freeze({
       ERROR: "error",
@@ -81183,12 +81205,20 @@ async function prepareRelease(options) {
   try {
     await evidence.append({ phase: "config", status: "started" });
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
     await evidence.append({
       phase: "config",
       status: "completed",
       configPath: relative22(realRoot, configPath),
       configDigest
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: "public-surface-adoption",
+        status: "warning",
+        ...warning
+      });
+    }
     const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
@@ -82110,7 +82140,8 @@ To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (
     return {
       planPath: writtenPath,
       planDigest,
-      evidenceDir
+      evidenceDir,
+      warnings: adoptionWarnings
     };
   } catch (err) {
     await evidence.append({
@@ -90431,9 +90462,13 @@ if (command === "prepare") {
         ...plan,
         planPath: result.planPath,
         planDigest: result.planDigest,
-        evidenceDir: result.evidenceDir
+        evidenceDir: result.evidenceDir,
+        warnings: result.warnings
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/adapters/kimi/.kimi-plugin/plugin.json

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

package/adapters/kimi/bin/release-skill.bundle.mjs

@@ -9,7 +9,7 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 // 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({"name":"release-skill","version":"0.2.8"});
+const __bundlePkg = Object.freeze({"name":"release-skill","version":"0.2.9"});
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -21535,6 +21535,15 @@ import {
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
+function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? []).filter((unit) => !unit?.expectedPublicSurface).map((unit) => Object.freeze({
+      code: PUBLIC_SURFACE_CONFIG_MISSING,
+      unitId: unit.id,
+      message: `\u53D1\u5E03\u5355\u5143 "${unit.id}" \u672A\u914D\u7F6E expectedPublicSurface\uFF1B\u65B0\u589E\u6216\u6F0F\u914D\u6587\u4EF6\u4E0D\u4F1A\u88AB\u5206\u7C7B\u95E8\u7981\u53D1\u73B0\u3002\u8BF7\u5BA1\u9605\u9879\u76EE\u53D1\u5E03\u8FB9\u754C\u540E\uFF0C\u5728 .release-skill/project.yaml \u4E2D\u914D\u7F6E expectedPublicSurface.scanRoots\u3002`
+    }))
+  );
+}
 function toPosixPath(path3) {
   return path3.split(sep3).join("/");
 }
@@ -21911,14 +21920,16 @@ async function assertExpectedPublicSurface(options) {
     }
   );
 }
-var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS;
+var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS, PUBLIC_SURFACE_CONFIG_MISSING;
 var init_public_surface = __esm({
   "src/core/public-surface.mjs"() {
     init_errors();
     init_public_path();
     ROOT_CONTROL_DIRECTORIES = Object.freeze([".git", ".release-skill"]);
     UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+    PUBLIC_SURFACE_CONFIG_MISSING = "PUBLIC_SURFACE_CONFIG_MISSING";
     __name(compareStrings, "compareStrings");
+    __name(collectExpectedPublicSurfaceAdoptionWarnings, "collectExpectedPublicSurfaceAdoptionWarnings");
     __name(toPosixPath, "toPosixPath");
     __name(isContainedOrEqual, "isContainedOrEqual");
     __name(isWorkspaceControlPath, "isWorkspaceControlPath");
@@ -23138,6 +23149,16 @@ async function assessProject(options) {
   }
   const config = configResult.config;
   const topology = identifyTopology(config);
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: ".release-skill/project.yaml"
+    }));
+  }
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
   const manifestGaps = await checkPluginManifests(root, config);
@@ -23174,6 +23195,7 @@ var init_assess = __esm({
   async "src/commands/assess.mjs"() {
     await init_config();
     init_errors();
+    init_public_surface();
     execFile4 = promisify4(execFileCb4);
     Severity = Object.freeze({
       ERROR: "error",
@@ -81183,12 +81205,20 @@ async function prepareRelease(options) {
   try {
     await evidence.append({ phase: "config", status: "started" });
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
     await evidence.append({
       phase: "config",
       status: "completed",
       configPath: relative22(realRoot, configPath),
       configDigest
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: "public-surface-adoption",
+        status: "warning",
+        ...warning
+      });
+    }
     const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
@@ -82110,7 +82140,8 @@ To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (
     return {
       planPath: writtenPath,
       planDigest,
-      evidenceDir
+      evidenceDir,
+      warnings: adoptionWarnings
     };
   } catch (err) {
     await evidence.append({
@@ -90431,9 +90462,13 @@ if (command === "prepare") {
         ...plan,
         planPath: result.planPath,
         planDigest: result.planDigest,
-        evidenceDir: result.evidenceDir
+        evidenceDir: result.evidenceDir,
+        warnings: result.warnings
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/adapters/workbuddy/.codebuddy-plugin/plugin.json

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

package/adapters/workbuddy/bin/release-skill.bundle.mjs

@@ -9,7 +9,7 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 // 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({"name":"release-skill","version":"0.2.8"});
+const __bundlePkg = Object.freeze({"name":"release-skill","version":"0.2.9"});
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -21535,6 +21535,15 @@ import {
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
+function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? []).filter((unit) => !unit?.expectedPublicSurface).map((unit) => Object.freeze({
+      code: PUBLIC_SURFACE_CONFIG_MISSING,
+      unitId: unit.id,
+      message: `\u53D1\u5E03\u5355\u5143 "${unit.id}" \u672A\u914D\u7F6E expectedPublicSurface\uFF1B\u65B0\u589E\u6216\u6F0F\u914D\u6587\u4EF6\u4E0D\u4F1A\u88AB\u5206\u7C7B\u95E8\u7981\u53D1\u73B0\u3002\u8BF7\u5BA1\u9605\u9879\u76EE\u53D1\u5E03\u8FB9\u754C\u540E\uFF0C\u5728 .release-skill/project.yaml \u4E2D\u914D\u7F6E expectedPublicSurface.scanRoots\u3002`
+    }))
+  );
+}
 function toPosixPath(path3) {
   return path3.split(sep3).join("/");
 }
@@ -21911,14 +21920,16 @@ async function assertExpectedPublicSurface(options) {
     }
   );
 }
-var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS;
+var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS, PUBLIC_SURFACE_CONFIG_MISSING;
 var init_public_surface = __esm({
   "src/core/public-surface.mjs"() {
     init_errors();
     init_public_path();
     ROOT_CONTROL_DIRECTORIES = Object.freeze([".git", ".release-skill"]);
     UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+    PUBLIC_SURFACE_CONFIG_MISSING = "PUBLIC_SURFACE_CONFIG_MISSING";
     __name(compareStrings, "compareStrings");
+    __name(collectExpectedPublicSurfaceAdoptionWarnings, "collectExpectedPublicSurfaceAdoptionWarnings");
     __name(toPosixPath, "toPosixPath");
     __name(isContainedOrEqual, "isContainedOrEqual");
     __name(isWorkspaceControlPath, "isWorkspaceControlPath");
@@ -23138,6 +23149,16 @@ async function assessProject(options) {
   }
   const config = configResult.config;
   const topology = identifyTopology(config);
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: ".release-skill/project.yaml"
+    }));
+  }
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
   const manifestGaps = await checkPluginManifests(root, config);
@@ -23174,6 +23195,7 @@ var init_assess = __esm({
   async "src/commands/assess.mjs"() {
     await init_config();
     init_errors();
+    init_public_surface();
     execFile4 = promisify4(execFileCb4);
     Severity = Object.freeze({
       ERROR: "error",
@@ -81183,12 +81205,20 @@ async function prepareRelease(options) {
   try {
     await evidence.append({ phase: "config", status: "started" });
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
     await evidence.append({
       phase: "config",
       status: "completed",
       configPath: relative22(realRoot, configPath),
       configDigest
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: "public-surface-adoption",
+        status: "warning",
+        ...warning
+      });
+    }
     const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
@@ -82110,7 +82140,8 @@ To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (
     return {
       planPath: writtenPath,
       planDigest,
-      evidenceDir
+      evidenceDir,
+      warnings: adoptionWarnings
     };
   } catch (err) {
     await evidence.append({
@@ -90431,9 +90462,13 @@ if (command === "prepare") {
         ...plan,
         planPath: result.planPath,
         planDigest: result.planDigest,
-        evidenceDir: result.evidenceDir
+        evidenceDir: result.evidenceDir,
+        warnings: result.warnings
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/bin/release-skill-cli.mjs

@@ -551,8 +551,12 @@ if (command === 'prepare') {
         planPath: result.planPath,
         planDigest: result.planDigest,
         evidenceDir: result.evidenceDir,
+        warnings: result.warnings,
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/bin/release-skill.bundle.mjs

@@ -9,7 +9,7 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 // 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({"name":"release-skill","version":"0.2.8"});
+const __bundlePkg = Object.freeze({"name":"release-skill","version":"0.2.9"});
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -21535,6 +21535,15 @@ import {
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
+function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? []).filter((unit) => !unit?.expectedPublicSurface).map((unit) => Object.freeze({
+      code: PUBLIC_SURFACE_CONFIG_MISSING,
+      unitId: unit.id,
+      message: `\u53D1\u5E03\u5355\u5143 "${unit.id}" \u672A\u914D\u7F6E expectedPublicSurface\uFF1B\u65B0\u589E\u6216\u6F0F\u914D\u6587\u4EF6\u4E0D\u4F1A\u88AB\u5206\u7C7B\u95E8\u7981\u53D1\u73B0\u3002\u8BF7\u5BA1\u9605\u9879\u76EE\u53D1\u5E03\u8FB9\u754C\u540E\uFF0C\u5728 .release-skill/project.yaml \u4E2D\u914D\u7F6E expectedPublicSurface.scanRoots\u3002`
+    }))
+  );
+}
 function toPosixPath(path3) {
   return path3.split(sep3).join("/");
 }
@@ -21911,14 +21920,16 @@ async function assertExpectedPublicSurface(options) {
     }
   );
 }
-var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS;
+var ROOT_CONTROL_DIRECTORIES, UNSUPPORTED_GLOB_CHARACTERS, PUBLIC_SURFACE_CONFIG_MISSING;
 var init_public_surface = __esm({
   "src/core/public-surface.mjs"() {
     init_errors();
     init_public_path();
     ROOT_CONTROL_DIRECTORIES = Object.freeze([".git", ".release-skill"]);
     UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+    PUBLIC_SURFACE_CONFIG_MISSING = "PUBLIC_SURFACE_CONFIG_MISSING";
     __name(compareStrings, "compareStrings");
+    __name(collectExpectedPublicSurfaceAdoptionWarnings, "collectExpectedPublicSurfaceAdoptionWarnings");
     __name(toPosixPath, "toPosixPath");
     __name(isContainedOrEqual, "isContainedOrEqual");
     __name(isWorkspaceControlPath, "isWorkspaceControlPath");
@@ -23138,6 +23149,16 @@ async function assessProject(options) {
   }
   const config = configResult.config;
   const topology = identifyTopology(config);
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: ".release-skill/project.yaml"
+    }));
+  }
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
   const manifestGaps = await checkPluginManifests(root, config);
@@ -23174,6 +23195,7 @@ var init_assess = __esm({
   async "src/commands/assess.mjs"() {
     await init_config();
     init_errors();
+    init_public_surface();
     execFile4 = promisify4(execFileCb4);
     Severity = Object.freeze({
       ERROR: "error",
@@ -81183,12 +81205,20 @@ async function prepareRelease(options) {
   try {
     await evidence.append({ phase: "config", status: "started" });
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
     await evidence.append({
       phase: "config",
       status: "completed",
       configPath: relative22(realRoot, configPath),
       configDigest
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: "public-surface-adoption",
+        status: "warning",
+        ...warning
+      });
+    }
     const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
@@ -82110,7 +82140,8 @@ To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (
     return {
       planPath: writtenPath,
       planDigest,
-      evidenceDir
+      evidenceDir,
+      warnings: adoptionWarnings
     };
   } catch (err) {
     await evidence.append({
@@ -90431,9 +90462,13 @@ if (command === "prepare") {
         ...plan,
         planPath: result.planPath,
         planDigest: result.planDigest,
-        evidenceDir: result.evidenceDir
+        evidenceDir: result.evidenceDir,
+        warnings: result.warnings
       }, null, 2));
     } else {
+      for (const warning of result.warnings) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);

package/package.json

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

package/src/commands/assess.mjs

@@ -23,6 +23,7 @@ import { promisify } from 'node:util';
 
 import { loadProjectConfig } from '../core/config.mjs';
 import { ReleaseError, CONFIG_INVALID, GATE_FAILED } from '../core/errors.mjs';
+import { collectExpectedPublicSurfaceAdoptionWarnings } from '../core/public-surface.mjs';
 
 const execFile = promisify(execFileCb);
 
@@ -880,23 +881,35 @@ export async function assessProject(options) {
   // --- 2. Topology identification ---
   const topology = identifyTopology(config);
 
-  // --- 3. Common docs check ---
+  // --- 3. Expected public-surface adoption ---
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: '.release-skill/project.yaml',
+    }));
+  }
+
+  // --- 4. Common docs check ---
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
 
-  // --- 4. Plugin manifest check ---
+  // --- 5. Plugin manifest check ---
   const manifestGaps = await checkPluginManifests(root, config);
   allGaps.push(...manifestGaps);
 
-  // --- 5. Package metadata check ---
+  // --- 6. Package metadata check ---
   const metadataGaps = await checkPackageMetadata(root, config);
   allGaps.push(...metadataGaps);
 
-  // --- 6. Remote prerequisites ---
+  // --- 7. Remote prerequisites ---
   const remoteGaps = await checkRemotePrerequisites(root, config, offline);
   allGaps.push(...remoteGaps);
 
-  // --- 7. README structure check ---
+  // --- 8. README structure check ---
   const readmeGaps = await checkReadmeStructure(root, config);
   allGaps.push(...readmeGaps);
 

package/src/commands/prepare.mjs

@@ -29,7 +29,10 @@ import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
 import { computeHookCacheKey, readHookCache, writeHookCache } from '../core/hook-cache.mjs';
-import { assertExpectedPublicSurface } from '../core/public-surface.mjs';
+import {
+  assertExpectedPublicSurface,
+  collectExpectedPublicSurfaceAdoptionWarnings,
+} from '../core/public-surface.mjs';
 import { runSnapshotVerificationGates } from '../core/verification-gates.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { computePlanDigest, writePlanAtomic, writePlanImmutable } from '../core/plan.mjs';
@@ -1670,7 +1673,7 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
  *   every declared hook runs in full and the incremental hook cache is neither
  *   read nor written.
  *
- * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string }>}
+ * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string, warnings: ReadonlyArray<object> }>}
  *
  * @throws {ReleaseError} on any gate failure. No PREPARED plan is written.
  */
@@ -1750,6 +1753,7 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'config', status: 'started' });
 
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
 
     await evidence.append({
       phase: 'config',
@@ -1757,6 +1761,13 @@ export async function prepareRelease(options) {
       configPath: relative(realRoot, configPath),
       configDigest,
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: 'public-surface-adoption',
+        status: 'warning',
+        ...warning,
+      });
+    }
 
     // --- Step 1b: Resolve authoritative versions and gate release-document
     //     freshness BEFORE hook authorization ---
@@ -2913,6 +2924,7 @@ export async function prepareRelease(options) {
       planPath: writtenPath,
       planDigest,
       evidenceDir,
+      warnings: adoptionWarnings,
     };
   } catch (err) {
     // Record failure evidence

package/src/core/public-surface.mjs

@@ -22,11 +22,37 @@ import { canonicalPublicPath } from '../snapshot/public-path.mjs';
 
 const ROOT_CONTROL_DIRECTORIES = Object.freeze(['.git', '.release-skill']);
 const UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+export const PUBLIC_SURFACE_CONFIG_MISSING = 'PUBLIC_SURFACE_CONFIG_MISSING';
 
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+/**
+ * Return actionable, non-blocking adoption warnings for release units that
+ * have not enabled the expected public-surface gate.
+ *
+ * This helper never invents project policy or writes configuration. It gives
+ * assess and prepare one stable machine code and message while legacy projects
+ * remain releasable during the adoption window.
+ *
+ * @param {object} config
+ * @returns {ReadonlyArray<object>}
+ */
+export function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? [])
+      .filter((unit) => !unit?.expectedPublicSurface)
+      .map((unit) => Object.freeze({
+        code: PUBLIC_SURFACE_CONFIG_MISSING,
+        unitId: unit.id,
+        message:
+          `发布单元 "${unit.id}" 未配置 expectedPublicSurface；新增或漏配文件不会被分类门禁发现。` +
+          '请审阅项目发布边界后，在 .release-skill/project.yaml 中配置 expectedPublicSurface.scanRoots。',
+      })),
+  );
+}
+
 function toPosixPath(path) {
   return path.split(sep).join('/');
 }