release-skill 0.4.2 → 0.5.0

package/src/commands/assess.mjs

@@ -105,6 +105,50 @@ function unitFile(unit, file) {
   return unit.source === '.' ? file : `${unit.source}/${file}`;
 }
 
+/**
+ * Decide whether a failed `npm view` check proves the queried version is
+ * absent from the registry.
+ *
+ * Only an explicit E404/ETARGET from npm (the registry answered "not found",
+ * either for the package or for the exact version) is trusted as proof of
+ * absence. Network errors, auth failures, timeouts, a missing npm CLI, and
+ * any other failure remain unknown: they must be reported as a failed check
+ * instead of being silently treated as "no gap".
+ *
+ * @param {Error & { stdout?: string, stderr?: string, message?: string }} error - execFile rejection.
+ * @returns {boolean} true when npm explicitly reported the version as absent.
+ */
+function isVersionAbsentError(error) {
+  const text = [
+    error?.stdout,
+    error?.stderr,
+    error?.message,
+  ]
+    .filter((part) => typeof part === 'string')
+    .join('\n');
+  return /\bE404\b|\bETARGET\b/i.test(text);
+}
+
+/**
+ * Extract a short, safe error token from a failed `npm view` invocation.
+ *
+ * Only npm's machine error code (e.g. ECONNREFUSED, E404) or a spawn-level
+ * code (e.g. ENOENT for a missing npm CLI) is returned. Raw stderr is never
+ * embedded because it can contain absolute paths and npm log file locations.
+ *
+ * @param {Error & { code?: unknown, stderr?: string, message?: string }} error - execFile rejection.
+ * @returns {string} npm error code, spawn-level code, or 'UNKNOWN'.
+ */
+function describeNpmError(error) {
+  const spawnCode = error?.code;
+  if (typeof spawnCode === 'string' && /^[A-Z][A-Z0-9_]{2,}$/.test(spawnCode)) {
+    return spawnCode;
+  }
+  const text = `${error?.stderr ?? ''}\n${error?.message ?? ''}`;
+  const match = /\bcode\s+([A-Z][A-Z0-9_]{2,})\b/i.exec(text);
+  return match ? match[1] : 'UNKNOWN';
+}
+
 /**
  * Determine the project topology from the loaded config.
  *
@@ -643,8 +687,22 @@ async function checkRemotePrerequisites(root, config, offline) {
           message: `npm 包 ${npmDist.package}@${version} 已存在于 registry`,
         }),
       );
-    } catch {
-      // Version not published -- good, no gap
+    } catch (error) {
+      // Only an explicit E404/ETARGET from the registry proves the version is
+      // absent -- good, no gap. All other failures (network, auth, timeout,
+      // missing npm CLI) are a failed check and must be reported instead of
+      // being silently treated as "version not published".
+      if (!isVersionAbsentError(error)) {
+        gaps.push(
+          createGap({
+            scope: GapScope.PROFILE,
+            category: GapCategory.REMOTE,
+            severity: Severity.WARNING,
+            code: 'NPM_VERSION_CHECK_FAILED',
+            message: `npm 包 ${npmDist.package}@${version} 的 registry 版本检查失败（${describeNpmError(error)}），无法确认该版本是否已发布，已跳过版本冲突检查`,
+          }),
+        );
+      }
     }
   }
 

package/src/commands/attest.mjs

@@ -85,6 +85,17 @@ async function validateInstalledConsumerClosure({
  * Record the human fact needed by an interactive-only consumer. Identity
  * fields come exclusively from the generated requirement; the operator only
  * supplies the result, actor and optional observed install facts.
+ *
+ * Proof-boundary note: the receipt is a local, self-declared record, not a
+ * signed attestation. `--actor` is validated only as a non-empty string and
+ * there is no external signature or identity verification, so any process
+ * that can run the CLI can claim any actor name. Forging a receipt already
+ * requires write access to the `.release-skill` authority directory, which
+ * is the same trust boundary as the receipt files themselves. New plans do
+ * not use this path: Kimi/CodeBuddy installations are collected as
+ * `manualFollowUps` with `verifiedBySystem: false` and never participate in
+ * the `VERIFIED` terminal state. This legacy command only supports old
+ * frozen plans that predate the manualFollowUps strategy.
  */
 export async function recordManualAttestation(options = {}, injected = {}) {
   const {

package/src/core/approval.mjs

@@ -24,7 +24,7 @@
 
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { computePlanDigest } from './plan.mjs';
-import { sha256Hex } from './digest.mjs';
+import { digestBytes } from 'skill-family-harness-node';
 import { readFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import Ajv from 'ajv';
@@ -50,7 +50,10 @@ export function validateApprovalRecordSchema(approval) {
 }
 
 export function computeApprovalDigest(rawApproval) {
-  return sha256Hex(typeof rawApproval === 'string' || Buffer.isBuffer(rawApproval)
+  // 摘要机制委托 Foundation digestBytes。注意：rawApproval 对象保持本地
+  // 插入序 pretty-print JSON.stringify（approval 记录格式语义），不用
+  // canonicalJson —— 迁移前后字节必须逐位一致（冻结证据见 1.6/pre-freeze）。
+  return digestBytes(typeof rawApproval === 'string' || Buffer.isBuffer(rawApproval)
     ? rawApproval
     : JSON.stringify(rawApproval, null, 2));
 }

package/src/core/digest.mjs

@@ -1,6 +1,14 @@
 /**
  * Deterministic canonical JSON serialisation and SHA-256 digest.
  *
+ * 机制已委托 Foundation（skill-family-foundation-adoption-20260815 节点 1.6）：
+ * - `canonicalJson` 的权威序列化由 `skill-family-contracts` 的 canonicalJson
+ *   承担（键递归排序 + JSON.stringify，严格 JSON 数据域）；本地保留宽松输入域
+ *   归一化包装（undefined 对象属性省略 / 数组 undefined→null / Date→ISO 字符串 /
+ *   Buffer→{data,type} / NaN→null），与迁移前的本地宽松字节语义完全一致。
+ * - `sha256Hex` 委托 `skill-family-harness-node` 的 digestBytes（同一
+ *   createHash('sha256') 实现，字节一致）。
+ *
  * `canonicalJson` recursively sorts object keys (deep-first) while preserving
  * array element order, then serialises the result as a UTF-8 JSON string.
  * Two objects with the same logical content but different key insertion order
@@ -12,13 +20,14 @@
  * @module digest
  */
 
-import { createHash } from 'node:crypto';
+import { canonicalJson as contractsCanonicalJson } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 
 /**
  * Recursively sort every object key in depth-first order and serialise as
  * a deterministic UTF-8 JSON string.
  *
- * Rules:
+ * Rules (本地宽松语义，迁移前后字节一致):
  * - Object keys are sorted lexicographically (same order as `Array.sort()`).
  * - Array element order is preserved.
  * - Primitives (`null`, booleans, numbers, strings) pass through unchanged.
@@ -27,39 +36,59 @@ import { createHash } from 'node:crypto';
  * - `BigInt` values throw (matching `JSON.stringify`).
  * - `Date` objects are serialised via `.toISOString()` (matching
  *   `JSON.stringify`).
+ * - `NaN`/`Infinity` become `null`; function/symbol object properties are
+ *   omitted, array elements become `null` (matching `JSON.stringify`).
+ *
+ * 输入域适配后再委托 Foundation contracts 的严格权威序列化，因此对纯 JSON
+ * 输入与 Foundation `digestDocument` 完全同构。
  *
  * @param {*} obj - Any JSON-serialisable value.
  * @returns {string} A UTF-8 JSON string whose key ordering is deterministic.
  */
 export function canonicalJson(obj) {
-  return JSON.stringify(canonicalise(obj));
+  const normalized = normalizeLenient(obj);
+  // JSON.stringify 顶层对 undefined/function/symbol 返回 undefined（本地原语义）。
+  if (normalized === undefined || typeof normalized === 'function' || typeof normalized === 'symbol') {
+    return undefined;
+  }
+  return contractsCanonicalJson(normalized);
 }
 
 /**
  * Compute the SHA-256 digest of a UTF-8 string or Buffer.
  *
+ * 委托 Foundation harness-node `digestBytes`（实现与本地 createHash 完全一致）。
+ *
  * @param {string | Buffer} input - The data to hash.
  * @returns {string} Lowercase hexadecimal SHA-256 digest (64 hex chars).
  */
 export function sha256Hex(input) {
-  return createHash('sha256').update(input).digest('hex');
+  return digestBytes(input);
 }
 
 // ---- internal helpers (not exported) ----
 
 /**
- * Deep-clone a value while sorting all object keys lexicographically.
+ * 宽松输入域归一化：把本地历史接受的、非严格 JSON 的值转换为与
+ * `JSON.stringify` 一致的严格 JSON 兼容值，再交由 Foundation 权威序列化。
+ * 该函数产生的字节序列与迁移前的本地 canonicalise + JSON.stringify 完全一致。
  *
  * @param {*} value
  * @returns {*}
  */
-function canonicalise(value) {
+function normalizeLenient(value) {
   if (value === null || value === undefined) {
     return value;
   }
 
   if (Array.isArray(value)) {
-    return value.map((item) => canonicalise(item));
+    return value.map((item) => {
+      const normalized = normalizeLenient(item);
+      // JSON.stringify 把数组中的 undefined/function/symbol 序列化为 null。
+      return (normalized === undefined || typeof normalized === 'function' || typeof normalized === 'symbol')
+        ? null
+        : normalized;
+    });
   }
 
   // Date gets its own branch so we can call toISOString() before the
@@ -71,20 +100,26 @@ function canonicalise(value) {
   // Buffer gets its own branch: toJSON() returns {type:'Buffer', data:[...]}
   // which matches JSON.stringify and survives a JSON roundtrip.
   if (Buffer.isBuffer(value)) {
-    return canonicalise(value.toJSON());
+    return normalizeLenient(value.toJSON());
   }
 
   if (typeof value === 'object') {
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
       const v = value[key];
-      // Skip undefined object properties (mirrors JSON.stringify behaviour).
-      if (v === undefined) continue;
-      sorted[key] = canonicalise(v);
+      // JSON.stringify 语义：对象中 undefined/function/symbol 属性被省略。
+      if (v === undefined || typeof v === 'function' || typeof v === 'symbol') continue;
+      sorted[key] = normalizeLenient(v);
     }
     return sorted;
   }
 
-  // Primitives: string, number, boolean, null.
+  // JSON.stringify 把 NaN/±Infinity 序列化为 null。
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    return null;
+  }
+
+  // Primitives: string, number, boolean, null, bigint (bigint 由 Foundation
+  // 严格序列化抛 TypeError，与本地 JSON.stringify 抛 TypeError 一致)。
   return value;
 }

package/src/core/foundation-inflight.mjs

@@ -0,0 +1,39 @@
+/**
+ * Foundation capability bridge (G4 conditional adoption, released form).
+ *
+ * 背景：1.5 revision 2 把 writePlanImmutable / writeRunAtomic / acquireProjectLock /
+ * breakProjectLock 四条件项委托给 Foundation 能力（strict-file-publication 的
+ * publishFileExclusive、token-lock 的 acquireFilesystemLock / releaseFilesystemLock /
+ * recoverFilesystemLock / inspectFilesystemLock），其不在已发布
+ * skill-family-harness-node@0.3.0 导出面，只存在于 Foundation 工作树在途改动。
+ *
+ * 解锁路径（用户裁决）：Foundation 0.4.0 于 2026-08-16 发布（npm 三包
+ * contracts / harness-node / engineering-kit，latest=0.4.0），harness-node 0.4.0
+ * index.mjs 导出 publishFileExclusive 与 token-lock 五函数及 HARNESS_ERROR_KINDS。
+ * 本桥从 5 级相对路径 import（包外工作树引用）切换为包名 import
+ * （'skill-family-harness-node'），随 npm 依赖发布，不再依赖 Foundation 工作树在旁。
+ *
+ * 发布形态：包名 import 可直接用于包内 src（node_modules 解析），bundle
+ * （bin/release-skill.bundle.mjs，esbuild 内联）保持自包含。
+ *
+ * vendor/foundation-pin 与 scripts/materialize-foundation-pin.mjs 因语义失效
+ * （pin 指向工作树在途字节）按 D4 裁决退役并归档，不再存在检查期漂移证据。
+ */
+
+import {
+  publishFileExclusive,
+  acquireFilesystemLock,
+  inspectFilesystemLock,
+  releaseFilesystemLock,
+  recoverFilesystemLock,
+  HARNESS_ERROR_KINDS,
+} from 'skill-family-harness-node';
+
+export {
+  publishFileExclusive,
+  acquireFilesystemLock,
+  inspectFilesystemLock,
+  releaseFilesystemLock,
+  recoverFilesystemLock,
+  HARNESS_ERROR_KINDS,
+};

package/src/core/hook-cache.mjs

@@ -166,6 +166,9 @@ export async function computeHookCacheKey(hook, root) {
     fileEntries.push({ path: relPath, sha256: sha256Hex(content) });
   }
 
+  // 摘要机制已委托 Foundation：canonicalJson（contracts 权威序列化 + 本地宽松
+  // 输入域包装）与 sha256Hex（harness-node digestBytes）。拼接哈希组合无法用
+  // digestDocument 表达，保持组合结构不变（迁移前后字节一致）。
   const cacheKey = sha256Hex(canonicalJson(hook) + canonicalJson(fileEntries));
   return { cacheKey, matchedFiles: matched };
 }

package/src/core/installation-contract.mjs

@@ -24,7 +24,7 @@
  * @module core/installation-contract
  */
 
-import { canonicalJson, sha256Hex } from './digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
 
 /**
  * 安装契约摘要算法版本。
@@ -271,8 +271,10 @@ export function buildInstallationContract({
  * @returns {string} SHA-256 摘要（64 位十六进制）
  */
 export function computeInstallationContractDigest(params) {
+  // 契约对象为纯 JSON（深度冻结、无 undefined/Date/NaN），直接委托 Foundation
+  // digestDocument（= sha256(contracts canonicalJson)，与迁移前字节一致）。
   const contract = buildInstallationContract(params);
-  return sha256Hex(canonicalJson(contract));
+  return digestDocument(contract);
 }
 
 /**

package/src/core/plan.mjs

@@ -15,10 +15,13 @@
  * @module core/plan
  */
 
-import { readFile, writeFile, rename, mkdir, open, link, unlink, lstat } from 'node:fs/promises';
+import { readFile, mkdir, lstat } from 'node:fs/promises';
 import { basename, dirname, join, resolve, parse, sep } from 'node:path';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
+import { digestDocument } from 'skill-family-contracts';
+import { writeFileAtomic } from 'skill-family-harness-node';
+import { publishFileExclusive, HARNESS_ERROR_KINDS as INFLIGHT_KINDS } from './foundation-inflight.mjs';
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
@@ -248,6 +251,11 @@ function stripRecordLayerV2(plan) {
  * @returns {string} Lowercase 64-char hex SHA-256 digest.
  */
 export function computePlanDigest(plan) {
+  // 输入域适配：计划绑定层可能含条件置 undefined 的字段（如 codebuddy 的
+  // marketplace），本地语义为省略该字段。因此不直接用严格 digestDocument，
+  // 而是经 digest.mjs 的宽松输入域包装（contracts 权威序列化 + 本地归一化）
+  // 后由 Foundation digestBytes 摘要 —— 对纯 JSON 计划与 digestDocument 字节
+  // 完全一致，对含 undefined 的计划保持迁移前字节语义。
   if (plan.planVersion === 2) {
     return sha256Hex(canonicalJson(stripRecordLayerV2(plan)));
   }
@@ -286,15 +294,11 @@ export async function writePlanAtomic(planPath, plan) {
   // 4. Serialise
   const json = JSON.stringify(augmented, null, 2);
 
-  // 5. Write to temp file in the same directory
+  // 5. Write atomically via Foundation (contained, exclusive temp, fsync, rename)
   const dir = dirname(planPath);
   await prepareAuthorityDirectory(dir);
   await assertAuthorityFileTarget(planPath);
-  const tmpPath = `${dir}/.release-plan-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
-  await writeFile(tmpPath, json, 'utf8');
-
-  // 6. Atomic rename
-  await rename(tmpPath, planPath);
+  await writeFileAtomic(dir, basename(planPath), json);
 
   return { planPath, planDigest };
 }
@@ -303,9 +307,11 @@ export async function writePlanAtomic(planPath, plan) {
  * Create a digest-addressed plan authority exactly once.
  *
  * The target must be named by the computed digest. An existing byte-identical
- * authority is reused; an existing divergent file fails closed. A temporary
- * file is fsynced and atomically linked into place so concurrent prepares can
- * never replace an authority that another process already created.
+ * authority is reused; an existing divergent file fails closed. The write
+ * delegates to Foundation `publishFileExclusive` (temp + fsync + exclusive
+ * link + byte/mode/identity verification + directory fsync); this wrapper
+ * supplies the idempotent-same-bytes branch that the in-flight Foundation
+ * version does not have (G4 conflict-surface.md 第一节).
  */
 export async function writePlanImmutable(planPath, plan) {
   const planDigest = computePlanDigest(plan);
@@ -324,21 +330,15 @@ export async function writePlanImmutable(planPath, plan) {
   const dir = dirname(planPath);
   await prepareAuthorityDirectory(dir);
   await assertAuthorityFileTarget(planPath);
-  const tmpPath = join(dir, `.release-plan-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
-  const handle = await open(tmpPath, 'wx', 0o600);
-  try {
-    await handle.writeFile(json, 'utf8');
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
 
   try {
-    await link(tmpPath, planPath);
-  } catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    const existing = await readFile(planPath, 'utf8');
-    if (existing !== json) {
+    await publishFileExclusive(dir, basename(planPath), json, { mode: 0o600 });
+  } catch (cause) {
+    if (cause?.details?.kind === INFLIGHT_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+      // 同字节幂等：目标已存在且字节相同 → 幂等成功（Foundation 在途版
+      // EEXIST 直接抛冲突，无幂等分支；wrapper 补齐，fail-closed 无双路径）。
+      const existing = await readFile(planPath, 'utf8').catch(() => null);
+      if (existing === json) return { planPath, planDigest };
       // planVersion 2 (design: t1-2-digest-decoupling.md §4.1): record-layer
       // fields (status/createdAt/baseline) are excluded from the digest, so
       // re-preparing over identical binding content yields the SAME digest
@@ -346,7 +346,7 @@ export async function writePlanImmutable(planPath, plan) {
       // it is genuinely self-consistent (its embedded digest and recomputed
       // digest both equal this digest) -- the authority is never replaced.
       // Any other divergence (tampering, malformed file) still fails closed.
-      if (plan.planVersion === 2) {
+      if (plan.planVersion === 2 && existing !== null) {
         let existingPlan = null;
         try {
           existingPlan = JSON.parse(existing);
@@ -367,8 +367,11 @@ export async function writePlanImmutable(planPath, plan) {
         { planPath, planDigest },
       );
     }
-  } finally {
-    await unlink(tmpPath).catch(() => {});
+    throw new ReleaseError(
+      GATE_FAILED,
+      `immutable plan authority write failed: ${cause?.message ?? String(cause)}`,
+      { planPath, planDigest },
+    );
   }
 
   return { planPath, planDigest };
@@ -1149,7 +1152,7 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         // 不能只比较两个可一起篡改的字符串；必须重新由 distribution 的 installationContract 计算并验证
         if (hasFieldGroup && dist.installationContract) {
           // 从 distribution 的 installationContract 重新计算摘要
-          const recomputedDigest = sha256Hex(canonicalJson(dist.installationContract));
+          const recomputedDigest = digestDocument(dist.installationContract);
           const actionDigest = action.parameters?.installationContractDigest;
           const distDigest = dist.installationContractDigest;
 

package/src/core/run.mjs

@@ -12,7 +12,7 @@
  * @module core/run
  */
 
-import { link, lstat, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { lstat, mkdir, readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, isAbsolute } from 'node:path';
 import Ajv from 'ajv';
@@ -22,6 +22,7 @@ import { assertImmutablePlanAuthority, computePlanDigest } from './plan.mjs';
 import { sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
+import { publishFileExclusive, HARNESS_ERROR_KINDS as INFLIGHT_KINDS } from './foundation-inflight.mjs';
 
 const RELEASE_RUN_SCHEMA = JSON.parse((await readTrustedPackageResource(
   'schemas/release-run.schema.json',
@@ -578,25 +579,18 @@ function sealRun(run) {
   return sealed;
 }
 
-async function syncDirectory(dir) {
-  const handle = await open(dir, 'r');
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-
 /**
  * Write a run file atomically to disk.
  *
  * Validates the run against the schema before writing.
- * Uses temp-file + rename for atomicity.
+ * Delegates to Foundation `publishFileExclusive` (temp + fsync + exclusive
+ * link + byte/mode/identity verification + directory fsync).
  *
  * **Exclusive-create semantics**: if a file already exists at `runPath`
  * with different bytes, the write fails.  This prevents a stale run from
  * silently overwriting a newer run record.  Writes are idempotent when
- * the content is byte-identical.
+ * the content is byte-identical (wrapper-supplied branch; the in-flight
+ * Foundation version has no same-bytes idempotency — G4 conflict-surface.md).
  *
  * @param {string} runPath - Absolute path to write the run to.
  * @param {Object} run - The run object to write.
@@ -608,34 +602,26 @@ export async function writeRunAtomic(runPath, run) {
   const sealed = sealRun(run);
   const json = JSON.stringify(sealed, null, 2);
   const dir = dirname(runPath);
-  const tmpPath = `${dir}/.release-run-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
   await mkdir(dir, { recursive: true });
 
-  const handle = await open(tmpPath, 'wx', 0o600);
   try {
-    await handle.writeFile(json, 'utf8');
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-
-  try {
-    try {
-      await link(tmpPath, runPath);
-      await syncDirectory(dir);
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      const existing = await readFile(runPath, 'utf8');
-      if (existing !== json) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'run file already exists with different bytes; exclusive-create rejected overwrite',
-          { runPath },
-        );
-      }
+    await publishFileExclusive(dir, basename(runPath), json, { mode: 0o600 });
+  } catch (cause) {
+    if (cause?.details?.kind === INFLIGHT_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+      // 同字节幂等：目标已存在且字节相同 → 幂等成功（fail-closed 无双路径）。
+      const existing = await readFile(runPath, 'utf8').catch(() => null);
+      if (existing === json) return Object.freeze(sealed);
+      throw new ReleaseError(
+        GATE_FAILED,
+        'run file already exists with different bytes; exclusive-create rejected overwrite',
+        { runPath },
+      );
     }
-  } finally {
-    await unlink(tmpPath).catch(() => {});
+    throw new ReleaseError(
+      GATE_FAILED,
+      `run file write failed: ${cause?.message ?? String(cause)}`,
+      { runPath },
+    );
   }
 
   return Object.freeze(sealed);

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

@@ -10,7 +10,7 @@
 import { lstat, readFile, readdir } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
-import { canonicalJson, sha256Hex } from './digest.mjs';
+import { canonicalJson, digestDocument } from 'skill-family-contracts';
 import { GATE_FAILED, ReleaseError } from './errors.mjs';
 import { computeFrozenSnapshot } from '../snapshot/frozen.mjs';
 
@@ -258,6 +258,8 @@ export function createSkillResourceClosureReceipt(result, identity = {}) {
 }
 
 export function assertSkillResourceClosureReceipt(expected, observed, label = 'release unit') {
+  // 收据对象均为纯 JSON（JSON.parse 派生或固定字段投影），直接委托 Foundation
+  // contracts 严格 canonicalJson 比较（非 JSON 输入 fail-closed，抛 TypeError）。
   if (canonicalJson(expected) !== canonicalJson(observed)) {
     throw new ReleaseError(
       GATE_FAILED,
@@ -319,9 +321,9 @@ export async function checkSkillResourceClosure({
     })).digest;
   } catch (error) {
     snapshotError = error;
-    inputDigest = sha256Hex(canonicalJson({
+    inputDigest = digestDocument({
       invalidTree: error.message,
-    }));
+    });
   }
   const skillPaths = await discoverSkills(scanRoot);
   const findings = [];
@@ -426,6 +428,6 @@ export async function checkSkillResourceClosure({
     sourceOnlyCount,
     findings,
   };
-  result.receiptDigest = sha256Hex(canonicalJson(receiptProjection(result)));
+  result.receiptDigest = digestDocument(receiptProjection(result));
   return result;
 }