release-skill 0.2.8 → 0.3.0

package/src/commands/ship.mjs

@@ -0,0 +1,356 @@
+import { readFile, lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import {
+  ReleaseError,
+  GATE_FAILED,
+  PLAN_DIGEST_MISMATCH,
+  CONSUMER_VERIFICATION_DEFERRED,
+} from '../core/errors.mjs';
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const { stateDigest: _oldDigest, ...body } = value;
+  const sealed = {
+    ...body,
+    stateDigest: sha256Hex(canonicalJson(body)),
+  };
+  try {
+    await writeFile(temp, `${JSON.stringify(sealed, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temp, path);
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function readState(path) {
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error('ship state must be a regular non-symlink file');
+    }
+    const state = JSON.parse(await readFile(path, 'utf8'));
+    const { stateDigest, ...body } = state;
+    if (
+      typeof stateDigest !== 'string'
+      || stateDigest !== sha256Hex(canonicalJson(body))
+      || body.statePath !== path
+    ) {
+      throw new Error('ship state digest or authority path does not match');
+    }
+    return state;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new ReleaseError(GATE_FAILED, `cannot read ship state: ${error.message}`, { statePath: path });
+  }
+}
+
+async function defaultDependencies() {
+  const [
+    configModule,
+    prepareModule,
+    approveModule,
+    publishModule,
+    reconcileModule,
+    verifyModule,
+    transportModule,
+    metadataModule,
+  ] = await Promise.all([
+    import('../core/config.mjs'),
+    import('./prepare.mjs'),
+    import('./approve.mjs'),
+    import('./publish.mjs'),
+    import('./reconcile.mjs'),
+    import('./verify.mjs'),
+    import('../core/git-transport.mjs'),
+    import('../core/release-metadata.mjs'),
+  ]);
+  return {
+    loadProjectConfig: configModule.loadProjectConfig,
+    prepareRelease: prepareModule.prepareRelease,
+    approvePlan: approveModule.approvePlan,
+    publishRelease: publishModule.publishRelease,
+    reconcileRelease: reconcileModule.reconcileRelease,
+    verifyRelease: verifyModule.verifyRelease,
+    preflightGitTransports: transportModule.preflightGitTransports,
+    updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
+  };
+}
+
+function publicState(state) {
+  return {
+    command: 'ship',
+    status: state.status,
+    statePath: state.statePath,
+    targetVersion: state.targetVersion,
+    ...(state.hookAuthorizationDigest ? {
+      hookAuthorizationDigest: state.hookAuthorizationDigest,
+      hooks: state.hooks,
+    } : {}),
+    ...(state.planPath ? {
+      planPath: state.planPath,
+      planDigest: state.planDigest,
+      evidenceDir: state.evidenceDir,
+      warnings: state.warnings ?? [],
+    } : {}),
+    ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
+    ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
+    ...(state.requirements ? { requirements: state.requirements } : {}),
+    ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
+    verificationGateAuthorizationIncludedInPlanApproval:
+      state.status !== 'NEEDS_HOOK_AUTHORIZATION',
+    postVerifyMetadataUpdateIncludedInPlanApproval:
+      state.status !== 'NEEDS_HOOK_AUTHORIZATION',
+  };
+}
+
+function hookAuthority(loaded, targetVersion) {
+  const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+  return {
+    hooks,
+    digest: sha256Hex(canonicalJson({
+      kind: 'release-skill-hook-authorization/v1',
+      configDigest: loaded.configDigest,
+      hooks: loaded.config.hooks ?? {},
+      targetVersion: targetVersion ?? null,
+    })),
+  };
+}
+
+/**
+ * Advance one durable production release. Re-running is safe: the state file
+ * carries the immutable plan, approval and source-run paths so the command
+ * resumes instead of reconstructing authority from terminal/chat output.
+ */
+export async function advanceShip(options = {}, injected = {}) {
+  const root = resolve(options.root ?? process.cwd());
+  const statePath = resolve(
+    options.statePath ?? resolve(root, '.release-skill', 'ships', 'current.json'),
+  );
+  const deps = Object.keys(injected).length > 0
+    ? injected
+    : await defaultDependencies();
+  let state = await readState(statePath);
+  if (state?.gitTransport) {
+    process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
+  }
+
+  if (!state) {
+    const loaded = await deps.loadProjectConfig({ root });
+    const authority = hookAuthority(loaded, options.targetVersion);
+    const hooks = authority.hooks;
+    const hookAuthorizationDigest = authority.digest;
+    state = {
+      schemaVersion: 1,
+      root,
+      statePath,
+      targetVersion: options.targetVersion ?? null,
+      configDigest: loaded.configDigest,
+      hooks,
+      hookAuthorizationDigest,
+      status: hooks.length > 0 ? 'NEEDS_HOOK_AUTHORIZATION' : 'NEW',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+    if (hooks.length > 0 && options.hookAuthorizationDigest !== hookAuthorizationDigest) {
+      return publicState(state);
+    }
+  }
+
+  if (state.status === 'NEEDS_HOOK_AUTHORIZATION') {
+    const loaded = await deps.loadProjectConfig({ root });
+    const current = hookAuthority(loaded, state.targetVersion);
+    if (
+      loaded.configDigest !== state.configDigest
+      || current.digest !== state.hookAuthorizationDigest
+    ) {
+      state = {
+        ...state,
+        configDigest: loaded.configDigest,
+        hooks: current.hooks,
+        hookAuthorizationDigest: current.digest,
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+      if (verified.status === 'VERIFIED' && deps.updatePreviousPublicBaselines) {
+        try {
+          state.metadataUpdate = await deps.updatePreviousPublicBaselines({
+            root,
+            planPath: state.planPath,
+          });
+        } catch (error) {
+          state.metadataUpdate = {
+            status: 'FAILED',
+            error: error.message,
+          };
+        }
+        state.updatedAt = new Date().toISOString();
+        await writeJsonAtomic(statePath, state);
+      }
+      return publicState(state);
+    }
+    if (options.hookAuthorizationDigest !== state.hookAuthorizationDigest) {
+      if (options.hookAuthorizationDigest) {
+        throw new ReleaseError(
+          PLAN_DIGEST_MISMATCH,
+          'hook authorization digest does not match the current config, hooks and target version',
+        );
+      }
+      return publicState(state);
+    }
+    state.hookAuthorizedBy = options.actor ?? null;
+    state.status = 'NEW';
+    state.updatedAt = new Date().toISOString();
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'NEW') {
+    const loaded = await deps.loadProjectConfig({ root });
+    if (loaded.configDigest !== state.configDigest) {
+      const current = hookAuthority(loaded, state.targetVersion);
+      state = {
+        ...state,
+        configDigest: loaded.configDigest,
+        hooks: current.hooks,
+        hookAuthorizationDigest: current.digest,
+        status: current.hooks.length > 0 ? 'NEEDS_HOOK_AUTHORIZATION' : 'NEW',
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+      if (state.status === 'NEEDS_HOOK_AUTHORIZATION') return publicState(state);
+    }
+    const prepared = await deps.prepareRelease({
+      root,
+      version: state.targetVersion ?? undefined,
+      offline: false,
+      production: true,
+      hooksAuthorized: true,
+      verificationGatesAuthorized: false,
+      hookCache: true,
+    });
+    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;
+    }
+    state = {
+      ...state,
+      status: 'NEEDS_PLAN_APPROVAL',
+      planPath: prepared.planPath,
+      planDigest: prepared.planDigest,
+      evidenceDir: prepared.evidenceDir,
+      warnings: prepared.warnings,
+      ...(transportPreflight ? {
+        gitTransport: transportPreflight.transport,
+        gitTransportPreflight: transportPreflight.repositories,
+      } : {}),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'NEEDS_PLAN_APPROVAL') {
+    if (!options.planApprovalDigest) return publicState(state);
+    if (options.planApprovalDigest !== state.planDigest) {
+      throw new ReleaseError(PLAN_DIGEST_MISMATCH, 'ship plan approval digest does not match the frozen plan');
+    }
+    if (!options.actor) {
+      throw new ReleaseError(GATE_FAILED, 'ship plan approval requires --actor <person>');
+    }
+    const approval = await deps.approvePlan({
+      planPath: state.planPath,
+      expectedDigest: state.planDigest,
+      actor: options.actor,
+    });
+    state = {
+      ...state,
+      status: 'APPROVED',
+      approvalPath: approval.approvalPath,
+      verificationGatesAuthorized: true,
+      approvedBy: options.actor,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'APPROVED' || state.status === 'PUBLISHING') {
+    if (!options.adapterRegistry) {
+      throw new ReleaseError(GATE_FAILED, 'ship requires an adapter registry to publish');
+    }
+    state.status = 'PUBLISHING';
+    await writeJsonAtomic(statePath, state);
+    const published = await deps.publishRelease({
+      planPath: state.planPath,
+      approvalPath: state.approvalPath,
+      adapterRegistry: options.adapterRegistry,
+      root,
+      productionMode: true,
+      productionConfirmation: state.planDigest,
+    });
+    state = {
+      ...state,
+      status: published.status,
+      sourceRunPath: published.runPath,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'PARTIAL') {
+    const reconciled = await deps.reconcileRelease({
+      planPath: state.planPath,
+      sourceRunPath: state.sourceRunPath,
+      approvalPath: state.approvalPath,
+      adapterRegistry: options.adapterRegistry,
+      root,
+      productionConfirmation: state.planDigest,
+    });
+    state = {
+      ...state,
+      status: reconciled.status,
+      sourceRunPath: reconciled.runPath,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'PUBLISHED' || state.status === 'NEEDS_MANUAL_ATTESTATIONS') {
+    try {
+      const verified = await deps.verifyRelease({
+        planPath: state.planPath,
+        sourceRunPath: state.sourceRunPath,
+        adapterRegistry: options.adapterRegistry,
+        root,
+        verificationGatesAuthorized: state.verificationGatesAuthorized === true,
+      });
+      state = {
+        ...state,
+        status: verified.status,
+        verifyRunPath: verified.runPath,
+        requirements: undefined,
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    } catch (error) {
+      if (error?.code !== CONSUMER_VERIFICATION_DEFERRED) throw error;
+      state = {
+        ...state,
+        status: 'NEEDS_MANUAL_ATTESTATIONS',
+        requirements: error.details?.requirements ?? [],
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    }
+  }
+
+  return publicState(state);
+}

package/src/commands/verify.mjs

@@ -43,6 +43,7 @@ import {
   GATE_FAILED,
   CONFIG_MISSING,
   POST_PUBLISH_VERIFY_FAILED,
+  CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
@@ -67,6 +68,20 @@ import {
   buildDirectoryFileIndex,
   checkNpmEntryClosure,
 } from '../npm/npm-entry-closure.mjs';
+import {
+  KIMI_ATTESTATION_FILE,
+  KIMI_REQUIREMENT_FILE,
+  kimiAuthorityDir,
+  resolveBoundPlanDigest,
+  validateKimiAttestation,
+} from '../platforms/kimi.mjs';
+import {
+  CODEBUDDY_ATTESTATION_FILE,
+  CODEBUDDY_REQUIREMENT_FILE,
+  codebuddyAuthorityDir,
+  resolveCodeBuddyBoundPlanDigest,
+  validateCodeBuddyAttestation,
+} from '../platforms/codebuddy.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -120,6 +135,103 @@ function isValidDigest(digest) {
   return typeof digest === 'string' && /^[a-f0-9]{64}$/.test(digest);
 }
 
+/**
+ * Generate every manual consumer requirement before any expensive automatic
+ * consumer install starts. This turns a sequence of "install Kimi, rerun,
+ * then discover CodeBuddy" failures into one actionable response.
+ */
+async function collectMissingManualAttestations({
+  actions,
+  adapterRegistry,
+  plan,
+  root,
+  runDir,
+  clockFn,
+}) {
+  const manual = actions.filter((action) => (
+    action.type === 'kimi-marketplace-install'
+    || action.type === 'codebuddy-marketplace-install'
+  ));
+  if (manual.length === 0) return [];
+
+  const missing = [];
+  for (const action of manual) {
+    const adapterActionType = ADAPTER_ACTION_TYPE_MAP[action.type];
+    const adapter = adapterRegistry.getAdapter(adapterActionType);
+    // Tests and embedders may intentionally register a fully automatic
+    // adapter for these action types. Only the real platform adapter owns the
+    // interactive manual-install protocol and its stable authority files.
+    if (adapter.name !== 'plugin-marketplace') continue;
+    const context = {
+      externalWritesAuthorized: false,
+      isolatedConsumerWritesAuthorized: true,
+      plan,
+      baseline: plan.baseline,
+      root,
+      runDir,
+    };
+    const actionInput = { actionType: adapterActionType, ...action.parameters };
+    const preflight = await adapter.preflight(actionInput, context);
+    if (preflight.status !== 'PREFLIGHT_PASSED') {
+      throw new ReleaseError(
+        POST_PUBLISH_VERIFY_FAILED,
+        `manual consumer preflight did not pass for action "${action.id}": ${preflight.error}`,
+        { actionId: action.id, platform: action.type.split('-')[0] },
+      );
+    }
+    const executed = await adapter.execute(actionInput, context);
+    if (executed.status !== 'EXECUTED') {
+      throw new ReleaseError(
+        POST_PUBLISH_VERIFY_FAILED,
+        `cannot generate manual consumer requirement for action "${action.id}": ${executed.error}`,
+        { actionId: action.id, platform: action.type.split('-')[0] },
+      );
+    }
+
+    const isKimi = action.type === 'kimi-marketplace-install';
+    const planDigest = isKimi
+      ? resolveBoundPlanDigest(context)
+      : await resolveCodeBuddyBoundPlanDigest(context);
+    const authorityDir = isKimi
+      ? kimiAuthorityDir(context, planDigest, action.parameters.plugin)
+      : codebuddyAuthorityDir(context, planDigest, action.parameters.plugin);
+    const requirementPath = join(
+      authorityDir,
+      isKimi ? KIMI_REQUIREMENT_FILE : CODEBUDDY_REQUIREMENT_FILE,
+    );
+    const attestationPath = join(
+      authorityDir,
+      isKimi ? KIMI_ATTESTATION_FILE : CODEBUDDY_ATTESTATION_FILE,
+    );
+
+    let valid = false;
+    let reason = 'attestation file is missing';
+    try {
+      const attestation = JSON.parse(await readFile(attestationPath, 'utf8'));
+      const validation = isKimi
+        ? validateKimiAttestation(attestation, action.parameters, clockFn(), planDigest)
+        : validateCodeBuddyAttestation(attestation, action.parameters, clockFn(), planDigest);
+      valid = validation.valid;
+      reason = validation.error;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') reason = `attestation cannot be read: ${error.message}`;
+    }
+    if (!valid) {
+      missing.push({
+        actionId: action.id,
+        platform: isKimi ? 'kimi' : 'codebuddy',
+        plugin: action.parameters.plugin,
+        version: action.parameters.version,
+        planDigest,
+        requirementPath,
+        attestationPath,
+        reason,
+      });
+    }
+  }
+  return missing;
+}
+
 // ---------------------------------------------------------------------------
 // Smoke test
 // ---------------------------------------------------------------------------
@@ -1000,7 +1112,33 @@ export async function verifyRelease(options) {
       }
     }
 
-    for (const action of actions) {
+    const missingManualAttestations = await collectMissingManualAttestations({
+      actions,
+      adapterRegistry,
+      plan,
+      root,
+      runDir,
+      clockFn,
+    });
+    if (missingManualAttestations.length > 0) {
+      await evidence.append({
+        phase: 'verify',
+        step: 'manual-attestations',
+        status: 'needs-input',
+        requirements: missingManualAttestations,
+      });
+      throw new ReleaseError(
+        CONSUMER_VERIFICATION_DEFERRED,
+        `${missingManualAttestations.length} manual consumer attestation(s) are required`,
+        { requirements: missingManualAttestations },
+      );
+    }
+
+    // Every action is identity-bound and adapters receive read-only or
+    // per-action isolated consumer paths. Run independent checks concurrently;
+    // the evidence writer serializes append operations and result arrays are
+    // sorted afterwards for deterministic receipts.
+    const actionResults = await Promise.allSettled(actions.map(async (action) => {
       const adapterActionType = ADAPTER_ACTION_TYPE_MAP[action.type];
 
       // Skip meta-checkpoints
@@ -1011,7 +1149,7 @@ export async function verifyRelease(options) {
           status: 'SKIPPED',
           reason: 'meta-checkpoint',
         });
-        continue;
+        return;
       }
 
       let adapter;
@@ -1142,7 +1280,7 @@ export async function verifyRelease(options) {
               installationContractDigest: currentDigest,
             });
 
-            continue;
+            return;
           }
         }
 
@@ -1305,7 +1443,12 @@ export async function verifyRelease(options) {
           );
         }
       }
-    }
+    }));
+    adapterChecks.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    consumerVerificationReceipts.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    consumerGateResults.sort((a, b) => a.id.localeCompare(b.id));
+    const rejectedAction = actionResults.find((result) => result.status === 'rejected');
+    if (rejectedAction) throw rejectedAction.reason;
 
     await evidence.append({ phase: 'verify', step: 'adapter-verify', status: 'completed' });
 

package/src/core/git-transport.mjs

@@ -0,0 +1,93 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { ReleaseError, REMOTE_UNAVAILABLE, REMOTE_CONFLICT } from './errors.mjs';
+
+const execFile = promisify(execFileCb);
+
+function urls(repo, host) {
+  if (typeof repo !== 'string' || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) {
+    throw new ReleaseError(REMOTE_UNAVAILABLE, 'git transport preflight requires owner/name repositories');
+  }
+  const safeHost = host ?? 'github.com';
+  if (!/^[A-Za-z0-9.-]+$/.test(safeHost)) {
+    throw new ReleaseError(REMOTE_UNAVAILABLE, 'git transport preflight requires a safe GitHub hostname');
+  }
+  return {
+    https: `https://${safeHost}/${repo}.git`,
+    ssh: `git@${safeHost}:${repo}.git`,
+  };
+}
+
+function identity(stdout) {
+  const lines = String(stdout).trim().split('\n').filter(Boolean);
+  const head = lines.find((line) => /^[a-f0-9]{40,64}\s+HEAD$/.test(line.trim()));
+  const symref = lines.find((line) => line.startsWith('ref: '));
+  return `${symref ?? ''}\n${head ?? ''}`;
+}
+
+export async function preflightGitTransports(plan, options = {}) {
+  const exec = options.exec ?? ((command, args, execOptions) => execFile(command, args, execOptions));
+  const repositories = new Map();
+  for (const action of plan.externalActions ?? []) {
+    const repo = action.parameters?.repo;
+    if (!repo) continue;
+    const host = action.parameters?.githubHost ?? 'github.com';
+    repositories.set(`${host}/${repo}`, { repo, host });
+  }
+  const observations = [];
+  for (const { repo, host } of repositories.values()) {
+    const candidates = urls(repo, host);
+    const observation = { repo, host };
+    for (const transport of ['https', 'ssh']) {
+      try {
+        const { stdout } = await exec(
+          'git',
+          ['ls-remote', '--symref', candidates[transport], 'HEAD'],
+          { shell: false, encoding: 'utf8', timeout: 30_000 },
+        );
+        observation[transport] = {
+          status: 'available',
+          identity: identity(stdout),
+        };
+      } catch (error) {
+        observation[transport] = {
+          status: 'unavailable',
+          error: error.message,
+        };
+      }
+    }
+    if (observation.https.status === 'unavailable' && observation.ssh.status === 'unavailable') {
+      throw new ReleaseError(
+        REMOTE_UNAVAILABLE,
+        `neither HTTPS nor SSH can read ${repo}`,
+        { repository: repo, transports: observation },
+      );
+    }
+    if (
+      observation.https.status === 'available'
+      && observation.ssh.status === 'available'
+      && observation.https.identity !== observation.ssh.identity
+    ) {
+      throw new ReleaseError(
+        REMOTE_CONFLICT,
+        `HTTPS and SSH resolve different remote identities for ${repo}`,
+        { repository: repo },
+      );
+    }
+    observations.push(observation);
+  }
+  const transport = observations.some((entry) => entry.https.status === 'unavailable')
+    ? 'ssh'
+    : 'https';
+  if (
+    transport === 'ssh'
+    && observations.some((entry) => entry.ssh.status !== 'available')
+  ) {
+    throw new ReleaseError(
+      REMOTE_UNAVAILABLE,
+      'no single safe Git transport is available for every release repository',
+    );
+  }
+  return { transport, repositories: observations };
+}

package/src/core/public-surface.mjs

@@ -22,11 +22,37 @@ import { canonicalPublicPath } from '../snapshot/public-path.mjs';
 
 const ROOT_CONTROL_DIRECTORIES = Object.freeze(['.git', '.release-skill']);
 const UNSUPPORTED_GLOB_CHARACTERS = /[!()[\]{}]/u;
+export const PUBLIC_SURFACE_CONFIG_MISSING = 'PUBLIC_SURFACE_CONFIG_MISSING';
 
 function compareStrings(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+/**
+ * Return actionable, non-blocking adoption warnings for release units that
+ * have not enabled the expected public-surface gate.
+ *
+ * This helper never invents project policy or writes configuration. It gives
+ * assess and prepare one stable machine code and message while legacy projects
+ * remain releasable during the adoption window.
+ *
+ * @param {object} config
+ * @returns {ReadonlyArray<object>}
+ */
+export function collectExpectedPublicSurfaceAdoptionWarnings(config) {
+  return Object.freeze(
+    (config?.releaseUnits ?? [])
+      .filter((unit) => !unit?.expectedPublicSurface)
+      .map((unit) => Object.freeze({
+        code: PUBLIC_SURFACE_CONFIG_MISSING,
+        unitId: unit.id,
+        message:
+          `发布单元 "${unit.id}" 未配置 expectedPublicSurface；新增或漏配文件不会被分类门禁发现。` +
+          '请审阅项目发布边界后，在 .release-skill/project.yaml 中配置 expectedPublicSurface.scanRoots。',
+      })),
+  );
+}
+
 function toPosixPath(path) {
   return path.split(sep).join('/');
 }