release-skill 0.9.3 → 0.9.4

package/src/commands/prepare.mjs

@@ -2917,6 +2917,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 +3067,7 @@ export async function prepareRelease(options) {
     workflow = 'full',
     observePreviousPublicBaselineFn,
     testSelection = 'full',
+    unitIds,
   } = options ?? {};
 
   // --- Workflow profile (H5) ---
@@ -3039,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];
@@ -3057,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
@@ -3132,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,
@@ -3330,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',
@@ -3435,7 +3597,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 +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
@@ -4280,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
@@ -4524,7 +4686,7 @@ export async function prepareRelease(options) {
             },
           }
         : {}),
-      verificationGates: config.verificationGates ?? [],
+      verificationGates: declaredVerificationGates,
       snapshotDigest: overallSnapshotDigest,
       ...(humanConsumersStrategy ? { humanConsumersStrategy } : {}),
       ...(production ? {
@@ -4608,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',
@@ -4624,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

package/src/commands/ship.mjs

@@ -15,11 +15,92 @@ import {
 } from './post-release-local.mjs';
 import {
   ReleaseError,
+  CONFIG_INVALID,
   GATE_FAILED,
   PLAN_DIGEST_MISMATCH,
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 
+function normalizeNewShipUnitIds(releaseUnits, requestedUnitIds) {
+  if (requestedUnitIds === undefined) return undefined;
+  const availableUnitIds = (releaseUnits ?? []).map((unit) => unit.id);
+  if (!Array.isArray(requestedUnitIds) || requestedUnitIds.length === 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'explicit ship release-unit selection must contain at least one unit id',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  const requestedSet = new Set(requestedUnitIds);
+  const invalid = requestedUnitIds.filter((unitId) => typeof unitId !== 'string' || unitId.length === 0);
+  const unknown = requestedUnitIds.filter((unitId) => !availableUnitIds.includes(unitId));
+  if (invalid.length > 0 || requestedSet.size !== requestedUnitIds.length || unknown.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'ship release-unit selection contains empty, duplicate, or unknown unit ids',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  return availableUnitIds.filter((unitId) => requestedSet.has(unitId));
+}
+
+function sameUnitSelection(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && new Set(left).size === left.length
+    && new Set(right).size === right.length
+    && left.every((unitId) => right.includes(unitId));
+}
+
+function sameUnitOrder(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((unitId, index) => unitId === right[index]);
+}
+
+function unitScopeMismatch(statePath, stateUnitIds, requestedUnitIds, message) {
+  return new ReleaseError(
+    GATE_FAILED,
+    message,
+    {
+      reason: 'SHIP_STATE_UNIT_SCOPE_MISMATCH',
+      statePath,
+      stateUnitIds: stateUnitIds ?? null,
+      requestedUnitIds: requestedUnitIds ?? null,
+    },
+  );
+}
+
+function assertFrozenPlanUnitScope({ statePath, stateUnitIds, expectedUnitIds, plan }) {
+  const planUnitIds = (plan.units ?? []).map((unit) => unit.id);
+  const exactMatch = Array.isArray(expectedUnitIds)
+    && planUnitIds.length === expectedUnitIds.length
+    && planUnitIds.every((unitId, index) => unitId === expectedUnitIds[index]);
+  if (!exactMatch) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      planUnitIds,
+      'ship state release-unit scope does not match frozen plan.units',
+    );
+  }
+}
+
+async function readFrozenPlanForUnitScope(planPath, statePath, stateUnitIds) {
+  try {
+    return JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (error) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      null,
+      `cannot verify ship state release-unit scope against frozen plan: ${error.message}`,
+    );
+  }
+}
+
 async function writeJsonAtomic(path, value) {
   await mkdir(dirname(path), { recursive: true });
   const { stateDigest: _oldDigest, ...body } = value;
@@ -102,6 +183,7 @@ function publicState(state) {
     ...(state.hooks && state.hooks.length > 0 ? {
       hooks: state.hooks,
     } : {}),
+    ...(state.selectedUnitIds ? { selectedUnitIds: state.selectedUnitIds } : {}),
     ...(state.planPath ? {
       planPath: state.planPath,
       planDigest: state.planDigest,
@@ -334,6 +416,24 @@ export async function advanceShip(options = {}, injected = {}) {
       );
     }
   }
+  if (state && options.unitIds !== undefined) {
+    if (!Array.isArray(state.selectedUnitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        null,
+        options.unitIds,
+        'an existing full-scope or legacy ship state cannot acquire --unit; provide a new --state path',
+      );
+    }
+    if (!sameUnitSelection(state.selectedUnitIds, options.unitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        state.selectedUnitIds,
+        options.unitIds,
+        'ship state release-unit scope does not match the requested --unit values',
+      );
+    }
+  }
   if (state?.gitTransport) {
     process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
   }
@@ -341,6 +441,7 @@ export async function advanceShip(options = {}, injected = {}) {
   if (!state) {
     const loaded = await deps.loadProjectConfig({ root });
     const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+    const selectedUnitIds = normalizeNewShipUnitIds(loaded.config.releaseUnits, options.unitIds);
     state = {
       schemaVersion: 2,
       root,
@@ -348,6 +449,7 @@ export async function advanceShip(options = {}, injected = {}) {
       targetVersion: options.targetVersion ?? null,
       configDigest: loaded.configDigest,
       hooks,
+      ...(selectedUnitIds ? { selectedUnitIds } : {}),
       status: 'NEW',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
@@ -364,8 +466,53 @@ export async function advanceShip(options = {}, injected = {}) {
     await writeJsonAtomic(statePath, state);
   }
 
+  if (state.planPath && Array.isArray(state.selectedUnitIds)) {
+    const frozenPlan = await readFrozenPlanForUnitScope(
+      state.planPath,
+      statePath,
+      state.selectedUnitIds,
+    );
+    assertFrozenPlanUnitScope({
+      statePath,
+      stateUnitIds: state.selectedUnitIds,
+      expectedUnitIds: state.selectedUnitIds,
+      plan: frozenPlan,
+    });
+  }
+
   if (state.status === 'NEW') {
     const loaded = await deps.loadProjectConfig({ root });
+    let stateChanged = false;
+    if (Array.isArray(state.selectedUnitIds)) {
+      const normalizedStateUnitIds = normalizeNewShipUnitIds(
+        loaded.config.releaseUnits,
+        state.selectedUnitIds,
+      );
+      if (!sameUnitSelection(normalizedStateUnitIds, state.selectedUnitIds)) {
+        throw unitScopeMismatch(
+          statePath,
+          state.selectedUnitIds,
+          normalizedStateUnitIds,
+          'ship state release-unit scope no longer matches project configuration',
+        );
+      }
+      if (!sameUnitOrder(normalizedStateUnitIds, state.selectedUnitIds)) {
+        if (state.planPath) {
+          throw unitScopeMismatch(
+            statePath,
+            state.selectedUnitIds,
+            normalizedStateUnitIds,
+            'frozen ship state release-unit order no longer matches project configuration',
+          );
+        }
+        state = {
+          ...state,
+          selectedUnitIds: normalizedStateUnitIds,
+          updatedAt: new Date().toISOString(),
+        };
+        stateChanged = true;
+      }
+    }
     if (loaded.configDigest !== state.configDigest) {
       const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
       state = {
@@ -375,8 +522,9 @@ export async function advanceShip(options = {}, injected = {}) {
         status: 'NEW',
         updatedAt: new Date().toISOString(),
       };
-      await writeJsonAtomic(statePath, state);
+      stateChanged = true;
     }
+    if (stateChanged) await writeJsonAtomic(statePath, state);
     const prepared = await deps.prepareRelease({
       root,
       version: state.targetVersion ?? undefined,
@@ -385,10 +533,24 @@ export async function advanceShip(options = {}, injected = {}) {
       hooksAuthorized: true,
       verificationGatesAuthorized: true,
       hookCache: true,
+      ...(state.selectedUnitIds ? { unitIds: state.selectedUnitIds } : {}),
     });
+    let frozenPlan = null;
+    if (Array.isArray(state.selectedUnitIds) || deps.preflightGitTransports) {
+      frozenPlan = Array.isArray(state.selectedUnitIds)
+        ? await readFrozenPlanForUnitScope(prepared.planPath, statePath, state.selectedUnitIds)
+        : JSON.parse(await readFile(prepared.planPath, 'utf8'));
+    }
+    if (Array.isArray(state.selectedUnitIds)) {
+      assertFrozenPlanUnitScope({
+        statePath,
+        stateUnitIds: state.selectedUnitIds,
+        expectedUnitIds: state.selectedUnitIds,
+        plan: frozenPlan,
+      });
+    }
     let transportPreflight = null;
     if (deps.preflightGitTransports) {
-      const frozenPlan = JSON.parse(await readFile(prepared.planPath, 'utf8'));
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }

package/src/core/foundation-plugin-verification.mjs

@@ -33,7 +33,6 @@ import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
 // this value so an upstream contract change fails closed during adoption.
 const FOUNDATION_PLUGIN_DRIVER_VERSION = '1.0.0';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
-const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
 
 function isSafeRelativePath(value) {
   return typeof value === 'string'
@@ -46,7 +45,28 @@ function isSafeRelativePath(value) {
 }
 
 function decodeCanonicalBase64(value) {
-  if (typeof value !== 'string' || !BASE64_PATTERN.test(value)) return null;
+  if (typeof value !== 'string' || value.length % 4 !== 0) return null;
+  let paddingStart = -1;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 61) {
+      if (paddingStart === -1) paddingStart = index;
+      continue;
+    }
+    if (paddingStart !== -1 || !(
+      code >= 65 && code <= 90
+      || code >= 97 && code <= 122
+      || code >= 48 && code <= 57
+      || code === 43
+      || code === 47
+    )) return null;
+  }
+  if (
+    paddingStart !== -1
+    && value.length - paddingStart > 2
+    || paddingStart !== -1
+    && paddingStart % 4 < 2
+  ) return null;
   const decoded = Buffer.from(value, 'base64');
   return decoded.toString('base64') === value ? decoded : null;
 }

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

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