release-skill 0.8.0 → 0.9.0

package/src/core/postpublish-bundle.mjs

@@ -244,28 +244,38 @@ function sameClosureResources(actual, expected) {
 }
 
 /**
- * Re-verify the frozen execution bundle and install ONLY the verified bytes
- * into the detached tag worktree. Runs BEFORE any hook or external write.
+ * Verify the frozen execution bundle closure WITHOUT installing anything
+ * (rework R-01: the full-declaration preflight reuses this exact
+ * implementation before the first external write — a later declaration's
+ * missing/drifted bundle must fail the whole saga with zero writes).
  *
- * Steps:
+ * Steps (the first half of verifyAndInstallExecutionBundle, shared verbatim):
  * 1. Strictly read every frozen resource from the digest-addressed store
  *    (`readFileStrict` with the frozen sha256 content guard); the file mode
  *    must still equal the publication mode — any deviation is tamper;
  * 2. recompute the closure through Foundation in a disposable workspace and
- *    compare it (digest + resources) with the plan's frozen closure;
- * 3. exclusively publish the verified bytes into the worktree — an occupied
- *    target means the bundle would shadow a frozen tag file and fails closed.
+ *    compare it (digest + resources) with the plan's frozen closure.
  *
  * @param {object} params
- * @param {object} params.plan - Frozen plan (postPublish.executionBundle).
+ * @param {object} params.postPublish - The CURRENT declaration being
+ *   verified (REQUIRED, rework R-06: the v1/v2 normalized single item or the
+ *   v3 loop item; an array fails closed).
  * @param {string} params.planPath - Absolute plan authority path (mechanical
  *   bundle-root anchor).
- * @param {string} params.worktreePath - Detached tag worktree root.
- * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ * @returns {Promise<{verified: boolean, bytesByPath: Map<string, Buffer>}>}
+ *   `verified: false` with an empty map when the declaration carries no
+ *   executionBundle (a legal no-bundle declaration).
  */
-export async function verifyAndInstallExecutionBundle({ plan, planPath, worktreePath } = {}) {
-  const bundle = plan?.postPublish?.executionBundle;
-  if (!bundle) return { installed: [] };
+export async function verifyExecutionBundle({ planPath, postPublish } = {}) {
+  const declaration = postPublish;
+  if (!declaration || typeof declaration !== 'object') {
+    fail('verifyExecutionBundle requires the current postPublish declaration; pass the normalized single item or the v3 loop item explicitly');
+  }
+  if (Array.isArray(declaration)) {
+    fail('verifyExecutionBundle requires the current postPublish declaration, never the declaration array');
+  }
+  const bundle = declaration.executionBundle;
+  if (!bundle) return { verified: false, bytesByPath: new Map() };
   const closure = bundle.closure;
   if (!closure || !Array.isArray(closure.resources) || typeof closure.digest !== 'string') {
     fail('plan carries a malformed executionBundle closure');
@@ -318,10 +328,38 @@ export async function verifyAndInstallExecutionBundle({ plan, planPath, worktree
     fail(`bundle closure recomputation failed: ${cause?.message ?? cause}`, { kind: cause?.details?.kind });
   }
 
+  return { verified: true, bytesByPath };
+}
+
+/**
+ * Re-verify the frozen execution bundle (the SAME closure verification the
+ * full-declaration preflight runs) and install ONLY the verified bytes into
+ * the detached tag worktree. Runs BEFORE any hook or external write.
+ *
+ * Install step: exclusively publish the verified bytes into the worktree —
+ * an occupied target means the bundle would shadow a frozen tag file and
+ * fails closed.
+ *
+ * @param {object} params
+ * @param {object} params.postPublish - The CURRENT declaration being
+ *   executed (v3 multi-unit contract §4.3). REQUIRED (rework R-06): callers
+ *   must pass the declaration explicitly — v1/v2 callers pass the single item
+ *   obtained from normalizePostPublishView(), v3 callers pass their loop
+ *   item. Omitting it fails closed; an array never matches (fail-closed).
+ * @param {string} params.planPath - Absolute plan authority path (mechanical
+ *   bundle-root anchor).
+ * @param {string} params.worktreePath - Detached tag worktree root.
+ * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ */
+export async function verifyAndInstallExecutionBundle({ planPath, worktreePath, postPublish } = {}) {
+  const { bytesByPath } = await verifyExecutionBundle({ planPath, postPublish });
+  const declaration = postPublish;
+  const closure = declaration?.executionBundle?.closure;
+
   // Install verified bytes into the tag worktree — exclusively: the bundle
   // must never overwrite (shadow) a file that already belongs to the tag.
   const installed = [];
-  for (const resource of closure.resources) {
+  for (const resource of closure?.resources ?? []) {
     try {
       await publishFileExclusive(worktreePath, resource.path, bytesByPath.get(resource.path), {
         mode: EXECUTION_BUNDLE_FILE_MODE,

package/src/core/postpublish.mjs

@@ -481,6 +481,131 @@ export function validatePostPublishDeclaration(postPublish, options = {}) {
   return postPublish;
 }
 
+/**
+ * Version-aware read-only normalization of the frozen plan's postPublish
+ * field (multi-release-unit postPublish v3, design §4.2 归一表).
+ *
+ * This is the SINGLE normalization seam every reader (approve, distribute,
+ * postVerify, ship, verify, recovery, publish, reconcile, approval) must use
+ * to obtain the declaration array view. The accepted shape is derived from
+ * `plan.planVersion` ONLY — readers must never guess the shape from the
+ * field value (no shape sniffing), and no second normalizer or compatibility
+ * schema may exist. Pure and strictly read-only: never mutates the plan and
+ * never rewrites legacy plans, summaries, or evidence.
+ *
+ * | planVersion | input shape   | result           |
+ * |-------------|---------------|------------------|
+ * | 1/2         | absent        | []               |
+ * | 1/2         | single object | [declaration]    |
+ * | 1/2         | array         | rejected         |
+ * | 3           | array         | the array itself |
+ * | 3           | object/absent | rejected         |
+ *
+ * Values outside the table (null, primitives, unknown planVersion) fail
+ * closed with GATE_FAILED: a schema-valid plan can never produce them, and a
+ * reader must never paper over a shape it does not understand.
+ *
+ * @param {object} plan - Frozen plan (schema-valid by the caller's contract).
+ * @returns {object[]} The declaration array view (empty for legacy absent).
+ * @throws {ReleaseError} GATE_FAILED on any shape/version mismatch.
+ */
+export function normalizePostPublishView(plan) {
+  const version = plan?.planVersion;
+  const postPublish = plan?.postPublish;
+  if (version === 1 || version === 2) {
+    if (postPublish === undefined) return [];
+    if (Array.isArray(postPublish)) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion ${version} plans must not carry a postPublish array; only planVersion 3 accepts the array shape`,
+        { planVersion: version, postPublishKind: 'array' },
+      );
+    }
+    if (postPublish === null || typeof postPublish !== 'object') {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion ${version} plans must carry a single postPublish object or none; found ${postPublish === null ? 'null' : typeof postPublish}`,
+        { planVersion: version },
+      );
+    }
+    return [postPublish];
+  }
+  if (version === 3) {
+    if (!Array.isArray(postPublish)) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion 3 plans must carry a postPublish array (possibly empty); found ${postPublish === undefined ? 'no postPublish field' : postPublish === null ? 'null' : 'a single object'}`,
+        { planVersion: 3, postPublishKind: postPublish === undefined ? 'absent' : postPublish === null ? 'null' : 'object' },
+      );
+    }
+    return postPublish;
+  }
+  throw new ReleaseError(
+    GATE_FAILED,
+    `cannot normalize postPublish shape: unknown planVersion ${String(version)}`,
+    { planVersion: version },
+  );
+}
+
+/**
+ * Array-level domain validation: every EXPLICIT hooks[].id must be unique
+ * across the whole declaration array (multi-release-unit postPublish v3,
+ * design §9.2 rule 3; rework R-02). The (planDigest, hookId) approval
+ * contract binds each explicit hook id plan-wide, so a duplicate across
+ * units must fail before any approval is minted or consumed and before any
+ * side effect — JSON Schema cannot express cross-array business uniqueness,
+ * so this function is the SINGLE runtime authority for it.
+ *
+ * Every entry only normalizes its input to the declaration array view and
+ * calls this function: prepare, setup/adoption assessment, approve, the
+ * postpublish approval validator, distribute, and postVerify. Target and
+ * internal probe local ids may repeat across units (checkpoints are
+ * unit-namespaced); explicit hook ids may not.
+ *
+ * @param {object[]} declarations - The declaration array view
+ *   (`normalizePostPublishView()` output, or the per-unit postPublish blocks
+ *   collected by prepare/setup).
+ * @throws {ReleaseError} GATE_FAILED with details { hookId, unitIds } on the
+ *   first cross-unit duplicate.
+ */
+export function validatePostPublishHookIdUniqueness(declarations) {
+  const explicitHookIdOwner = new Map();
+  for (const declaration of declarations ?? []) {
+    for (const hook of declaration?.hooks ?? []) {
+      const owner = explicitHookIdOwner.get(hook.id);
+      if (owner !== undefined && owner !== declaration.unitId) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `postPublish hook id "${hook.id}" is declared by units "${owner}" and "${declaration.unitId}"; explicit hooks[].id must be unique across the whole project (target and probe local ids may repeat across units)`,
+          { hookId: hook.id, unitIds: [owner, declaration.unitId] },
+        );
+      }
+      explicitHookIdOwner.set(hook.id, declaration.unitId);
+    }
+  }
+}
+
+/**
+ * Deterministically derive the checkpoint action id for one postPublish
+ * local action (target probe/mirror or hook) inside one release unit
+ * (§4.3 checkpoint binding). planVersion 3 namespaces every action id under
+ * the owning declaration's unitId (`unitId/localId`); legacy plans keep the
+ * bare local id so pre-existing checkpoint records and approvals stay valid.
+ * This is the SINGLE derivation used by every consumer (distribute,
+ * postVerify, recovery, verify), so a checkpoint id can never drift between
+ * the run records, the recovery mapping, and the approval binding.
+ *
+ * @param {object} params
+ * @param {number} params.planVersion - Frozen plan's planVersion.
+ * @param {string} params.unitId - Owning declaration's unitId.
+ * @param {string} params.localId - Local action id (`probe-<target.id>`,
+ *   `<target.id>`, or the hook id).
+ * @returns {string} The checkpoint action id.
+ */
+export function postPublishActionId({ planVersion, unitId, localId }) {
+  return planVersion === 3 ? `${unitId}/${localId}` : localId;
+}
+
 /**
  * Order targets so every target comes after its dependsOn target.
  *
@@ -595,24 +720,39 @@ export function effectiveHookRequiresApproval(hook) {
  *
  * @param {object} args
  * @param {object} args.plan - Frozen plan (digest + units + postPublish).
+ * @param {object} args.postPublish - THE current declaration the caller is
+ *   executing. REQUIRED (rework R-06): callers must pass the declaration
+ *   explicitly — the unit identity is never derived from a global
+ *   single-object read (contract §4.3). v1/v2 callers pass the single item
+ *   obtained from normalizePostPublishView(); v3 callers pass their loop
+ *   item. Omitting it fails closed with GATE_FAILED; a declaration ARRAY
+ *   (or anything non-object) fails closed too.
  * @param {string} args.runId - Current distribute run id.
  * @param {object} args.sourceRun - Sealed source run (finishedAt = publishedAt).
  * @param {string} args.payloadDir - Materialized payload directory.
  * @param {'distribute'|'postVerify'} args.phase
  * @param {object} [args.verifyEvidence] - Verify evidence (postVerify phase).
  * @returns {object} The context projection.
+ * @throws {ReleaseError} GATE_FAILED when no single declaration is in scope.
  */
-export function buildPostPublishContext({ plan, runId, sourceRun, payloadDir, phase, verifyEvidence }) {
-  const postPublish = plan.postPublish ?? {};
-  const unit = (plan.units ?? []).find((entry) => entry.id === postPublish.unitId);
+export function buildPostPublishContext({ plan, postPublish, runId, sourceRun, payloadDir, phase, verifyEvidence }) {
+  const declaration = postPublish;
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `buildPostPublishContext requires the current postPublish declaration; found ${declaration === undefined ? 'no declaration' : Array.isArray(declaration) ? 'a declaration array' : typeof declaration}`,
+      { planVersion: plan?.planVersion, unitId: declaration?.unitId ?? null },
+    );
+  }
+  const unit = (plan.units ?? []).find((entry) => entry.id === declaration.unitId);
   const frozenSnapshot = unit?.frozenSnapshot ?? {};
   return {
     planDigest: plan.digest,
     runId,
-    unitId: postPublish.unitId,
+    unitId: declaration.unitId,
     version: unit?.targetVersion,
-    tag: postPublish.tag,
-    commit: postPublish.tagCommit,
+    tag: declaration.tag,
+    commit: declaration.tagCommit,
     ...(frozenSnapshot.tree !== undefined ? { tree: frozenSnapshot.tree } : {}),
     ...(frozenSnapshot.manifestDigest !== undefined ? { manifestDigest: frozenSnapshot.manifestDigest } : {}),
     publishedAt: sourceRun?.finishedAt,

package/src/core/preset-executor.mjs

@@ -22,12 +22,17 @@
  * @module core/preset-executor
  */
 
+import { rm } from 'node:fs/promises';
+
 import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
 import { resolveProposalInboxTransport } from './presets.mjs';
 import { executeNotifyHandoffHook } from './notify-handoff.mjs';
 import {
+  buildProposalDocument,
   executeProposalInboxGitPushHook,
   executeProposalInboxLocalFileHook,
+  observeProposalInboxGitPush,
+  proposalFileName,
 } from './proposal-inbox.mjs';
 import { executeMarketplaceRegistryEntryHook } from './marketplace-registry-entry.mjs';
 import { executeDocsRefreshHook } from './docs-refresh-preset.mjs';
@@ -173,3 +178,51 @@ export async function executePresetHook(params) {
     }
   }
 }
+
+/**
+ * Narrow READ-ONLY preset preflight (rework R-01): deterministic conflicts a
+ * preset can already recognize from its existing observe-before-write
+ * observation, evaluated BEFORE the first external write of the phase. This
+ * is NOT a second dispatch table and NOT a lock — it only covers the presets
+ * whose observation implementation already exists (proposal-inbox git-push:
+ * the proposal path exists with different bytes -> the shared observation
+ * throws REMOTE_CONFLICT), and every preset hook is re-observed at execution
+ * time regardless.
+ *
+ * Returns `null` for presets/transports without a read-only deterministic
+ * conflict observation (proposal-inbox local-file, notify-handoff, ...) —
+ * their execution-phase observe-before-write stays the only gate.
+ *
+ * @param {object} params
+ * @param {object} params.hook - Declared preset hook entry.
+ * @param {object} params.contextProjection - The deterministic §2.3 context
+ *   projection of the current run (the same bytes the execution-phase
+ *   delivery serializes; lineage-stable runId).
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @returns {Promise<{verdict: string, proposalPath: string}|null>}
+ * @throws {ReleaseError} REMOTE_CONFLICT/REMOTE_UNAVAILABLE from the shared
+ *   observation implementation.
+ */
+export async function preflightPresetHook(params) {
+  const { hook, contextProjection, exec } = params ?? {};
+  if (!hook || typeof hook.preset !== 'string') return null;
+  if (hook.preset !== 'proposal-inbox') return null;
+  const target = hook.config?.target;
+  if (!target) return null; // targetOptional degradation: nothing remote to observe.
+  const transport = resolveProposalInboxTransport(hook.config);
+  if (transport !== 'git-push') return null; // local-file: no deterministic remote conflict observation.
+
+  // The same observation implementation the execution-phase delivery uses:
+  // build the byte-deterministic proposal and observe-before-write.
+  const document = buildProposalDocument(contextProjection);
+  const proposalPath = proposalFileName(contextProjection.unitId, contextProjection.version);
+  const { cloneDir, verdict } = await observeProposalInboxGitPush({
+    remoteUrl: target.remoteUrl,
+    branch: target.branch,
+    proposalPath,
+    proposalDocument: document,
+    ...(exec !== undefined ? { exec } : {}),
+  });
+  await rm(cloneDir, { recursive: true, force: true }).catch(() => {});
+  return { verdict, proposalPath };
+}

package/src/core/proposal-inbox.mjs

@@ -288,40 +288,42 @@ export async function crossCheckPushedCommit(exec, remoteUrl, branch, pushedComm
 }
 
 /**
- * Deliver one proposal document through the git-push transport:
- * clone -> write (absent only) -> commit (frozen identity) -> push.
+ * Observe-before-write for the git-push transport (rework R-01): clone the
+ * downstream into a fresh disposable checkout and compare any existing
+ * proposal bytes with the serialized document. This is the SINGLE observation
+ * implementation shared by the execution-phase delivery (observe-before-write)
+ * and the full-declaration preflight (deterministic conflict detection BEFORE
+ * the first external write) — no second observe algorithm or dispatch table.
  *
- * - identical existing content -> NO_CHANGE, nothing written;
- * - different existing content -> REMOTE_CONFLICT (human decision);
- * - NEVER --force.
+ * - existing identical content -> verdict 'IDENTICAL';
+ * - different existing content -> REMOTE_CONFLICT (human decision), thrown
+ *   from here so preflight and delivery can never drift apart;
+ * - absent -> verdict 'ABSENT'.
  *
- * No preset-level dry-run (R4 review m-3): the command-level DRY_RUN skip
- * contract skips preset hooks wholesale (SKIPPED/DRY_RUN checkpoints in
- * distribute/postVerify) before this delivery is ever invoked, so a dryRun
- * parameter here would be unreachable dead surface.
+ * On success the CALLER owns `cloneDir` and must remove it (the delivery
+ * continues writing/committing/pushing from that checkout; the preflight
+ * discards it immediately). On any thrown failure the clone dir is already
+ * removed.
  *
  * @param {object} params
  * @param {string} params.remoteUrl - Downstream repository URL.
  * @param {string} params.branch - Downstream branch.
  * @param {string} params.proposalPath - Repository-relative proposal path.
  * @param {object} params.proposalDocument - The proposal document.
- * @param {object} params.commitIdentity - Frozen { name, email }.
  * @param {Function} [params.exec] - Injectable git exec (tests).
- * @returns {Promise<{ status: 'EXECUTED'|'NO_CHANGE', observation: object }>}
+ * @returns {Promise<{cloneDir: string, previousHead: string|null, verdict: 'ABSENT'|'IDENTICAL'}>}
  */
-export async function deliverProposalGitPush(params) {
+export async function observeProposalInboxGitPush(params) {
   const {
     remoteUrl,
     branch,
     proposalPath,
     proposalDocument,
-    commitIdentity,
     exec: execOpt,
   } = params ?? {};
   assertSafeRemoteUrl(remoteUrl);
   assertSafeBranch(branch);
   assertSafeProposalPath(proposalPath);
-  assertCommitIdentity(commitIdentity);
   if (!proposalDocument || typeof proposalDocument !== 'object' || Array.isArray(proposalDocument)) {
     throw new ReleaseError(GATE_FAILED, 'proposal-inbox requires a proposal document');
   }
@@ -365,7 +367,7 @@ export async function deliverProposalGitPush(params) {
       await git(['checkout', '--quiet', '--orphan', branch]);
     }
 
-    // Observe-before-write: an existing proposal decides the outcome.
+    // Observe: an existing proposal decides the outcome.
     const targetPath = join(cloneDir, proposalPath);
     let existing = null;
     try {
@@ -373,20 +375,82 @@ export async function deliverProposalGitPush(params) {
     } catch {
       existing = null;
     }
-    if (existing !== null) {
-      if (existing === serialized) {
-        return {
-          status: 'NO_CHANGE',
-          observation: { mode: 'no-change', previousHead, branchTip: previousHead },
-        };
-      }
-      throw new ReleaseError(
-        REMOTE_CONFLICT,
-        `proposal ${proposalPath} already exists in ${redactUrlCredentialsIfPresent(remoteUrl)} with different content; overwriting a downstream proposal requires a human decision`,
-        { remoteUrl: redactUrlCredentialsIfPresent(remoteUrl), proposalPath },
-      );
+    if (existing === null) {
+      return { cloneDir, previousHead, verdict: 'ABSENT' };
+    }
+    if (existing === serialized) {
+      return { cloneDir, previousHead, verdict: 'IDENTICAL' };
     }
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      `proposal ${proposalPath} already exists in ${redactUrlCredentialsIfPresent(remoteUrl)} with different content; overwriting a downstream proposal requires a human decision`,
+      { remoteUrl: redactUrlCredentialsIfPresent(remoteUrl), proposalPath },
+    );
+  } catch (cause) {
+    await rm(cloneDir, { recursive: true, force: true }).catch(() => {});
+    throw cause;
+  }
+}
 
+/**
+ * Deliver one proposal document through the git-push transport:
+ * observe -> write (absent only) -> commit (frozen identity) -> push.
+ *
+ * - identical existing content -> NO_CHANGE, nothing written;
+ * - different existing content -> REMOTE_CONFLICT (human decision);
+ * - NEVER --force.
+ *
+ * The observe-before-write step calls the SAME shared observation
+ * implementation the full-declaration preflight uses, so the execution phase
+ * always re-observes the remote (the preflight is never a lock).
+ *
+ * No preset-level dry-run (R4 review m-3): the command-level DRY_RUN skip
+ * contract skips preset hooks wholesale (SKIPPED/DRY_RUN checkpoints in
+ * distribute/postVerify) before this delivery is ever invoked, so a dryRun
+ * parameter here would be unreachable dead surface.
+ *
+ * @param {object} params
+ * @param {string} params.remoteUrl - Downstream repository URL.
+ * @param {string} params.branch - Downstream branch.
+ * @param {string} params.proposalPath - Repository-relative proposal path.
+ * @param {object} params.proposalDocument - The proposal document.
+ * @param {object} params.commitIdentity - Frozen { name, email }.
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @returns {Promise<{ status: 'EXECUTED'|'NO_CHANGE', observation: object }>}
+ */
+export async function deliverProposalGitPush(params) {
+  const {
+    remoteUrl,
+    branch,
+    proposalPath,
+    proposalDocument,
+    commitIdentity,
+    exec: execOpt,
+  } = params ?? {};
+  assertCommitIdentity(commitIdentity);
+  const exec = typeof execOpt === 'function' ? execOpt : defaultExec;
+  const serialized = `${JSON.stringify(proposalDocument, null, 2)}\n`;
+
+  // Shared observe-before-write: identical -> NO_CHANGE; different -> the
+  // shared observation throws REMOTE_CONFLICT (human decision).
+  const { cloneDir, previousHead, verdict } = await observeProposalInboxGitPush({
+    remoteUrl,
+    branch,
+    proposalPath,
+    proposalDocument,
+    ...(execOpt !== undefined ? { exec: execOpt } : {}),
+  });
+
+  try {
+    if (verdict === 'IDENTICAL') {
+      return {
+        status: 'NO_CHANGE',
+        observation: { mode: 'no-change', previousHead, branchTip: previousHead },
+      };
+    }
+
+    const git = (args, options = {}) => exec('git', args, { cwd: cloneDir, shell: false, timeout: GIT_TIMEOUT_MS, ...options });
+    const targetPath = join(cloneDir, proposalPath);
     await mkdir(dirname(targetPath), { recursive: true });
     await writeFile(targetPath, serialized);
     await git(['add', '-A']);

package/src/core/recovery.mjs

@@ -33,7 +33,7 @@ import { validatePlan, computePlanDigest, assertImmutablePlanAuthority } from '.
 import { validateApproval, validateApprovalRecordSchema, assertImmutableApprovalAuthority, computeApprovalDigest } from './approval.mjs';
 import { isMarketplaceAction } from './checkpoints.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
-import { effectiveHookRequiresApproval } from './postpublish.mjs';
+import { effectiveHookRequiresApproval, normalizePostPublishView, postPublishActionId } from './postpublish.mjs';
 import { assertPostPublishApprovalAuthority, validatePostPublishApproval } from './postpublish-approval.mjs';
 
 /** Remote errors alone are insufficient to select a safe recovery phase. */
@@ -194,12 +194,18 @@ export async function readRunRecovery(runPath, options = {}) {
         throw new ReleaseError(GATE_FAILED, 'distribute recovery requires its same-lineage PUBLISHED publication');
       }
       // Mapping only: the common 1:1 checkpoint validator remains authoritative.
-      const actions = (plan.postPublish?.targets ?? []).flatMap((target) => [
-        { id: `probe-${target.id}`, type: 'distribute-probe' },
-        { id: target.id, type: 'distribute-mirror' },
-      ]).concat((plan.postPublish?.hooks ?? [])
-        .filter((hook) => hook.phase !== 'postVerify')
-        .map((hook) => ({ id: hook.id, type: 'postpublish-hook' })));
+      // §4.3 unified normalization: per-declaration mapping through the shared
+      // action-id derivation so v3 checkpoint ids (unitId/localId) match the
+      // executed records exactly; legacy plans resolve to the same bare ids.
+      const actions = normalizePostPublishView(plan).flatMap((declaration) => [
+        ...(declaration.targets ?? []).flatMap((target) => [
+          { id: postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: `probe-${target.id}` }), type: 'distribute-probe' },
+          { id: postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: target.id }), type: 'distribute-mirror' },
+        ]),
+        ...(declaration.hooks ?? [])
+          .filter((hook) => hook.phase !== 'postVerify')
+          .map((hook) => ({ id: postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: hook.id }), type: 'postpublish-hook' })),
+      ]);
       // A preflight BLOCKED record may precede checkpoint initialization.
       if (!(run.status === 'BLOCKED' && run.checkpoints.length === 0)) {
         validateRunCheckpointMapping(run, actions);
@@ -268,8 +274,11 @@ export async function readRunRecovery(runPath, options = {}) {
       }
     } else if (['publish', 'reconcile'].includes(command)) {
       if (run.status === 'PUBLISHED') {
-        const needsDistribution = (plan.postPublish?.targets?.length ?? 0) > 0
-          || (plan.postPublish?.hooks?.length ?? 0) > 0;
+        // §4.3 unified normalization: v3 empty arrays mean no distribute work
+        // at all; only declarations carrying targets or hooks require the
+        // distribution phase.
+        const needsDistribution = normalizePostPublishView(plan).some((declaration) =>
+          (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
         code = needsDistribution ? 'DISTRIBUTE' : 'VERIFY';
       } else if (run.status === 'PARTIAL') {
         code = 'RECONCILE';
@@ -280,9 +289,15 @@ export async function readRunRecovery(runPath, options = {}) {
     } else code = 'DIAGNOSE';
 
     if (code === 'DISTRIBUTE') {
-      const pendingApprovals = (plan.postPublish?.hooks ?? []).filter((hook) => hook.phase !== 'postVerify'
-        && effectiveHookRequiresApproval(hook)
-        && !(run.command === 'distribute' && run.checkpoints.some((cp) => cp.actionId === hook.id && completed(cp))));
+      // §4.3 unified normalization: approval gating resolves declared hooks
+      // across all declarations; checkpoint match uses the shared action-id
+      // derivation so a v3 record (unitId/hookId) counts as completed.
+      const pendingApprovals = normalizePostPublishView(plan).flatMap((declaration) =>
+        (declaration.hooks ?? [])
+          .filter((hook) => hook.phase !== 'postVerify' && effectiveHookRequiresApproval(hook))
+          .filter((hook) => !(run.command === 'distribute' && run.checkpoints.some((cp) =>
+            cp.actionId === postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: hook.id })
+            && completed(cp)))));
       if (pendingApprovals.length > 0) {
         try {
           const approved = new Set();

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

@@ -376,10 +376,14 @@ export function evaluateConsumerSkillResourceClosureReceipts(plan, receipts) {
     'kimi-plugin',
     'codebuddy-plugin',
   ]);
-  // When plan declares humanConsumersStrategy: 'manualFollowUps', Kimi/CodeBuddy
-  // are non-blocking manual follow-up tasks and are not verified by the system.
-  // Exclude them from the expected receipt set.
-  const humanConsumerTypes = plan.humanConsumersStrategy === 'manualFollowUps'
+  // Kimi/CodeBuddy remain non-blocking manual marketplace/invocation tasks in
+  // both strategy generations. The newer strategy adds a Foundation frozen
+  // payload observation but still does not establish an installed host
+  // surface, so these distributions stay outside this receipt set.
+  const humanConsumerTypes = [
+    'manualFollowUps',
+    'foundationPayloadThenManualFollowUps',
+  ].includes(plan.humanConsumersStrategy)
     ? new Set(['kimi-plugin', 'codebuddy-plugin'])
     : new Set();
   const expectedKeys = [];

package/src/producers/build-adapters.mjs

@@ -371,9 +371,17 @@ function renderSkillForPlatform(content, platformName) {
     const hostLabel = platformName === 'codex' ? 'Codex' : 'Kimi';
     const preamble = platformName === 'codex' ? CODEX_PREAMBLE : KIMI_PREAMBLE;
     let rendered = content.replaceAll(
+      '${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs',
+      '$RELEASE_SKILL_LOCAL_FINISH_ENTRY',
+    ).replaceAll(
       '${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs',
       '$RELEASE_SKILL_ENTRY',
     );
+    const renderedPreamble = rendered.includes('$RELEASE_SKILL_LOCAL_FINISH_ENTRY')
+      ? preamble
+        .replaceAll('RELEASE_SKILL_ENTRY', 'RELEASE_SKILL_LOCAL_FINISH_ENTRY')
+        .replaceAll('release-skill.mjs', 'release-skill-local-finish.mjs')
+      : preamble;
     // A remaining bare host-root reference has no safe path-derived equivalent.
     if (rendered.includes('${CLAUDE_PLUGIN_ROOT}')) {
       throw new Error(`${hostLabel} rendering found an unsupported bare CLAUDE_PLUGIN_ROOT reference`);
@@ -385,7 +393,7 @@ function renderSkillForPlatform(content, platformName) {
       throw new Error(`${hostLabel} rendering requires a valid leading YAML frontmatter block`);
     }
     const insertionPoint = frontmatterEnd + '\n---\n'.length;
-    return `${rendered.slice(0, insertionPoint)}\n${preamble}${rendered.slice(insertionPoint)}`;
+    return `${rendered.slice(0, insertionPoint)}\n${renderedPreamble}${rendered.slice(insertionPoint)}`;
   }
 
   return content;
@@ -527,6 +535,7 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
 
   const HOST_BIN_FILES = new Set([
     'release-skill.mjs',
+    'release-skill-local-finish.mjs',
     'release-skill.bundle.mjs',
     'release-skill-cli.mjs',
     'foundation-resource-binding.json',

package/src/producers/foundation-resource-projection.mjs

@@ -55,9 +55,9 @@ import { digestBytes, publishFileOrReplace, readFileStrict, withTemporaryWorkspa
 import { canonicalJson } from '../core/digest.mjs';
 
 export const FOUNDATION_PACKAGES = Object.freeze({
-  'skill-family-contracts': '0.12.0',
-  'skill-family-engineering-kit': '0.12.0',
-  'skill-family-harness-node': '0.12.0',
+  'skill-family-contracts': '0.13.0',
+  'skill-family-engineering-kit': '0.13.0',
+  'skill-family-harness-node': '0.13.0',
 });
 
 export const BINDING_RECORD_PATH = 'bin/foundation-resource-binding.json';