release-skill 0.6.2 → 0.7.0

package/src/commands/prepare.mjs

@@ -18,13 +18,14 @@
  * @module commands/prepare
  */
 
-import { resolve, relative, isAbsolute, normalize, dirname, basename } from 'node:path';
-import { readFile, mkdir, readdir, realpath } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, normalize, dirname, basename, posix as pathPosix } from 'node:path';
+import { readFile, mkdir, readdir, realpath, lstat } from 'node:fs/promises';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCb);
 
+import { classifyPathInput } from 'skill-family-harness-node';
 import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
@@ -56,6 +57,7 @@ import {
 } from '../snapshot/frozen.mjs';
 import { ReleaseError, GATE_FAILED, CONFIG_INVALID, CONFIG_MISSING, FORBIDDEN_CONTENT_DETECTED, RELEASE_DOCS_STALE, DIRTY_SOURCE_INPUT, BUNDLE_STALE } from '../core/errors.mjs';
 import { assertBundleFreshness } from '../core/bundle-freshness.mjs';
+import { assertAdapterFreshness, assertSelfBootstrapFacts } from '../core/derived-artifact-gates.mjs';
 import { PKG_ROOT } from '../core/pkg-root.mjs';
 import { writeFrozenMarker, FROZEN_MARKER_FILENAME } from '../core/frozen-marker.mjs';
 import {
@@ -71,7 +73,13 @@ import { createProductionPrepareRunDir } from '../core/run.mjs';
 import { PLATFORMS } from '../platforms/registry.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
 import { buildInstallationContract, computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from '../core/installation-contract.mjs';
-import { validatePostPublishDeclaration, PAYLOAD_SOURCE_TAG_WORKTREE } from '../core/postpublish.mjs';
+import {
+  validatePostPublishDeclaration,
+  normalizePostPublishDeclaration,
+  orderNormalizedHooks,
+  PAYLOAD_SOURCE_TAG_WORKTREE,
+} from '../core/postpublish.mjs';
+import { freezeExecutionBundle, bundleRootForAuthorityDir } from '../core/postpublish-bundle.mjs';
 
 // ---------------------------------------------------------------------------
 // 安装契约常量
@@ -228,39 +236,15 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
 // Hooks execution
 // ---------------------------------------------------------------------------
 
-/** Maximum number of output lines preserved in a hook-failure tail. */
-const HOOK_OUTPUT_TAIL_MAX_LINES = 50;
-/** Maximum bytes preserved in a hook-failure tail. */
-const HOOK_OUTPUT_TAIL_MAX_BYTES = 8 * 1024;
-
-/**
- * Bound a captured child-output stream to the tail that matters for triage:
- * the last 50 lines, further capped at 8 KB — whichever is smaller.
- *
- * @param {string} [text] - Captured stdout/stderr text.
- * @returns {string} The bounded tail ('' for empty/absent input).
- */
-export function boundedOutputTail(text) {
-  if (typeof text !== 'string' || text.length === 0) return '';
-  let lines = text.split('\n');
-  // A trailing newline produces an empty final element; drop it so the line
-  // budget counts real output lines.
-  if (lines.length > 1 && lines[lines.length - 1] === '') {
-    lines = lines.slice(0, -1);
-  }
-  let tail = lines.slice(-HOOK_OUTPUT_TAIL_MAX_LINES);
-  let joined = tail.join('\n');
-  while (tail.length > 1 && Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
-    tail = tail.slice(1);
-    joined = tail.join('\n');
-  }
-  if (Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
-    // A single line exceeds the byte cap: keep the trailing bytes.
-    const buf = Buffer.from(joined, 'utf8');
-    joined = buf.subarray(buf.length - HOOK_OUTPUT_TAIL_MAX_BYTES).toString('utf8');
-  }
-  return joined;
-}
+// v0.6.3 R1 tail unification: the "last 50 lines / 8 KiB" tail authority now
+// lives in core/bounded-output.mjs, shared by prepare and distribute. The
+// re-export preserves prepare's historical public surface.
+export {
+  boundedOutputTail,
+  HOOK_OUTPUT_TAIL_MAX_LINES,
+  HOOK_OUTPUT_TAIL_MAX_BYTES,
+} from '../core/bounded-output.mjs';
+import { boundedOutputTail } from '../core/bounded-output.mjs';
 
 /**
  * Run all declared project hooks in order: docs, build, test, typecheck.
@@ -908,6 +892,94 @@ function normalizedProductionConfig(unit) {
   };
 }
 
+/**
+ * O5 (2026-08-18 release-cycle investigation §3.2): observe how the local
+ * workspace HEAD relates to `origin/<defaultBranch>` for an ONLINE production
+ * prepare. This is a WARNING-LEVEL, non-blocking pre-publish signal: in the
+ * 0.6.1 cycle a workspace 15 commits ahead of origin only surfaced when the
+ * publish source-authority gate rejected it. Pushing is a legitimate
+ * pre-publish action, so the observation must inform, never block the freeze.
+ *
+ * Read-only git plumbing only (argv arrays, no shell): rev-parse, ls-remote,
+ * cat-file, rev-list. Every failure degrades to a descriptive status object —
+ * this function NEVER throws, so it can never break a freeze.
+ *
+ * @param {object} options
+ * @param {string} options.root - Workspace (git repository) root.
+ * @param {string} options.defaultBranch - Default branch name on origin.
+ * @returns {Promise<{
+ *   status: 'in-sync' | 'ahead' | 'behind' | 'diverged' | 'no-origin' | 'remote-ref-missing' | 'unknown',
+ *   localHead?: string,
+ *   remoteHead?: string,
+ *   aheadCount?: number,
+ *   behindCount?: number,
+ *   error?: string,
+ * }>}
+ */
+export async function observeOriginAhead({ root, defaultBranch }) {
+  const runGit = (gitArgs) => execFile('git', ['-C', root, ...gitArgs], {
+    shell: false,
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+
+  let localHead;
+  try {
+    ({ stdout: localHead } = await runGit(['rev-parse', 'HEAD']));
+    localHead = localHead.trim();
+  } catch (err) {
+    return { status: 'unknown', error: `rev-parse HEAD failed: ${err.message}` };
+  }
+
+  // Distinguish "no origin remote" from a transient ls-remote failure.
+  try {
+    await runGit(['remote', 'get-url', 'origin']);
+  } catch {
+    return { status: 'no-origin', localHead };
+  }
+
+  let remoteHead;
+  try {
+    const { stdout } = await runGit(['ls-remote', 'origin', `refs/heads/${defaultBranch}`]);
+    const firstLine = stdout.trim().split('\n').filter((line) => line.length > 0)[0];
+    if (!firstLine) {
+      return { status: 'remote-ref-missing', localHead, defaultBranch };
+    }
+    remoteHead = firstLine.split('\t')[0];
+  } catch (err) {
+    return { status: 'unknown', localHead, error: `ls-remote origin failed: ${err.message}` };
+  }
+
+  if (remoteHead === localHead) {
+    return { status: 'in-sync', localHead, remoteHead };
+  }
+
+  // Ancestry is only computable when the remote head object exists locally
+  // (no implicit fetch — this observer is read-only on the network beyond the
+  // single ls-remote above). When it does not, report diverged with no counts.
+  try {
+    await runGit(['cat-file', '-e', `${remoteHead}^{commit}`]);
+  } catch {
+    return { status: 'diverged', localHead, remoteHead };
+  }
+
+  try {
+    const aheadRaw = await runGit(['rev-list', '--count', `${remoteHead}..HEAD`]);
+    const behindRaw = await runGit(['rev-list', '--count', `HEAD..${remoteHead}`]);
+    const aheadCount = Number.parseInt(aheadRaw.stdout.trim(), 10) || 0;
+    const behindCount = Number.parseInt(behindRaw.stdout.trim(), 10) || 0;
+    if (aheadCount > 0 && behindCount === 0) {
+      return { status: 'ahead', localHead, remoteHead, aheadCount };
+    }
+    if (behindCount > 0 && aheadCount === 0) {
+      return { status: 'behind', localHead, remoteHead, behindCount };
+    }
+    return { status: 'diverged', localHead, remoteHead, aheadCount, behindCount };
+  } catch (err) {
+    return { status: 'diverged', localHead, remoteHead, error: err.message };
+  }
+}
+
 /**
  * Derive the deterministic freeze timestamp for planVersion 2 plans (design:
  * t1-2-digest-decoupling.md §4.2): the baseline headCommit's committer date,
@@ -1052,6 +1124,128 @@ async function buildProductionAssets(
   return assets;
 }
 
+// ---------------------------------------------------------------------------
+// F-01 / T1: private execution inputs freeze gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize one relative path for closure-style set comparison (the same
+ * lexical normalization Foundation applies to closure resource paths).
+ *
+ * @param {string} value - Relative path candidate.
+ * @returns {string} POSIX-normalized form.
+ */
+function normalizeRelativeClosurePath(value) {
+  return pathPosix.normalize(String(value).replaceAll('\\', '/'));
+}
+
+/**
+ * Enumerate the paths present in the frozen tag tree: the production asset
+ * commit is the commit the distribution tag will point at, and its tree
+ * lives in the detached asset repository built by buildProductionAssets.
+ * Read-only local git; no network.
+ *
+ * @param {string} root - Release workspace root.
+ * @param {object} asset - productionAssets entry (gitObjectDir + commit).
+ * @returns {Promise<Set<string>>} Normalized paths contained in the tag.
+ */
+async function enumerateFrozenTagPaths(root, asset) {
+  const gitDir = resolve(root, asset.gitObjectDir);
+  let stdout;
+  try {
+    ({ stdout } = await execFile('git', [
+      '--git-dir', gitDir,
+      'ls-tree', '-r', '-z', '--name-only', asset.commit,
+    ]));
+  } catch (err) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot enumerate the frozen tag tree for the executionFiles gate: ${err?.message ?? err}`,
+      { gitObjectDir: asset.gitObjectDir, commit: asset.commit },
+    );
+  }
+  return new Set(`${stdout}`.split('\0').filter(Boolean).map(normalizeRelativeClosurePath));
+}
+
+/**
+ * Collect the relative-path candidates from every postPublish command array
+ * (materialize, steps, custom command hooks). Flag-like elements are not
+ * path candidates; lexical safety is decided by Foundation classification.
+ *
+ * @param {object} postPublish - The unit postPublish declaration.
+ * @returns {Array<{where: string, element: string}>}
+ */
+function collectPostPublishCommandCandidates(postPublish) {
+  const candidates = [];
+  const visit = (where, command) => {
+    if (!Array.isArray(command)) return;
+    for (const element of command) {
+      if (typeof element !== 'string' || element.length === 0 || element.startsWith('-')) continue;
+      candidates.push({ where, element });
+    }
+  };
+  visit('materialize', postPublish.materialize?.command);
+  for (const step of postPublish.steps ?? []) visit(`steps[${step.name}]`, step.command);
+  for (const hook of postPublish.hooks ?? []) {
+    if (Array.isArray(hook.command)) visit(`hooks[${hook.id}]`, hook.command);
+  }
+  return candidates;
+}
+
+/**
+ * F-01 / T1 declaration gate (fail-closed, before any plan write):
+ *
+ * - a command-array element that is a safe relative path, EXISTS as a
+ *   regular file in the live workspace, is ABSENT from the frozen tag tree,
+ *   and is NOT declared in executionFiles is an undeclared private input —
+ *   report it immediately instead of letting distribute guess or copy;
+ * - an executionFiles entry that already exists in the frozen tag is
+ *   rejected: tag files stay bound to tagCommit and the execution bundle
+ *   must never shadow them.
+ *
+ * When no frozen tag exists yet (non-production prepare) the tag-dependent
+ * checks are skipped — distribute fails closed later without a tagCommit.
+ *
+ * @param {object} postPublish - Unit postPublish declaration.
+ * @param {object} params
+ * @param {string} params.workspaceRoot - Release workspace root (realpath).
+ * @param {Set<string>|null} params.frozenTagPaths - Frozen tag tree paths.
+ * @param {string[]} params.executionFiles - Declared closed-world manifest.
+ */
+async function assertPrivateExecutionDeclarations(postPublish, { workspaceRoot, frozenTagPaths, executionFiles }) {
+  const declared = new Set(executionFiles.map(normalizeRelativeClosurePath));
+  for (const { where, element } of collectPostPublishCommandCandidates(postPublish)) {
+    const classification = classifyPathInput(element);
+    if (!classification.ok) continue; // absolute/UNC/backslash inputs are not workspace-relative files
+    let stats = null;
+    try {
+      stats = await lstat(resolve(workspaceRoot, element));
+    } catch {
+      continue; // not present in the live workspace: nothing to declare
+    }
+    if (!stats.isFile()) continue;
+    const normalized = normalizeRelativeClosurePath(element);
+    if (frozenTagPaths && frozenTagPaths.has(normalized)) continue; // bound by tagCommit
+    if (declared.has(normalized)) continue;
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postPublish ${where} command references the workspace-private file "${element}" that exists in the workspace but is absent from the frozen tag; declare it in postPublish.executionFiles (closed world — helper files included)`,
+      { where, path: element },
+    );
+  }
+  if (frozenTagPaths) {
+    for (const entry of executionFiles) {
+      if (frozenTagPaths.has(normalizeRelativeClosurePath(entry))) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `postPublish.executionFiles entry "${entry}" already exists in the frozen tag; tag files stay bound to tagCommit and the execution bundle must never shadow them`,
+          { path: entry },
+        );
+      }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // External independent marketplace freeze (production + online only)
 // ---------------------------------------------------------------------------
@@ -1211,7 +1405,8 @@ export async function resolveExternalMarketplaceFreezes({
       if (offline) {
         throw new ReleaseError(
           GATE_FAILED,
-          `unit "${unit.id}" ${dist.type} external marketplace form requires online production prepare to freeze the marketplace commit sha`,
+          `unit "${unit.id}" ${dist.type} external marketplace form requires online production prepare to freeze the marketplace commit sha. ` +
+          `Remediation: release-skill prepare --production --online`,
           { unitId: unit.id, marketplaceSourceType: dist.marketplaceSourceType },
         );
       }
@@ -1765,8 +1960,17 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
  * @param {boolean} [options.hookCache=true] - When false (CLI --no-hook-cache),
  *   every declared hook runs in full and the incremental hook cache is neither
  *   read nor written.
+ * @param {Function} [options.adapterFreshnessFn] - Adapter derived-artifact
+ *   pre-gate (default assertAdapterFreshness). No environment variable
+ *   exempts the default gate (F-03): it runs in the CLI, plain function
+ *   calls, and the node:test harness alike. Tests that need a lightweight
+ *   fixture inject a double explicitly in-process; the CLI exposes no
+ *   parameter for it.
+ * @param {Function} [options.selfBootstrapFactsFn] - Self-bootstrap fact-pin
+ *   pre-gate (default assertSelfBootstrapFacts); same injection contract as
+ *   adapterFreshnessFn.
  *
- * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string, warnings: ReadonlyArray<object> }>}
+ * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string, warnings: ReadonlyArray<object>, nextSteps: ReadonlyArray<{ code: string, message: string }> }>}
  *
  * @throws {ReleaseError} on any gate failure. No PREPARED plan is written.
  */
@@ -1925,6 +2129,9 @@ export async function prepareRelease(options) {
 
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
     const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
+    // Mutable operator-facing warning list: seeded from the adoption warnings,
+    // appended by later gates (O5 origin-ahead). Returned as `warnings`.
+    const runWarnings = [...adoptionWarnings];
 
     await evidence.append({
       phase: 'config',
@@ -2026,6 +2233,75 @@ export async function prepareRelease(options) {
       reasonTag: 'RELEASE_DOCS_STALE',
     });
 
+    // --- Step 1b-fast: version-sensitive derived-artifact fast pre-gates (O1) ---
+    // 2026-08-18 investigation §3.2: adapter drift and stale self-bootstrap
+    // fact pins used to surface only deep inside the ~80s full test hook.
+    // Promote the two exact canonical checks (build-adapters --check and the
+    // release-docs-self-bootstrap single-file test) to prepare's earliest
+    // stage so the same drift fails closed in seconds, before any hook. Like
+    // the bundle freshness gate this is artifact-integrity class: workflow
+    // trimming never exempts it. Installed layouts record not-applicable.
+    // F-03 (2026-08-21 architecture review): the gates run identically in
+    // the CLI, plain function calls, and the node:test harness — no
+    // environment variable may exempt them (a test seam is never a
+    // production switch). Tests that need lightweight fixtures inject the
+    // adapterFreshnessFn/selfBootstrapFactsFn seams explicitly in-process.
+    await evidence.append({ phase: 'adapter-freshness', status: 'started' });
+    const adapterFreshnessFn = options.adapterFreshnessFn ?? assertAdapterFreshness;
+    let adapterFreshness;
+    try {
+      adapterFreshness = await adapterFreshnessFn(PKG_ROOT);
+    } catch (err) {
+      await evidence.append({
+        phase: 'adapter-freshness',
+        status: 'blocking',
+        reason: err.details?.reason ?? null,
+        error: { code: err.code, message: err.message },
+      });
+      throw err;
+    }
+    if (adapterFreshness?.applicable === false) {
+      await evidence.append({
+        phase: 'adapter-freshness',
+        status: 'not-applicable',
+        reason: adapterFreshness.reason,
+      });
+    } else {
+      await evidence.append({
+        phase: 'adapter-freshness',
+        status: 'completed',
+        durationMs: adapterFreshness?.durationMs ?? null,
+      });
+    }
+
+    await evidence.append({ phase: 'self-bootstrap-facts', status: 'started' });
+    const selfBootstrapFactsFn = options.selfBootstrapFactsFn ?? assertSelfBootstrapFacts;
+    let selfBootstrapFacts;
+    try {
+      selfBootstrapFacts = await selfBootstrapFactsFn(PKG_ROOT);
+    } catch (err) {
+      await evidence.append({
+        phase: 'self-bootstrap-facts',
+        status: 'blocking',
+        reason: err.details?.reason ?? null,
+        error: { code: err.code, message: err.message },
+      });
+      throw err;
+    }
+    if (selfBootstrapFacts?.applicable === false) {
+      await evidence.append({
+        phase: 'self-bootstrap-facts',
+        status: 'not-applicable',
+        reason: selfBootstrapFacts.reason,
+      });
+    } else {
+      await evidence.append({
+        phase: 'self-bootstrap-facts',
+        status: 'completed',
+        durationMs: selfBootstrapFacts?.durationMs ?? null,
+      });
+    }
+
     // --- Step 1c: postPublish distribution declaration gate (R1/R2) ---
     // The per-unit postPublish block drives the post-publish distribute
     // command. Validate it here, before any hook, baseline, snapshot, remote
@@ -2033,8 +2309,13 @@ export async function prepareRelease(options) {
     // side effects. This is the runtime re-check on top of the config JSON
     // schema: plans frozen by older schema versions must not be able to
     // smuggle shell strings, option-like executables, or secret-ish env
-    // keys through. A plan binds exactly one declaration; multiple units
-    // declaring postPublish is a hard gate failure.
+    // keys through. R2: preset references resolve against the built-in
+    // preset registry (per-preset config validation + requiresApproval
+    // grading), and targets normalize onto preset hooks — the normalized
+    // table is a deterministic projection of the digest-bound declaration,
+    // so any list change changes the plan digest and voids approvals. A
+    // plan binds exactly one declaration; multiple units declaring
+    // postPublish is a hard gate failure.
     const postPublishDeclarations = configUnits
       .map((unit, index) => ({ unit, index }))
       .filter(({ unit }) => unit.postPublish !== undefined);
@@ -2049,12 +2330,20 @@ export async function prepareRelease(options) {
     if (postPublishDeclarations.length === 1) {
       const { unit, index } = postPublishDeclarations[0];
       validatePostPublishDeclaration(unit.postPublish, { unitId: unit.id });
+      // Normalized hook table (design §2.2): validate the dependency
+      // topology at freeze time too, so a cyclic/dangling declaration can
+      // never be frozen for distribute to trip over.
+      const normalizedDeclaration = normalizePostPublishDeclaration(unit.postPublish);
+      const orderedNormalizedHooks = orderNormalizedHooks(normalizedDeclaration.hooks);
       postPublishDeclaration = { unit, index };
       await evidence.append({
         phase: 'postpublish-declaration',
         status: 'validated',
         unitId: unit.id,
-        targetCount: unit.postPublish.targets.length,
+        targetCount: (unit.postPublish.targets ?? []).length,
+        hookCount: (unit.postPublish.hooks ?? []).length,
+        normalizedHookCount: orderedNormalizedHooks.length,
+        preGates: normalizedDeclaration.preGates.map((gate) => gate.gate),
       });
     }
 
@@ -2297,6 +2586,73 @@ export async function prepareRelease(options) {
         inputDigest: sourceInputClosure.digest,
         remoteObservation: offline ? 'unobserved-offline' : 'deferred-to-publish',
       });
+
+      // --- Step 3c-ahead: local vs origin ahead observation (O5) ---
+      // Online production prepare only. WARNING level, never blocking: pushing
+      // is a legitimate pre-publish action, but the operator must know before
+      // approval — the publish source-authority gate compares the frozen
+      // source-input closure against the remote default branch and rejects
+      // unpushed local commits (0.6.1 cycle: 15 commits ahead, discovered only
+      // at publish). Offline prepare keeps the legacy zero-observation form.
+      if (!offline) {
+        if (!configDefaultBranch) {
+          await evidence.append({
+            phase: 'origin-ahead',
+            status: 'skipped',
+            reason: 'no project.defaultBranch configured',
+          });
+        } else {
+          await evidence.append({ phase: 'origin-ahead', status: 'started' });
+          const observeOriginAheadFn = options.observeOriginAheadFn ?? observeOriginAhead;
+          let originObservation;
+          try {
+            originObservation = await observeOriginAheadFn({
+              root: realRoot,
+              defaultBranch: configDefaultBranch,
+            });
+          } catch (err) {
+            originObservation = { status: 'unknown', error: err?.message ?? String(err) };
+          }
+          if (originObservation?.status === 'ahead') {
+            await evidence.append({
+              phase: 'origin-ahead',
+              status: 'warning',
+              defaultBranch: configDefaultBranch,
+              localHead: originObservation.localHead ?? null,
+              remoteHead: originObservation.remoteHead ?? null,
+              aheadCount: originObservation.aheadCount ?? null,
+              guidance: 'push the workspace before publish (git push); the publish source-authority gate compares against the remote default branch',
+            });
+            runWarnings.push({
+              code: 'ORIGIN_AHEAD',
+              defaultBranch: configDefaultBranch,
+              aheadCount: originObservation.aheadCount ?? null,
+              message:
+                `local HEAD is ${originObservation.aheadCount ?? 'an unknown number of'} commit(s) ahead of origin/${configDefaultBranch}; ` +
+                'the publish source-authority gate compares against the remote default branch — push the workspace (git push) before publish',
+            });
+          } else if (['in-sync', 'behind', 'diverged'].includes(originObservation?.status)) {
+            await evidence.append({
+              phase: 'origin-ahead',
+              status: 'completed',
+              observation: originObservation.status,
+              defaultBranch: configDefaultBranch,
+              localHead: originObservation.localHead ?? null,
+              remoteHead: originObservation.remoteHead ?? null,
+              aheadCount: originObservation.aheadCount ?? null,
+              behindCount: originObservation.behindCount ?? null,
+            });
+          } else {
+            await evidence.append({
+              phase: 'origin-ahead',
+              status: 'unobserved',
+              reason: originObservation?.status ?? 'unknown',
+              defaultBranch: configDefaultBranch,
+              error: originObservation?.error ?? null,
+            });
+          }
+        }
+      }
     } else if (production) {
       await evidence.append({
         phase: 'source-authority',
@@ -2391,7 +2747,8 @@ export async function prepareRelease(options) {
         if (offline) {
           throw new ReleaseError(
             GATE_FAILED,
-            `unit "${unit.id}" branch strategy "${branchStrategy}" requires online production prepare`,
+            `unit "${unit.id}" branch strategy "${branchStrategy}" requires online production prepare. ` +
+            `Remediation: release-skill prepare --production --online`,
             { unitId: unit.id, branchStrategy },
           );
         }
@@ -2495,7 +2852,8 @@ export async function prepareRelease(options) {
           throw new ReleaseError(
             GATE_FAILED,
             `unit "${unit.id}" has bound previousPublicBaseline but production prepare uses --offline. ` +
-            `Must use --online to observe the previous public baseline before freezing a production plan.`,
+            `Must use --online to observe the previous public baseline before freezing a production plan. ` +
+            `Remediation: release-skill prepare --production --online`,
             { unitId: unit.id, repo: ppbConfig.repo, ref: ppbConfig.ref },
           );
         }
@@ -3375,16 +3733,51 @@ export async function prepareRelease(options) {
     // tagCommit, never from workspace state). planVersion 2 record-layer
     // stripping does not strip this block, so every declaration detail is
     // bound into the plan digest.
+    //
+    // F-01 / T1 private execution bundle: parent-workspace files that the
+    // post-publish commands need but the frozen tag does not contain are
+    // frozen here — Foundation closure (verbatim computeResourceClosure
+    // return) + the release-unit publicFiles projection — and their bytes
+    // are published digest-addressed under this plan's .release-skill. The
+    // plan is the bundle's only source of truth (no parallel manifest, no
+    // second bundle digest): the raw executionFiles list folds into the
+    // closure and is NOT duplicated into the frozen block.
     let frozenPostPublish = null;
     if (postPublishDeclaration) {
       const { unit, index } = postPublishDeclaration;
       const { tag } = resolveProductionBranch(unit, resolvedVersions[index]);
+      const declaredExecutionFiles = unit.postPublish.executionFiles ?? [];
+      const frozenTagPaths = productionAssets
+        ? await enumerateFrozenTagPaths(realRoot, productionAssets[index])
+        : null;
+      await assertPrivateExecutionDeclarations(unit.postPublish, {
+        workspaceRoot: realRoot,
+        frozenTagPaths,
+        executionFiles: declaredExecutionFiles,
+      });
+      const executionBundle = await freezeExecutionBundle({
+        workspaceRoot: realRoot,
+        releaseSkillDir: releaseDir,
+        executionFiles: declaredExecutionFiles,
+        publicFiles: unit.publicFiles ?? [],
+      });
+      await evidence.append({
+        phase: 'postpublish-execution-bundle',
+        status: 'frozen',
+        unitId: unit.id,
+        closureDigest: executionBundle.closure.digest,
+        resourceCount: executionBundle.closure.resources.length,
+        publicFileCount: executionBundle.publicFiles.length,
+        bundleRoot: relative(realRoot, bundleRootForAuthorityDir(releaseDir)),
+      });
+      const { executionFiles: _executionFiles, ...declarationWithoutManifest } = structuredClone(unit.postPublish);
       frozenPostPublish = {
-        ...structuredClone(unit.postPublish),
+        ...declarationWithoutManifest,
         tag,
         ...(productionAssets ? { tagCommit: productionAssets[index].commit } : {}),
         unitId: unit.id,
         payloadSource: PAYLOAD_SOURCE_TAG_WORKTREE,
+        executionBundle,
       };
     }
 
@@ -3494,11 +3887,29 @@ export async function prepareRelease(options) {
       completedAt: (clock ? clock() : new Date().toISOString()),
     });
 
+    // --- O4 (2026-08-18 investigation §3.2): success-time guidance ---
+    // A NON-PRODUCTION plan cannot be used by publish; historically operators
+    // discovered that only after a full prepare+approve round-trip. Surface the
+    // remediation at success time so the loop never starts. Production plans
+    // carry no such warning. The prepare command's own defaults are unchanged —
+    // this only enriches the result, never flips offline/production.
+    const nextSteps = [];
+    if (!production) {
+      nextSteps.push({
+        code: 'NON_PRODUCTION_PLAN_NOT_PUBLISHABLE',
+        message:
+          'This plan is NON-PRODUCTION and cannot be used by publish. ' +
+          'To release, re-run: release-skill prepare --production --online — ' +
+          'or use the guided happy end: release-skill ship --target-version <version>.',
+      });
+    }
+
     return {
       planPath: writtenPath,
       planDigest,
       evidenceDir,
-      warnings: adoptionWarnings,
+      warnings: runWarnings,
+      nextSteps,
     };
   } catch (err) {
     // Record failure evidence