release-skill 0.9.5 → 0.9.7

package/skills/release-help/SKILL.md

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，本机收尾必须等待 `ship` 产出的完成 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，可用 `postverify` 直接执行独立收尾 run，也可由 `ship` 编排该阶段；本机收尾必须等待完成的 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -51,6 +51,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-v
 # 多发布单元项目显式选择本轮范围；未传 --unit 时仍为全部单元
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> \
   --target-version <version> --unit <unit-a> --unit <unit-b> --json
+# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks

package/skills/release-verify/SKILL.md

@@ -15,6 +15,11 @@ verify 是发布流程的最终验证阶段，是唯一能将状态提升到 `VE
 它执行远端状态重检、精确 npm 安装烟雾测试和消费者插件安装验证。
 verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再次派生运行。
 
+计划声明 `postVerify` hook 时，`postverify` 命令负责执行独立的收尾阶段。它接收
+`VERIFIED` verify run、同一计划的 approval，以及逐个传入的 checkpoint approval，
+然后原样调用现有 `postVerifyRelease`。该命令产生独立的 `postverify` run，不读取或写入
+ship state；hook approval 缺失、错误或过期时，在 hook 执行前失败关闭。
+
 **注意**: distribute gate (W1) 已经实现并集成在标准 verify 流程中。verify 现在会检查 postPublish 分发状态（git mirror + marketplace index），只有当所有外部动作都完成并通过验证时才达到 VERIFIED。
 
 **工作流兼容性**: 
@@ -45,13 +50,17 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
 4. 只有 `VERIFIED` 才是发布 happy end
-5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：有未完成 hook 时，先按 approval 合同批准并通过 `ship` 完成 postVerify，再把最终 `DISTRIBUTED` postVerify run 路径交给 `release-finish`；没有 postVerify hook 时，才把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：直接收尾使用独立的 `postverify --plan --approval --run --hook-approval`，由该命令产生 `DISTRIBUTED` postVerify run；若仍由持久化 ship state 承担编排，则使用 `ship --hook-approval` 完成同一阶段，再把最终 run 路径交给 `release-finish`。没有 postVerify hook 时，把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
 ```bash
 # 从插件根运行
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 独立执行已 VERIFIED 计划的 postVerify hook；每个 requiresApproval hook 单独传入批准记录
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 ```
 
 ## 验证步骤
@@ -63,6 +72,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
 6. 全部通过 → `VERIFIED`
 
+`postverify` 不属于上述远端验证步骤。它只处理已经达到 `VERIFIED` 的计划，并把
+`postVerify` 阶段的执行结果写入独立 run。
+
 ## 发布后收尾
 
 `VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。

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

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，本机收尾必须等待 `ship` 产出的完成 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，可用 `postverify` 直接执行独立收尾 run，也可由 `ship` 编排该阶段；本机收尾必须等待完成的 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -51,6 +51,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-v
 # 多发布单元项目显式选择本轮范围；未传 --unit 时仍为全部单元
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> \
   --target-version <version> --unit <unit-a> --unit <unit-b> --json
+# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks

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

@@ -15,6 +15,11 @@ verify 是发布流程的最终验证阶段，是唯一能将状态提升到 `VE
 它执行远端状态重检、精确 npm 安装烟雾测试和消费者插件安装验证。
 verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再次派生运行。
 
+计划声明 `postVerify` hook 时，`postverify` 命令负责执行独立的收尾阶段。它接收
+`VERIFIED` verify run、同一计划的 approval，以及逐个传入的 checkpoint approval，
+然后原样调用现有 `postVerifyRelease`。该命令产生独立的 `postverify` run，不读取或写入
+ship state；hook approval 缺失、错误或过期时，在 hook 执行前失败关闭。
+
 **注意**: distribute gate (W1) 已经实现并集成在标准 verify 流程中。verify 现在会检查 postPublish 分发状态（git mirror + marketplace index），只有当所有外部动作都完成并通过验证时才达到 VERIFIED。
 
 **工作流兼容性**: 
@@ -45,13 +50,17 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
 4. 只有 `VERIFIED` 才是发布 happy end
-5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：有未完成 hook 时，先按 approval 合同批准并通过 `ship` 完成 postVerify，再把最终 `DISTRIBUTED` postVerify run 路径交给 `release-finish`；没有 postVerify hook 时，才把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：直接收尾使用独立的 `postverify --plan --approval --run --hook-approval`，由该命令产生 `DISTRIBUTED` postVerify run；若仍由持久化 ship state 承担编排，则使用 `ship --hook-approval` 完成同一阶段，再把最终 run 路径交给 `release-finish`。没有 postVerify hook 时，把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
 ```bash
 # 从插件根运行
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 独立执行已 VERIFIED 计划的 postVerify hook；每个 requiresApproval hook 单独传入批准记录
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 ```
 
 ## 验证步骤
@@ -63,6 +72,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
 6. 全部通过 → `VERIFIED`
 
+`postverify` 不属于上述远端验证步骤。它只处理已经达到 `VERIFIED` 的计划，并把
+`postVerify` 阶段的执行结果写入独立 run。
+
 ## 发布后收尾
 
 `VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。

package/src/adapters/plugin-marketplace.mjs

@@ -35,6 +35,7 @@ import {
 } from '../core/installation-contract.mjs';
 
 import { createHash } from 'node:crypto';
+import { createFilesystemRootBinding, observeFilesystemTree } from 'skill-family-harness-node';
 import { computeFrozenSnapshot, resolveFrozenPath } from '../snapshot/frozen.mjs';
 import { PLATFORMS, getPlatform, resolvePlatformRoute, resolveCapabilityConflicts } from '../platforms/registry.mjs';
 import {
@@ -101,6 +102,41 @@ const EXTRA_INSTALLED_PATHS_CAP = 200;
 /** Diagnostic cap: at most this many conflict paths are listed per error. */
 const PAYLOAD_CONFLICT_REPORT_CAP = 10;
 
+function foundationPayloadMembers(observation) {
+  return observation.members.map((member) => {
+    if (member.type === 'file') {
+      return {
+        path: member.path,
+        type: member.type,
+        mode: member.statMode & ~0o222,
+        size: member.bytes,
+        contentDigest: member.sha256,
+      };
+    }
+    if (member.type === 'directory') {
+      return { path: member.path, type: member.type, mode: member.statMode };
+    }
+    return {
+      path: member.path,
+      type: member.type,
+      mode: member.statMode,
+      size: member.bytes,
+      targetBase64: member.targetBase64,
+    };
+  });
+}
+
+async function observeMarketplaceInstallTree(installPath) {
+  const canonicalInstallPath = await realpath(installPath);
+  const rootBinding = await createFilesystemRootBinding(canonicalInstallPath);
+  const observation = await observeFilesystemTree({
+    root: canonicalInstallPath,
+    rootBinding,
+    symlinkPolicy: { mode: 'record' },
+  });
+  return foundationPayloadMembers(observation);
+}
+
 /** 消费端安装验证配方版本（与 prepare.mjs 一致）。 */
 const CONSUMER_INSTALL_RECIPE_VERSION = 'consumer-install-v1';
 
@@ -534,10 +570,10 @@ export async function verifyInstalledMarketplacePayload(action, context, install
     // containment semantics; they differ only in the authority subtree source
     // (declared-manifest reads the entry's declared source subpath; external
     // short-circuits to the whole tree '.').
-    const installedSnapshot = await computeFrozenSnapshot(installPath);
+    const installedMembers = await observeMarketplaceInstallTree(installPath);
     const authorityPayload = transportPayload(authorityEntries);
     const installedByPath = new Map(
-      transportPayload(installedSnapshot.entries).map((entry) => [entry.path, entry]),
+      installedMembers.map((entry) => [entry.path, entry]),
     );
     const conflicts = [];
     for (const authorityEntry of authorityPayload) {
@@ -567,15 +603,25 @@ export async function verifyInstalledMarketplacePayload(action, context, install
       );
     }
     const authorityPaths = new Set(authorityPayload.map((entry) => entry.path));
-    const extraPaths = installedSnapshot.entries
-      .map((entry) => entry.path)
-      .filter((path) => !authorityPaths.has(path));
+    const extraMembers = installedMembers
+      .filter((entry) => entry.type !== 'directory' && !authorityPaths.has(entry.path));
+    const extraPaths = extraMembers.map((entry) => entry.path);
     const extraInstalledPaths = extraPaths.slice(0, EXTRA_INSTALLED_PATHS_CAP);
+    const extraInstalledLinks = extraMembers
+      .filter((entry) => entry.type === 'symlink')
+      .slice(0, EXTRA_INSTALLED_PATHS_CAP)
+      .map((entry) => ({
+        path: entry.path,
+        targetBase64: entry.targetBase64,
+        bytes: entry.size,
+        statMode: entry.mode,
+      }));
     // This is not an expected-value backfill: the sealed authority digest was
     // revalidated above and every declared file was independently compared.
     return {
       manifestDigest: action.manifestDigest,
       extraInstalledPaths,
+      ...(extraInstalledLinks.length > 0 ? { extraInstalledLinks } : {}),
       ...(extraPaths.length > EXTRA_INSTALLED_PATHS_CAP
         ? { extraInstalledPathsTotal: extraPaths.length }
         : {}),
@@ -605,6 +651,9 @@ function extraInstalledPathsAudit(binding) {
   if (!binding || !Array.isArray(binding.extraInstalledPaths)) return {};
   return {
     extraInstalledPaths: binding.extraInstalledPaths,
+    ...(Array.isArray(binding.extraInstalledLinks) && binding.extraInstalledLinks.length > 0
+      ? { extraInstalledLinks: binding.extraInstalledLinks }
+      : {}),
     ...(binding.extraInstalledPathsTotal !== undefined
       ? { extraInstalledPathsTotal: binding.extraInstalledPathsTotal }
       : {}),

package/src/commands/prepare.mjs

@@ -82,7 +82,7 @@ import {
   normalizeHostId,
   buildExpectedStandaloneIndexInstallIdentity,
 } from '../platforms/registry.mjs';
-import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
+import { deriveSurfaceHostBinding, groupSurfaceHostBindings, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
 import { buildInstallationContract, computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from '../core/installation-contract.mjs';
 import {
@@ -2818,10 +2818,11 @@ async function runPrepareSkillResourceClosureGate({
       if (binding) surfaceHostBindings.push(binding);
     }
 
+    const { checkerBindings, coverageClaims } = groupSurfaceHostBindings(surfaceHostBindings);
     const closureResult = await checkSkillResourceClosure({
       snapshotDir: manifest.outputDir,
       host: 'root',
-      surfaceHostBindings,
+      surfaceHostBindings: checkerBindings,
     });
 
     // G5: bind execution time + exit code into the frozen receipt.
@@ -2880,6 +2881,7 @@ async function runPrepareSkillResourceClosureGate({
     const hostCoverage = evaluateDeclaredHostSurfaceCoverage(
       expectedHosts,
       closureResult.surfaces,
+      coverageClaims,
     );
     if (!hostCoverage.passed) {
       await evidence.append({
@@ -2908,7 +2910,7 @@ async function runPrepareSkillResourceClosureGate({
     // 含一个技能（binding-surface existence）。G4 按宿主名覆盖，这里按
     // 绑定表面路径覆盖 —— 例如 manifest 指向 './adapters/claude/skills/'
     // 但 publicFiles 丢弃该目录时，绑定表面缺失必须失败关闭。
-    for (const binding of surfaceHostBindings) {
+    for (const binding of coverageClaims) {
       const boundSurface = closureResult.surfaces.find(
         (surface) => surface.id === binding.surfaceId,
       );

package/src/commands/publish.mjs

@@ -27,8 +27,8 @@
 
 import { readFile, mkdir } from 'node:fs/promises';
 import { isAbsolute, join, relative } from 'node:path';
-import { PLATFORMS } from '../platforms/registry.mjs';
-import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
+import { PLATFORMS, normalizeHostId } from '../platforms/registry.mjs';
+import { deriveSurfaceHostBinding, groupSurfaceHostBindings, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 
 import { assertImmutablePlanAuthority, computePlanDigest, validatePlan, validatePlanActionCompleteness } from '../core/plan.mjs';
 import {
@@ -48,6 +48,7 @@ import {
   assertSkillResourceClosureReceipt,
   checkSkillResourceClosure,
   createSkillResourceClosureReceipt,
+  evaluateDeclaredHostSurfaceCoverage,
 } from '../core/skill-resource-closure.mjs';
 import {
   ADAPTER_ACTION_TYPE_MAP,
@@ -672,10 +673,11 @@ export async function publishRelease(options) {
           });
           if (binding) surfaceHostBindings.push(binding);
         }
+        const { checkerBindings, coverageClaims } = groupSurfaceHostBindings(surfaceHostBindings);
         const closureResult = await checkSkillResourceClosure({
           snapshotDir,
           host: 'root',
-          surfaceHostBindings,
+          surfaceHostBindings: checkerBindings,
         });
         if (closureResult.findings.length > 0) {
           await evidence.append({
@@ -691,6 +693,31 @@ export async function publishRelease(options) {
             { unitId, findings: closureResult.findings },
           );
         }
+        const expectedHosts = [];
+        for (const distribution of frozenUnit?.distributions ?? []) {
+          const platform = PLATFORMS.find((item) => item.distributionType === distribution.type);
+          if (platform) expectedHosts.push(await normalizeHostId(platform.buildAdapter.name));
+        }
+        const hostCoverage = evaluateDeclaredHostSurfaceCoverage(
+          expectedHosts,
+          closureResult.surfaces,
+          coverageClaims,
+        );
+        if (!hostCoverage.passed) {
+          await evidence.append({
+            phase: 'safety-gate',
+            gate: 'skill-resource-closure',
+            status: 'failed',
+            unitId,
+            reason: 'declared-host-surface-missing',
+            missingHosts: hostCoverage.missing,
+          });
+          throw new ReleaseError(
+            GATE_FAILED,
+            `skill resource closure recheck failed for unit "${unitId}": declared host surface(s) missing or empty: ${hostCoverage.missing.map((item) => item.host).join(', ')}`,
+            { unitId, missingHosts: hostCoverage.missing },
+          );
+        }
         // G5: preparedAt/exitCode are record-layer fields frozen by prepare
         // (bound by the plan digest); they cannot be recomputed from the
         // snapshot, so the recheck carries them forward from the expected

package/src/commands/verify.mjs

@@ -2052,11 +2052,12 @@ export async function verifyRelease(options) {
       await evidence.append({ phase: 'verify', step: 'skill-resource-closure', status: 'started' });
 
       // Collect install paths from marketplace adapter checks.
-      // R-13 P2 (ruling 6): the surface binding is derived from the frozen
-      // installation contract at the REAL install coordinates — the same
-      // derivation rule prepare and publish use, never a hard-coded '.'.
-      // Plans without a frozen installation contract (legacy) fall back to
-      // the plugin-root surface ('.') with the legacy permissive checks.
+      // R-13 P2 (ruling 6): prepare and publish derive surface bindings in
+      // frozen snapshot-root coordinates. An adapter observation is already
+      // rooted at the installed plugin, so verify derives the same manifest
+      // skills fact relative to '.' at that consumer coordinate. Plans
+      // without a frozen installation contract (legacy) fall back to the
+      // plugin-root surface ('.') with the legacy permissive checks.
       const installSurfaces = [];
       for (const check of adapterChecks) {
         const platform = PLATFORMS.find((p) => p.actionType === check.actionType);
@@ -2065,11 +2066,16 @@ export async function verifyRelease(options) {
         const unit = (plan.units ?? []).find((u) => u.id === unitId);
         const dist = unit?.distributions?.find((d) => d.type === platform.distributionType);
         let binding = null;
+        let frozenPluginRoot = null;
         const contract = dist?.installationContract;
         if (contract?.normalizedManifest) {
+          frozenPluginRoot = pluginRootFromManifestRelativePath(contract.manifestRelativePath);
           binding = await deriveSurfaceHostBinding({
             manifest: contract.normalizedManifest,
-            pluginRoot: pluginRootFromManifestRelativePath(contract.manifestRelativePath),
+            // Adapter observations are already rooted at the installed
+            // plugin. The frozen manifest's skills path is therefore
+            // relative to '.', not to the snapshot-root manifest path.
+            pluginRoot: '.',
             platform,
             snapshotDir: check.observation.installPath,
           });
@@ -2082,6 +2088,7 @@ export async function verifyRelease(options) {
           unitId,
           surfaceId: binding?.surfaceId ?? '.',
           binding,
+          frozenPluginRoot,
           unit,
         });
       }
@@ -2192,7 +2199,7 @@ export async function verifyRelease(options) {
           // publish's recheck uses.
           const pluginDistCount = (surface.unit?.distributions ?? [])
             .filter((d) => d.type !== 'npm').length;
-          if (pluginDistCount === 1) {
+          if (pluginDistCount === 1 && surface.frozenPluginRoot === '.') {
             const observedReceipt = createSkillResourceClosureReceipt(closureResult, {
               unitId: surface.unitId,
               preparedAt: expectedUnitReceipt.preparedAt ?? null,

package/src/core/skill-resource-closure.mjs

@@ -742,9 +742,27 @@ export async function checkSkillResourceClosure({
  * @param {Array<{ id: string, host: string, skillCount: number }>} surfaces
  * @returns {{ passed: boolean, missing: Array<{ host: string, skillCount: number }> }}
  */
-export function evaluateDeclaredHostSurfaceCoverage(expectedHosts, surfaces) {
+export function evaluateDeclaredHostSurfaceCoverage(expectedHosts, surfaces, coverageClaims = []) {
   const missing = [];
+  const observedById = new Map((surfaces ?? []).map((surface) => [surface.id, surface]));
+  const claimsByHost = new Map();
+  for (const claim of coverageClaims ?? []) {
+    const hostClaims = claimsByHost.get(claim.host) ?? [];
+    hostClaims.push(claim);
+    claimsByHost.set(claim.host, hostClaims);
+  }
   for (const expectedHost of [...new Set(expectedHosts ?? [])].sort((a, b) => a.localeCompare(b))) {
+    const declaredClaims = claimsByHost.get(expectedHost) ?? [];
+    if (declaredClaims.length > 0) {
+      const missingClaim = declaredClaims.find((claim) => {
+        const surface = observedById.get(claim.surfaceId);
+        return !surface || !(surface.skillCount >= 1);
+      });
+      if (!missingClaim) continue;
+      const surface = observedById.get(missingClaim.surfaceId);
+      missing.push({ host: expectedHost, skillCount: surface?.skillCount ?? 0 });
+      continue;
+    }
     const surface = (surfaces ?? []).find((item) => item.host === expectedHost);
     if (!surface || !(surface.skillCount >= 1)) {
       missing.push({ host: expectedHost, skillCount: surface?.skillCount ?? 0 });

package/src/core/surface-host-bindings.mjs

@@ -186,3 +186,38 @@ export async function deriveSurfaceHostBinding({ manifest, pluginRoot, platform,
   const host = await normalizeHostId(platform.buildAdapter.name);
   return { surfaceId, host };
 }
+
+/**
+ * Group manifest-backed claims before invoking the closure checker.
+ *
+ * A shared canonical source surface is scanned once. Claims remain complete
+ * for host coverage, while checker overrides are passed only for an
+ * unshared surface; this keeps the checker fail-closed when called directly
+ * with conflicting host claims.
+ *
+ * @param {Array<{surfaceId: string, host: string}>} claims
+ * @returns {{ coverageClaims: Array<{surfaceId: string, host: string}>, checkerBindings: Array<{surfaceId: string, host: string}> }}
+ */
+export function groupSurfaceHostBindings(claims = []) {
+  if (!Array.isArray(claims)) {
+    throw new TypeError('surfaceHostBindings must be an array');
+  }
+  const bySurface = new Map();
+  for (const claim of claims) {
+    if (!claim || typeof claim !== 'object'
+        || typeof claim.surfaceId !== 'string' || typeof claim.host !== 'string') {
+      throw new TypeError('surfaceHostBindings entries must be objects with string surfaceId and host');
+    }
+    const existing = bySurface.get(claim.surfaceId) ?? [];
+    existing.push({ surfaceId: claim.surfaceId, host: claim.host });
+    bySurface.set(claim.surfaceId, existing);
+  }
+  const coverageClaims = [...bySurface.values()]
+    .flat()
+    .sort((left, right) => left.surfaceId.localeCompare(right.surfaceId) || left.host.localeCompare(right.host));
+  const checkerBindings = [...bySurface.values()]
+    .filter((surfaceClaims) => surfaceClaims.length === 1)
+    .map(([claim]) => claim)
+    .sort((left, right) => left.surfaceId.localeCompare(right.surfaceId) || left.host.localeCompare(right.host));
+  return { coverageClaims, checkerBindings };
+}