release-skill 0.9.3 → 0.9.5

package/src/commands/prepare.mjs

@@ -77,7 +77,11 @@ import { acquireProjectLock } from '../artifacts/project-lock.mjs';
 import { observePreviousPublicBaseline } from '../core/previous-public-baseline.mjs';
 import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 import { createProductionPrepareRunDir } from '../core/run.mjs';
-import { PLATFORMS, normalizeHostId } from '../platforms/registry.mjs';
+import {
+  PLATFORMS,
+  normalizeHostId,
+  buildExpectedStandaloneIndexInstallIdentity,
+} from '../platforms/registry.mjs';
 import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.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';
@@ -97,6 +101,7 @@ import { digestReleaseAssetIdentities } from '../core/release-assets.mjs';
 
 /** 消费端安装验证配方版本。算法变更时递增。 */
 const CONSUMER_INSTALL_RECIPE_VERSION = 'consumer-install-v1';
+const FIRST_RELEASE_BOOTSTRAP_MODE = 'manual-index-checkpoint';
 
 // ---------------------------------------------------------------------------
 // Version resolution
@@ -1498,6 +1503,72 @@ async function defaultFetchExternalMarketplaceIndex(repo, manifestPath, ref, { g
   }
 }
 
+/**
+ * Observe the plugin repository before a first standalone-index release.
+ * This is deliberately a read-only, fail-closed observation: an empty
+ * repository, no target tag, and no target GitHub Release are all required.
+ */
+export function parseFirstReleasePluginRepositoryRefs(stdout, tag) {
+  if (typeof stdout !== 'string' || typeof tag !== 'string' || tag.length === 0) {
+    return { hasRefs: false, tagExists: false };
+  }
+  const refs = [];
+  let hasRefs = false;
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    const tabIndex = line.indexOf('\t');
+    if (tabIndex < 0) continue;
+    const sha = line.slice(0, tabIndex);
+    const ref = line.slice(tabIndex + 1);
+    if (EXTERNAL_MARKETPLACE_SHA_RE.test(sha)) {
+      hasRefs = true;
+      if (ref && ref !== 'HEAD') refs.push(ref);
+    }
+  }
+  const target = `refs/tags/${tag}`;
+  return {
+    hasRefs,
+    tagExists: refs.includes(target) || refs.includes(`${target}^{}`),
+  };
+}
+
+async function defaultObserveFirstReleasePluginRepository(repo, tag, { githubHost = 'github.com' } = {}) {
+  const url = `https://${githubHost}/${repo}.git`;
+  let repositoryRefs;
+  try {
+    const { stdout } = await execFile(
+      'git', ['ls-remote', '--symref', url],
+      { shell: false, encoding: 'utf8', timeout: 30000 },
+    );
+    repositoryRefs = parseFirstReleasePluginRepositoryRefs(String(stdout ?? ''), tag);
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+
+  let releaseExists = false;
+  try {
+    await execFile(
+      'gh', ['api', `repos/${repo}/releases/tags/${tag}`],
+      {
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30000,
+        env: { ...process.env, GH_HOST: githubHost },
+      },
+    );
+    releaseExists = true;
+  } catch (error) {
+    const diagnostic = `${error?.stderr ?? ''} ${error?.message ?? ''}`;
+    if (!/\b404\b|not found/i.test(diagnostic)) {
+      return { status: 'unknown', error: error.message };
+    }
+  }
+  return { status: repositoryRefs.hasRefs ? 'non-empty' : 'empty', tagExists: repositoryRefs.tagExists, releaseExists };
+}
+
+function isFirstReleaseBootstrap(dist) {
+  return dist?.firstReleaseBootstrap === FIRST_RELEASE_BOOTSTRAP_MODE;
+}
+
 /**
  * Freeze the external marketplace HEAD for every claude/codex distribution
  * that declares `marketplaceRepo` (production + online only). For each such
@@ -1518,6 +1589,8 @@ export async function resolveExternalMarketplaceFreezes({
   evidence,
   observeHeadFn,
   fetchIndexFn,
+  productionAssets = null,
+  observePluginRepositoryFn = defaultObserveFirstReleasePluginRepository,
 }) {
   const freezes = new Map();
   for (let index = 0; index < unitResults.length; index += 1) {
@@ -1525,10 +1598,26 @@ export async function resolveExternalMarketplaceFreezes({
     const version = resolvedVersions[index];
     const githubHost = unit.production?.githubHost ?? 'github.com';
     for (const dist of unit.distributions ?? []) {
+      if (isFirstReleaseBootstrap(dist) && dist.marketplaceSourceType !== 'standalone-index') {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} first-release bootstrap requires marketplaceSourceType standalone-index`,
+          { unitId: unit.id, distributionType: dist.type },
+        );
+      }
       // 只处理 standalone-index 来源；bundled-family 不需要外部冻结。
       if (dist.marketplaceSourceType !== 'standalone-index') continue;
       // standalone-index 必须有 marketplaceRepo；没有则跳过（兼容旧配置）。
-      if (!dist.marketplaceRepo) continue;
+      if (!dist.marketplaceRepo) {
+        if (isFirstReleaseBootstrap(dist)) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" ${dist.type} first-release bootstrap requires marketplaceRepo`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+        continue;
+      }
       const platform = PLATFORMS.find((p) => p.distributionType === dist.type);
       if (!platform) {
         throw new ReleaseError(
@@ -1545,6 +1634,13 @@ export async function resolveExternalMarketplaceFreezes({
           { unitId: unit.id, marketplaceSourceType: dist.marketplaceSourceType },
         );
       }
+      if (isFirstReleaseBootstrap(dist) && dist.type !== 'claude-plugin' && dist.type !== 'codex-plugin') {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} first-release bootstrap is supported only for claude-plugin or codex-plugin standalone-index distributions`,
+          { unitId: unit.id, distributionType: dist.type },
+        );
+      }
       const observed = await observeHeadFn(dist.marketplaceRepo, { githubHost });
       if (observed.status !== 'observed' || !EXTERNAL_MARKETPLACE_SHA_RE.test(observed.sha ?? '') || !observed.defaultBranch) {
         throw new ReleaseError(
@@ -1581,23 +1677,65 @@ export async function resolveExternalMarketplaceFreezes({
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
-      const pluginEntries = Array.isArray(marketplaceIndex.plugins)
-        ? marketplaceIndex.plugins.filter((entry) => entry && entry.name === dist.plugin)
-        : [];
-      if (pluginEntries.length !== 1) {
+      if (!Array.isArray(marketplaceIndex.plugins)) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} external marketplace index plugins must be an array`,
+          { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
+        );
+      }
+      const pluginEntries = marketplaceIndex.plugins.filter((entry) => entry && entry.name === dist.plugin);
+      if (isFirstReleaseBootstrap(dist) && pluginEntries.length > 0) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" first-release bootstrap requires the marketplace entry to be absent, found ${pluginEntries.length} matching entries`,
+          { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
+        );
+      }
+      if (pluginEntries.length !== 1 && !isFirstReleaseBootstrap(dist)) {
         throw new ReleaseError(
           GATE_FAILED,
           `unit "${unit.id}" external marketplace index must contain exactly one plugin entry named "${dist.plugin}", found ${pluginEntries.length}`,
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
-      if (platform.marketplaceEntryCarriesVersion && pluginEntries[0].version !== version) {
+      let selectedEntry = pluginEntries[0];
+      if (!isFirstReleaseBootstrap(dist) && platform.marketplaceEntryCarriesVersion && selectedEntry.version !== version) {
         throw new ReleaseError(
           GATE_FAILED,
           `unit "${unit.id}" external marketplace index entry version "${pluginEntries[0].version}" does not match target version "${version}"`,
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
+      if (isFirstReleaseBootstrap(dist)) {
+        const asset = productionAssets?.[index];
+        if (!asset || !EXTERNAL_MARKETPLACE_SHA_RE.test(asset.commit ?? '') || !asset.tag) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" first-release bootstrap requires a frozen plugin tag and commit`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+        const pluginState = await observePluginRepositoryFn(unit.publicRepo, asset.tag, { githubHost });
+        if (
+          pluginState?.status !== 'empty'
+          || pluginState.tagExists !== false
+          || pluginState.releaseExists !== false
+        ) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" first-release bootstrap requires an empty plugin repository without the target tag or release`,
+            { unitId: unit.id, publicRepo: unit.publicRepo, tag: asset.tag, observed: pluginState },
+          );
+        }
+        selectedEntry = buildExpectedStandaloneIndexInstallIdentity(platform, {
+          name: dist.plugin,
+          repo: unit.publicRepo,
+          tag: asset.tag,
+          sha: asset.commit,
+          version,
+        });
+      }
       // marketplaceRef：Claude 使用默认分支名（name-ref），其余平台使用提交 SHA。
       // 无 CLI 的平台（kimi、codebuddy）也必须能冻结，ref 用 SHA。
       const marketplaceRef = platform.marketplaceRefForm === 'name' ? observed.defaultBranch : sha;
@@ -1612,7 +1750,10 @@ export async function resolveExternalMarketplaceFreezes({
         marketplaceRef,
         marketplaceIndexPath: manifestPath,
         marketplaceName: marketplaceIndex.name,
-        selectedEntry: pluginEntries[0],
+        selectedEntry,
+        ...(isFirstReleaseBootstrap(dist)
+          ? { firstReleaseBootstrap: FIRST_RELEASE_BOOTSTRAP_MODE, marketplaceIndexSha: null }
+          : {}),
       });
       await evidence.append({
         phase: 'external-marketplace-freeze',
@@ -1624,7 +1765,10 @@ export async function resolveExternalMarketplaceFreezes({
         marketplaceRef,
         marketplaceIndexPath: manifestPath,
         marketplaceName: marketplaceIndex.name,
-        selectedEntry: pluginEntries[0],
+        selectedEntry,
+        ...(isFirstReleaseBootstrap(dist)
+          ? { firstReleaseBootstrap: FIRST_RELEASE_BOOTSTRAP_MODE, marketplaceIndexSha: null }
+          : {}),
         defaultBranch: observed.defaultBranch,
       });
     }
@@ -2043,6 +2187,10 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
             marketplaceIndexPath: freeze.marketplaceIndexPath,
             marketplaceName: freeze.marketplaceName,
             selectedEntry: freeze.selectedEntry,
+            ...(freeze.firstReleaseBootstrap ? {
+              firstReleaseBootstrap: freeze.firstReleaseBootstrap,
+              marketplaceIndexSha: null,
+            } : {}),
           } : {}),
         },
         expected: {
@@ -2058,6 +2206,10 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           entrySkillFound: true,
           manifestDigest: asset.manifestDigest,
           ...(externalMarketplace ? { marketplaceLocation: 'external', marketplaceCommitSha: freeze.marketplaceCommitSha } : {}),
+          ...(externalMarketplace && freeze?.firstReleaseBootstrap ? {
+            firstReleaseBootstrap: freeze.firstReleaseBootstrap,
+            marketplaceIndexSha: null,
+          } : {}),
         },
         status: 'PENDING',
       });
@@ -2917,6 +3069,142 @@ async function runPreHookPublicSurfaceGate({
   }
 }
 
+/**
+ * Resolve the operator's pre-freeze release-unit request against the complete
+ * validated project configuration. The returned units always follow config
+ * declaration order so plan ordering and digests never depend on argv order.
+ */
+function prepareRetryPathArg(path) {
+  return relative(process.cwd(), resolve(path)) || '.';
+}
+
+function buildPrepareRetryArgv(options, unitIds) {
+  const argv = [
+    'release-skill',
+    'prepare',
+    '--root',
+    prepareRetryPathArg(options.root),
+  ];
+  if (typeof options.version === 'string' && options.version.length > 0) {
+    argv.push('--target-version', options.version);
+  }
+  argv.push(options.offline ? '--offline' : '--online');
+  if (options.production) argv.push('--production');
+  argv.push('--workflow', options.workflow);
+  if (typeof options.testSelection === 'string') {
+    argv.push('--test-selection', options.testSelection);
+  }
+  if (typeof options.output === 'string') {
+    argv.push('--output', prepareRetryPathArg(options.output));
+  }
+  // A production --run-dir is single-use by contract and this failed attempt
+  // has already created it. Let the retry allocate a fresh evidence directory.
+  if (options.hookCache === false) argv.push('--no-hook-cache');
+  for (const unitId of unitIds) argv.push('--unit', unitId);
+  return argv;
+}
+
+/**
+ * Keep the deferred-unit evidence and operator guidance on one exact argv.
+ * The command points back to the caller's project root and carries the same
+ * prepare mode while selecting only the units that were deferred.
+ */
+function buildDeferredReleaseDiagnostics(options, deferredUnitIds) {
+  if (deferredUnitIds.length === 0) return null;
+  return {
+    deferredUnitIds: [...deferredUnitIds],
+    nextPrepareArgv: buildPrepareRetryArgv(options, deferredUnitIds),
+  };
+}
+
+function resolveRequestedReleaseUnits(config, requestedUnitIds, retryOptions) {
+  const availableUnits = config.releaseUnits ?? [];
+  const availableUnitIds = availableUnits.map((unit) => unit.id);
+  if (requestedUnitIds === undefined) {
+    return {
+      explicit: false,
+      selectedUnits: availableUnits,
+      selectedUnitIds: availableUnitIds,
+      deferredUnitIds: [],
+      receiptSelected: Boolean(config.publicSourceAuthorityReceipt),
+    };
+  }
+  if (!Array.isArray(requestedUnitIds) || requestedUnitIds.length === 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'explicit release-unit selection must contain at least one unit id',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+
+  const invalidUnitIds = requestedUnitIds.filter(
+    (unitId) => typeof unitId !== 'string' || unitId.length === 0,
+  );
+  const seen = new Set();
+  const duplicateUnitIds = [];
+  for (const unitId of requestedUnitIds) {
+    if (seen.has(unitId) && !duplicateUnitIds.includes(unitId)) duplicateUnitIds.push(unitId);
+    seen.add(unitId);
+  }
+  const availableSet = new Set(availableUnitIds);
+  const unknownUnitIds = requestedUnitIds.filter(
+    (unitId) => typeof unitId === 'string' && unitId.length > 0 && !availableSet.has(unitId),
+  );
+  if (invalidUnitIds.length > 0 || duplicateUnitIds.length > 0 || unknownUnitIds.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'release-unit selection contains empty, duplicate, or unknown unit ids',
+      {
+        requestedUnitIds,
+        availableUnitIds,
+        invalidUnitIds,
+        duplicateUnitIds,
+        unknownUnitIds,
+      },
+    );
+  }
+
+  const selectedSet = new Set(requestedUnitIds);
+  const selectedUnits = availableUnits.filter((unit) => selectedSet.has(unit.id));
+  const selectedUnitIds = selectedUnits.map((unit) => unit.id);
+  const deferredUnitIds = availableUnitIds.filter((unitId) => !selectedSet.has(unitId));
+  const deferredReleaseDiagnostics = buildDeferredReleaseDiagnostics(retryOptions, deferredUnitIds);
+  const receipt = config.publicSourceAuthorityReceipt;
+  let receiptSelected = false;
+  if (receipt) {
+    const receiptSet = new Set([receipt.coordinatorUnitId, ...receipt.subjectUnitIds]);
+    const dependencyUnitIds = availableUnitIds.filter((unitId) => receiptSet.has(unitId));
+    receiptSelected = dependencyUnitIds.some((unitId) => selectedSet.has(unitId));
+    if (receiptSelected) {
+      const missingUnitIds = dependencyUnitIds.filter((unitId) => !selectedSet.has(unitId));
+      if (missingUnitIds.length > 0) {
+        const retryUnitIds = availableUnitIds.filter(
+          (unitId) => selectedSet.has(unitId) || receiptSet.has(unitId),
+        );
+        throw new ReleaseError(
+          GATE_FAILED,
+          'release-unit selection does not include the complete public source-authority dependency closure',
+          {
+            selectedUnitIds,
+            missingUnitIds,
+            dependencyUnitIds,
+            retryArgv: buildPrepareRetryArgv(retryOptions, retryUnitIds),
+          },
+        );
+      }
+    }
+  }
+
+  return {
+    explicit: true,
+    selectedUnits,
+    selectedUnitIds,
+    deferredUnitIds,
+    deferredReleaseDiagnostics,
+    receiptSelected,
+  };
+}
+
 export async function prepareRelease(options) {
   const {
     root,
@@ -2931,6 +3219,7 @@ export async function prepareRelease(options) {
     workflow = 'full',
     observePreviousPublicBaselineFn,
     testSelection = 'full',
+    unitIds,
   } = options ?? {};
 
   // --- Workflow profile (H5) ---
@@ -3039,7 +3328,20 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'config', status: 'started' });
 
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
-    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
+    const releaseSelection = resolveRequestedReleaseUnits(config, unitIds, {
+      root,
+      version,
+      offline,
+      production,
+      workflow,
+      testSelection: typeof options?.testSelection === 'string' ? testSelection : undefined,
+      output,
+      hookCache: options?.hookCache,
+    });
+    const configUnits = releaseSelection.selectedUnits;
+    const selectedConfig = { ...config, releaseUnits: configUnits };
+    const selectedUnitIdSet = new Set(releaseSelection.selectedUnitIds);
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(selectedConfig);
     // Mutable operator-facing warning list: seeded from the adoption warnings,
     // appended by later gates (O5 origin-ahead). Returned as `warnings`.
     const runWarnings = [...adoptionWarnings];
@@ -3057,6 +3359,18 @@ export async function prepareRelease(options) {
         ...warning,
       });
     }
+    if (releaseSelection.explicit) {
+      await evidence.append({
+        phase: 'release-scope',
+        status: 'selected',
+        mode: 'selected',
+        selectedUnitIds: releaseSelection.selectedUnitIds,
+        deferredUnitIds: releaseSelection.deferredUnitIds,
+        ...(releaseSelection.deferredReleaseDiagnostics
+          ? { nextPrepareArgv: releaseSelection.deferredReleaseDiagnostics.nextPrepareArgv }
+          : {}),
+      });
+    }
 
     // --- Step 1-fresh: Bundle freshness gate (BUNDLE_STALE, fail-closed) ---
     // 2026-08-18 investigation §4.2: a stale bin/release-skill.bundle.mjs
@@ -3132,7 +3446,6 @@ export async function prepareRelease(options) {
     // gate, baseline, snapshot, remote check, or plan write runs. Units
     // without releaseDocuments keep the exact legacy behaviour (the gate
     // appends no evidence and performs no check).
-    const configUnits = config.releaseUnits ?? [];
     const resolvedVersions = await resolveAllUnitVersions(
       configUnits,
       realRoot,
@@ -3330,7 +3643,8 @@ export async function prepareRelease(options) {
       });
     }
 
-    const declaredVerificationGates = config.verificationGates ?? [];
+    const declaredVerificationGates = (config.verificationGates ?? [])
+      .filter((gate) => selectedUnitIdSet.has(gate.scope.unit));
     if (declaredVerificationGates.length > 0) {
       await evidence.append({
         phase: 'verification-gate-authorization',
@@ -3435,7 +3749,7 @@ export async function prepareRelease(options) {
     // R93-01: optional ephemeral public-surface check immediately before the
     // first hook. Its staging and closure receipt never enter the plan.
     await runPreHookPublicSurfaceGate({
-      config,
+      config: selectedConfig,
       root: realRoot,
       resolvedVersions,
       evidence,
@@ -3894,7 +4208,7 @@ export async function prepareRelease(options) {
 
     // --- Step 5: Build snapshots, scan, and evaluate README ---
     const { unitResults, snapshotDigests } = await processSnapshots(
-      config, realRoot, evidence, runDir, production,
+      selectedConfig, realRoot, evidence, runDir, production,
     );
 
     // Snapshot gates always run on disposable writable copies. The public
@@ -4080,6 +4394,17 @@ export async function prepareRelease(options) {
     // and validate the marketplace index entry at that sha before freezing the
     // add-ref. The remote is only ever read (git ls-remote / gh api), never
     // written, and it is only ever reached AFTER the local closure passed.
+    for (const { unit } of unitResults) {
+      for (const dist of unit.distributions ?? []) {
+        if (isFirstReleaseBootstrap(dist) && (!production || offline)) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" ${dist.type} first-release bootstrap requires online production prepare`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+      }
+    }
     const externalMarketplaceFreezes = production
       ? await resolveExternalMarketplaceFreezes({
           unitResults,
@@ -4088,6 +4413,8 @@ export async function prepareRelease(options) {
           evidence,
           observeHeadFn: options.observeExternalMarketplaceHeadFn ?? defaultObserveExternalMarketplaceHead,
           fetchIndexFn: options.fetchExternalMarketplaceIndexFn ?? defaultFetchExternalMarketplaceIndex,
+          productionAssets,
+          observePluginRepositoryFn: options.observeFirstReleasePluginRepositoryFn ?? defaultObserveFirstReleasePluginRepository,
         })
       : new Map();
 
@@ -4191,6 +4518,10 @@ export async function prepareRelease(options) {
             frozenDist.marketplaceIndexPath = freeze.marketplaceIndexPath;
             frozenDist.marketplaceName = freeze.marketplaceName;
             frozenDist.selectedEntry = freeze.selectedEntry;
+            if (freeze.firstReleaseBootstrap) {
+              frozenDist.firstReleaseBootstrap = freeze.firstReleaseBootstrap;
+              frozenDist.marketplaceIndexSha = null;
+            }
           }
         }
 
@@ -4280,7 +4611,7 @@ export async function prepareRelease(options) {
     }
 
     let publicSourceAuthorityReceipt = null;
-    if (config.publicSourceAuthorityReceipt) {
+    if (config.publicSourceAuthorityReceipt && releaseSelection.receiptSelected) {
       // P3 (ruling 7): config scenario A (no-publish-needed) means the public
       // bytes are unchanged and nothing will be published — a configured
       // public source receipt must not require or generate a nonexistent
@@ -4524,7 +4855,7 @@ export async function prepareRelease(options) {
             },
           }
         : {}),
-      verificationGates: config.verificationGates ?? [],
+      verificationGates: declaredVerificationGates,
       snapshotDigest: overallSnapshotDigest,
       ...(humanConsumersStrategy ? { humanConsumersStrategy } : {}),
       ...(production ? {
@@ -4608,6 +4939,13 @@ export async function prepareRelease(options) {
     // carry no such warning. The prepare command's own defaults are unchanged —
     // this only enriches the result, never flips offline/production.
     const nextSteps = [];
+    if (releaseSelection.explicit && releaseSelection.deferredUnitIds.length > 0) {
+      nextSteps.push({
+        code: 'DEFERRED_RELEASE_UNITS',
+        message: `Prepare the deferred release units separately: ${releaseSelection.deferredUnitIds.join(', ')}`,
+        argv: releaseSelection.deferredReleaseDiagnostics.nextPrepareArgv,
+      });
+    }
     if (!production) {
       nextSteps.push({
         code: 'NON_PRODUCTION_PLAN_NOT_PUBLISHABLE',
@@ -4624,6 +4962,13 @@ export async function prepareRelease(options) {
       evidenceDir,
       warnings: runWarnings,
       nextSteps,
+      ...(releaseSelection.explicit ? {
+        releaseScope: {
+          mode: 'selected',
+          selectedUnitIds: releaseSelection.selectedUnitIds,
+          deferredUnitIds: releaseSelection.deferredUnitIds,
+        },
+      } : {}),
     };
   } catch (err) {
     // Record failure evidence (best effort). A broken clock can make the