release-skill 0.8.1 → 0.9.1

package/src/commands/prepare.mjs

@@ -28,7 +28,7 @@ const execFile = promisify(execFileCb);
 import { classifyPathInput, writeFileAtomic } from 'skill-family-harness-node';
 import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
-import { findPostPublishUnitConflict, runHook } from '../core/hooks.mjs';
+import { runHook } from '../core/hooks.mjs';
 import { computeHookCacheKey, readHookCache, writeHookCache } from '../core/hook-cache.mjs';
 import {
   assertExpectedPublicSurface,
@@ -57,7 +57,11 @@ import {
 } from '../snapshot/frozen.mjs';
 import { ReleaseError, GATE_FAILED, CONFIG_INVALID, CONFIG_MISSING, FORBIDDEN_CONTENT_DETECTED, RELEASE_DOCS_STALE, DIRTY_SOURCE_INPUT, BUNDLE_STALE } from '../core/errors.mjs';
 import { assertBundleFreshness } from '../core/bundle-freshness.mjs';
-import { assertAdapterFreshness, assertSelfBootstrapFacts } from '../core/derived-artifact-gates.mjs';
+import {
+  assertAdapterFreshness,
+  assertPlatformManifestFreshness,
+  assertSelfBootstrapFacts,
+} from '../core/derived-artifact-gates.mjs';
 import { isFoundationPluginVerificationEligible } from '../core/foundation-plugin-verification.mjs';
 import { PKG_ROOT } from '../core/pkg-root.mjs';
 import { writeFrozenMarker, FROZEN_MARKER_FILENAME } from '../core/frozen-marker.mjs';
@@ -81,6 +85,7 @@ import {
   validatePostPublishDeclaration,
   normalizePostPublishDeclaration,
   orderNormalizedHooks,
+  validatePostPublishHookIdUniqueness,
   PAYLOAD_SOURCE_TAG_WORKTREE,
 } from '../core/postpublish.mjs';
 import { freezeExecutionBundle, bundleRootForAuthorityDir } from '../core/postpublish-bundle.mjs';
@@ -3024,8 +3029,9 @@ export async function prepareRelease(options) {
     // --- Step 1b-fast: version-sensitive derived-artifact fast pre-gates (O1) ---
     // 2026-08-18 investigation §3.2: adapter drift and stale self-bootstrap
     // fact pins used to surface only deep inside the ~80s full test hook.
-    // Promote the two exact canonical checks (build-adapters --check and the
-    // release-docs-self-bootstrap single-file test) to prepare's earliest
+    // Promote the three exact canonical checks (build-adapters --check,
+    // generate-platform-manifest --check, and the release-docs-self-bootstrap
+    // single-file test) to prepare's earliest
     // stage so the same drift fails closed in seconds, before any hook. Like
     // the bundle freshness gate this is artifact-integrity class: workflow
     // trimming never exempts it. Installed layouts record not-applicable.
@@ -3033,7 +3039,8 @@ export async function prepareRelease(options) {
     // the CLI, plain function calls, and the node:test harness — no
     // environment variable may exempt them (a test seam is never a
     // production switch). Tests that need lightweight fixtures inject the
-    // adapterFreshnessFn/selfBootstrapFactsFn seams explicitly in-process.
+    // adapterFreshnessFn/platformManifestFreshnessFn/selfBootstrapFactsFn
+    // seams explicitly in-process.
     await evidence.append({ phase: 'adapter-freshness', status: 'started' });
     const adapterFreshnessFn = options.adapterFreshnessFn ?? assertAdapterFreshness;
     let adapterFreshness;
@@ -3062,6 +3069,35 @@ export async function prepareRelease(options) {
       });
     }
 
+    await evidence.append({ phase: 'platform-manifest-freshness', status: 'started' });
+    const platformManifestFreshnessFn = options.platformManifestFreshnessFn
+      ?? assertPlatformManifestFreshness;
+    let platformManifestFreshness;
+    try {
+      platformManifestFreshness = await platformManifestFreshnessFn(PKG_ROOT);
+    } catch (err) {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'blocking',
+        reason: err.details?.reason ?? null,
+        error: { code: err.code, message: err.message },
+      });
+      throw err;
+    }
+    if (platformManifestFreshness?.applicable === false) {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'not-applicable',
+        reason: platformManifestFreshness.reason,
+      });
+    } else {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'completed',
+        durationMs: platformManifestFreshness?.durationMs ?? null,
+      });
+    }
+
     await evidence.append({ phase: 'self-bootstrap-facts', status: 'started' });
     const selfBootstrapFactsFn = options.selfBootstrapFactsFn ?? assertSelfBootstrapFacts;
     let selfBootstrapFacts;
@@ -3092,38 +3128,31 @@ export async function prepareRelease(options) {
 
     // --- Step 1c: postPublish distribution declaration gate (R1/R2) ---
     // The per-unit postPublish block drives the post-publish distribute
-    // command. Validate it here, before any hook, baseline, snapshot, remote
-    // check, or plan write, so an unsafe declaration fails closed with zero
-    // side effects. This is the runtime re-check on top of the config JSON
-    // schema: plans frozen by older schema versions must not be able to
-    // smuggle shell strings, option-like executables, or secret-ish env
-    // keys through. R2: preset references resolve against the built-in
-    // preset registry (per-preset config validation + requiresApproval
-    // grading), and targets normalize onto preset hooks — the normalized
-    // table is a deterministic projection of the digest-bound declaration,
-    // so any list change changes the plan digest and voids approvals. A
-    // plan binds exactly one declaration; multiple units declaring
-    // postPublish is a hard gate failure.
+    // command. Validate every declaration here, before any hook, baseline,
+    // snapshot, remote check, or plan write, so an unsafe declaration fails
+    // closed with zero side effects. This is the runtime re-check on top of
+    // the config JSON schema: plans frozen by older schema versions must not
+    // be able to smuggle shell strings, option-like executables, or
+    // secret-ish env keys through. R2: preset references resolve against the
+    // built-in preset registry (per-preset config validation +
+    // requiresApproval grading), and targets normalize onto preset hooks —
+    // the normalized table is a deterministic projection of the digest-bound
+    // declaration, so any list change changes the plan digest and voids
+    // approvals. Multiple units may each declare postPublish (multi-release-
+    // unit v3): every declaration is validated individually, in plan.units
+    // order, and the whole project's EXPLICIT hooks[].id must be unique
+    // across units (target and internal probe local ids may repeat; the
+    // (planDigest, hookId) approval contract needs globally unique hook ids).
     const postPublishDeclarations = configUnits
       .map((unit, index) => ({ unit, index }))
       .filter(({ unit }) => unit.postPublish !== undefined);
-    if (findPostPublishUnitConflict(configUnits)) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `multiple units declare postPublish (${postPublishDeclarations.map(({ unit }) => unit.id).join(', ')}); a release plan binds exactly one postPublish declaration`,
-        { unitIds: postPublishDeclarations.map(({ unit }) => unit.id) },
-      );
-    }
-    let postPublishDeclaration = null;
-    if (postPublishDeclarations.length === 1) {
-      const { unit, index } = postPublishDeclarations[0];
+    for (const { unit } of postPublishDeclarations) {
       validatePostPublishDeclaration(unit.postPublish, { unitId: unit.id });
       // Normalized hook table (design §2.2): validate the dependency
       // topology at freeze time too, so a cyclic/dangling declaration can
       // never be frozen for distribute to trip over.
       const normalizedDeclaration = normalizePostPublishDeclaration(unit.postPublish);
       const orderedNormalizedHooks = orderNormalizedHooks(normalizedDeclaration.hooks);
-      postPublishDeclaration = { unit, index };
       await evidence.append({
         phase: 'postpublish-declaration',
         status: 'validated',
@@ -3134,6 +3163,19 @@ export async function prepareRelease(options) {
         preGates: normalizedDeclaration.preGates.map((gate) => gate.gate),
       });
     }
+    // Whole-project explicit hooks[].id uniqueness (design §9.2 rule 3;
+    // rework R-02): the (planDigest, hookId) approval contract binds every
+    // explicit hook id plan-wide, so a duplicate across units must fail
+    // before any plan write and before any project hook runs. The single
+    // array-level authority lives in core/postpublish.mjs
+    // validatePostPublishHookIdUniqueness — this entry only normalizes its
+    // input to the declaration array view (config blocks carry no unitId;
+    // the owning unit id is bound here, exactly as the frozen plan does) and
+    // calls it. Per-declaration duplicates are already rejected by
+    // validatePostPublishDeclaration.
+    validatePostPublishHookIdUniqueness(
+      postPublishDeclarations.map(({ unit }) => ({ ...unit.postPublish, unitId: unit.id })),
+    );
 
     // --- Step 2: Hook authorization gate ---
     // Hooks are user-configured arbitrary local processes without filesystem
@@ -3841,20 +3883,21 @@ export async function prepareRelease(options) {
       });
     }
 
-    // New prepares emit planVersion 2 (design: t1-2-digest-decoupling.md
-    // §4.2/§7). Production freeze timestamps are derived deterministically
-    // from the baseline headCommit's committer date, before the first frozen
-    // Git object exists. This single canonical value becomes
-    // GIT_AUTHOR_DATE/GIT_COMMITTER_DATE for every unit's frozen commit and
-    // every unit's frozenSnapshot.commitTimestamp; identical sources freeze
-    // byte-identical Git objects on every re-prepare. The wall-clock sample
-    // is still validated here (fail closed before any Git write) and becomes
-    // plan.createdAt -- record-layer real clock behind the 24h approval
-    // window, no longer equal to the freeze timestamp for v2 plans. The v1
-    // legacy path used this same sample as the freeze timestamp itself
-    // (commitTimestamp == createdAt). publish, retry, and reconcile consume
-    // the frozen value from the plan and never re-read the wall clock or
-    // re-derive it.
+    // New prepares emit planVersion 3 (multi-release-unit postPublish v3;
+    // v3 inherits the v2 record-layer freeze-timestamp semantics from
+    // t1-2-digest-decoupling.md §4.2/§7). Production freeze timestamps are
+    // derived deterministically from the baseline headCommit's committer
+    // date, before the first frozen Git object exists. This single canonical
+    // value becomes GIT_AUTHOR_DATE/GIT_COMMITTER_DATE for every unit's
+    // frozen commit and every unit's frozenSnapshot.commitTimestamp;
+    // identical sources freeze byte-identical Git objects on every
+    // re-prepare. The wall-clock sample is still validated here (fail closed
+    // before any Git write) and becomes plan.createdAt -- record-layer real
+    // clock behind the 24h approval window, no longer equal to the freeze
+    // timestamp for v2/v3 plans. The v1 legacy path used this same sample as
+    // the freeze timestamp itself (commitTimestamp == createdAt). publish,
+    // retry, and reconcile consume the frozen value from the plan and never
+    // re-read the wall clock or re-derive it.
     const createdAtTimestamp = production
       ? normalizeGitTimestamp(clock ? clock() : new Date().toISOString(), 'plan createdAt timestamp')
       : null;
@@ -4252,16 +4295,20 @@ export async function prepareRelease(options) {
         ? 'foundationPayloadThenManualFollowUps'
         : 'manualFollowUps';
 
-    // --- Fold the validated postPublish declaration into the frozen plan ---
-    // Bindings: tag (tagTemplate rendered at the resolved target version —
-    // the same computation create-tag will use), tagCommit (the frozen
-    // production asset commit the tag will point at; only production
+    // --- Fold the validated postPublish declarations into the frozen plan ---
+    // Multi-release-unit v3 contract: the frozen field is ALWAYS an array,
+    // one entry per declaring unit in plan.units order (zero declarations
+    // freeze the empty array, which never enters post-release execution).
+    // Bindings per entry: tag (tagTemplate rendered at the resolved target
+    // version — the same computation create-tag will use), tagCommit (the
+    // frozen production asset commit the tag will point at; only production
     // prepares can freeze it — distribute fails closed when it is absent),
     // unitId (declaring unit), and payloadSource "tag-worktree" (R1 timing
     // contract: payload may only come from the detached worktree at
-    // tagCommit, never from workspace state). planVersion 2 record-layer
-    // stripping does not strip this block, so every declaration detail is
-    // bound into the plan digest.
+    // tagCommit, never from workspace state). The array and every entry
+    // participate in the plan digest through the existing digest mechanism
+    // (no per-entry summaries, maps, or second manifest), so declaration
+    // order and any bound field change change the plan digest.
     //
     // F-01 / T1 private execution bundle: parent-workspace files that the
     // post-publish commands need but the frozen tag does not contain are
@@ -4271,9 +4318,8 @@ export async function prepareRelease(options) {
     // plan is the bundle's only source of truth (no parallel manifest, no
     // second bundle digest): the raw executionFiles list folds into the
     // closure and is NOT duplicated into the frozen block.
-    let frozenPostPublish = null;
-    if (postPublishDeclaration) {
-      const { unit, index } = postPublishDeclaration;
+    const frozenPostPublish = [];
+    for (const { unit, index } of postPublishDeclarations) {
       const { tag } = resolveProductionBranch(unit, resolvedVersions[index]);
       const declaredExecutionFiles = unit.postPublish.executionFiles ?? [];
       const frozenTagPaths = productionAssets
@@ -4300,18 +4346,22 @@ export async function prepareRelease(options) {
         bundleRoot: relative(realRoot, bundleRootForAuthorityDir(releaseDir)),
       });
       const { executionFiles: _executionFiles, ...declarationWithoutManifest } = structuredClone(unit.postPublish);
-      frozenPostPublish = {
+      frozenPostPublish.push({
         ...declarationWithoutManifest,
         tag,
         ...(productionAssets ? { tagCommit: productionAssets[index].commit } : {}),
         unitId: unit.id,
         payloadSource: PAYLOAD_SOURCE_TAG_WORKTREE,
         executionBundle,
-      };
+      });
     }
 
     const plan = {
-      planVersion: 2,
+      // New prepares emit planVersion 3 (multi-release-unit postPublish v3):
+      // postPublish is the declaration ARRAY (possibly empty). v3 inherits
+      // the v2 record-layer digest and approval semantics; only the
+      // postPublish shape changes.
+      planVersion: 3,
       status: 'PREPARED',
       // Workflow profile (H5): 'full' for the complete gate set;
       // 'docs'/'config'/'marketplace' for trimmed code-class gates. Both
@@ -4352,7 +4402,7 @@ export async function prepareRelease(options) {
       units,
       externalActions,
       ...(publicSourceAuthorityReceipt ? { publicSourceAuthorityReceipt } : {}),
-      ...(frozenPostPublish ? { postPublish: frozenPostPublish } : {}),
+      postPublish: frozenPostPublish,
       ...(sourceAuthority ? { sourceAuthority } : {}),
       createdAt: production ? createdAtTimestamp : (clock ? clock() : new Date().toISOString()),
     };

package/src/commands/publish.mjs

@@ -791,21 +791,22 @@ export async function publishRelease(options) {
 
     const currentBaseline = await captureBaselineActual(root);
 
-    // planVersion fork (design: t1-2-digest-decoupling.md §4.3): for v2
-    // plans the baseline is record-layer audit data. Drift is recorded as a
-    // warning and execution continues -- artifact integrity is sealed by the
-    // frozen-artifact re-verification above, never by workspace equality.
-    // v1 plans keep the BASELINE_CHANGED hard failure, byte for byte.
-    const planV2 = plan.planVersion === 2;
+    // planVersion fork (design: t1-2-digest-decoupling.md §4.3): for
+    // planVersion 2/3 plans (v3 inherits the v2 semantics per 多发布单元
+    // postPublish v3 §4.2) the baseline is record-layer audit data. Drift is
+    // recorded as a warning and execution continues -- artifact integrity is
+    // sealed by the frozen-artifact re-verification above, never by workspace
+    // equality. v1 plans keep the BASELINE_CHANGED hard failure, byte for byte.
+    const recordLayerBaseline = plan.planVersion === 2 || plan.planVersion === 3;
 
     if (currentBaseline.gitTreeHash !== plan.baseline.gitTreeHash) {
-      if (planV2) {
+      if (recordLayerBaseline) {
         await evidence.append({
           phase: 'safety-gate',
           gate: 'baseline-check',
           status: 'warning',
           severity: 'warning',
-          reason: 'planVersion 2: baseline drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
+          reason: 'planVersion 2/3: baseline drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
           planTreeHash: plan.baseline.gitTreeHash,
           currentTreeHash: currentBaseline.gitTreeHash,
         });
@@ -831,13 +832,13 @@ export async function publishRelease(options) {
       plan.baseline.workspaceDigest &&
       currentBaseline.workspaceDigest !== plan.baseline.workspaceDigest
     ) {
-      if (planV2) {
+      if (recordLayerBaseline) {
         await evidence.append({
           phase: 'safety-gate',
           gate: 'baseline-check',
           status: 'warning',
           severity: 'warning',
-          reason: 'planVersion 2: workspace digest drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
+          reason: 'planVersion 2/3: workspace digest drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
           planWorkspaceDigest: plan.baseline.workspaceDigest,
           currentWorkspaceDigest: currentBaseline.workspaceDigest,
         });

package/src/commands/reconcile.mjs

@@ -357,21 +357,22 @@ export async function reconcileRelease(options) {
 
     const currentBaseline = await captureBaselineActual(root);
 
-    // planVersion fork (design: t1-2-digest-decoupling.md §4.3): for v2
-    // plans the baseline is record-layer audit data. Drift is recorded as a
-    // warning and execution continues -- artifact integrity is sealed by the
-    // frozen-artifact re-verification, never by workspace equality. v1 plans
-    // keep the BASELINE_CHANGED hard failure, byte for byte.
-    const planV2 = plan.planVersion === 2;
+    // planVersion fork (design: t1-2-digest-decoupling.md §4.3): for
+    // planVersion 2/3 plans (v3 inherits the v2 semantics per 多发布单元
+    // postPublish v3 §4.2) the baseline is record-layer audit data. Drift is
+    // recorded as a warning and execution continues -- artifact integrity is
+    // sealed by the frozen-artifact re-verification, never by workspace
+    // equality. v1 plans keep the BASELINE_CHANGED hard failure, byte for byte.
+    const recordLayerBaseline = plan.planVersion === 2 || plan.planVersion === 3;
 
     if (currentBaseline.gitTreeHash !== plan.baseline.gitTreeHash) {
-      if (planV2) {
+      if (recordLayerBaseline) {
         await evidence.append({
           phase: 'safety-gate',
           gate: 'baseline-check',
           status: 'warning',
           severity: 'warning',
-          reason: 'planVersion 2: baseline drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
+          reason: 'planVersion 2/3: baseline drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
           planTreeHash: plan.baseline.gitTreeHash,
           currentTreeHash: currentBaseline.gitTreeHash,
         });
@@ -396,13 +397,13 @@ export async function reconcileRelease(options) {
       plan.baseline.workspaceDigest &&
       currentBaseline.workspaceDigest !== plan.baseline.workspaceDigest
     ) {
-      if (planV2) {
+      if (recordLayerBaseline) {
         await evidence.append({
           phase: 'safety-gate',
           gate: 'baseline-check',
           status: 'warning',
           severity: 'warning',
-          reason: 'planVersion 2: workspace digest drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
+          reason: 'planVersion 2/3: workspace digest drift is record-layer audit data; frozen-artifact re-verification remains the integrity authority',
           planWorkspaceDigest: plan.baseline.workspaceDigest,
           currentWorkspaceDigest: currentBaseline.workspaceDigest,
         });

package/src/commands/setup.mjs

@@ -34,7 +34,7 @@ import {
 } from '../core/errors.mjs';
 import { readTrustedPackageResource } from '../core/trusted-resource.mjs';
 import { validatePresetHook } from '../core/presets.mjs';
-import { validatePostPublishDeclaration } from '../core/postpublish.mjs';
+import { validatePostPublishDeclaration, validatePostPublishHookIdUniqueness } from '../core/postpublish.mjs';
 import { loadProjectConfig } from '../core/config.mjs';
 import { resolveProducerVersion } from '../core/evidence.mjs';
 import { validateHook } from '../core/hooks.mjs';
@@ -46,7 +46,6 @@ import {
   deriveGateSuggestions,
   deriveHookDurations,
   deriveLongHookSuggestions,
-  findPostPublishUnitConflict,
   scanGateDeclarationFindings,
   FINDING_CATEGORY,
   ASSESSMENT_STATUS,
@@ -3101,17 +3100,31 @@ export async function assessAdoption({ root } = {}) {
     evidence: { configDigest },
   }));
 
-  // 裁决 20: 跨单元 postPublish 规则（一次发布计划只绑定一个声明）。
-  const postPublishConflict = findPostPublishUnitConflict(declaredUnits);
-  if (postPublishConflict) {
-    findings.push(createFinding({
-      category: FINDING_CATEGORY.MANDATORY_GAP, code: 'POSTPUBLISH_MULTI_UNIT_CONFLICT',
-      fieldPath: 'releaseUnits[].postPublish',
-      message: `多个发布单元声明 postPublish（${postPublishConflict.unitIds.join(', ')}）；一次发布计划只绑定一个 postPublish 声明。`,
-      evidence: { unitIds: postPublishConflict.unitIds },
-      action: '只保留一个发布单元的 postPublish 声明（或将分发目标合并进同一单元）后重新评估。',
-      severity: 'blocking',
-    }));
+  // 多发布单元 postPublish v3（设计 §9.2/§9.7；返工 R-02）：多个发布单元
+  // 各自声明 postPublish 本身不再构成缺口——每个声明的字段级校验已在上面
+  // 逐项完成。仍失败关闭的只有：声明内容无效（POSTPUBLISH_INVALID，逐项
+  // 报告）与整份计划显式 hooks[].id 跨单元重复（(planDigest, hookId) 批准
+  // 合同要求全局唯一；target 与内部 probe 的本地 ID 可跨单元重复，检查点
+  // 以 unitId 区分）。唯一校验真源是 core/postpublish.mjs 的
+  // validatePostPublishHookIdUniqueness——本入口只做输入归一（收集各单元的
+  // 声明块）并调用同一函数，再把领域事实转成评估 finding。
+  const declaredPostPublishBlocks = declaredUnits
+    .filter((unit) => unit.postPublish !== undefined)
+    .map((unit) => ({ ...unit.postPublish, unitId: unit.id }));
+  try {
+    validatePostPublishHookIdUniqueness(declaredPostPublishBlocks);
+  } catch (error) {
+    if (error?.details?.hookId !== undefined && Array.isArray(error?.details?.unitIds)) {
+      const [owner, unitId] = error.details.unitIds;
+      findings.push(createFinding({
+        category: FINDING_CATEGORY.MANDATORY_GAP, code: 'POSTPUBLISH_HOOK_ID_DUPLICATE',
+        unitId, fieldPath: 'releaseUnits[].postPublish.hooks[].id',
+        message: `postPublish 显式 hook id "${error.details.hookId}" 同时由发布单元 "${owner}" 与 "${unitId}" 声明；整份计划的显式 hooks[].id 必须唯一（target 与内部 probe 的本地 ID 可跨单元重复）。`,
+        evidence: { hookId: error.details.hookId, unitIds: error.details.unitIds },
+        action: '为重复的显式 hook id 改名（或合并声明）后重新评估。',
+        severity: 'blocking',
+      }));
+    }
   }
 
   // 裁决 20: 评估复用实际 Hook 校验（core/hooks.mjs 的纯校验函数，不调用