release-skill 0.4.2 → 0.5.1

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,14 +687,193 @@ 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)}），无法确认该版本是否已发布，已跳过版本冲突检查`,
+          }),
+        );
+      }
     }
   }
 
   return gaps;
 }
 
+/**
+ * Parse a semver-ish version string into comparable components.
+ *
+ * Accepts `major.minor.patch` with an optional `-prerelease` suffix (which
+ * sorts strictly below the same release triple). Returns null for anything
+ * that is not a version-shaped tag (candidate names like `0.1.27-candidate.2`
+ * parse fine; non-version tags are skipped).
+ *
+ * @param {string} version
+ * @returns {{ major: number, minor: number, patch: number, prerelease: string|null } | null}
+ */
+export function parseSemverVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(version);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null,
+  };
+}
+
+/**
+ * Compare two parsed semver values. Returns a negative/zero/positive number.
+ *
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} a
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} b
+ * @returns {number}
+ */
+export function compareSemverVersions(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.prerelease && !b.prerelease) return -1;
+  if (!a.prerelease && b.prerelease) return 1;
+  return 0;
+}
+
+/**
+ * Describe a version-sequence gap between an immediate predecessor and the
+ * target version, or null when the step is contiguous.
+ *
+ * A gap means some version between the two was never released (e.g. the
+ * historical 0.1.1 -> 0.1.3 jump with no v0.1.2 tag). Pre-release steps
+ * never count as gaps by themselves.
+ *
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} prev
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} target
+ * @returns {string|null}
+ */
+export function describeVersionSequenceGap(prev, target) {
+  if (prev.major !== target.major) {
+    return prev.major + 1 < target.major
+      ? `major ${prev.major}.x.x -> ${target.major}.x.x`
+      : null;
+  }
+  if (prev.minor !== target.minor) {
+    return prev.minor + 1 < target.minor
+      ? `minor ${prev.major}.${prev.minor}.x -> ${target.major}.${target.minor}.x`
+      : null;
+  }
+  if (prev.patch !== target.patch) {
+    return prev.patch + 1 < target.patch
+      ? `patch ${prev.major}.${prev.minor}.${prev.patch} -> ${target.major}.${target.minor}.${target.patch}`
+      : null;
+  }
+  return null;
+}
+
+/**
+ * Build a regex that extracts the version from a tag name following the
+ * unit's tagTemplate (`{version}` placeholder, regex-special characters
+ * escaped).
+ *
+ * @param {string} tagTemplate
+ * @returns {RegExp}
+ */
+export function buildTagVersionRegex(tagTemplate) {
+  const escaped = tagTemplate
+    .split('{version}')
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('(.+)');
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Check the public repository's release tag sequence for version jumps
+ * (0.5.1 chain hardening): when the immediate predecessor release is more
+ * than one version step below the current target version, register a
+ * warning-level gap `VERSION_SEQUENCE_GAP` (e.g. 0.1.1 -> 0.1.3 with no
+ * v0.1.2 tag). This never blocks: it records the observation for the human
+ * release planner.
+ *
+ * @param {string} root - Project root.
+ * @param {Object} config - The loaded project config.
+ * @returns {Promise<Object[]>} Array of warning gap entries.
+ */
+async function checkReleaseTagSequence(root, config) {
+  const gaps = [];
+  for (const unit of config.releaseUnits ?? []) {
+    const tagTemplate = unit.version?.tagTemplate;
+    if (!tagTemplate || !unit.publicRepo) continue;
+
+    const versionRegex = buildTagVersionRegex(tagTemplate);
+    const tagPattern = tagTemplate.replace('{version}', '*');
+
+    let stdout;
+    try {
+      ({ stdout } = await execFile(
+        'git',
+        ['ls-remote', `https://github.com/${unit.publicRepo}.git`, `refs/tags/${tagPattern}`],
+        { cwd: root, shell: false, encoding: 'utf8', timeout: 15_000 },
+      ));
+    } catch {
+      // Tag enumeration failure (network/auth/repo absent) is not a version
+      // gap and must not block; the remote-prerequisites npm check already
+      // reports unreachable registries where relevant.
+      continue;
+    }
+
+    let targetVersion;
+    try {
+      const pkg = JSON.parse(await readFile(resolve(root, unit.source, 'package.json'), 'utf8'));
+      targetVersion = pkg.version;
+    } catch {
+      continue; // package metadata issues are reported elsewhere
+    }
+    const targetParsed = parseSemverVersion(targetVersion);
+    if (!targetParsed) continue;
+
+    let previousParsed = null;
+    let previousTag = null;
+    for (const line of stdout.trim().split('\n')) {
+      if (!line) continue;
+      const tagName = line.split('\t')[1]?.replace(/^refs\/tags\//, '');
+      if (!tagName) continue;
+      const versionMatch = versionRegex.exec(tagName);
+      if (!versionMatch) continue;
+      const parsed = parseSemverVersion(versionMatch[1]);
+      if (!parsed) continue;
+      // Prereleases never qualify as the "previous release" predecessor.
+      if (parsed.prerelease) continue;
+      if (compareSemverVersions(parsed, targetParsed) >= 0) continue;
+      if (previousParsed === null || compareSemverVersions(parsed, previousParsed) > 0) {
+        previousParsed = parsed;
+        previousTag = tagName;
+      }
+    }
+
+    if (!previousParsed) continue;
+    const gap = describeVersionSequenceGap(previousParsed, targetParsed);
+    if (gap) {
+      gaps.push(createGap({
+        scope: GapScope.PROJECT,
+        category: GapCategory.REMOTE,
+        severity: Severity.WARNING,
+        code: 'VERSION_SEQUENCE_GAP',
+        message: `发布单元 "${unit.id}" 的版本序列存在跳号（${gap}，上一发布标签 ${previousTag}，目标版本 ${targetVersion}）：请确认中间版本未发布是否是有意为之；发布链仍会以链式历史推进，但跳过的版本不会补造标签`,
+        file: '.release-skill/project.yaml',
+      }));
+    }
+  }
+  return gaps;
+}
+
 /**
  * Perform a basic README structural check.
  *
@@ -909,6 +1132,12 @@ export async function assessProject(options) {
   const remoteGaps = await checkRemotePrerequisites(root, config, offline);
   allGaps.push(...remoteGaps);
 
+  // --- 7b. Release tag sequence (online only; warning, never blocking) ---
+  if (!offline) {
+    const tagSequenceGaps = await checkReleaseTagSequence(root, config);
+    allGaps.push(...tagSequenceGaps);
+  }
+
   // --- 8. README structure check ---
   const readmeGaps = await checkReadmeStructure(root, config);
   allGaps.push(...readmeGaps);

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/commands/hooks.mjs

@@ -28,7 +28,12 @@ export async function validateDeclaredHooks(options = {}) {
     clock: () => new Date().toISOString(),
   });
   const startedAt = new Date().toISOString();
-  await runDeclaredHooks(config, root, evidence, undefined, { hookCache });
+  await runDeclaredHooks(config, root, evidence, undefined, {
+    hookCache,
+    // Explicit env delivery (0.5.1 hook-env-delivery fix): same semantics as
+    // prepare — allowlisted keys are read from this explicit map only.
+    env: process.env,
+  });
   return {
     command: 'hooks validate',
     status: 'PASSED',

package/src/commands/prepare.mjs

@@ -243,6 +243,13 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
  * @param {object} [options]
  * @param {boolean} [options.hookCache=true] - When false (--no-hook-cache),
  *   every hook runs in full and the cache is neither read nor written.
+ * @param {Record<string, string>} [options.env] - Explicit environment map
+ *   merged into the hook context (`hookFn(hook, { root, env })`). The hook
+ *   runner's `buildFilteredEnv` reads `envAllowlist` keys exclusively from
+ *   this map (never from process.env), so the caller decides what is
+ *   injectable. Defaults to process.env at the prepare call site, which makes
+ *   allowlisted keys exported by the invoking shell reach the hook
+ *   subprocess.
  * @returns {Promise<void>}
  * @throws {ReleaseError} GATE_FAILED if any hook returns a non-zero exit code,
  *   throws, or declares a cacheInputs glob that matches no file.
@@ -294,7 +301,10 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
 
     let result;
     try {
-      result = await hookFn(hook, { root });
+      result = await hookFn(hook, {
+        root,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+      });
     } catch (err) {
       await evidence.append({
         phase: 'hooks',
@@ -1850,6 +1860,11 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'hooks', status: 'started' });
     await runDeclaredHooks(config, realRoot, evidence, options.runHookFn ?? runHook, {
       hookCache: options.hookCache,
+      // Explicit env delivery (0.5.1 hook-env-delivery fix): the hook runner
+      // reads envAllowlist keys exclusively from context.env, so the invoking
+      // shell's environment is injected here explicitly. Allowlist semantics
+      // are unchanged — only allowlisted keys from this map reach the child.
+      env: options.env ?? process.env,
     });
     await evidence.append({ phase: 'hooks', status: 'completed' });
 
@@ -2077,6 +2092,29 @@ export async function prepareRelease(options) {
       }
     };
     const observeDefaultBranch = options.observeDefaultBranchFn ?? defaultObserveDefaultBranchFn;
+    // CHAIN_GAP detection (0.5.1 chain hardening): when a unit declares
+    // previousPublicBaseline.mode=none (first-release semantics) but the
+    // public repository already carries release tags for the unit's
+    // tagTemplate, a subsequent release pretending to be the first would
+    // freeze a plan whose push-snapshot creates a new orphan root commit.
+    // Detection is online-only: `git ls-remote` on the tag pattern
+    // (tagTemplate with {version} → *). Any match proves a prior release.
+    const defaultPriorReleaseTagDetector = async (repo, tagPattern, { githubHost = 'github.com' } = {}) => {
+      try {
+        const { stdout } = await execFile(
+          'git',
+          ['ls-remote', `https://${githubHost}/${repo}.git`, `refs/tags/${tagPattern}`],
+          { shell: false, encoding: 'utf8', timeout: 30000 },
+        );
+        return { found: stdout.trim().length > 0 };
+      } catch (err) {
+        // Network/auth failure: unknown, not "no prior release". The caller
+        // records a warning and continues (consistent with the bound-baseline
+        // observer's unknown status); it never silently proves first release.
+        return { error: err.message };
+      }
+    };
+    const detectPriorReleaseTags = options.detectPriorReleaseTagsFn ?? defaultPriorReleaseTagDetector;
     const unitBaselineResults = new Map();
     for (let unitIndex = 0; unitIndex < configUnits.length; unitIndex += 1) {
       const unit = configUnits[unitIndex];
@@ -2120,6 +2158,50 @@ export async function prepareRelease(options) {
       });
 
       if (ppbConfig.mode === "none") {
+        // Chain-integrity gate (0.5.1, CHAIN_GAP): a production online
+        // prepare must not freeze a first-release plan for a repository that
+        // has already published. This is the orphan-root channel that caused
+        // the synthetic 2000-01-01 root commits in the historical public
+        // repositories: first releases used mode=none, push-snapshot degraded
+        // to create-release-branch with no parent, and every later release
+        // started a fresh lineage. Fail closed and demand a bound baseline
+        // pointing at the previous release commit instead.
+        if (production && !offline) {
+          const tagTemplate = unit.version?.tagTemplate;
+          const tagPattern = tagTemplate ? tagTemplate.replace('{version}', '*') : null;
+          if (tagPattern) {
+            const detection = await detectPriorReleaseTags(unit.publicRepo, tagPattern, {
+              githubHost: productionGithubHost,
+            });
+            if (detection.found) {
+              await evidence.append({
+                phase: "previous-public-baseline",
+                unitId: unit.id,
+                status: "blocking",
+                reason: "CHAIN_GAP",
+                repo: unit.publicRepo,
+                tagPattern,
+                guidance: "非首次发布：必须把 previousPublicBaseline 绑定到上一发布提交（mode=bound），不能以 mode=none 制造新的孤儿根提交",
+              });
+              throw new ReleaseError(
+                GATE_FAILED,
+                `unit "${unit.id}" previousPublicBaseline.mode=none but the public repository already has release tags matching "${tagPattern}" (CHAIN_GAP): bind the previous public release commit as a bound baseline`,
+                { unitId: unit.id, reason: 'CHAIN_GAP', repo: unit.publicRepo, tagPattern },
+              );
+            }
+            if (detection.error) {
+              await evidence.append({
+                phase: "previous-public-baseline",
+                unitId: unit.id,
+                status: "warning",
+                reason: "CHAIN_GAP_DETECTION_FAILED",
+                repo: unit.publicRepo,
+                tagPattern,
+                error: detection.error,
+              });
+            }
+          }
+        }
         unitBaselineResults.set(unit.id, {
           mode: "none",
           status: "consistent",

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/baseline.mjs

@@ -146,7 +146,17 @@ function parseStatusPorcelainZ(statusOut) {
  * @returns {Promise<string>} Hex-encoded SHA-256 digest.
  */
 async function computeWorkspaceDigest(root) {
-  const opts = { cwd: root, shell: false, encoding: 'utf8' };
+  // 64 MiB upper bound (official fix 39c631f): `git ls-files -s -z` emits one
+  // line per tracked file and routinely exceeds Node's default 1 MiB
+  // execFile maxBuffer on large repositories (measured 8494 tracked files →
+  // 1,519,151 B stdout). Large enough for any realistic baseline, small
+  // enough to fail closed before exhausting memory.
+  const opts = {
+    cwd: root,
+    shell: false,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  };
 
   const [
     { stdout: stagedOut },

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,46 @@
+/**
+ * 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 工作树在旁。
+ *
+ * 0.5.1 依赖提升：skill-family-contracts / skill-family-harness-node 由 0.4.0
+ * 提升至 0.5.0（npm latest，2026-08-16 发布）。harness-node 0.5.0 导出面已逐项
+ * 核对：publishFileExclusive（atomic.mjs）、acquireFilesystemLock /
+ * inspectFilesystemLock / releaseFilesystemLock / recoverFilesystemLock
+ * （token-lock.mjs）、HARNESS_ERROR_KINDS（errors.mjs）均在 index.mjs 导出面，
+ * 包名 import 无需改动。
+ *
+ * 发布形态：包名 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);
 }
 
 /**