release-skill 0.3.0 → 0.4.0

package/src/commands/prepare.mjs

@@ -1809,41 +1809,16 @@ export async function prepareRelease(options) {
         cwd: hook.cwd ?? '.',
       }));
 
+    // Hook and gate authorization: the command invocation itself authorizes
+    // execution of configured commands. Old acknowledgement parameters
+    // (--acknowledge-hook-side-effects, --acknowledge-gate-side-effects) are
+    // accepted as no-effect compatibility inputs but are not required.
     if (declaredHooks.length > 0) {
-      await evidence.append({
-        phase: 'hook-authorization',
-        status: 'started',
-        hookCount: declaredHooks.length,
-        hooks: declaredHooks.map((h) => `${h.name}: ${h.executable} ${h.args.join(' ')}`),
-      });
-
-      if (hooksAuthorized !== true) {
-        const hookList = declaredHooks
-          .map((h) => `  - ${h.name}: executable="${h.executable}", args=[${h.args.join(', ')}], cwd="${h.cwd}"`)
-          .join('\n');
-
-        await evidence.append({
-          phase: 'hook-authorization',
-          status: 'denied',
-          reason: 'hooks not explicitly authorized',
-        });
-
-        throw new ReleaseError(
-          GATE_FAILED,
-          `project declares ${declaredHooks.length} hook(s) that will be executed as arbitrary local processes.\n` +
-          `These hooks are NOT sandboxed — they may write to the filesystem outside the project, ` +
-          `access local credentials, or make network calls.\n` +
-          `The following hooks will run:\n${hookList}\n\n` +
-          `To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (API). ` +
-          `Authorization means you accept hook side-effect risks; it does NOT make hooks safe.`,
-          { hookNames: declaredHooks.map((h) => h.name), hookCount: declaredHooks.length },
-        );
-      }
-
       await evidence.append({
         phase: 'hook-authorization',
         status: 'authorized',
         hookCount: declaredHooks.length,
+        hooks: declaredHooks.map((h) => `${h.name}: ${h.executable} ${h.args.join(' ')}`),
       });
     }
 
@@ -1851,7 +1826,7 @@ export async function prepareRelease(options) {
     if (declaredVerificationGates.length > 0) {
       await evidence.append({
         phase: 'verification-gate-authorization',
-        status: 'started',
+        status: 'authorized',
         gateCount: declaredVerificationGates.length,
         gates: declaredVerificationGates.map((gate) => ({
           id: gate.id,
@@ -1863,25 +1838,6 @@ export async function prepareRelease(options) {
           cwd: gate.cwd,
         })),
       });
-      if (verificationGatesAuthorized !== true) {
-        await evidence.append({
-          phase: 'verification-gate-authorization',
-          status: 'denied',
-          gateCount: declaredVerificationGates.length,
-        });
-        throw new ReleaseError(
-          GATE_FAILED,
-          `project declares ${declaredVerificationGates.length} verification gate(s). ` +
-          'They run local project commands without a network sandbox. ' +
-          'To proceed, pass --acknowledge-gate-side-effects (CLI) or verificationGatesAuthorized=true (API).',
-          { gateIds: declaredVerificationGates.map((gate) => gate.id) },
-        );
-      }
-      await evidence.append({
-        phase: 'verification-gate-authorization',
-        status: 'authorized',
-        gateCount: declaredVerificationGates.length,
-      });
     }
 
     // --- Step 3: Run declared hooks ---
@@ -2848,6 +2804,12 @@ export async function prepareRelease(options) {
     // Compute overall snapshot digest
     const overallSnapshotDigest = sha256Hex(snapshotDigests.join(':'));
 
+    // Detect human consumer platforms (Kimi/CodeBuddy) in the plan.
+    // When present, new plans mark them as non-blocking manual follow-up tasks.
+    const hasHumanConsumerActions = externalActions.some(
+      (a) => a.type === 'kimi-marketplace-install' || a.type === 'codebuddy-marketplace-install',
+    );
+
     const plan = {
       planVersion: 2,
       status: 'PREPARED',
@@ -2870,6 +2832,7 @@ export async function prepareRelease(options) {
       },
       verificationGates: config.verificationGates ?? [],
       snapshotDigest: overallSnapshotDigest,
+      ...(hasHumanConsumerActions ? { humanConsumersStrategy: 'manualFollowUps' } : {}),
       ...(production ? {
         production: {
           mode: 'github-npm-v1',

package/src/commands/publish.mjs

@@ -465,7 +465,6 @@ export async function publishRelease(options) {
     clock: clockOpt,
     captureBaselineFn,
     productionMode = false,
-    productionConfirmation,
     observePreviousPublicBaselineFn,
     observeRetrySleep,
   } = options ?? {};
@@ -544,13 +543,6 @@ export async function publishRelease(options) {
       if (!plan.production.assetRoot || plan.production.assetRoot === '.') {
         throw new ReleaseError(GATE_FAILED, 'production plan requires a dedicated assetRoot');
       }
-      if (!productionConfirmation || productionConfirmation !== actualDigest) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'production confirmation must exactly match the current plan digest',
-          { planDigest: actualDigest },
-        );
-      }
     }
 
     // =======================================================================

package/src/commands/reconcile.mjs

@@ -91,7 +91,6 @@ function defaultClock() {
  * @param {string} options.planPath - Absolute path to the frozen release plan.
  * @param {string} options.sourceRunPath - Absolute path to the source run (publish or prior reconcile).
  * @param {string} [options.approvalPath] - Path to the approval record (required if any action needs retry).
- * @param {string} [options.productionConfirmation] - Exact plan digest required before retrying production writes.
  * @param {Object} options.adapterRegistry - Adapter registry for action execution.
  * @param {string} [options.runDir] - Evidence directory. Defaults to `<planDir>/runs/reconcile-<ts>`.
  * @param {string} [options.root] - Project root for baseline capture.
@@ -114,7 +113,6 @@ export async function reconcileRelease(options) {
     root = process.cwd(),
     clock: clockOpt,
     captureBaselineFn,
-    productionConfirmation,
     observePreviousPublicBaselineFn,
     observeRetrySleep,
   } = options ?? {};
@@ -332,29 +330,6 @@ export async function reconcileRelease(options) {
       );
     }
 
-    // A production retry authority must be confirmed before any remote
-    // observation can influence whether a permanent write will be retried.
-    // Isolated marketplace consumer checks remain outside this requirement.
-    const planActionsById = new Map(
-      (plan.externalActions ?? []).map((action) => [action.id, action]),
-    );
-    const hasNonMarketplaceRetryCandidate = sourceRun.checkpoints.some((checkpoint) => {
-      if (checkpoint.status === 'succeeded') return false;
-      const action = planActionsById.get(checkpoint.actionId);
-      return action && !isMarketplaceAction(action.type);
-    });
-    if (
-      plan.production?.mode === 'github-npm-v1' &&
-      hasNonMarketplaceRetryCandidate &&
-      productionConfirmation !== actualDigest
-    ) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        'production reconcile confirmation must exactly match the current plan digest before retry',
-        { planDigest: actualDigest },
-      );
-    }
-
     await evidence.append({
       phase: 'safety-gate',
       gate: 'source-run-load',
@@ -918,7 +893,7 @@ export async function reconcileRelease(options) {
     // --- Phase 2: Validate approval and global preflight before retrying ---
     //
     // Marketplace recovery is deferred to phase 4 and does NOT require
-    // approval or productionConfirmation; marketplace actions are isolated
+    // approval; marketplace actions are isolated
     // consumer checks, not permanent remote writes. Only non-marketplace
     // retries require approval.
     // =======================================================================
@@ -926,17 +901,8 @@ export async function reconcileRelease(options) {
     const nonMarketplaceRetries = actionsToRetry.filter((a) => !isMarketplaceAction(a.type));
 
     if (nonMarketplaceRetries.length > 0) {
-      // Non-marketplace retries require approval and productionConfirmation
-      if (
-        plan.production?.mode === 'github-npm-v1' &&
-        productionConfirmation !== actualDigest
-      ) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'production reconcile confirmation must exactly match the current plan digest before retry',
-          { planDigest: actualDigest, actionsToRetry: nonMarketplaceRetries.map((action) => action.id) },
-        );
-      }
+      // Non-marketplace retries require a current immutable approval. The
+      // approval already binds the exact plan digest and action set.
       if (!approval) {
         throw new ReleaseError(
           GATE_FAILED,

package/src/commands/ship.mjs

@@ -90,8 +90,7 @@ function publicState(state) {
     status: state.status,
     statePath: state.statePath,
     targetVersion: state.targetVersion,
-    ...(state.hookAuthorizationDigest ? {
-      hookAuthorizationDigest: state.hookAuthorizationDigest,
+    ...(state.hooks && state.hooks.length > 0 ? {
       hooks: state.hooks,
     } : {}),
     ...(state.planPath ? {
@@ -100,34 +99,52 @@ function publicState(state) {
       evidenceDir: state.evidenceDir,
       warnings: state.warnings ?? [],
     } : {}),
+    ...(state.approvalSummary ? { approvalSummary: state.approvalSummary } : {}),
     ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
     ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
     ...(state.requirements ? { requirements: state.requirements } : {}),
+    ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
-    verificationGateAuthorizationIncludedInPlanApproval:
-      state.status !== 'NEEDS_HOOK_AUTHORIZATION',
-    postVerifyMetadataUpdateIncludedInPlanApproval:
-      state.status !== 'NEEDS_HOOK_AUTHORIZATION',
+    verificationGateAuthorizationIncludedInPlanApproval: true,
+    postVerifyMetadataUpdateIncludedInPlanApproval: true,
   };
 }
 
-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,
-    })),
-  };
+/**
+ * Build a human-readable approval summary from the frozen plan.
+ * Lists each unit's version and every external action's id/type/unitId.
+ * Returns an empty summary when the plan file is not yet available (e.g., in tests).
+ *
+ * @param {string} planPath - Path to the frozen release plan.
+ * @returns {Promise<object>} The approval summary.
+ */
+async function buildApprovalSummary(planPath) {
+  try {
+    const plan = JSON.parse(await readFile(planPath, 'utf8'));
+    const units = (plan.units ?? []).map((unit) => ({
+      id: unit.id,
+      targetVersion: unit.targetVersion ?? unit.version,
+    }));
+    const actions = (plan.externalActions ?? []).map((action) => ({
+      id: action.id,
+      type: action.type,
+      unitId: action.unitId,
+    }));
+    return { units, actions };
+  } catch {
+    return { units: [], actions: [] };
+  }
 }
 
 /**
  * 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.
+ *
+ * New flow (v0.4+): ship directly runs configured hooks and verification gates
+ * without a separate hook authorization step. The only human gate is plan
+ * approval. Kimi/CodeBuddy installations are non-blocking manual follow-up
+ * tasks when the plan declares humanConsumersStrategy: 'manualFollowUps'.
  */
 export async function advanceShip(options = {}, injected = {}) {
   const root = resolve(options.root ?? process.cwd());
@@ -144,69 +161,25 @@ export async function advanceShip(options = {}, injected = {}) {
 
   if (!state) {
     const loaded = await deps.loadProjectConfig({ root });
-    const authority = hookAuthority(loaded, options.targetVersion);
-    const hooks = authority.hooks;
-    const hookAuthorizationDigest = authority.digest;
+    const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
     state = {
-      schemaVersion: 1,
+      schemaVersion: 2,
       root,
       statePath,
       targetVersion: options.targetVersion ?? null,
       configDigest: loaded.configDigest,
       hooks,
-      hookAuthorizationDigest,
-      status: hooks.length > 0 ? 'NEEDS_HOOK_AUTHORIZATION' : 'NEW',
+      status: 'NEW',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     };
     await writeJsonAtomic(statePath, state);
-    if (hooks.length > 0 && options.hookAuthorizationDigest !== hookAuthorizationDigest) {
-      return publicState(state);
-    }
   }
 
+  // Backward compatibility: auto-recover from legacy NEEDS_HOOK_AUTHORIZATION
+  // state. Old state files may have this status from the previous two-gate
+  // flow; the new flow runs hooks directly so we advance to NEW immediately.
   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);
@@ -215,17 +188,15 @@ export async function advanceShip(options = {}, injected = {}) {
   if (state.status === 'NEW') {
     const loaded = await deps.loadProjectConfig({ root });
     if (loaded.configDigest !== state.configDigest) {
-      const current = hookAuthority(loaded, state.targetVersion);
+      const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
       state = {
         ...state,
         configDigest: loaded.configDigest,
-        hooks: current.hooks,
-        hookAuthorizationDigest: current.digest,
-        status: current.hooks.length > 0 ? 'NEEDS_HOOK_AUTHORIZATION' : 'NEW',
+        hooks,
+        status: 'NEW',
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);
-      if (state.status === 'NEEDS_HOOK_AUTHORIZATION') return publicState(state);
     }
     const prepared = await deps.prepareRelease({
       root,
@@ -233,7 +204,7 @@ export async function advanceShip(options = {}, injected = {}) {
       offline: false,
       production: true,
       hooksAuthorized: true,
-      verificationGatesAuthorized: false,
+      verificationGatesAuthorized: true,
       hookCache: true,
     });
     let transportPreflight = null;
@@ -242,6 +213,7 @@ export async function advanceShip(options = {}, injected = {}) {
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }
+    const approvalSummary = await buildApprovalSummary(prepared.planPath);
     state = {
       ...state,
       status: 'NEEDS_PLAN_APPROVAL',
@@ -249,6 +221,7 @@ export async function advanceShip(options = {}, injected = {}) {
       planDigest: prepared.planDigest,
       evidenceDir: prepared.evidenceDir,
       warnings: prepared.warnings,
+      approvalSummary,
       ...(transportPreflight ? {
         gitTransport: transportPreflight.transport,
         gitTransportPreflight: transportPreflight.repositories,
@@ -259,8 +232,14 @@ export async function advanceShip(options = {}, injected = {}) {
   }
 
   if (state.status === 'NEEDS_PLAN_APPROVAL') {
-    if (!options.planApprovalDigest) return publicState(state);
-    if (options.planApprovalDigest !== state.planDigest) {
+    // Boolean --approve: auto-use the stored planDigest (no user digest input needed).
+    // Legacy --approve-plan <digest>: explicit digest must match.
+    const approveRequested = options.approve === true
+      || (typeof options.planApprovalDigest === 'string' && options.planApprovalDigest.length > 0);
+    if (!approveRequested) return publicState(state);
+    if (options.approve === true) {
+      // Boolean approve: no digest input; the stored planDigest is authoritative.
+    } else if (options.planApprovalDigest !== state.planDigest) {
       throw new ReleaseError(PLAN_DIGEST_MISMATCH, 'ship plan approval digest does not match the frozen plan');
     }
     if (!options.actor) {
@@ -294,7 +273,6 @@ export async function advanceShip(options = {}, injected = {}) {
       adapterRegistry: options.adapterRegistry,
       root,
       productionMode: true,
-      productionConfirmation: state.planDigest,
     });
     state = {
       ...state,
@@ -312,7 +290,6 @@ export async function advanceShip(options = {}, injected = {}) {
       approvalPath: state.approvalPath,
       adapterRegistry: options.adapterRegistry,
       root,
-      productionConfirmation: state.planDigest,
     });
     state = {
       ...state,
@@ -337,6 +314,7 @@ export async function advanceShip(options = {}, injected = {}) {
         status: verified.status,
         verifyRunPath: verified.runPath,
         requirements: undefined,
+        manualFollowUps: verified.manualFollowUps ?? undefined,
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);

package/src/commands/verify.mjs

@@ -755,7 +755,7 @@ export async function verifyRelease(options) {
     runDir: runDirOpt,
     clock: clockOpt,
     npmExecutor,
-    verificationGatesAuthorized,
+    verificationGatesAuthorized: _verificationGatesAuthorized,
     gateEnv,
     previousVerifyRun,
   } = options ?? {};
@@ -826,16 +826,9 @@ export async function verifyRelease(options) {
         .filter((distribution) => distribution.type === 'npm' && distribution.smokeBin)
         .map((distribution) => ({ unitId: unit.id, smokeBin: distribution.smokeBin }))
     ));
-    if ((consumerGates.length > 0 || configuredSmokeBins.length > 0) && verificationGatesAuthorized !== true) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `plan declares ${consumerGates.length} consumer verification gate(s) and ` +
-        `${configuredSmokeBins.length} npm CLI smoke process(es). ` +
-        'They execute installed project code without an OS or network sandbox. ' +
-        'To proceed, pass --acknowledge-gate-side-effects (CLI) or verificationGatesAuthorized=true (API).',
-        { gateIds: consumerGates.map((gate) => gate.id), configuredSmokeBins },
-      );
-    }
+    // The command invocation itself authorizes execution of configured
+    // verification gates and smoke processes. Old --acknowledge-gate-side-effects
+    // is accepted as a no-effect compatibility input.
 
     await evidence.append({ phase: 'verify', step: 'plan-load', status: 'passed' });
 
@@ -1112,14 +1105,21 @@ export async function verifyRelease(options) {
       }
     }
 
-    const missingManualAttestations = await collectMissingManualAttestations({
-      actions,
-      adapterRegistry,
-      plan,
-      root,
-      runDir,
-      clockFn,
-    });
+    // When the plan declares humanConsumersStrategy: 'manualFollowUps',
+    // Kimi/CodeBuddy installations are non-blocking post-release manual tasks.
+    // Skip attestation collection and blocking for these platforms.
+    const isHumanConsumerFollowUp = plan.humanConsumersStrategy === 'manualFollowUps';
+
+    const missingManualAttestations = isHumanConsumerFollowUp
+      ? []
+      : await collectMissingManualAttestations({
+          actions,
+          adapterRegistry,
+          plan,
+          root,
+          runDir,
+          clockFn,
+        });
     if (missingManualAttestations.length > 0) {
       await evidence.append({
         phase: 'verify',
@@ -1134,6 +1134,9 @@ export async function verifyRelease(options) {
       );
     }
 
+    // Collect non-blocking manual follow-up tasks for human consumer platforms
+    const manualFollowUps = [];
+
     // 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
@@ -1165,6 +1168,38 @@ export async function verifyRelease(options) {
       }
 
       if (isMarketplaceAction(action.type)) {
+        // When humanConsumersStrategy is 'manualFollowUps', Kimi/CodeBuddy
+        // installations are non-blocking manual follow-up tasks. Skip adapter
+        // processing and collect them as manualFollowUps.
+        const isHumanConsumerPlatform = action.type === 'kimi-marketplace-install'
+          || action.type === 'codebuddy-marketplace-install';
+        if (isHumanConsumerFollowUp && isHumanConsumerPlatform) {
+          const platform = action.type === 'kimi-marketplace-install' ? 'kimi' : 'codebuddy';
+          manualFollowUps.push({
+            actionId: action.id,
+            platform,
+            plugin: action.parameters?.plugin,
+            version: action.parameters?.version,
+            unitId: action.unitId,
+            verifiedBySystem: false,
+            reason: 'human consumer platform — installation is a manual post-release task; not verified by system',
+          });
+          adapterChecks.push({
+            actionId: action.id,
+            actionType: action.type,
+            status: 'SKIPPED',
+            reason: 'manual-follow-up',
+          });
+          await evidence.append({
+            phase: 'verify-marketplace',
+            actionId: action.id,
+            actionType: action.type,
+            status: 'SKIPPED',
+            reason: 'manual-follow-up',
+          });
+          return;
+        }
+
         // --- Marketplace: fresh consumer verification in verify's own runDir ---
         // Context: isolatedConsumerWritesAuthorized allows writing to verify's
         // runDir/consumers/ directory; externalWritesAuthorized stays false.
@@ -1637,6 +1672,7 @@ export async function verifyRelease(options) {
       gateResults: consumerGateResults,
       consumerVerificationReceipts,
       skillResourceClosureReceipts,
+      ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
       startedAt: clockFn(),
       finishedAt: clockFn(),
     };
@@ -1660,6 +1696,7 @@ export async function verifyRelease(options) {
       adapterChecks,
       smokeTest,
       gateResults: consumerGateResults,
+      ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
     };
   } catch (err) {
     await evidence.append({

package/src/core/skill-resource-closure.mjs

@@ -275,10 +275,16 @@ export function evaluateConsumerSkillResourceClosureReceipts(plan, receipts) {
     'kimi-plugin',
     'codebuddy-plugin',
   ]);
+  // When plan declares humanConsumersStrategy: 'manualFollowUps', Kimi/CodeBuddy
+  // are non-blocking manual follow-up tasks and are not verified by the system.
+  // Exclude them from the expected receipt set.
+  const humanConsumerTypes = plan.humanConsumersStrategy === 'manualFollowUps'
+    ? new Set(['kimi-plugin', 'codebuddy-plugin'])
+    : new Set();
   const expectedKeys = [];
   for (const unit of plan.units ?? []) {
     for (const distribution of unit.distributions ?? []) {
-      if (supported.has(distribution.type)) {
+      if (supported.has(distribution.type) && !humanConsumerTypes.has(distribution.type)) {
         expectedKeys.push(`${unit.id}:${distribution.type}`);
       }
     }