release-skill 0.6.2 → 0.7.0

package/src/commands/distribute.mjs

@@ -7,9 +7,33 @@
  *
  * Timing contract (R1): the payload may ONLY ever come from a detached git
  * worktree checked out at the frozen `postPublish.tagCommit` — never from
- * the live workspace, which has already moved ahead. The consumer-declared
- * materialize hook runs inside that worktree and announces the isolated
- * payload directory through its `outputMarker` line.
+ * the live workspace, which has already moved ahead. Since F-06 / T6 the
+ * frozen plan selects exactly one of two staging routes:
+ * - a consumer materialize hook (when declared): it runs inside that
+ *   worktree and announces the isolated payload directory through its
+ *   `outputMarker` line;
+ * - the Foundation managed projection (when the plan declares no materialize
+ *   hook): the frozen `postPublish.executionBundle.publicFiles` mapping is
+ *   staged from the tag worktree into a fresh `hub-payload` root through the
+ *   Engineering Kit `compileProjectionPlan`/`runProjection` contract —
+ *   never by live project configuration and never by a parent-workspace
+ *   script.
+ *
+ * Private execution bundle (F-01 / T1): consumer-declared hook commands
+ * (materialize, steps, custom distribute-phase hooks) may reference scripts
+ * by workspace-relative paths that the frozen tag tree never contains —
+ * parent-workspace tooling never leaks into the public surface. prepare
+ * freezes those files (closed-world `executionFiles` manifest) into the
+ * plan's `postPublish.executionBundle` and publishes the bytes
+ * digest-addressed under the plan's `.release-skill`. Before ANY hook runs,
+ * distribute strictly re-reads the bundle bytes, recomputes the closure
+ * through Foundation, and installs ONLY the verified bytes into the tag
+ * worktree (never overwriting tag files). Live-workspace copying and the
+ * RELEASE_SKILL_WORKSPACE_ROOT injection are gone: after the freeze, the
+ * workspace copies are never read back. The payload timing contract is
+ * untouched: payload content must still be produced from the frozen
+ * checkout and the announced payload directory must stay inside the
+ * worktree.
  *
  * Safety gates (all verified before any adapter execute):
  *  1. plan schema validation
@@ -61,11 +85,21 @@ import {
 } from '../core/run.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { runHook } from '../core/hooks.mjs';
+import { boundedOutputTail } from '../core/bounded-output.mjs';
 import {
   orderTargetsByDependency,
   validatePostPublishDeclaration,
+  buildPostPublishContext,
+  normalizePostPublishDeclaration,
+  orderNormalizedHooks,
+  effectiveHookRequiresApproval,
+  POSTPUBLISH_CONTEXT_ENV,
   PAYLOAD_SOURCE_TAG_WORKTREE,
 } from '../core/postpublish.mjs';
+import { verifyAndInstallExecutionBundle } from '../core/postpublish-bundle.mjs';
+import { projectPublicPayload, PROJECTION_MECHANISM, PUBLIC_PAYLOAD_DIRNAME } from '../core/postpublish-projection.mjs';
+import { assertPostPublishApprovalAuthority, validatePostPublishApproval } from '../core/postpublish-approval.mjs';
+import { executePresetHook } from '../core/preset-executor.mjs';
 import {
   ReleaseError,
   GATE_FAILED,
@@ -80,9 +114,6 @@ const execFileAsync = promisify(execFileCb);
 /** Executor identity recorded in every distribute checkpoint trace. */
 const EXECUTOR = 'release-skill distribute';
 
-/** Tail length for hook stdout/stderr recorded in evidence. */
-const TAIL_CHARS = 4000;
-
 /** Full 40-hex commit sha. */
 const SHA_RE = /^[a-f0-9]{40}$/;
 
@@ -105,6 +136,7 @@ const DISTRIBUTING = 'DISTRIBUTING';
 const DISTRIBUTED = 'DISTRIBUTED';
 const PARTIAL = 'PARTIAL';
 const BLOCKED = 'BLOCKED';
+const NEEDS_INPUT = 'NEEDS_INPUT';
 
 function defaultClock() {
   return new Date().toISOString();
@@ -114,11 +146,6 @@ function defaultExec(command, args, options = {}) {
   return execFileAsync(command, args, { shell: false, encoding: 'utf8', timeout: 120_000, ...options });
 }
 
-function tail(text, limit = TAIL_CHARS) {
-  const value = `${text ?? ''}`;
-  return value.length > limit ? value.slice(-limit) : value;
-}
-
 /** Map an adapter/details error code onto the run-schema checkpoint enum. */
 function mapToSchemaCode(code) {
   return SCHEMA_ERROR_CODES.has(code) ? code : GATE_FAILED;
@@ -230,6 +257,11 @@ function resolvePluginName(plan, unitId) {
  * @param {() => string} [options.clock] - Clock function returning ISO-8601 strings.
  * @param {Function} [options.execFn] - Injectable git exec (tests).
  * @param {Function} [options.runHookFn] - Injectable hook runner (tests).
+ * @param {string[]} [options.postpublishApprovalPaths] - Checkpoint approval
+ *   records for requiresApproval postPublish hooks (v0.6.3 R1); each record
+ *   binds (planDigest, hookId), must be consumed from the immutable
+ *   digest-addressed authority minted by approvePostPublishHook (F-02), and
+ *   is validated fail-closed before any write.
  *
  * @returns {Promise<{ planPath: string, runPath: string, status: string, checkpoints: Object[] }>}
  *
@@ -248,6 +280,7 @@ export async function distributeRelease(options) {
     clock: clockOpt,
     execFn,
     runHookFn,
+    postpublishApprovalPaths,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -407,7 +440,16 @@ export async function distributeRelease(options) {
       ?? computeApprovalDigest(approvalRaw);
 
     validateApprovalRecordSchema(approval);
-    validateApproval(plan, approval, { clock: clockFn });
+    // distribute is a post-publish phase: like reconcile/verify it validates
+    // the approval binding (planDigest/approvedActions/digest) without
+    // requiring an unexpired window — distribution may legitimately happen
+    // after the 24h publish-approval window. requiresApproval hook approvals
+    // remain expiry-enforced by validatePostPublishApproval.
+    // requireUnexpired: false aligns with reconcile.mjs:321 and
+    // verify.mjs:1098; the binding checks (plan digest, approved actions,
+    // approval digest) are NOT relaxed here — only the expiry window is
+    // waived for the post-publish phase.
+    validateApproval(plan, approval, { clock: clockFn, requireUnexpired: false });
 
     await evidence.append({ phase: 'safety-gate', gate: 'approval-validated', status: 'passed' });
 
@@ -448,12 +490,127 @@ export async function distributeRelease(options) {
 
     // =======================================================================
     // Declaration re-validation + deterministic target ordering.
+    // R2: preset references resolve against the built-in preset registry
+    // (core/presets.mjs); per-preset config validation (dual addressing,
+    // marketplace/staticFiles shapes, secret scan) fails closed here.
     // =======================================================================
     const postPublish = plan.postPublish;
     validatePostPublishDeclaration(postPublish, { unitId: postPublish.unitId });
-    const orderedTargets = orderTargetsByDependency(postPublish.targets);
+    const orderedTargets = orderTargetsByDependency(postPublish.targets ?? []);
+
+    // Normalized hook table (design §2.2): every targets[] entry maps onto a
+    // preset hook (payload-mirror -> git-mirror, marketplace-index ->
+    // marketplace-index-render); the table is a deterministic projection of
+    // the digest-bound declaration, ordered by dependency topology +
+    // declaration order. Target execution below keeps the exact legacy
+    // semantics; hooks[] preset execution dispatches in the hook loop
+    // (proposal-inbox git-push is wired; other presets fail closed until
+    // their behavior ships).
+    const normalizedDeclaration = normalizePostPublishDeclaration(postPublish);
+    const orderedNormalizedHooks = orderNormalizedHooks(normalizedDeclaration.hooks);
+    await evidence.append({
+      phase: 'postpublish-normalization',
+      status: 'passed',
+      preGates: normalizedDeclaration.preGates.map((gate) => gate.gate),
+      hookCount: orderedNormalizedHooks.length,
+      hookIds: orderedNormalizedHooks.map((hook) => hook.id),
+    });
+
+    // postPublish hooks (v0.6.3 R1): distribute-phase hooks run in this saga;
+    // postVerify-phase hooks belong to the independent postVerify run (R3)
+    // and are only evidenced here — never executed, never silent.
+    const declaredHooks = postPublish.hooks ?? [];
+    const distributeHooks = declaredHooks.filter((hook) => (hook.phase ?? 'distribute') === 'distribute');
+    const deferredPostVerifyHooks = declaredHooks.length - distributeHooks.length;
+
+    /** Gate failure after lineage is known: persist BLOCKED, then rethrow. */
+    const failBlocked = async (error) => {
+      await recordBlocked();
+      throw error;
+    };
+
+    // =======================================================================
+    // Gate: checkpoint approvals for requiresApproval hooks. Every provided
+    // record is validated fail-closed BEFORE any write: first the immutable
+    // authority binding (F-02: the consumption path must BE the digest-
+    // addressed authority minted by approvePostPublishHook — recomputed
+    // planDigest directory, recomputed approvalDigest file name, strict
+    // no-follow regular-file read, no symlinked ancestor), then the content
+    // checks (schema, planDigest binding, declared hook, requiresApproval,
+    // 24h window, expiry). A bad approval aborts the whole saga; a missing
+    // one parks the hook at AWAITING_APPROVAL.
+    // =======================================================================
+    const approvedHookIds = new Set();
+    const hookApprovalPaths = postpublishApprovalPaths ?? [];
+    if (hookApprovalPaths.length > 0) {
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'postpublish-hook-approvals',
+        status: 'started',
+        approvalCount: hookApprovalPaths.length,
+      });
+      for (const hookApprovalPath of hookApprovalPaths) {
+        let hookApprovalRaw;
+        try {
+          hookApprovalRaw = await readFile(hookApprovalPath, 'utf8');
+        } catch (err) {
+          await failBlocked(new ReleaseError(
+            GATE_FAILED,
+            `cannot read postpublish hook approval: ${err.message}`,
+            { hookApprovalPath, cause: err.code },
+          ));
+        }
+        let hookApproval;
+        try {
+          hookApproval = JSON.parse(hookApprovalRaw);
+        } catch (err) {
+          await failBlocked(new ReleaseError(
+            GATE_FAILED,
+            `postpublish hook approval is not valid JSON: ${err.message}`,
+            { hookApprovalPath },
+          ));
+        }
+        // F-02: identical bytes anywhere else are not an approval. The
+        // authority assertion runs before content validation and before the
+        // hook may enter approvedHookIds.
+        try {
+          await assertPostPublishApprovalAuthority(planPath, hookApprovalPath, plan, hookApprovalRaw);
+        } catch (err) {
+          await failBlocked(err instanceof ReleaseError ? err : new ReleaseError(
+            GATE_FAILED,
+            `postpublish hook approval authority check failed: ${err?.message ?? err}`,
+            { hookApprovalPath },
+          ));
+        }
+        validatePostPublishApproval(plan, hookApproval, { clock: clockFn });
+        if (approvedHookIds.has(hookApproval.hookId)) {
+          await failBlocked(new ReleaseError(
+            GATE_FAILED,
+            `duplicate postpublish hook approvals for hook "${hookApproval.hookId}"`,
+            { hookId: hookApproval.hookId },
+          ));
+        }
+        approvedHookIds.add(hookApproval.hookId);
+      }
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'postpublish-hook-approvals',
+        status: 'passed',
+        approvedHookIds: [...approvedHookIds],
+      });
+    }
+
+    // Hooks whose checkpoint approval is still missing. While any exist, the
+    // declared postPublish steps (unaudited project code) must not execute:
+    // the run parks at NEEDS_INPUT/PARTIAL and the approved reconcile rerun
+    // re-executes them. Targets remain plan-approval-authorized idempotent
+    // remote-state convergence and are unaffected.
+    const pendingHookApprovals = distributeHooks.filter(
+      (hook) => effectiveHookRequiresApproval(hook) && !approvedHookIds.has(hook.id),
+    );
 
-    // Checkpoint registry: one probe + one mirror per target, declared order.
+    // Checkpoint registry: one probe + one mirror per target, declared order,
+    // then one postpublish-hook checkpoint per distribute-phase hook.
     checkpoints = [];
     for (const target of orderedTargets) {
       checkpoints.push({
@@ -478,17 +635,19 @@ export async function distributeRelease(options) {
         executor: EXECUTOR,
       });
     }
+    for (const hook of distributeHooks) {
+      checkpoints.push({
+        actionId: hook.id,
+        actionType: 'postpublish-hook',
+        status: 'PENDING',
+        executor: EXECUTOR,
+      });
+    }
     const checkpointById = new Map(checkpoints.map((cp) => [cp.actionId, cp]));
 
     // Durable pre-execute authority (seq 0).
     await snapshot(DISTRIBUTING);
 
-    /** Gate failure after lineage is known: persist BLOCKED, then rethrow. */
-    const failBlocked = async (error) => {
-      await recordBlocked();
-      throw error;
-    };
-
     // =======================================================================
     // Gate 4: tag identity — the live tag must still point at the frozen
     // tagCommit. A missing binding or a moved tag fails closed.
@@ -518,7 +677,7 @@ export async function distributeRelease(options) {
         phase: 'safety-gate',
         gate: 'tag-identity',
         status: 'failed',
-        error: tail(err?.stderr ?? err?.message),
+        error: boundedOutputTail(err?.stderr ?? err?.message),
       });
       await failBlocked(new ReleaseError(
         GATE_FAILED,
@@ -663,7 +822,7 @@ export async function distributeRelease(options) {
       worktreePath = join(tmpBase, 'worktree');
       await exec('git', ['-C', root, 'worktree', 'add', '--detach', worktreePath, postPublish.tagCommit]);
     } catch (err) {
-      await evidence.append({ phase: 'worktree', status: 'failed', error: tail(err?.stderr ?? err?.message) });
+      await evidence.append({ phase: 'worktree', status: 'failed', error: boundedOutputTail(err?.stderr ?? err?.message) });
       await failBlocked(new ReleaseError(
         GATE_FAILED,
         `cannot create the detached tag worktree at ${postPublish.tagCommit}: ${err?.message ?? err}`,
@@ -673,99 +832,243 @@ export async function distributeRelease(options) {
     await evidence.append({ phase: 'worktree', status: 'passed' });
 
     // =======================================================================
-    // Materialize: run the consumer hook inside the tag worktree, verify its
-    // report, and bind the announced payload directory (fail-closed).
+    // Private execution bundle (F-01 / T1): consumer-declared commands may
+    // reference scripts that exist only in the parent workspace (tooling
+    // never leaks into the frozen public surface). prepare froze those bytes
+    // digest-addressed under the plan's .release-skill; re-verify them
+    // through Foundation and install ONLY the verified bytes into the tag
+    // worktree before any hook runs. Any mismatch fails closed here —
+    // before any hook and before any external write.
     // =======================================================================
-    await evidence.append({ phase: 'materialize', status: 'started' });
-
-    const materialize = postPublish.materialize;
-    const hookResult = await hookRunner(
-      {
-        command: materialize.command,
-        ...(materialize.cwd ? { cwd: materialize.cwd } : {}),
-        ...(materialize.timeoutMs !== undefined ? { timeoutMs: materialize.timeoutMs } : {}),
-        ...(materialize.envAllowlist ? { envAllowlist: materialize.envAllowlist } : {}),
-      },
-      { root: worktreePath, env: process.env },
-    );
-
-    if (hookResult.exitCode !== 0) {
+    // =======================================================================
+    // F-04 root split: the saga holds TWO distinct roots from here on —
+    // - releaseWorkspaceRoot: the real project root the user releases from;
+    //   only used to resolve preset target.workspace, compare the release-
+    //   workspace write exclusion, and audit;
+    // - executionWorktreeRoot (worktreePath): the detached worktree at the
+    //   frozen tagCommit; only used as the hook runner context.root for
+    //   materialize, steps and custom command hooks.
+    // The two roots never fall back onto each other through defaults.
+    // =======================================================================
+    let releaseWorkspaceRoot;
+    try {
+      releaseWorkspaceRoot = await realpath(root);
+    } catch (err) {
+      await failBlocked(new ReleaseError(
+        GATE_FAILED,
+        `release workspace root does not resolve to an existing directory: ${err.message}`,
+        { root, cause: err.code },
+      ));
+    }
+    let installedBundlePaths = [];
+    try {
+      ({ installed: installedBundlePaths } = await verifyAndInstallExecutionBundle({
+        plan,
+        planPath,
+        worktreePath,
+      }));
+    } catch (err) {
       await evidence.append({
-        phase: 'materialize',
+        phase: 'worktree',
+        gate: 'execution-bundle',
         status: 'failed',
-        exitCode: hookResult.exitCode,
-        stdoutTail: tail(hookResult.stdout),
-        stderrTail: tail(hookResult.stderr),
+        error: boundedOutputTail(err?.message ?? String(err)),
       });
-      await failBlocked(new ReleaseError(
-        POST_PUBLISH_VERIFY_FAILED,
-        `materialize hook exited with code ${hookResult.exitCode}; payload cannot be trusted`,
-        { exitCode: hookResult.exitCode, stdoutTail: tail(hookResult.stdout), stderrTail: tail(hookResult.stderr) },
+      await failBlocked(err instanceof ReleaseError ? err : new ReleaseError(
+        GATE_FAILED,
+        `cannot verify the frozen execution bundle: ${err?.message ?? err}`,
       ));
     }
+    await evidence.append({
+      phase: 'worktree',
+      gate: 'execution-bundle',
+      status: 'passed',
+      installed: installedBundlePaths,
+    });
+
+    // =======================================================================
+    // Payload staging (fail-closed). The frozen plan selects exactly one
+    // route (schema anyOf + runtime re-check):
+    // - consumer materialize hook: run it inside the tag worktree, verify
+    //   its report, and bind the announced payload directory;
+    // - Foundation managed projection (F-06 / T6): when the plan declares
+    //   no materialize hook, the frozen executionBundle.publicFiles mapping
+    //   is staged from the tag worktree into a fresh hub-payload root by
+    //   the Engineering Kit compileProjectionPlan/runProjection contract.
+    //   The saga supplies ONLY the release-domain parameters (what is
+    //   projected, where the frozen bytes live, where the payload lands);
+    //   every preflight, containment check, transactional write, and
+    //   rollback belongs to Foundation and is never reimplemented here.
+    // =======================================================================
+    let payloadReal;
+    const materialize = postPublish.materialize;
+
+    if (materialize !== undefined) {
+      await evidence.append({ phase: 'materialize', status: 'started' });
 
-    // requireReport: stdout-first-json deep compare (declared equals subset).
-    if (materialize.requireReport) {
-      const report = parseFirstJsonObject(hookResult.stdout);
-      if (!report) {
+      const hookResult = await hookRunner(
+        {
+          command: materialize.command,
+          ...(materialize.cwd ? { cwd: materialize.cwd } : {}),
+          ...(materialize.timeoutMs !== undefined ? { timeoutMs: materialize.timeoutMs } : {}),
+          ...(materialize.envAllowlist ? { envAllowlist: materialize.envAllowlist } : {}),
+        },
+        {
+          // F-04: materialize runs in the execution worktree, never in the
+          // release workspace. Private workspace-side inputs reach the hook
+          // exclusively through the frozen execution bundle installed above —
+          // no live workspace root is announced anymore (F-01 / T1).
+          root: worktreePath,
+          env: process.env,
+        },
+      );
+
+      if (hookResult.exitCode !== 0) {
         await evidence.append({
           phase: 'materialize',
           status: 'failed',
-          reason: 'report-missing',
-          stdoutTail: tail(hookResult.stdout),
+          exitCode: hookResult.exitCode,
+          stdoutTail: boundedOutputTail(hookResult.stdout),
+          stderrTail: boundedOutputTail(hookResult.stderr),
         });
         await failBlocked(new ReleaseError(
           POST_PUBLISH_VERIFY_FAILED,
-          'materialize report missing: no JSON object found on stdout (requireReport.parse = stdout-first-json)',
-          { stdoutTail: tail(hookResult.stdout) },
+          `materialize hook exited with code ${hookResult.exitCode}; payload cannot be trusted`,
+          { exitCode: hookResult.exitCode, stdoutTail: boundedOutputTail(hookResult.stdout), stderrTail: boundedOutputTail(hookResult.stderr) },
         ));
       }
-      const equals = materialize.requireReport.equals ?? {};
-      for (const [key, expectedValue] of Object.entries(equals)) {
-        if (JSON.stringify(report[key]) !== JSON.stringify(expectedValue)) {
+
+      // requireReport: stdout-first-json deep compare (declared equals subset).
+      if (materialize.requireReport) {
+        const report = parseFirstJsonObject(hookResult.stdout);
+        if (!report) {
           await evidence.append({
             phase: 'materialize',
             status: 'failed',
-            reason: 'report-mismatch',
-            mismatchedKeys: Object.keys(equals).filter(
-              (k) => JSON.stringify(report[k]) !== JSON.stringify(equals[k]),
-            ),
+            reason: 'report-missing',
+            stdoutTail: boundedOutputTail(hookResult.stdout),
           });
           await failBlocked(new ReleaseError(
             POST_PUBLISH_VERIFY_FAILED,
-            `materialize report mismatch: "${key}" did not meet the frozen requireReport contract`,
-            { mismatchedKey: key },
+            'materialize report missing: no JSON object found on stdout (requireReport.parse = stdout-first-json)',
+            { stdoutTail: boundedOutputTail(hookResult.stdout) },
           ));
         }
+        const equals = materialize.requireReport.equals ?? {};
+        for (const [key, expectedValue] of Object.entries(equals)) {
+          if (JSON.stringify(report[key]) !== JSON.stringify(expectedValue)) {
+            await evidence.append({
+              phase: 'materialize',
+              status: 'failed',
+              reason: 'report-mismatch',
+              mismatchedKeys: Object.keys(equals).filter(
+                (k) => JSON.stringify(report[k]) !== JSON.stringify(equals[k]),
+              ),
+            });
+            await failBlocked(new ReleaseError(
+              POST_PUBLISH_VERIFY_FAILED,
+              `materialize report mismatch: "${key}" did not meet the frozen requireReport contract`,
+              { mismatchedKey: key },
+            ));
+          }
+        }
       }
-    }
 
-    // outputMarker: the LAST line containing the marker announces the payload.
-    const announced = parseOutputMarker(hookResult.stdout, materialize.outputMarker);
-    if (!announced) {
+      // outputMarker: the LAST line containing the marker announces the payload.
+      const announced = parseOutputMarker(hookResult.stdout, materialize.outputMarker);
+      if (!announced) {
+        await evidence.append({
+          phase: 'materialize',
+          status: 'failed',
+          reason: 'marker-missing',
+          stdoutTail: boundedOutputTail(hookResult.stdout),
+        });
+        await failBlocked(new ReleaseError(
+          POST_PUBLISH_VERIFY_FAILED,
+          `materialize output marker "${materialize.outputMarker}" not found on stdout; payload directory unbound`,
+          { stdoutTail: boundedOutputTail(hookResult.stdout) },
+        ));
+      }
+      payloadReal = await assertContainedDirectory(
+        worktreePath,
+        resolve(worktreePath, announced),
+        'materialized payload directory',
+      );
+      await evidence.append({ phase: 'materialize', status: 'passed', payloadDirAnnounced: announced });
+    } else {
+      await evidence.append({ phase: 'materialize', status: 'started', mechanism: PROJECTION_MECHANISM });
+
+      // Release-domain parameter selection ONLY: the frozen mapping rides the
+      // plan digest; live project configuration is never read here.
+      const publicFiles = postPublish.executionBundle?.publicFiles;
+      if (!Array.isArray(publicFiles) || publicFiles.length === 0) {
+        await evidence.append({
+          phase: 'materialize',
+          status: 'failed',
+          mechanism: PROJECTION_MECHANISM,
+          reason: 'public-files-missing',
+        });
+        await failBlocked(new ReleaseError(
+          POST_PUBLISH_VERIFY_FAILED,
+          'public payload projection: the frozen plan declares no materialize hook and carries no non-empty executionBundle.publicFiles mapping; the payload cannot be staged',
+        ));
+      }
+
+      // Disposable candidate staging root, external to the payload root and
+      // owned by the saga (cleaned up with tmpBase).
+      const candidateRoot = join(tmpBase, 'projection-candidate');
+      try {
+        await mkdir(candidateRoot, { recursive: true });
+        const projected = await projectPublicPayload({
+          executionWorktreeRoot: worktreePath,
+          candidateRoot,
+          publicFiles,
+        });
+        payloadReal = projected.payloadRoot;
+      } catch (err) {
+        await evidence.append({
+          phase: 'materialize',
+          status: 'failed',
+          mechanism: PROJECTION_MECHANISM,
+          error: boundedOutputTail(err?.message ?? String(err)),
+        });
+        await failBlocked(err instanceof ReleaseError ? err : new ReleaseError(
+          POST_PUBLISH_VERIFY_FAILED,
+          `public payload projection failed: ${err?.message ?? err}`,
+        ));
+      }
       await evidence.append({
         phase: 'materialize',
-        status: 'failed',
-        reason: 'marker-missing',
-        stdoutTail: tail(hookResult.stdout),
+        status: 'passed',
+        mechanism: PROJECTION_MECHANISM,
+        payloadDir: PUBLIC_PAYLOAD_DIRNAME,
+        fileCount: publicFiles.length,
       });
-      await failBlocked(new ReleaseError(
-        POST_PUBLISH_VERIFY_FAILED,
-        `materialize output marker "${materialize.outputMarker}" not found on stdout; payload directory unbound`,
-        { stdoutTail: tail(hookResult.stdout) },
-      ));
     }
-    const payloadReal = await assertContainedDirectory(
-      worktreePath,
-      resolve(worktreePath, announced),
-      'materialized payload directory',
-    );
-    await evidence.append({ phase: 'materialize', status: 'passed', payloadDirAnnounced: announced });
 
     // =======================================================================
     // Declared postPublish steps, in order (fail-closed).
     // =======================================================================
     for (const step of postPublish.steps ?? []) {
+      if (dryRun === true) {
+        // R1 dry-run contract: steps are arbitrary project code with
+        // potentially remote side effects; they never execute in a rehearsal.
+        await evidence.append({ phase: 'postpublish-step', step: step.name, status: 'skipped', reason: 'DRY_RUN' });
+        continue;
+      }
+      if (pendingHookApprovals.length > 0) {
+        // A requiresApproval hook is still unapproved: the step pipeline must
+        // not execute before the checkpoint approval exists; the approved
+        // reconcile rerun re-executes the steps (idempotence-by-default).
+        await evidence.append({
+          phase: 'postpublish-step',
+          step: step.name,
+          status: 'skipped',
+          reason: 'AWAITING_CHECKPOINT_APPROVAL',
+          pendingHookApprovals: pendingHookApprovals.map((hook) => hook.id),
+        });
+        continue;
+      }
       await evidence.append({ phase: 'postpublish-step', step: step.name, status: 'started' });
       const stepResult = await hookRunner(
         {
@@ -774,7 +1077,12 @@ export async function distributeRelease(options) {
           ...(step.timeoutMs !== undefined ? { timeoutMs: step.timeoutMs } : {}),
           ...(step.envAllowlist ? { envAllowlist: step.envAllowlist } : {}),
         },
-        { root: worktreePath, env: process.env },
+        {
+          // F-04: steps run in the execution worktree (see materialize).
+          // Private inputs arrive via the frozen execution bundle only.
+          root: worktreePath,
+          env: process.env,
+        },
       );
       if (stepResult.exitCode !== 0) {
         await evidence.append({
@@ -782,8 +1090,8 @@ export async function distributeRelease(options) {
           step: step.name,
           status: 'failed',
           exitCode: stepResult.exitCode,
-          stdoutTail: tail(stepResult.stdout),
-          stderrTail: tail(stepResult.stderr),
+          stdoutTail: boundedOutputTail(stepResult.stdout),
+          stderrTail: boundedOutputTail(stepResult.stderr),
         });
         await failBlocked(new ReleaseError(
           GATE_FAILED,
@@ -1022,15 +1330,267 @@ export async function distributeRelease(options) {
     }
 
     // =======================================================================
-    // Classification: DISTRIBUTED | PARTIAL | BLOCKED (returned, not thrown).
+    // postPublish hooks (distribute phase), executed AFTER the target writes.
+    // Contract (design §2.3): the read-only frozen-plan projection travels via
+    // RELEASE_SKILL_POSTPUBLISH_CONTEXT; hooks run inside the frozen tag
+    // worktree; a failure stops the hook chain; a requiresApproval hook
+    // without a checkpoint approval parks at AWAITING_APPROVAL and never
+    // executes; dry-run executes nothing; postVerify-phase hooks belong to
+    // the independent postVerify run (R3) and are evidenced as deferred.
+    // =======================================================================
+    if (deferredPostVerifyHooks > 0) {
+      await evidence.append({ phase: 'postpublish-hooks', deferredPostVerifyHooks });
+    }
+
+    let hooksStopped = stopped;
+    let awaitingApproval = 0;
+    let hookSuccesses = 0;
+    const hookContextProjection = buildPostPublishContext({
+      plan,
+      runId,
+      sourceRun,
+      payloadDir: payloadReal,
+      phase: 'distribute',
+    });
+
+    // Proposal documents must stay byte-deterministic across redeliveries of
+    // the SAME release event (NO_CHANGE idempotence on reconcile reruns):
+    // they travel with the stable lineage-derived event identity, not the
+    // per-attempt runId.
+    const proposalContextProjection = {
+      ...hookContextProjection,
+      runId: `distribute-${sourceRunId}`,
+    };
+
+    for (const hook of distributeHooks) {
+      const cp = checkpointById.get(hook.id);
+      cp.startedAt = clockFn();
+
+      if (hooksStopped) {
+        cp.status = 'SKIPPED';
+        cp.reason = 'EARLIER_TARGET_FAILED';
+        cp.finishedAt = clockFn();
+        await evidence.append({
+          phase: 'postpublish-hook',
+          hookId: hook.id,
+          status: 'skipped',
+          reason: 'EARLIER_TARGET_FAILED',
+        });
+        continue;
+      }
+
+      if (dryRun === true) {
+        cp.status = 'SKIPPED';
+        cp.reason = 'DRY_RUN';
+        cp.finishedAt = clockFn();
+        await evidence.append({ phase: 'postpublish-hook', hookId: hook.id, status: 'skipped', reason: 'DRY_RUN' });
+        continue;
+      }
+
+      if (effectiveHookRequiresApproval(hook) && !approvedHookIds.has(hook.id)) {
+        // No checkpoint approval: the hook must not execute. It parks (does
+        // not stop the chain — later reconcile reruns retry it once approved).
+        cp.status = 'AWAITING_APPROVAL';
+        cp.finishedAt = clockFn();
+        awaitingApproval += 1;
+        await evidence.append({ phase: 'postpublish-hook', hookId: hook.id, status: 'awaiting-approval' });
+        continue;
+      }
+
+      // -----------------------------------------------------------------
+      // Preset hooks dispatch through the R4 preset executor (one seam for
+      // every registered preset; fail-closed wording for presets registered
+      // but not yet shipped).
+      // -----------------------------------------------------------------
+      if (hook.preset !== undefined) {
+        await evidence.append({ phase: 'postpublish-hook', hookId: hook.id, status: 'started' });
+        let delivery;
+        try {
+          delivery = await executePresetHook({
+            hook,
+            contextProjection: hookContextProjection,
+            proposalContextProjection,
+            commitIdentity: postPublish.commitIdentity,
+            // F-04: presets receive the RELEASE workspace root (target.workspace
+            // resolution + release-workspace write exclusion). The detached
+            // worktree is the execution worktree and never impersonates it.
+            releaseWorkspaceRoot,
+            evidencePath: join(runDir, 'evidence.jsonl'),
+            payloadDir: hookContextProjection.payloadDir,
+            exec,
+            hookRunner,
+          });
+        } catch (err) {
+          const code = mapToSchemaCode(err?.code);
+          cp.status = 'FAILED';
+          cp.error = { code, message: err?.message ?? String(err) };
+          cp.finishedAt = clockFn();
+          failures += 1;
+          hooksStopped = true;
+          await evidence.append({
+            phase: 'postpublish-hook',
+            hookId: hook.id,
+            status: 'failed',
+            error: err?.message ?? String(err),
+            details: { code },
+          });
+          await snapshot(PARTIAL);
+          continue;
+        }
+
+        if (delivery.status === 'NO_CHANGE') {
+          cp.status = 'NO_CHANGE';
+          cp.mode = 'no-change';
+          cp.finishedAt = clockFn();
+          hookSuccesses += 1;
+          await evidence.append({
+            phase: 'postpublish-hook',
+            hookId: hook.id,
+            status: 'no-change',
+            ...(delivery.manualSyncPrompt ? { manualSyncPrompt: delivery.manualSyncPrompt } : {}),
+            // §2.6 execution realpath evidence (R4 review m-2).
+            ...(delivery.observation?.workspaceRealpath
+              ? { workspaceRealpath: delivery.observation.workspaceRealpath }
+              : {}),
+            ...(delivery.workspaceRealpath ? { workspaceRealpath: delivery.workspaceRealpath } : {}),
+          });
+          await snapshot(PARTIAL);
+          continue;
+        }
+
+        cp.status = 'SUCCEEDED';
+        if (delivery.observation?.mode === 'pushed' && delivery.observation?.pushedCommit) {
+          cp.mode = 'pushed';
+          cp.pushedCommit = delivery.observation.pushedCommit;
+        }
+        cp.finishedAt = clockFn();
+        hookSuccesses += 1;
+        await evidence.append({
+          phase: 'postpublish-hook',
+          hookId: hook.id,
+          status: 'succeeded',
+          preset: hook.preset,
+          mode: delivery.mode ?? delivery.observation?.mode,
+          ...(delivery.observation?.pushedCommit ? { pushedCommit: delivery.observation.pushedCommit } : {}),
+          ...(delivery.manualSyncPrompt ? { manualSyncPrompt: delivery.manualSyncPrompt } : {}),
+          ...(delivery.checklist ? { checklist: delivery.checklist } : {}),
+          ...(delivery.degradedToNotifyHandoff === true ? { degradedToNotifyHandoff: true } : {}),
+          ...(Array.isArray(delivery.observations) ? { targets: delivery.observations } : {}),
+          // §2.6 execution realpath evidence (R4 review m-2) + explicit
+          // cross-check skip note (R4 review m-4).
+          ...(delivery.observation?.workspaceRealpath
+            ? { workspaceRealpath: delivery.observation.workspaceRealpath }
+            : {}),
+          ...(delivery.workspaceRealpath ? { workspaceRealpath: delivery.workspaceRealpath } : {}),
+          ...(delivery.observation?.crossCheck ? { crossCheck: delivery.observation.crossCheck } : {}),
+        });
+        await snapshot(PARTIAL);
+        continue;
+      }
+
+      if (!Array.isArray(hook.command)) {
+        // Fail-closed: a hook with no executable command stops the chain.
+        cp.status = 'FAILED';
+        cp.error = {
+          code: POST_PUBLISH_VERIFY_FAILED,
+          message: `hook "${hook.id}" has no executable command`,
+        };
+        cp.finishedAt = clockFn();
+        failures += 1;
+        hooksStopped = true;
+        await evidence.append({
+          phase: 'postpublish-hook',
+          hookId: hook.id,
+          status: 'failed',
+          reason: 'no-command',
+        });
+        await snapshot(PARTIAL);
+        continue;
+      }
+
+      await evidence.append({ phase: 'postpublish-hook', hookId: hook.id, status: 'started' });
+      let hookExecution;
+      try {
+        hookExecution = await hookRunner(
+          {
+            command: hook.command,
+            ...(hook.cwd ? { cwd: hook.cwd } : {}),
+            ...(hook.timeoutMs !== undefined ? { timeoutMs: hook.timeoutMs } : {}),
+            ...(hook.envAllowlist ? { envAllowlist: hook.envAllowlist } : {}),
+          },
+          {
+            // F-04: custom command hooks keep running in the execution
+            // worktree; the runner's cwd containment binds them there.
+            root: worktreePath,
+            env: process.env,
+            injectEnv: {
+              [POSTPUBLISH_CONTEXT_ENV]: JSON.stringify(hookContextProjection),
+            },
+          },
+        );
+      } catch (err) {
+        // HOOK_TIMEOUT (or a runner defect): FAILED checkpoint, stop the chain.
+        const code = err?.code === 'HOOK_TIMEOUT' ? 'HOOK_TIMEOUT' : POST_PUBLISH_VERIFY_FAILED;
+        cp.status = 'FAILED';
+        cp.error = { code, message: err?.message ?? String(err) };
+        cp.finishedAt = clockFn();
+        failures += 1;
+        hooksStopped = true;
+        await evidence.append({
+          phase: 'postpublish-hook',
+          hookId: hook.id,
+          status: 'failed',
+          error: err?.message ?? String(err),
+        });
+        await snapshot(PARTIAL);
+        continue;
+      }
+
+      if (hookExecution.exitCode !== 0) {
+        cp.status = 'FAILED';
+        cp.error = {
+          code: POST_PUBLISH_VERIFY_FAILED,
+          message: `postPublish hook "${hook.id}" exited with code ${hookExecution.exitCode}`,
+        };
+        cp.finishedAt = clockFn();
+        failures += 1;
+        hooksStopped = true;
+        await evidence.append({
+          phase: 'postpublish-hook',
+          hookId: hook.id,
+          status: 'failed',
+          exitCode: hookExecution.exitCode,
+          stdoutTail: boundedOutputTail(hookExecution.stdout),
+          stderrTail: boundedOutputTail(hookExecution.stderr),
+        });
+        await snapshot(PARTIAL);
+        continue;
+      }
+
+      cp.status = 'SUCCEEDED';
+      cp.finishedAt = clockFn();
+      hookSuccesses += 1;
+      await evidence.append({ phase: 'postpublish-hook', hookId: hook.id, status: 'succeeded' });
+      await snapshot(PARTIAL);
+    }
+
+    // =======================================================================
+    // Classification (returned, not thrown):
+    // - DISTRIBUTED: no failures and no awaiting-approval hooks;
+    // - NEEDS_INPUT: only awaiting-approval checkpoints and zero external
+    //   side effects so far (pure input-needed state, never PARTIAL);
+    // - PARTIAL: at least one external success (pushed write or succeeded
+    //   hook) alongside failures or awaiting-approval checkpoints;
+    // - BLOCKED: failures with zero external side effects landed.
     // =======================================================================
+    const externalCheckpointSuccesses = pushedWrites + hookSuccesses;
     let overallStatus;
-    if (failures === 0) {
+    if (failures === 0 && awaitingApproval === 0) {
       overallStatus = DISTRIBUTED;
-    } else if (pushedWrites > 0) {
-      overallStatus = PARTIAL;
+    } else if (failures === 0) {
+      overallStatus = externalCheckpointSuccesses > 0 ? PARTIAL : NEEDS_INPUT;
     } else {
-      overallStatus = BLOCKED;
+      overallStatus = externalCheckpointSuccesses > 0 ? PARTIAL : BLOCKED;
     }
 
     const finishedAt = clockFn();