release-skill 0.4.2 → 0.5.0

package/bin/rules.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.contracts.rules",
+  "contractsVersion": "1.4.0",
+  "budget": {
+    "firstVersionMax": 20,
+    "absoluteMax": 30,
+    "note": "Mechanical gate: runChecks fails with SFC1008 when the mandatory rule count exceeds firstVersionMax, and fails harder when it exceeds absoluteMax. The count includes every rule with severity mandatory, including budget rules themselves."
+  },
+  "checkTypes": [
+    {
+      "type": "schema.compile",
+      "description": "Each registered schema must compile under its declared dialect; an uncompilable schema fails with SFC1012."
+    },
+    {
+      "type": "schema.unique-id",
+      "description": "No two registered schemas may share a $id; duplicates fail with SFC1003."
+    },
+    {
+      "type": "protocol.unique-name",
+      "description": "No two registered protocols may share the same name and version; duplicates fail with SFC1004."
+    },
+    {
+      "type": "schema.ref-resolves",
+      "description": "Every $ref in registered schemas must resolve within the registered schema set; unresolved targets fail with SFC1005."
+    },
+    {
+      "type": "schema.dialect-declared",
+      "description": "Every registered schema must declare a dialect from the supported set, consistent with its $schema URI; violations fail with SFC1006."
+    },
+    {
+      "type": "fixture.positive-passes",
+      "description": "Every fixture expecting validity must validate against its target schema under its declared dialect and policy; mismatches fail with SFC1010."
+    },
+    {
+      "type": "fixture.negative-coded",
+      "description": "Every fixture expecting invalidity must fail with exactly its declared stable error code; mismatches fail with SFC1010."
+    },
+    {
+      "type": "error-code.registered",
+      "description": "Every error code declared in fixture expectations must exist in the frozen error registry; unknown codes fail with SFC1009."
+    },
+    {
+      "type": "rules.budget",
+      "description": "The mandatory rule count must stay within the first-version budget (and never exceed the absolute cap); excess fails with SFC1008."
+    }
+  ],
+  "rules": [
+    {
+      "ruleId": "CR-001",
+      "severity": "mandatory",
+      "checkType": "schema.compile",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-006",
+      "severity": "mandatory",
+      "checkType": "schema.unique-id",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-007",
+      "severity": "mandatory",
+      "checkType": "protocol.unique-name",
+      "target": { "registry": "protocols" }
+    },
+    {
+      "ruleId": "CR-008",
+      "severity": "mandatory",
+      "checkType": "schema.ref-resolves",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-009",
+      "severity": "mandatory",
+      "checkType": "schema.dialect-declared",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-010",
+      "severity": "mandatory",
+      "checkType": "fixture.positive-passes",
+      "target": { "fixtures": "expect-valid" }
+    },
+    {
+      "ruleId": "CR-011",
+      "severity": "mandatory",
+      "checkType": "fixture.negative-coded",
+      "target": { "fixtures": "expect-invalid" }
+    },
+    {
+      "ruleId": "CR-012",
+      "severity": "mandatory",
+      "checkType": "error-code.registered",
+      "target": { "references": "fixture-expectations" }
+    },
+    {
+      "ruleId": "CR-013",
+      "severity": "mandatory",
+      "checkType": "rules.budget",
+      "target": { "budget": "firstVersionMax" }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -76,6 +76,8 @@
     "ajv-formats": "3.0.1",
     "libnpmpublish": "11.1.0",
     "npm-registry-fetch": "18.0.2",
+    "skill-family-contracts": "0.4.0",
+    "skill-family-harness-node": "0.4.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/scripts/build-bundle.mjs

@@ -7,7 +7,10 @@
  * ESM file that runs without node_modules.
  *
  * Schemas and native addons remain external (loaded at runtime from
- * the plugin root via PKG_ROOT).
+ * the plugin root via PKG_ROOT). Runtime JSON resources read by inlined
+ * dependency modules (new URL(<rel>, import.meta.url)) are emitted as
+ * deterministic sidecars next to the bundle (see "Runtime sidecar
+ * resources" section below).
  *
  * Usage:
  *   node scripts/build-bundle.mjs           # build mode
@@ -15,7 +18,8 @@
  */
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 
 const CHECK_MODE = process.argv.includes('--check');
@@ -55,6 +59,100 @@ const REQUIRE_SHIM_PATTERN = /var __require = \/\* @__PURE__ \*\/ \(\(x\) => typ
 
 const REQUIRE_SHIM_REPLACEMENT = `var __require = __bundleRealRequire;`;
 
+// ─── Runtime sidecar resources for inlined dependencies ────────────────
+//
+// Dependencies bundled into the CLI (e.g. skill-family-contracts) can load
+// JSON resources at module init via new URL(<rel>, import.meta.url). Once
+// inlined into the bundle, import.meta.url is the bundle's own URL, so such
+// reads resolve relative to the bundle directory (bin/). To keep the bundle
+// self-contained in copied/installed closures (no node_modules), the build
+// emits each referenced resource that is not already provided at that
+// target as a deterministic sidecar next to the bundle. Reads whose target
+// already exists (e.g. ../package.json resolving to the package's own
+// package.json) are host-provided by design and are not emitted. --check
+// verifies bundle bytes, every expected sidecar, and that every runtime
+// read in the output resolves next to the bundle (fail-closed).
+
+// Module markers esbuild leaves in the output: `// <path>` comments and
+// `<path>() {` __esm keys, with <path> relative to the package root.
+const MODULE_MARK_RE = /(?:\/\/\s*|")((?:\.\.\/)+[^\s"()]+\.(?:mjs|js|cjs))/g;
+const RUNTIME_URL_READ_RE = /new URL\(\s*"([^"]+)"\s*,\s*import\.meta\.url\s*\)/g;
+
+function isAbsoluteOrScheme(rel) {
+  return rel.startsWith('/') || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(rel);
+}
+
+/** Collect every relative runtime read (module source → rel) present in the output. */
+function collectRuntimeReads(content, pkgRoot) {
+  const reads = [];
+  const seenModules = new Set();
+  for (const mark of content.matchAll(MODULE_MARK_RE)) {
+    const modulePath = mark[1];
+    if (seenModules.has(modulePath)) continue;
+    seenModules.add(modulePath);
+    const sourceFile = join(pkgRoot, modulePath);
+    if (!existsSync(sourceFile)) continue;
+    const sourceText = readFileSync(sourceFile, 'utf-8');
+    for (const read of sourceText.matchAll(RUNTIME_URL_READ_RE)) {
+      const rel = read[1];
+      if (isAbsoluteOrScheme(rel)) continue;
+      reads.push({ modulePath, rel });
+    }
+  }
+  return reads;
+}
+
+/** Sidecars to emit: reads whose target next to the bundle is not already provided. */
+function computeSidecars(reads, pkgRoot, outDir) {
+  const sidecars = [];
+  for (const { modulePath, rel } of reads) {
+    if (rel.endsWith('/')) continue; // directory URL composition; not a file load
+    const target = resolve(outDir, rel);
+    const source = resolve(join(pkgRoot, modulePath), '..', rel);
+    if (!existsSync(source)) {
+      throw new Error(
+        `build-bundle: runtime read "${rel}" in ${modulePath} has no source resource (${source})`,
+      );
+    }
+    // Host-provided targets (e.g. ../package.json resolving to the package's
+    // own package.json) lie outside the bundle directory and must not be
+    // emitted or freshened. Targets inside the bundle directory are
+    // sidecar-managed: an existing target is NOT host-provided — a stale
+    // sidecar from a previous dependency generation must be freshened in
+    // write mode and must fail the --check byte comparison.
+    const relativeToOutDir = relative(outDir, target);
+    if (relativeToOutDir.startsWith('..') || isAbsolute(relativeToOutDir)) {
+      continue;
+    }
+    if (!sidecars.some((s) => s.target === target)) {
+      sidecars.push({ target, source });
+    }
+  }
+  return sidecars;
+}
+
+/** Fail-closed check: every relative runtime read in the output must resolve next to the bundle. */
+function verifyRuntimeReadsResolve(content, outDir) {
+  const missing = new Set();
+  for (const read of content.matchAll(RUNTIME_URL_READ_RE)) {
+    const rel = read[1];
+    if (isAbsoluteOrScheme(rel) || rel.endsWith('/')) continue;
+    if (!existsSync(resolve(outDir, rel))) missing.add(rel);
+  }
+  return [...missing].sort();
+}
+
+// Inlined Foundation modules must not perform bundle-relative runtime reads
+// of files that adapter closures do not ship. skill-family-harness-node's
+// report.mjs reads its own package.json at module init
+// (readFileSync(new URL("../package.json", import.meta.url))); once inlined
+// into the bundle that read resolves next to the bundle and breaks in
+// adapter closures (which ship no package.json by design — the banner
+// injects __bundlePkg instead). Neutralize the read at build time with the
+// same injected package identity, fail-closed if Foundation changes shape.
+const REPORT_PACKAGE_META_READ_RE =
+  /JSON\.parse\(readFileSync\(new URL\("\.\.\/package\.json", import\.meta\.url\), "utf8"\)\)/;
+
 async function buildBundle() {
   // Dynamic import so the script works even if esbuild is not yet installed.
   let esbuild;
@@ -68,6 +166,25 @@ async function buildBundle() {
   const pkgJson = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf-8'));
   const banner = buildBanner({ name: pkgJson.name, version: pkgJson.version });
 
+  const identity = Object.freeze({ name: pkgJson.name, version: pkgJson.version });
+
+  const identityPlugins = [{
+    name: 'inline-foundation-package-identity',
+    setup(build) {
+      build.onLoad({ filter: /skill-family-harness-node[\\/]src[\\/]report\.mjs$/ }, async (args) => {
+        const source = await readFile(args.path, 'utf-8');
+        const injected = source.replace(REPORT_PACKAGE_META_READ_RE, () =>
+          `Object.freeze(${JSON.stringify(identity)})`);
+        if (injected === source) {
+          throw new Error(
+            'build-bundle: could not neutralize Foundation report.mjs package.json read',
+          );
+        }
+        return { contents: injected, loader: 'js' };
+      });
+    },
+  }];
+
   const result = await esbuild.build({
     entryPoints: [ENTRY],
     absWorkingDir: PKG_ROOT,
@@ -77,6 +194,7 @@ async function buildBundle() {
     target: 'node22',
     outfile: OUTFILE,
     banner: { js: banner },
+    plugins: identityPlugins,
     // External: Node.js builtins, native addon loader, and the native addon itself.
     external: [
       'node:*',
@@ -106,11 +224,20 @@ async function buildBundle() {
   // Normalize them so committed bundles pass repository whitespace checks.
   content = content.replace(/[ \t]+$/gm, '');
 
-  return content;
+  // Compute runtime sidecars (resources read by inlined dependency modules
+  // via new URL(<rel>, import.meta.url), resolved next to the bundle).
+  const sidecars = computeSidecars(
+    collectRuntimeReads(content, PKG_ROOT),
+    PKG_ROOT,
+    dirname(OUTFILE),
+  );
+
+  return { content, sidecars };
 }
 
 async function main() {
-  const content = await buildBundle();
+  const { content, sidecars } = await buildBundle();
+  const outDir = dirname(OUTFILE);
 
   if (CHECK_MODE) {
     let existing;
@@ -128,11 +255,38 @@ async function main() {
       console.error(`  expected: sha256:${expectedHash}`);
       process.exit(1);
     }
+    for (const { target, source } of sidecars) {
+      let existingSidecar;
+      try {
+        existingSidecar = await readFile(target);
+      } catch {
+        console.error(`Bundle drift: runtime sidecar missing: ${relative(PKG_ROOT, target)}`);
+        process.exit(1);
+      }
+      const expectedSidecar = await readFile(source);
+      if (!existingSidecar.equals(expectedSidecar)) {
+        console.error(`Bundle drift: runtime sidecar differs: ${relative(PKG_ROOT, target)}`);
+        process.exit(1);
+      }
+    }
+    const unresolved = verifyRuntimeReadsResolve(content, outDir);
+    if (unresolved.length > 0) {
+      console.error(`Bundle drift: runtime resource reads unresolved next to bundle: ${unresolved.join(', ')}`);
+      process.exit(1);
+    }
     console.log('Bundle in sync.');
     process.exit(0);
   }
 
-  await mkdir(dirname(OUTFILE), { recursive: true });
+  for (const { target, source } of sidecars) {
+    const bytes = await readFile(source);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, bytes);
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    console.log(`Sidecar written: ${relative(PKG_ROOT, target)}`);
+    console.log(`  sha256:${hash}`);
+  }
+  await mkdir(outDir, { recursive: true });
   await writeFile(OUTFILE, content, 'utf-8');
   const hash = createHash('sha256').update(content).digest('hex');
   console.log(`Bundle written: ${OUTFILE}`);

package/scripts/sync-public-files.mjs

@@ -228,6 +228,10 @@ async function collectEntries(packageRoot) {
   //    - release-notes/      (consumed by docs-refresh, not a public artifact)
   //    - native/*/build/     (native build artifacts, only prebuilds are shipped)
   //    - scripts/*           (mostly dev-only; explicit whitelist below)
+  //    - vendor/             (G4 foundation-pin: check-time drift evidence, not
+  //                           a distribution artifact; the shipped bundle
+  //                           inlines the adopted capability — matches the npm
+  //                           pack closure contract)
   const baseFiles = allFiles.filter((f) => {
     if (f.startsWith('adapters/')) return false;
     if (f.startsWith('test/')) return false;
@@ -235,6 +239,7 @@ async function collectEntries(packageRoot) {
     if (f.startsWith('release-notes/')) return false;
     if (f.startsWith('native/') && f.includes('/build/')) return false;
     if (f.startsWith('scripts/')) return false;
+    if (f.startsWith('vendor/')) return false;
     return true;
   });
 

package/skills/release-assess/SKILL.md

@@ -44,6 +44,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 
 offline assess 不访问 GitHub/npm 认证，因此不会以顶层 `AUTH_MISSING` 作为正常诊断结果；生产认证缺口由 help 的 `readiness.productionPublish` 和发布前在线门禁报告。
 
+在线模式下 npm 版本检查区分两种失败：registry 明确返回 E404/ETARGET 才算「版本不存在，无 gap」；网络、认证、超时等检查失败会以 `NPM_VERSION_CHECK_FAILED`（warning 级 gap）显式报告，不得把检查失败当作「版本未发布」。
+
 重试时只保留最新结构化错误码和失败门，不沿用早期猜测。
 
 ## 后续引导

package/skills/release-help/SKILL.md

@@ -38,9 +38,11 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 # 日常发布快速路径：仅在发布前确认一次可读计划摘要，状态文件可恢复
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+# 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> --json
 # 仅旧冻结计划兼容：记录历史 Kimi/CodeBuddy 人工证明
+# （本地自声明收据，证明力弱：--actor 仅非空字符串校验、无外部签名核验；新计划不适用）
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
   --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
@@ -59,7 +61,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
 - **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
 - **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
 
-**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权。写入后必须审阅、提交，再重新 prepare。
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权——在 project.yaml 配置 hook 即完成授权（配置时刻即授权契约，FM-16 处置 A）：hook 是任意本地进程、无文件系统/网络隔离、触发前无确认点，配置者须对其内容负责；恢复触发前强制确认门为后续加固项。写入后必须审阅、提交，再重新 prepare。
 
 ## 故障路由
 

package/skills/release-prepare/SKILL.md

@@ -11,9 +11,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 ## 职责与边界
 
-运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。hook 是任意本地进程，不受文件系统/网络隔离，可能产生项目目录外的副作用或远端写入。
+运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-**Hook 与 Gate 执行**: 命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节。
+**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 

package/skills/release-verify/SKILL.md

@@ -19,6 +19,8 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 验证远端所有自动化 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证。新计划中的 Kimi/CodeBuddy 安装只返回 `manualFollowUps`，明确标记 `verifiedBySystem: false`，不阻塞 `VERIFIED`；缺少该策略字段的旧冻结计划继续走历史 attestation 兼容路径。
 
+**attestation 证明力边界**: `attest` 命令记录的旧计划兼容人工证明（`humanConfirmed: true` → `PASSED_MANUAL`）是本地自声明收据，不是签名见证：`--actor` 仅做非空字符串校验，无外部签名或身份核验，任何能运行 CLI 的进程都能自称任意 actor；伪造收据需写 `.release-skill` authority 目录，与直接改写收据文件属同一信任边界。因此旧兼容路径的人工证明只用于旧冻结计划收尾，不构成独立可审计的人工见证。新计划的 Kimi/CodeBuddy 安装一律走 `manualFollowUps`（`verifiedBySystem: false`），不参与 `VERIFIED` 终态判定。
+
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
 **源 run 要求**: `--run` 必需；源 run 的所有 checkpoint 必须为 succeeded 或 skipped。

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

@@ -44,6 +44,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 
 offline assess 不访问 GitHub/npm 认证，因此不会以顶层 `AUTH_MISSING` 作为正常诊断结果；生产认证缺口由 help 的 `readiness.productionPublish` 和发布前在线门禁报告。
 
+在线模式下 npm 版本检查区分两种失败：registry 明确返回 E404/ETARGET 才算「版本不存在，无 gap」；网络、认证、超时等检查失败会以 `NPM_VERSION_CHECK_FAILED`（warning 级 gap）显式报告，不得把检查失败当作「版本未发布」。
+
 重试时只保留最新结构化错误码和失败门，不沿用早期猜测。
 
 ## 后续引导

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

@@ -38,9 +38,11 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 # 日常发布快速路径：仅在发布前确认一次可读计划摘要，状态文件可恢复
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+# 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> --json
 # 仅旧冻结计划兼容：记录历史 Kimi/CodeBuddy 人工证明
+# （本地自声明收据，证明力弱：--actor 仅非空字符串校验、无外部签名核验；新计划不适用）
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
   --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
@@ -59,7 +61,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
 - **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
 - **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
 
-**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权。写入后必须审阅、提交，再重新 prepare。
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权——在 project.yaml 配置 hook 即完成授权（配置时刻即授权契约，FM-16 处置 A）：hook 是任意本地进程、无文件系统/网络隔离、触发前无确认点，配置者须对其内容负责；恢复触发前强制确认门为后续加固项。写入后必须审阅、提交，再重新 prepare。
 
 ## 故障路由
 

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

@@ -11,9 +11,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 ## 职责与边界
 
-运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。hook 是任意本地进程，不受文件系统/网络隔离，可能产生项目目录外的副作用或远端写入。
+运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-**Hook 与 Gate 执行**: 命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节。
+**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 

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

@@ -19,6 +19,8 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 验证远端所有自动化 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证。新计划中的 Kimi/CodeBuddy 安装只返回 `manualFollowUps`，明确标记 `verifiedBySystem: false`，不阻塞 `VERIFIED`；缺少该策略字段的旧冻结计划继续走历史 attestation 兼容路径。
 
+**attestation 证明力边界**: `attest` 命令记录的旧计划兼容人工证明（`humanConfirmed: true` → `PASSED_MANUAL`）是本地自声明收据，不是签名见证：`--actor` 仅做非空字符串校验，无外部签名或身份核验，任何能运行 CLI 的进程都能自称任意 actor；伪造收据需写 `.release-skill` authority 目录，与直接改写收据文件属同一信任边界。因此旧兼容路径的人工证明只用于旧冻结计划收尾，不构成独立可审计的人工见证。新计划的 Kimi/CodeBuddy 安装一律走 `manualFollowUps`（`verifiedBySystem: false`），不参与 `VERIFIED` 终态判定。
+
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
 **源 run 要求**: `--run` 必需；源 run 的所有 checkpoint 必须为 succeeded 或 skipped。

package/src/adapters/contract.mjs

@@ -13,7 +13,9 @@
  * @module adapters/contract
  */
 
-import { writeFile, rename, rm } from 'node:fs/promises';
+import { dirname, basename } from 'node:path';
+
+import { writeFileAtomic } from 'skill-family-harness-node';
 
 import { ReleaseError, AUTH_MISSING } from '../core/errors.mjs';
 
@@ -193,18 +195,16 @@ export function resolveTimeoutMs(action) {
  * create, rename into place). Crash-safe: a partial write never replaces an
  * existing file.
  *
- * @param {string} filePath
+ * 机制已委托 Foundation writeFileAtomic（resolveContained 路径包含三层校验 +
+ * 独占临时文件 + fsync + rename + 目录 fsync）；文件内容与 mode 保持本地语义。
+ *
+ * @param {string} filePath - Absolute path to write.
  * @param {object} value
  */
 export async function writeEvidenceAtomic(filePath, value) {
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-    await rename(tempPath, filePath);
-  } catch (err) {
-    await rm(tempPath, { force: true }).catch(() => {});
-    throw err;
-  }
+  const root = dirname(filePath);
+  const relPath = basename(filePath);
+  await writeFileAtomic(root, relPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
 }
 
 /**

package/src/artifacts/entry.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
 import { ReleaseError, PATH_UNSAFE } from '../core/errors.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -151,10 +152,12 @@ async function enumerateTreeEntries(root, dirPath, relBase) {
  * @returns {string} `sha256:<hex>` digest.
  */
 export function digestEntryManifest(entries) {
+  // 纯 JSON 投影（path/type/mode/size/sha256 定字段），直接委托 Foundation
+  // digestDocument（= sha256(contracts canonicalJson)，与迁移前字节一致）。
   const canonical = entries.map(({ path, type, mode, sha256, size }) => ({
     path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }
 
 // ---------------------------------------------------------------------------

package/src/artifacts/producer-registry.mjs

@@ -14,10 +14,10 @@ import { readFile, readdir, stat, mkdir, writeFile, rm } from 'node:fs/promises'
 import { join } from 'node:path';
 import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestBytes } from 'skill-family-harness-node';
 import {
   ReleaseError,
   ARTIFACT_POLICY_INVALID,
@@ -155,11 +155,14 @@ export async function createBuiltInProducerRegistry() {
  * @returns {string}
  */
 export function computeImplDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 // ---------------------------------------------------------------------------