release-skill 0.8.1 → 0.9.1

package/src/commands/ship.mjs

@@ -2,8 +2,17 @@ import { readFile, lstat, mkdir } from 'node:fs/promises';
 import { basename, dirname, resolve } from 'node:path';
 import { publishFileOrReplace } from 'skill-family-harness-node';
 
+import { MAX_APPROVAL_MS } from '../core/approval.mjs';
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
-import { effectiveHookRequiresApproval } from '../core/postpublish.mjs';
+import {
+  effectiveHookRequiresApproval,
+  normalizePostPublishView,
+  postPublishActionId,
+} from '../core/postpublish.mjs';
+import {
+  derivePostReleaseChecklist,
+  unavailablePostReleaseChecklist,
+} from './post-release-local.mjs';
 import {
   ReleaseError,
   GATE_FAILED,
@@ -80,6 +89,7 @@ async function defaultDependencies() {
     postVerifyRelease: postverifyModule.postVerifyRelease,
     preflightGitTransports: transportModule.preflightGitTransports,
     updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
+    readMaxApprovalMs: () => MAX_APPROVAL_MS,
   };
 }
 
@@ -101,39 +111,142 @@ function publicState(state) {
     ...(state.approvalSummary ? { approvalSummary: state.approvalSummary } : {}),
     ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
     ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
+    ...(state.verifyRunPath ? { verifyRunPath: state.verifyRunPath } : {}),
     ...(state.distributeRunPath ? { distributeRunPath: state.distributeRunPath } : {}),
     ...(state.postVerify ? { postVerify: state.postVerify } : {}),
     ...(state.requirements ? { requirements: state.requirements } : {}),
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
-    verificationGateAuthorizationIncludedInPlanApproval: true,
-    postVerifyMetadataUpdateIncludedInPlanApproval: true,
+    ...(state.postRelease ? { postRelease: state.postRelease } : {}),
+    externalActionsIncludedInPlanApproval: true,
+    verificationGatesIncludedInPlanApproval: true,
+    postPublishCheckpointApprovalsIncludedInPlanApproval: false,
   };
 }
 
+const HOUR_MS = 60 * 60 * 1000;
+
+const ACTION_TARGET_FIELDS = Object.freeze({
+  'push-commit': Object.freeze(['remote', 'branch']),
+  'push-snapshot': Object.freeze(['repo', 'branch', 'branchStrategy', 'commit']),
+  'create-tag': Object.freeze(['repo', 'tag', 'commit']),
+  'npm-publish': Object.freeze(['package', 'version', 'registry', 'tag', 'access', 'provenance']),
+  'github-release': Object.freeze(['repo', 'tag', 'name', 'commit']),
+  'claude-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'codex-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'kimi-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'codebuddy-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'set-default-branch': Object.freeze(['repo', 'oldBranch', 'newBranch', 'expectedNewBranchCommit']),
+});
+
+function deriveApprovalWindowHours(maxApprovalMs) {
+  if (
+    !Number.isSafeInteger(maxApprovalMs)
+    || maxApprovalMs <= 0
+    || maxApprovalMs % HOUR_MS !== 0
+  ) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'core approval window must be a positive whole number of hours',
+      { maxApprovalMs },
+    );
+  }
+  return maxApprovalMs / HOUR_MS;
+}
+
+function projectActionTarget(action) {
+  const parameters = action?.parameters ?? {};
+  return Object.fromEntries(
+    (ACTION_TARGET_FIELDS[action?.type] ?? [])
+      .filter((field) => parameters[field] !== undefined)
+      .map((field) => [field, parameters[field]]),
+  );
+}
+
 /**
  * Build a human-readable approval summary from the frozen plan.
- * Lists each unit's version and every external action's id/type/unitId.
- * Returns an empty summary when the plan file is not yet available (e.g., in tests).
+ * Lists every publish target and every checkpoint approval separately. All
+ * fields are mechanically projected from the frozen plan; unreadable plans
+ * fail closed instead of producing an empty or partial summary.
  *
  * @param {string} planPath - Path to the frozen release plan.
  * @returns {Promise<object>} The approval summary.
  */
-async function buildApprovalSummary(planPath) {
+async function buildApprovalSummary(planPath, maxApprovalMs = MAX_APPROVAL_MS) {
   try {
     const plan = JSON.parse(await readFile(planPath, 'utf8'));
-    const units = (plan.units ?? []).map((unit) => ({
-      id: unit.id,
-      targetVersion: unit.targetVersion ?? unit.version,
-    }));
+    const approvalWindowHours = deriveApprovalWindowHours(maxApprovalMs);
     const actions = (plan.externalActions ?? []).map((action) => ({
       id: action.id,
       type: action.type,
       unitId: action.unitId,
+      target: projectActionTarget(action),
     }));
-    return { units, actions };
-  } catch {
-    return { units: [], actions: [] };
+    const units = (plan.units ?? []).map((unit) => {
+      const targetVersion = unit.targetVersion ?? unit.version;
+      const githubRelease = (plan.externalActions ?? [])
+        .find((action) => action.unitId === unit.id && action.type === 'github-release');
+      return {
+        id: unit.id,
+        targetVersion,
+        publicRepo: unit.publicRepo,
+        branch: unit.frozenSnapshot?.branch
+          ?? unit.productionConfig?.branchTemplate
+            ?.replaceAll('{tag}', unit.tagTemplate?.replace('{version}', targetVersion) ?? '')
+            .replaceAll('{version}', targetVersion)
+            .replaceAll('{unit}', unit.id),
+        branchStrategy: unit.frozenSnapshot?.branchStrategy ?? unit.productionConfig?.branchStrategy,
+        tag: unit.tagTemplate?.replace('{version}', targetVersion),
+        npm: (unit.distributions ?? [])
+          .filter((distribution) => distribution.type === 'npm')
+          .map((distribution) => ({
+            package: distribution.package,
+            version: targetVersion,
+            registry: distribution.registry,
+            distTag: distribution.tag,
+            access: distribution.access,
+            provenance: distribution.provenance,
+          })),
+        ...(githubRelease ? {
+          githubRelease: {
+            repo: githubRelease.parameters?.repo ?? githubRelease.parameters?.publicRepo,
+            tag: githubRelease.parameters?.tag,
+            name: githubRelease.parameters?.name,
+          },
+        } : {}),
+      };
+    });
+    const postPublishCheckpointApprovals = normalizePostPublishView(plan)
+      .flatMap((declaration) => (declaration.hooks ?? [])
+        .filter((hook) => effectiveHookRequiresApproval(hook))
+        .map((hook) => ({
+          unitId: declaration.unitId,
+          hookId: hook.id,
+          actionId: postPublishActionId({
+            planVersion: plan.planVersion,
+            unitId: declaration.unitId,
+            localId: hook.id,
+          }),
+          phase: hook.phase ?? 'distribute',
+          ...(hook.preset !== undefined ? { preset: hook.preset } : {}),
+          ...(hook.config?.delivery !== undefined ? { delivery: hook.config.delivery } : {}),
+          requiresApproval: true,
+          includedInPlanApproval: false,
+          approvalWindowHours,
+          binding: { planDigest: plan.digest, hookId: hook.id },
+        })));
+    return {
+      units,
+      actions,
+      waivers: Array.isArray(plan.waivers) ? plan.waivers : [],
+      postPublishCheckpointApprovals,
+    };
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot build ship approval summary from frozen plan: ${error.message}`,
+      { planPath },
+    );
   }
 }
 
@@ -146,11 +259,19 @@ async function buildApprovalSummary(planPath) {
  * or missing record falls back to ALL declared hooks — fail-safe, because a
  * gated hook in doubt keeps the gate shut.
  *
+ * Checkpoint action ids are unit-scoped for planVersion 3
+ * (`unitId/localId`, postPublishActionId) and bare local ids for legacy
+ * plans, so the closed-set comparison must derive the id from the owning
+ * declaration instead of comparing the bare hook id — otherwise every v3
+ * hook looks unclosed and a closed gated hook keeps the gate shut.
+ *
  * @param {object} state - Ship state (postVerify.runPath inspected).
- * @param {object[]} postVerifyHooks - Declared phase:postVerify hooks.
+ * @param {Array<{hook: object, unitId: string}>} postVerifyHooks - Declared
+ *   phase:postVerify hooks bound to their owning declaration's unitId.
+ * @param {number} planVersion - Frozen plan's planVersion (action-id rule).
  * @returns {Promise<boolean>}
  */
-async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks) {
+async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks, planVersion) {
   if (!Array.isArray(postVerifyHooks) || postVerifyHooks.length === 0) return false;
   let candidates = postVerifyHooks;
   if (state.postVerify?.runPath) {
@@ -163,13 +284,14 @@ async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks) {
             && (cp.status === 'succeeded' || cp.status === 'NO_CHANGE'))
           .map((cp) => cp.actionId),
       );
-      candidates = postVerifyHooks.filter((hook) => !closedIds.has(hook.id));
+      candidates = postVerifyHooks.filter(({ hook, unitId }) =>
+        !closedIds.has(postPublishActionId({ planVersion, unitId, localId: hook.id })));
     } catch {
       candidates = postVerifyHooks; // unreadable record: fail safe
     }
   }
   if (candidates.length === 0) return false;
-  return candidates.every((hook) => effectiveHookRequiresApproval(hook) === false);
+  return candidates.every(({ hook }) => effectiveHookRequiresApproval(hook) === false);
 }
 
 /**
@@ -178,9 +300,11 @@ async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks) {
  * resumes instead of reconstructing authority from terminal/chat output.
  *
  * New flow (v0.4+): ship directly runs configured hooks and verification gates
- * without a separate hook authorization step. The only human gate is plan
- * approval. Kimi/CodeBuddy installations are non-blocking manual follow-up
- * tasks when the plan declares humanConsumersStrategy: 'manualFollowUps'.
+ * without a separate hook authorization step. Plan approval is the only
+ * normal release-level gate. A postPublish hook whose effective
+ * requiresApproval is true still needs its independent checkpoint approval.
+ * Kimi/CodeBuddy installations are non-blocking manual follow-up tasks when
+ * the plan declares humanConsumersStrategy: 'manualFollowUps'.
  */
 export async function advanceShip(options = {}, injected = {}) {
   const root = resolve(options.root ?? process.cwd());
@@ -249,7 +373,10 @@ export async function advanceShip(options = {}, injected = {}) {
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }
-    const approvalSummary = await buildApprovalSummary(prepared.planPath);
+    const maxApprovalMs = typeof deps.readMaxApprovalMs === 'function'
+      ? await deps.readMaxApprovalMs()
+      : MAX_APPROVAL_MS;
+    const approvalSummary = await buildApprovalSummary(prepared.planPath, maxApprovalMs);
     state = {
       ...state,
       status: 'NEEDS_PLAN_APPROVAL',
@@ -344,10 +471,12 @@ export async function advanceShip(options = {}, injected = {}) {
   if (state.status === 'PUBLISHED' || state.status === 'NEEDS_MANUAL_ATTESTATIONS') {
     // Step 1: Check if postPublish requires distribution.
     // Hooks-only declarations (no targets) still route through distribute.
+    // §4.3 unified normalization: v3 empty arrays carry no distribute work;
+    // legacy absent postPublish resolves to the same empty view.
     const plan = JSON.parse(await readFile(state.planPath, 'utf8'));
-    const hasDistributeWork = (plan.postPublish?.targets?.length ?? 0) > 0
-      || (plan.postPublish?.hooks?.length ?? 0) > 0;
-    const needsDistribution = Boolean(plan.postPublish) && hasDistributeWork;
+    const hasDistributeWork = normalizePostPublishView(plan).some((declaration) =>
+      (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
+    const needsDistribution = hasDistributeWork;
     if (needsDistribution && deps.distributeRelease) {
       state.status = 'DISTRIBUTING';
       await writeJsonAtomic(statePath, state);
@@ -404,9 +533,19 @@ export async function advanceShip(options = {}, injected = {}) {
         requirements: undefined,
         manualFollowUps: verified.manualFollowUps ?? undefined,
         baselineAdvance: verified.baselineAdvance ?? undefined,
+        postRelease: undefined,
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);
+      if (verified.status === 'VERIFIED') {
+        try {
+          state.postRelease = derivePostReleaseChecklist(plan);
+        } catch (error) {
+          state.postRelease = unavailablePostReleaseChecklist(plan, error);
+        }
+        state.updatedAt = new Date().toISOString();
+        await writeJsonAtomic(statePath, state);
+      }
     } catch (error) {
       if (error?.code !== CONSUMER_VERIFICATION_DEFERRED) throw error;
       state = {
@@ -422,7 +561,8 @@ export async function advanceShip(options = {}, injected = {}) {
     // independent run after the main run is VERIFIED, with the verify run as
     // lineage source. A PARTIAL postVerify run or a postVerify gate failure
     // NEVER demotes VERIFIED — the outcome is recorded on the ship state.
-    const postVerifyHooks = (plan.postPublish?.hooks ?? [])
+    const postVerifyHooks = normalizePostPublishView(plan)
+      .flatMap((declaration) => declaration.hooks ?? [])
       .filter((hook) => hook.phase === 'postVerify');
     if (state.status === 'VERIFIED' && postVerifyHooks.length > 0 && deps.postVerifyRelease) {
       postVerifyRanThisCall = true;
@@ -476,10 +616,11 @@ export async function advanceShip(options = {}, injected = {}) {
     && (!state.postVerify || state.postVerify.status !== 'DISTRIBUTED')
   ) {
     const reentryPlan = JSON.parse(await readFile(state.planPath, 'utf8'));
-    const reentryPostVerifyHooks = (reentryPlan.postPublish?.hooks ?? [])
-      .filter((hook) => hook.phase === 'postVerify');
+    const reentryPostVerifyHooks = normalizePostPublishView(reentryPlan)
+      .flatMap((declaration) => (declaration.hooks ?? []).map((hook) => ({ hook, unitId: declaration.unitId })))
+      .filter(({ hook }) => hook.phase === 'postVerify');
     const approvallessRetryAllowed = reentryApprovalPaths.length === 0
-      && await allUnclosedPostVerifyHooksUngated(state, reentryPostVerifyHooks);
+      && await allUnclosedPostVerifyHooksUngated(state, reentryPostVerifyHooks, reentryPlan.planVersion);
     if (reentryPostVerifyHooks.length > 0
       && (reentryApprovalPaths.length > 0 || approvallessRetryAllowed)) {
       let postVerifyOutcome;

package/src/commands/verify.mjs

@@ -23,6 +23,7 @@ import { resolveContained } from 'skill-family-harness-node';
 const execFile = promisify(execFileCb);
 
 import { validatePlan, computePlanDigest, validatePlanActionCompleteness } from '../core/plan.mjs';
+import { normalizePostPublishView, postPublishActionId } from '../core/postpublish.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { readRunRecovery } from '../core/recovery.mjs';
 import {
@@ -888,7 +889,7 @@ async function discoverDistributeRuns({ planPath, plan }) {
  *   governance rule that NEEDS_INPUT/BLOCKED cannot silently become VERIFIED.
  *
  * @param {Object} run - A distribute run record (checkpoints + status).
- * @param {Object} plan - The frozen release plan (postPublish.hooks source).
+ * @param {Object} plan - The frozen release plan (normalized postPublish declaration source).
  * @returns {{ pass: boolean, warned: boolean, exemptions: Object[] }}
  */
 export function evaluateDistributeGateRun(run, plan) {
@@ -896,12 +897,19 @@ export function evaluateDistributeGateRun(run, plan) {
   if (run.status === 'DISTRIBUTED') return { pass: true, warned: false, exemptions: [] };
   if (run.status !== 'PARTIAL') return { pass: false, warned: false, exemptions: [] };
 
-  const hooksById = new Map(((plan?.postPublish?.hooks ?? [])).map((hook) => [hook.id, hook]));
+  // §4.3 unified normalization: hooks resolve across all declarations and
+  // are keyed by the SAME action-id derivation the distribute run used, so
+  // v3 namespaced checkpoint ids (unitId/hookId) map back to their hook.
+  const hooksByActionId = new Map((plan ? normalizePostPublishView(plan) : [])
+    .flatMap((declaration) => (declaration.hooks ?? []).map((hook) => [
+      postPublishActionId({ planVersion: plan?.planVersion, unitId: declaration.unitId, localId: hook.id }),
+      hook,
+    ])));
   const exemptions = [];
   for (const checkpoint of run.checkpoints ?? []) {
     if (checkpoint.status === 'succeeded' || checkpoint.status === 'skipped') continue;
     const hook = checkpoint.actionType === 'postpublish-hook'
-      ? hooksById.get(checkpoint.actionId)
+      ? hooksByActionId.get(checkpoint.actionId)
       : undefined;
     if (hook && checkpoint.status === 'failed' && hook.blocksVerified === false) {
       exemptions.push({ actionId: checkpoint.actionId, status: checkpoint.status });
@@ -929,7 +937,7 @@ export function evaluateDistributeGateRun(run, plan) {
  * @param {() => string} [options.clock] - Clock function returning ISO-8601 strings.
  * @param {Object} [options.previousVerifyRun] - 上一次验证成功的 verify run 记录，用于安装契约摘要免验。
  *
- * @returns {Promise<{ planPath: string, status: string, adapterChecks: Object[], smokeTest: Object }>}
+ * @returns {Promise<{ planPath: string, runPath: string, status: string, adapterChecks: Object[], smokeTest: Object }>}
  *
  * @throws {ReleaseError} GATE_FAILED on safety gate failures.
  * @throws {ReleaseError} POST_PUBLISH_VERIFY_FAILED if any verification fails.
@@ -1068,10 +1076,12 @@ export async function verifyRelease(options) {
     // PARTIAL distribute run passes only through the blocksVerified:false
     // exemption path (evaluateDistributeGateRun) — warned, never silent.
     // =======================================================================
-    const declaredPostPublishTargets = plan.postPublish?.targets ?? [];
-    const declaredPostPublishHooks = plan.postPublish?.hooks ?? [];
-    if (plan.postPublish
-      && (declaredPostPublishTargets.length > 0 || declaredPostPublishHooks.length > 0)) {
+    // §4.3 unified normalization: v3 empty arrays mean no distribution
+    // requirement; legacy absent postPublish resolves to the same empty view.
+    const postPublishDeclarations = normalizePostPublishView(plan);
+    const requiresDistribution = postPublishDeclarations.some((declaration) =>
+      (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
+    if (requiresDistribution) {
       await evidence.append({ phase: 'verify', step: 'distribute-run-discovery', status: 'started' });
 
       const distributeCandidates = await discoverDistributeRuns({ planPath, plan }) ?? [];
@@ -2176,6 +2186,7 @@ export async function verifyRelease(options) {
 
     return {
       planPath,
+      runPath: verifyRunPath,
       status: VERIFIED,
       adapterChecks,
       recoveryActionCode: null,

package/src/core/adoption-assessment.mjs

@@ -40,9 +40,6 @@
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { resolveProducerVersion } from './evidence.mjs';
 
-// Keep the assessment entry point compatible without duplicating the rule.
-export { findPostPublishUnitConflict } from './hooks.mjs';
-
 /** Four adoption statuses; never reuses ASSESSED (design §3.2). */
 export const ASSESSMENT_STATUS = Object.freeze({
   NOT_CONFIGURED: 'NOT_CONFIGURED',

package/src/core/approval.mjs

@@ -12,7 +12,8 @@
  * - approvedAt is not in the future (beyond 5-minute clock skew tolerance)
  *
  * The planVersion fork (design: t1-2-digest-decoupling.md §4.3) is
- * centralized here: for planVersion 2 plans the baseline is record-layer
+ * centralized here: for planVersion 2/3 plans (v3 inherits the v2 approval
+ * boundary per 多发布单元 postPublish v3 §4.2) the baseline is record-layer
  * data -- gitTreeHash/workspaceDigest equality and the production workspace
  * digest algorithm double-check are NOT invalidation conditions (artifact
  * integrity is sealed by the frozen-artifact re-verification at publish).
@@ -186,11 +187,13 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  // planVersion fork (centralized here; see module header): v2 plans treat
-  // the baseline as optional record-layer data.
-  const planV2 = plan?.planVersion === 2;
+  // planVersion fork (centralized here; see module header): planVersion 2/3
+  // plans treat the baseline as optional record-layer data (v3 inherits the
+  // v2 approval boundary per 多发布单元 postPublish v3 §4.2). Versions beyond
+  // {2,3} stay on the legacy v1 path and are never silently admitted.
+  const recordLayerBaseline = plan?.planVersion === 2 || plan?.planVersion === 3;
 
-  if (planV2) {
+  if (recordLayerBaseline) {
     if (!approval.planDigest || !approval.expiresAt) {
       throw new ReleaseError(
         GATE_FAILED,
@@ -206,7 +209,7 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  if (!planV2) {
+  if (!recordLayerBaseline) {
     if (plan.production?.mode === 'github-npm-v1') {
       if (plan.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
         throw new ReleaseError(
@@ -249,9 +252,9 @@ export function validateApproval(plan, approval, options = {}) {
   }
 
   // --- baseline equality checks (v1 plans only) ---
-  // For planVersion 2 plans the baseline is record-layer data: it stays in
+  // For planVersion 2/3 plans the baseline is record-layer data: it stays in
   // the plan/approval files for audit but is not an invalidation condition.
-  if (!planV2) {
+  if (!recordLayerBaseline) {
     // --- baseline.gitTreeHash match ---
     if (approval.baseline.gitTreeHash !== plan.baseline?.gitTreeHash) {
       throw new ReleaseError(

package/src/core/derived-artifact-gates.mjs

@@ -5,17 +5,20 @@
  * In the 0.6.1 cycle two prepares burned the full ~80s test hook before
  * surfacing drift that a sub-second check could have caught: adapter trees
  * out of sync with skills-src/, and self-bootstrap fact pins still bound to
- * the previous version. This module promotes those two exact checks to
- * prepare's earliest stage, alongside the bundle freshness gate:
+ * the previous version. This module promotes those checks and the platform
+ * manifest freshness check to prepare's earliest stage, alongside the bundle
+ * freshness gate:
  *
  * - adapter gate: runs `scripts/build-adapters.mjs --check` (drift list,
  *   exit 1 on drift — the same supported check the scripts surface offers);
+ * - platform manifest gate: runs
+ *   `scripts/generate-platform-manifest.mjs --check`;
  * - fact-pin gate: runs the version fact pins of
  *   `test/release-docs-self-bootstrap.test.mjs` — exactly its hermetic
  *   section 1 (`[self-bootstrap 1*]`: byte-level version assertions plus the
  *   in-process read-only planner), scoped via `--test-name-pattern`.
  *
- * Both promote the CANONICAL check logic — the gate and the full pipeline
+ * All three promote the CANONICAL check logic — the gates and the full pipeline
  * can never disagree about what "in sync" means. The facts gate is scoped to
  * the suite's hermetic fact-pin section deliberately: the suite's remaining
  * sections shell out to npm/git and drive fixture prepares, which would make
@@ -88,6 +91,15 @@ const GATES = Object.freeze({
       'Rebuild the existing adapters with: node scripts/build-adapters.mjs --apply ' +
       `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
   }),
+  'platform-manifest': Object.freeze({
+    artifact: 'platform-manifest',
+    marker: join('scripts', 'generate-platform-manifest.mjs'),
+    argv: (pkgRoot) => [join(pkgRoot, 'scripts', 'generate-platform-manifest.mjs'), '--check'],
+    timeoutMs: 120000,
+    remediation:
+      'Regenerate the platform manifest with: node scripts/generate-platform-manifest.mjs ' +
+      `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
+  }),
   'self-bootstrap-facts': Object.freeze({
     artifact: 'self-bootstrap-facts',
     marker: join('test', 'release-docs-self-bootstrap.test.mjs'),
@@ -118,7 +130,7 @@ async function isFile(path) {
 /**
  * Run one derived-artifact check (pure decision, never throws).
  *
- * @param {'adapters' | 'self-bootstrap-facts'} kind - Gate to run.
+ * @param {'adapters' | 'platform-manifest' | 'self-bootstrap-facts'} kind - Gate to run.
  * @param {string} pkgRoot - Absolute package root of the running checkout.
  * @param {object} [options]
  * @param {Function} [options.execFileFn] - execFile seam (tests).
@@ -202,6 +214,11 @@ export function checkAdapterFreshness(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('adapters', pkgRoot, options);
 }
 
+/** Platform manifest freshness decision (generate-platform-manifest --check). */
+export function checkPlatformManifestFreshness(pkgRoot, options = {}) {
+  return checkDerivedArtifactGate('platform-manifest', pkgRoot, options);
+}
+
 /** Self-bootstrap fact-pin decision (single-file test). */
 export function checkSelfBootstrapFacts(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('self-bootstrap-facts', pkgRoot, options);
@@ -215,7 +232,9 @@ async function assertGate(kind, pkgRoot, options = {}) {
   const gate = GATES[kind];
   const subject = kind === 'adapters'
     ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
-    : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+    : kind === 'platform-manifest'
+      ? 'platform-manifest.json is out of sync with the current package tree (generate-platform-manifest --check reported drift)'
+      : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
   throw new ReleaseError(
     DERIVED_ARTIFACT_STALE,
     `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE} ${gate.remediation}`,
@@ -243,6 +262,14 @@ export function assertAdapterFreshness(pkgRoot, options = {}) {
   return assertGate('adapters', pkgRoot, options);
 }
 
+/**
+ * Fail-closed platform manifest pre-gate used by prepare's earliest stage.
+ * Not-applicable layouts return quietly; drift throws DERIVED_ARTIFACT_STALE.
+ */
+export function assertPlatformManifestFreshness(pkgRoot, options = {}) {
+  return assertGate('platform-manifest', pkgRoot, options);
+}
+
 /**
  * Fail-closed self-bootstrap fact-pin pre-gate used by prepare's earliest
  * stage. Not-applicable layouts return quietly; drift throws

package/src/core/hooks.mjs

@@ -43,22 +43,6 @@ const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 // Validation
 // ---------------------------------------------------------------------------
 
-/**
- * A release plan binds at most one postPublish declaration. Both prepare
- * and adoption assessment consume this pure rule and retain their own
- * error codes and presentation. Declaration contents are validated by
- * the existing postPublish validator, not by this cross-unit check.
- *
- * @param {Array<Object>} units - config.releaseUnits.
- * @returns {null|{unitIds: string[]}} Sorted conflicting unit IDs, or null.
- */
-export function findPostPublishUnitConflict(units) {
-  const declaring = (units ?? [])
-    .filter((unit) => unit && typeof unit === 'object' && unit.postPublish !== undefined);
-  if (declaring.length <= 1) return null;
-  return { unitIds: declaring.map((unit) => unit.id).sort() };
-}
-
 /**
  * Validate the shape of a hook descriptor against the project contract.
  *

package/src/core/plan.mjs

@@ -202,7 +202,8 @@ export function validatePlan(plan) {
 }
 
 /**
- * planVersion 2 digest scope (design: t1-2-digest-decoupling.md §4.1).
+ * planVersion 2/3 digest scope (design: t1-2-digest-decoupling.md §4.1;
+ * v3 inherits the v2 scope per 多发布单元 postPublish v3 §4.2).
  *
  * The record layer -- top-level `digest`, lifecycle `status`, `createdAt`,
  * the whole `baseline` object, and each action's runtime `status` -- is
@@ -210,8 +211,10 @@ export function validatePlan(plan) {
  * but is excluded from the digest. Everything else (planVersion, units with
  * every frozenSnapshot artifact identity field, externalActions identity,
  * production, configDigest, verificationGates, snapshotDigest) binds.
+ * For v3 the frozen `postPublish` array and every item binding field stay in
+ * the binding layer: any order or binding change moves the digest.
  *
- * This is the ONLY place the v2 record layer is defined.
+ * This is the ONLY place the v2/v3 record layer is defined.
  *
  * @param {object} plan - A plan object.
  * @returns {object} The binding-layer projection of the plan.
@@ -242,9 +245,12 @@ function stripRecordLayerV2(plan) {
  *
  * Digest scope forks on `plan.planVersion` (centralized here, never spread
  * elsewhere):
- * - planVersion 2: record-layer fields (status/createdAt/baseline/action
+ * - planVersion 2/3: record-layer fields (status/createdAt/baseline/action
  *   status/digest) are stripped before hashing, so re-preparing over the
- *   same sources yields the same digest. See `stripRecordLayerV2`.
+ *   same sources yields the same digest. See `stripRecordLayerV2`. v3
+ *   inherits the v2 scope exactly (multi-release-unit postPublish v3 §4.2);
+ *   versions beyond {2,3} are NOT admitted and stay fail-closed on the
+ *   legacy v1 path rather than being silently bound to v2 semantics.
  * - planVersion 1 or absent (legacy): only the top-level `digest` field is
  *   stripped. Byte-for-byte legacy semantics -- this path must never change.
  *
@@ -258,7 +264,7 @@ export function computePlanDigest(plan) {
   // 而是经 digest.mjs 的宽松输入域包装（contracts 权威序列化 + 本地归一化）
   // 后由 Foundation digestBytes 摘要 —— 对纯 JSON 计划与 digestDocument 字节
   // 完全一致，对含 undefined 的计划保持迁移前字节语义。
-  if (plan.planVersion === 2) {
+  if (plan.planVersion === 2 || plan.planVersion === 3) {
     return sha256Hex(canonicalJson(stripRecordLayerV2(plan)));
   }
   // Strip the digest field if present so the hash is self-consistent.
@@ -341,14 +347,15 @@ export async function writePlanImmutable(planPath, plan) {
       // 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
+      // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.1; v3 inherits
+      // the scope per 多发布单元 postPublish v3 §4.2): record-layer fields
+      // (status/createdAt/baseline) are excluded from the digest, so
       // re-preparing over identical binding content yields the SAME digest
       // with legitimately different bytes. Reuse the existing authority IFF
       // 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 && existing !== null) {
+      if ((plan.planVersion === 2 || plan.planVersion === 3) && existing !== null) {
         let existingPlan = null;
         try {
           existingPlan = JSON.parse(existing);
@@ -386,7 +393,7 @@ export async function writePlanImmutable(planPath, plan) {
 /**
  * Canonical normalized freeze timestamp shape (`YYYY-MM-DDTHH:MM:SS+00:00`).
  * Mirrors the frozenSnapshot.commitTimestamp pattern in the release-plan
- * schema; used by the planVersion 2 completeness gate, which requires a
+ * schema; used by the planVersion 2/3 completeness gate, which requires a
  * canonical normalized timestamp without re-binding it to plan.createdAt.
  */
 const CANONICAL_COMMIT_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$/;
@@ -568,8 +575,9 @@ export function validatePlanActionCompleteness(plan, options = {}) {
       }
       if (!frozen.commitTimestamp || typeof frozen.commitTimestamp !== 'string') {
         failures.push(`unit "${unitId}" frozenSnapshot.commitTimestamp is missing; legacy production plans without a freeze timestamp are rejected, never silently backfilled`);
-      } else if (plan.planVersion === 2) {
-        // planVersion 2 (design: t1-2-digest-decoupling.md §4.2): the freeze
+      } else if (plan.planVersion === 2 || plan.planVersion === 3) {
+        // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.2; v3 inherits
+        // the semantics per 多发布单元 postPublish v3 §4.2): the freeze
         // timestamp is derived from the headCommit committer date, so it no
         // longer equals plan.createdAt (record-layer real clock). It must
         // still be a canonical normalized timestamp -- the same pattern the