release-skill 0.2.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/skills/release-help/SKILL.md

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -35,6 +35,14 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 日常发布快速路径：最多两个授权摘要，状态文件可恢复
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
+# 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> \
+  --acknowledge-hook-side-effects --json
+# Kimi/CodeBuddy 安装完成后记录人工事实，不手改 JSON
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
+  --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
 # 摘要确认后的本地写入（三项绑定缺一不可）

package/skills-src/release-help/SKILL.md

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -35,6 +35,14 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 日常发布快速路径：最多两个授权摘要，状态文件可恢复
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
+# 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> \
+  --acknowledge-hook-side-effects --json
+# Kimi/CodeBuddy 安装完成后记录人工事实，不手改 JSON
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
+  --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
 # 摘要确认后的本地写入（三项绑定缺一不可）

package/src/adapters/plugin-marketplace.mjs

@@ -476,7 +476,7 @@ async function resolveInstalledPayloadSubpath(snapshotDir, sourceEntries, action
   return extractDeclaredPluginSource(consumer, matches[0]);
 }
 
-async function verifyInstalledMarketplacePayload(action, context, installPath, consumer) {
+export async function verifyInstalledMarketplacePayload(action, context, installPath, consumer) {
   const sourcePath = await resolveFrozenPath(
     context.root,
     action.snapshotPath,

package/src/adapters/push-snapshot.mjs

@@ -32,7 +32,9 @@ export function githubRepositoryUrl(repo, host = 'github.com') {
   ) {
     throw new Error('githubHost must be a valid hostname');
   }
-  return `https://${host}/${repo}.git`;
+  return process.env.RELEASE_SKILL_GIT_TRANSPORT === 'ssh'
+    ? `git@${host}:${repo}.git`
+    : `https://${host}/${repo}.git`;
 }
 
 function validateOid(value, label) {

package/src/commands/attest.mjs

@@ -0,0 +1,195 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+
+import { SAFE_ID_RE, writeEvidenceAtomic } from '../adapters/contract.mjs';
+import { ReleaseError, GATE_FAILED, MISSING_PARAMETERS } from '../core/errors.mjs';
+
+const PLATFORM = Object.freeze({
+  kimi: {
+    directory: 'kimi-attestations',
+    requirementFile: 'release-skill-kimi-manual-install.json',
+  },
+  codebuddy: {
+    directory: 'codebuddy-attestations',
+    requirementFile: 'release-skill-codebuddy-manual-install.json',
+  },
+});
+
+async function validateInstalledConsumerClosure({
+  root,
+  platform,
+  requirement,
+  installPath,
+}) {
+  const planPath = resolve(root, '.release-skill', 'plans', `${requirement.planDigest}.json`);
+  const [
+    { validatePlan, computePlanDigest, assertImmutablePlanAuthority },
+    { createPluginMarketplaceAdapter, verifyInstalledMarketplacePayload },
+  ] = await Promise.all([
+    import('../core/plan.mjs'),
+    import('../adapters/plugin-marketplace.mjs'),
+  ]);
+  let plan;
+  try {
+    plan = JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot read the frozen plan required to verify the installed ${platform} payload: ${error.message}`,
+    );
+  }
+  validatePlan(plan);
+  assertImmutablePlanAuthority(planPath, plan);
+  if (computePlanDigest(plan) !== requirement.planDigest) {
+    throw new ReleaseError(GATE_FAILED, 'manual requirement planDigest does not match the frozen plan');
+  }
+  const actionType = `${platform}-marketplace-install`;
+  const action = (plan.externalActions ?? []).find((candidate) => (
+    candidate.type === actionType
+    && candidate.parameters?.plugin === requirement.plugin
+    && candidate.parameters?.version === requirement.version
+  ));
+  if (!action) {
+    throw new ReleaseError(GATE_FAILED, `frozen plan has no matching ${platform} install action`);
+  }
+  const adapter = createPluginMarketplaceAdapter();
+  const context = {
+    externalWritesAuthorized: false,
+    isolatedConsumerWritesAuthorized: false,
+    plan,
+    baseline: plan.baseline,
+    root,
+  };
+  const actionInput = { actionType, ...action.parameters };
+  const preflight = await adapter.preflight(actionInput, context);
+  if (preflight.status !== 'PREFLIGHT_PASSED') {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `${platform} installed-payload preflight failed: ${preflight.error}`,
+    );
+  }
+  const binding = await verifyInstalledMarketplacePayload(
+    actionInput,
+    context,
+    installPath,
+    platform,
+  );
+  return {
+    payloadDigest: action.parameters.manifestDigest,
+    manifestDigest: binding.manifestDigest,
+    extraInstalledPaths: binding.extraInstalledPaths ?? [],
+  };
+}
+
+/**
+ * Record the human fact needed by an interactive-only consumer. Identity
+ * fields come exclusively from the generated requirement; the operator only
+ * supplies the result, actor and optional observed install facts.
+ */
+export async function recordManualAttestation(options = {}, injected = {}) {
+  const {
+    root = process.cwd(),
+    platform,
+    plugin,
+    actor,
+    result,
+    installPath,
+    installChannel,
+    note,
+    clock = () => new Date().toISOString(),
+  } = options;
+  const descriptor = PLATFORM[platform];
+  if (!descriptor || !SAFE_ID_RE.test(plugin ?? '')) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      'attest requires --platform <kimi|codebuddy> and a safe --plugin <id>',
+    );
+  }
+  if (typeof actor !== 'string' || actor.trim() === '') {
+    throw new ReleaseError(MISSING_PARAMETERS, 'attest requires --actor <person>');
+  }
+  if (result !== 'passed' && result !== 'failed') {
+    throw new ReleaseError(MISSING_PARAMETERS, 'attest requires --result <passed|failed>');
+  }
+
+  const authorityDir = resolve(root, '.release-skill', descriptor.directory, plugin);
+  const requirementPath = join(authorityDir, descriptor.requirementFile);
+  let requirement;
+  try {
+    requirement = JSON.parse(await readFile(requirementPath, 'utf8'));
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot read generated ${platform} requirement: ${error.message}`,
+      { platform, plugin, requirementPath },
+    );
+  }
+  if (
+    requirement.platform !== platform
+    || requirement.plugin !== plugin
+    || typeof requirement.version !== 'string'
+    || !/^[a-f0-9]{64}$/.test(requirement.planDigest ?? '')
+    || typeof requirement.attestationFile !== 'string'
+  ) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `generated ${platform} requirement has invalid identity fields`,
+      { platform, plugin, requirementPath },
+    );
+  }
+  if (result === 'passed' && (typeof installPath !== 'string' || installPath === '')) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      `${platform} passed attestation requires --install-path for installed payload verification`,
+    );
+  }
+  const needsInstallChannel = Object.hasOwn(requirement.attestationTemplate ?? {}, 'installChannel');
+  if (
+    result === 'passed'
+    && needsInstallChannel
+    && installChannel !== 'desktop'
+    && installChannel !== 'cli'
+  ) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      `${platform} passed attestation requires --install-channel <desktop|cli>`,
+    );
+  }
+
+  const installBinding = result === 'passed'
+    ? await (injected.validateInstalledConsumerClosure ?? validateInstalledConsumerClosure)({
+        root,
+        platform,
+        requirement,
+        installPath,
+      })
+    : null;
+  const receipt = {
+    platform,
+    version: requirement.version,
+    planDigest: requirement.planDigest,
+    result,
+    actor: actor.trim(),
+    confirmedAt: clock(),
+    ...(installPath ? { installPath } : {}),
+    ...(installChannel ? { installChannel } : {}),
+    ...(note ? { note } : {}),
+    ...(installBinding ? {
+      payloadDigest: installBinding.payloadDigest,
+      installedClosureVerified: true,
+      extraInstalledPaths: installBinding.extraInstalledPaths,
+    } : {}),
+  };
+  const attestationPath = join(authorityDir, requirement.attestationFile);
+  await writeEvidenceAtomic(attestationPath, receipt);
+  return {
+    command: 'attest',
+    status: 'RECORDED',
+    platform,
+    plugin,
+    version: requirement.version,
+    planDigest: requirement.planDigest,
+    requirementPath,
+    attestationPath,
+  };
+}

package/src/commands/hooks.mjs

@@ -0,0 +1,46 @@
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { loadProjectConfig } from '../core/config.mjs';
+import { createEvidenceWriter } from '../core/evidence.mjs';
+import { runDeclaredHooks } from './prepare.mjs';
+import { ReleaseError, GATE_FAILED } from '../core/errors.mjs';
+
+/**
+ * Run the declared development gates and populate the exact same content-bound
+ * hook receipts consumed by prepare. A later ship/prepare reuses only
+ * cacheable hooks whose declared input closure is byte-identical.
+ */
+export async function validateDeclaredHooks(options = {}) {
+  const {
+    root = process.cwd(),
+    hooksAuthorized,
+    hookCache = true,
+    runDir = resolve(root, '.release-skill', 'runs', `hooks-${Date.now()}`),
+  } = options;
+  if (hooksAuthorized !== true) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'hooks validate executes declared project commands; pass --acknowledge-hook-side-effects',
+    );
+  }
+  const { config, configDigest } = await loadProjectConfig({ root });
+  await mkdir(runDir, { recursive: true });
+  const evidence = createEvidenceWriter({
+    runDir,
+    command: 'hooks-validate',
+    clock: () => new Date().toISOString(),
+  });
+  const startedAt = new Date().toISOString();
+  await runDeclaredHooks(config, root, evidence, undefined, { hookCache });
+  return {
+    command: 'hooks validate',
+    status: 'PASSED',
+    configDigest,
+    hooks: Object.keys(config.hooks ?? {}).sort(),
+    cacheEnabled: hookCache,
+    evidenceDir: runDir,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+  };
+}

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);
+}