release-skill 0.9.1 → 0.9.4

package/src/commands/prepare.mjs

@@ -25,7 +25,7 @@ import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCb);
 
-import { classifyPathInput, writeFileAtomic } from 'skill-family-harness-node';
+import { classifyPathInput, writeFileAtomic, withTemporaryWorkspace } from 'skill-family-harness-node';
 import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
@@ -323,9 +323,16 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
 
     // --- Incremental cache lookup (opt-in only; default zero change) ---
     let cacheKey;
+    let cacheReceipt;
+    let cacheRootBinding;
     if (cacheEnabled && hook.cacheable === true) {
       try {
-        ({ cacheKey } = await computeHookCacheKey(hook, root));
+        ({ cacheKey, receipt: cacheReceipt, projectRootBinding: cacheRootBinding } = await computeHookCacheKey(hook, root, {
+          env: options.env ?? process.env,
+          ...(typeof options.observeExecutableIdentityFn === 'function'
+            ? { observeExecutableIdentityFn: options.observeExecutableIdentityFn }
+            : {}),
+        }));
       } catch (err) {
         await evidence.append({
           phase: 'hooks',
@@ -336,7 +343,9 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
         throw err;
       }
 
-      const cached = await readHookCache(root, name, cacheKey);
+      const cached = cacheKey ? await readHookCache(root, name, cacheKey, {
+        rootBinding: cacheRootBinding,
+      }) : null;
       if (cached) {
         // Cache hit: skip execution. The authorization gate already passed and
         // no GATE is bypassed — ordering and failure semantics are untouched.
@@ -407,12 +416,13 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
     }
 
     // --- Write cache on success only; failures are never cached ---
-    if (cacheEnabled && hook.cacheable === true && cacheKey) {
+    if (cacheEnabled && hook.cacheable === true && cacheKey && cacheReceipt) {
       const written = await writeHookCache(root, name, cacheKey, {
         exitCode: 0,
         stdoutTail: result.stdout.slice(-4000),
         stderrTail: result.stderr.slice(-4000),
-      });
+        receipt: cacheReceipt,
+      }, { rootBinding: cacheRootBinding });
       if (!written.ok) {
         // The cache is an optimisation, not a gate: a write failure must not
         // abort prepare. Surface it as a warning-level evidence event.
@@ -2794,6 +2804,255 @@ async function runPrepareSkillResourceClosureGate({
   return skillResourceClosureResults;
 }
 
+/**
+ * R93-01: optionally inspect the public surface before the first declared
+ * hook. The staging and closure checks are deliberately ephemeral: their
+ * result is an execution gate, not a plan/approval/publish receipt. The
+ * normal post-hook snapshot and closure gate remains authoritative.
+ */
+async function runPreHookPublicSurfaceGate({
+  config,
+  root,
+  resolvedVersions,
+  evidence,
+  skipDeclaredHooks,
+  workflow,
+}) {
+  if (config.policy?.preHookPublicSurfaceCheck !== true) return;
+
+  const declaredHookCount = Object.values(config.hooks ?? {})
+    .filter((hook) => hook && hook.command).length;
+  if (skipDeclaredHooks || declaredHookCount === 0) {
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'skipped',
+      reason: skipDeclaredHooks
+        ? `workflow "${workflow}" trims code-class hooks`
+        : 'no declared hooks',
+    });
+    return;
+  }
+
+  await evidence.append({ phase: 'pre-hook-public-surface', status: 'started' });
+  let currentUnitId = null;
+  let unitCount = 0;
+  try {
+    await withTemporaryWorkspace(async (workspace) => {
+      const stagingRoot = workspace.root;
+      const unitResults = [];
+      for (const unit of config.releaseUnits ?? []) {
+        currentUnitId = unit.id;
+        const outputDir = resolveUnitScopedPath(stagingRoot, unit.id);
+        const publicManifest = await buildPublicStaging({
+          sourceRoot: root,
+          unit,
+          outputDir,
+        });
+        unitResults.push({
+          unit,
+          manifest: {
+            entries: publicManifest.entries,
+            files: publicManifest.entries.map((entry) => entry.path).sort(),
+            totalSize: publicManifest.totalSize,
+            fileCount: publicManifest.fileCount,
+            contentHash: publicManifest.contentHash,
+            snapshotDigest: publicManifest.contentHash,
+            source: unit.source,
+            outputDir: publicManifest.outputDir,
+          },
+        });
+      }
+
+      const { frozenManifestByDist } = await resolveDistributionManifestFacts(
+        unitResults,
+        resolvedVersions,
+      );
+      unitCount = unitResults.length;
+      // Reuse the production closure/host-surface implementation, but do not
+      // append its ordinary phase events or retain its receipt in the plan.
+      await runPrepareSkillResourceClosureGate({
+        unitResults,
+        frozenManifestByDist,
+        freezeTimestamp: null,
+        evidence: { append: async () => undefined },
+        skipSkillResourceClosure: false,
+        workflow: 'pre-hook-public-surface',
+      });
+    });
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'passed',
+      unitCount,
+    });
+  } catch (error) {
+    const details = {
+      ...(error instanceof ReleaseError ? error.details : {}),
+      phase: 'pre-hook-public-surface',
+      unitId: error?.details?.unitId ?? currentUnitId,
+    };
+    if (Array.isArray(details.findings)) {
+      details.findings = details.findings.slice(0, 50);
+    }
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'failed',
+      error: { code: error.code ?? GATE_FAILED, message: error.message },
+    });
+    if (error instanceof ReleaseError) {
+      throw new ReleaseError(
+        error.code,
+        `pre-hook public surface check failed before hooks: ${error.message}`,
+        details,
+        error.exitCode,
+      );
+    }
+    throw new ReleaseError(
+      GATE_FAILED,
+      `pre-hook public surface check failed before hooks: ${error.message}`,
+      details,
+    );
+  } finally {
+    // withTemporaryWorkspace disposes the Foundation-managed staging root on
+    // both success and failure; no project run artifact is retained.
+  }
+}
+
+/**
+ * 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,
@@ -2808,6 +3067,7 @@ export async function prepareRelease(options) {
     workflow = 'full',
     observePreviousPublicBaselineFn,
     testSelection = 'full',
+    unitIds,
   } = options ?? {};
 
   // --- Workflow profile (H5) ---
@@ -2916,7 +3176,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];
@@ -2934,6 +3207,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
@@ -3009,7 +3294,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,
@@ -3207,7 +3491,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',
@@ -3309,6 +3594,17 @@ 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: selectedConfig,
+      root: realRoot,
+      resolvedVersions,
+      evidence,
+      skipDeclaredHooks,
+      workflow,
+    });
+
     // --- Step 3: Run declared hooks ---
     let hookRecords = [];
     if (skipDeclaredHooks) {
@@ -3760,7 +4056,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
@@ -4146,7 +4442,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
@@ -4390,7 +4686,7 @@ export async function prepareRelease(options) {
             },
           }
         : {}),
-      verificationGates: config.verificationGates ?? [],
+      verificationGates: declaredVerificationGates,
       snapshotDigest: overallSnapshotDigest,
       ...(humanConsumersStrategy ? { humanConsumersStrategy } : {}),
       ...(production ? {
@@ -4474,6 +4770,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',
@@ -4490,6 +4793,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