release-skill 0.1.1 → 0.1.3

package/src/commands/verify.mjs

@@ -13,7 +13,7 @@
  */
 
 import { readFile, writeFile, mkdtemp, rm, mkdir, lstat, realpath } from 'node:fs/promises';
-import { join, relative, isAbsolute, resolve } from 'node:path';
+import { dirname, join, relative, isAbsolute, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -30,6 +30,7 @@ import {
   writeRunAtomic,
   computeRunDigest,
   resolveDefaultRunDir,
+  createProductionRunDir,
 } from '../core/run.mjs';
 import {
   assertImmutableApprovalAuthority,
@@ -48,6 +49,7 @@ import {
   registryTokenKey,
   resolveNpmRegistryAuthToken,
 } from '../adapters/npm.mjs';
+import { runConsumerVerificationGates } from '../core/verification-gates.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -60,6 +62,7 @@ import {
 const ADAPTER_ACTION_TYPE_MAP = {
   'push-commit': 'git-push',
   'push-snapshot': 'push-snapshot',
+  'set-default-branch': 'set-default-branch',
   'create-tag': 'git-tag',
   'npm-publish': 'npm-publish',
   'github-release': 'github-release',
@@ -170,10 +173,12 @@ export async function runSmokeTest(plan, root, options = {}) {
         passed: true,
         skipped: true,
         details: { message: 'No npm distributions in plan; smoke test skipped' },
+        gateResults: [],
       };
     }
 
     const results = [];
+    const gateResults = [];
 
     for (const { package: pkgName, registry, targetVersion, unitId, smokeBin, smokeArgs, smokeExpectedJson } of npmDistributions) {
       const packageAtVersion = `${pkgName}@${targetVersion}`;
@@ -237,6 +242,17 @@ export async function runSmokeTest(plan, root, options = {}) {
         };
       }
 
+      const pkgRoot = join(installDir, 'node_modules', pkgName);
+      gateResults.push(...await runConsumerVerificationGates({
+        plan,
+        unitId,
+        distribution: 'npm',
+        executionRoot: pkgRoot,
+        evidence: options.evidence,
+        env: options.gateEnv ?? process.env,
+        fixedEnv: { HOME: installDir },
+      }));
+
       // If smokeBin is not configured, install + name/version check is sufficient
       if (!smokeBin) {
         results.push({
@@ -277,7 +293,6 @@ export async function runSmokeTest(plan, root, options = {}) {
       }
 
       // Verify bin path does not escape the installed package root
-      const pkgRoot = join(installDir, 'node_modules', pkgName);
       const binPath = resolve(pkgRoot, binRelative);
       const relBin = relative(pkgRoot, binPath);
       const sep = process.platform === 'win32' ? '\\' : '/';
@@ -321,7 +336,17 @@ export async function runSmokeTest(plan, root, options = {}) {
       const cliArgs = smokeArgs.length > 0 ? smokeArgs : [];
       let binResult;
       try {
-        binResult = await npmExec.runBin(binPath, cliArgs);
+        binResult = await npmExec.runBin(binPath, cliArgs, {
+          cwd: pkgRoot,
+          env: {
+            HOME: installDir,
+            TMPDIR: installDir,
+            TEMP: installDir,
+            TMP: installDir,
+            PATH: dirname(process.execPath),
+            CI: '1',
+          },
+        });
       } catch (binErr) {
         return {
           passed: false,
@@ -403,6 +428,7 @@ export async function runSmokeTest(plan, root, options = {}) {
         distributions: results,
         count: results.length,
       },
+      gateResults,
     };
   } finally {
     await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
@@ -451,10 +477,14 @@ const defaultNpmExecutor = {
       return { success: true };
     } catch (err) {
       return { success: false, error: err.message };
+    } finally {
+      await rm(userConfig, { force: true }).catch(() => {});
     }
   },
-  async runBin(binPath, args = []) {
+  async runBin(binPath, args = [], options = {}) {
     return execFile(process.execPath, [binPath, ...args], {
+      cwd: options.cwd,
+      env: options.env,
       shell: false,
       encoding: 'utf8',
       timeout: 30_000,
@@ -491,6 +521,8 @@ export async function verifyRelease(options) {
     runDir: runDirOpt,
     clock: clockOpt,
     npmExecutor,
+    verificationGatesAuthorized,
+    gateEnv,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -504,10 +536,39 @@ export async function verifyRelease(options) {
     );
   }
 
+  // Load and validate the plan before creating any evidence directory. A
+  // production plan grants authority only to a fresh direct child of its
+  // sibling .release-skill/runs directory.
+  let planRaw;
+  try {
+    planRaw = await readFile(planPath, 'utf8');
+  } catch (err) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot read release plan: ${err.message}`,
+      { planPath, cause: err.code },
+    );
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(planRaw);
+  } catch (err) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `release plan is not valid JSON: ${err.message}`,
+      { planPath },
+    );
+  }
+  validatePlan(plan);
+
   // --- Set up directories ---
   const runId = `verify-${Date.now()}`;
-  const runDir = runDirOpt ?? resolveDefaultRunDir(planPath, 'verify', runId);
-  await mkdir(runDir, { recursive: true });
+  const requestedRunDir = runDirOpt ?? resolveDefaultRunDir(planPath, 'verify', runId);
+  const runDir = plan.production
+    ? await createProductionRunDir(requestedRunDir, planPath)
+    : requestedRunDir;
+  if (!plan.production) await mkdir(runDir, { recursive: true });
 
   const evidence = createEvidenceWriter({ runDir, command: 'verify', clock: clockFn });
 
@@ -517,30 +578,23 @@ export async function verifyRelease(options) {
     // =======================================================================
     await evidence.append({ phase: 'verify', step: 'plan-load', status: 'started' });
 
-    let planRaw;
-    try {
-      planRaw = await readFile(planPath, 'utf8');
-    } catch (err) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `cannot read release plan: ${err.message}`,
-        { planPath, cause: err.code },
-      );
-    }
-
-    let plan;
-    try {
-      plan = JSON.parse(planRaw);
-    } catch (err) {
+    const consumerGates = (plan.verificationGates ?? []).filter((gate) => gate.phase === 'consumer-verify');
+    const configuredSmokeBins = (plan.units ?? []).flatMap((unit) => (
+      (unit.distributions ?? [])
+        .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,
-        `release plan is not valid JSON: ${err.message}`,
-        { planPath },
+        `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 },
       );
     }
 
-    validatePlan(plan);
-
     await evidence.append({ phase: 'verify', step: 'plan-load', status: 'passed' });
 
     // =======================================================================
@@ -659,6 +713,7 @@ export async function verifyRelease(options) {
     await evidence.append({ phase: 'verify', step: 'adapter-verify', status: 'started' });
 
     const adapterChecks = [];
+    const consumerGateResults = [];
     const actions = plan.externalActions ?? [];
     const MARKETPLACE_TYPES = new Set([
       'claude-marketplace-install',
@@ -770,6 +825,28 @@ export async function verifyRelease(options) {
             { actionId: action.id, observation: verifyResult.observation },
           );
         }
+
+        const distribution = action.type === 'claude-marketplace-install'
+          ? 'claude-plugin'
+          : 'codex-plugin';
+        const installPath = verifyResult.observation?.installPath;
+        consumerGateResults.push(...await runConsumerVerificationGates({
+          plan,
+          unitId: action.unitId,
+          distribution,
+          executionRoot: installPath,
+          evidence,
+          env: gateEnv ?? process.env,
+          fixedEnv: action.type === 'claude-marketplace-install'
+            ? {
+                HOME: resolve(runDir, 'consumers', `claude-${action.parameters.plugin}`),
+                CLAUDE_CONFIG_DIR: resolve(runDir, 'consumers', `claude-${action.parameters.plugin}`, '.claude'),
+              }
+            : {
+                HOME: resolve(runDir, 'consumers', `codex-${action.parameters.plugin}`),
+                CODEX_HOME: resolve(runDir, 'consumers', `codex-${action.parameters.plugin}`),
+              },
+        }));
       } else {
         // --- Non-marketplace: read-only adapter.verify() ---
         const context = {
@@ -825,7 +902,12 @@ export async function verifyRelease(options) {
 
     let smokeTest;
     try {
-      smokeTest = await runSmokeTest(plan, root, { npmExecutor, baseDir: runDir });
+      smokeTest = await runSmokeTest(plan, root, {
+        npmExecutor,
+        baseDir: runDir,
+        evidence,
+        gateEnv: gateEnv ?? process.env,
+      });
     } catch (err) {
       smokeTest = { passed: false, details: { error: err.message } };
     }
@@ -845,6 +927,17 @@ export async function verifyRelease(options) {
       );
     }
 
+    consumerGateResults.push(...(smokeTest.gateResults ?? []));
+    const expectedGateIds = consumerGates.map((gate) => gate.id).sort();
+    const observedGateIds = consumerGateResults.map((result) => result.id).sort();
+    if (JSON.stringify(expectedGateIds) !== JSON.stringify(observedGateIds)) {
+      throw new ReleaseError(
+        POST_PUBLISH_VERIFY_FAILED,
+        'consumer verification gate execution set does not match the frozen plan',
+        { expectedGateIds, observedGateIds },
+      );
+    }
+
     // =======================================================================
     // All verifications passed — write verify run
     // =======================================================================
@@ -875,6 +968,7 @@ export async function verifyRelease(options) {
           status: check?.status === 'SKIPPED' ? 'skipped' : 'succeeded',
         };
       }),
+      gateResults: consumerGateResults,
       startedAt: clockFn(),
       finishedAt: clockFn(),
     };
@@ -888,6 +982,7 @@ export async function verifyRelease(options) {
       runDigest: persistedVerifyRun.runDigest,
       adapterCheckCount: adapterChecks.length,
       smokeTestPassed: true,
+      consumerGateCount: consumerGateResults.length,
       completedAt: clockFn(),
     });
 
@@ -896,6 +991,7 @@ export async function verifyRelease(options) {
       status: VERIFIED,
       adapterChecks,
       smokeTest,
+      gateResults: consumerGateResults,
     };
   } catch (err) {
     await evidence.append({

package/src/core/config.mjs

@@ -437,6 +437,40 @@ export async function loadProjectConfig({ root, configPath } = {}) {
     }
   }
 
+  // Verification gates are deliberately cross-referenced here instead of
+  // inferred at execution time. A gate must name one existing unit and, for
+  // consumer verification, one distribution that the unit actually ships.
+  const unitsById = new Map(config.releaseUnits.map((unit) => [unit.id, unit]));
+  const gateIds = new Set();
+  for (const gate of config.verificationGates ?? []) {
+    if (gateIds.has(gate.id)) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `duplicate verification gate id: "${gate.id}"`,
+        { gateId: gate.id },
+      );
+    }
+    gateIds.add(gate.id);
+    const unit = unitsById.get(gate.scope.unit);
+    if (!unit) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `verification gate "${gate.id}" references unknown unit "${gate.scope.unit}"`,
+        { gateId: gate.id, unitId: gate.scope.unit },
+      );
+    }
+    if (
+      gate.phase === 'consumer-verify' &&
+      !(unit.distributions ?? []).some((distribution) => distribution.type === gate.scope.distribution)
+    ) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `verification gate "${gate.id}" references undeclared distribution "${gate.scope.distribution}"`,
+        { gateId: gate.id, unitId: gate.scope.unit, distribution: gate.scope.distribution },
+      );
+    }
+  }
+
   // --- Compute deterministic digest ---
   const configDigest = sha256Hex(canonicalJson(config));
 

package/src/core/errors.mjs

@@ -33,6 +33,8 @@ const EXIT_CODE_MAP = Object.freeze({
   SENSITIVE_CONFLICT: 37,
   TRANSACTION_INCOMPLETE: 38,
   SAFE_WRITE_UNAVAILABLE: 39,
+  SETUP_DIGEST_MISMATCH: 40,
+  CONFIG_EXISTS: 41,
 });
 
 // ---- Error code constants ----
@@ -67,6 +69,8 @@ export const PLAN_STALE = 'PLAN_STALE';
 export const SENSITIVE_CONFLICT = 'SENSITIVE_CONFLICT';
 export const TRANSACTION_INCOMPLETE = 'TRANSACTION_INCOMPLETE';
 export const SAFE_WRITE_UNAVAILABLE = 'SAFE_WRITE_UNAVAILABLE';
+export const SETUP_DIGEST_MISMATCH = 'SETUP_DIGEST_MISMATCH';
+export const CONFIG_EXISTS = 'CONFIG_EXISTS';
 
 /**
  * Typed error for release-skill operations.

package/src/core/plan.mjs

@@ -132,6 +132,31 @@ export function validatePlan(plan) {
       { validationErrors: errors },
     );
   }
+
+  const unitsById = new Map((plan.units ?? []).map((unit) => [unit.id, unit]));
+  const gateIds = new Set();
+  for (const gate of plan.verificationGates ?? []) {
+    if (gateIds.has(gate.id)) {
+      throw new ReleaseError(GATE_FAILED, `duplicate verification gate id: "${gate.id}"`);
+    }
+    gateIds.add(gate.id);
+    const unit = unitsById.get(gate.scope.unit);
+    if (!unit) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `verification gate "${gate.id}" references unknown unit "${gate.scope.unit}"`,
+      );
+    }
+    if (
+      gate.phase === 'consumer-verify' &&
+      !(unit.distributions ?? []).some((distribution) => distribution.type === gate.scope.distribution)
+    ) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `verification gate "${gate.id}" references undeclared distribution "${gate.scope.distribution}"`,
+      );
+    }
+  }
 }
 
 /**
@@ -260,6 +285,7 @@ const EXPECTED_ADAPTER = {
   'npm-publish': 'npm',
   'claude-marketplace-install': 'plugin-marketplace',
   'codex-marketplace-install': 'plugin-marketplace',
+  'set-default-branch': 'git-github',
 };
 
 /** Required action types for every unit. */
@@ -317,6 +343,7 @@ export function validatePlanActionCompleteness(plan) {
     const production = plan.production?.mode === 'github-npm-v1';
     const frozen = unit.frozenSnapshot;
     const productionConfig = unit.productionConfig ?? {};
+    const branchStrategy = productionConfig.branchStrategy;
     const expectedTag = tagTemplate
       ? tagTemplate.replace('{version}', targetVersion ?? '')
       : null;
@@ -346,6 +373,9 @@ export function validatePlanActionCompleteness(plan) {
       failures.push(`unit "${unitId}" is missing frozenSnapshot for production publish`);
     }
     if (production && frozen) {
+      if (!['create-release-branch', 'advance-existing-branch', 'initialize-default-branch'].includes(branchStrategy)) {
+        failures.push(`unit "${unitId}" productionConfig.branchStrategy is missing or invalid`);
+      }
       const expectedBranch = (productionConfig.branchTemplate ?? 'release/{tag}')
         .replaceAll('{tag}', expectedTag ?? '')
         .replaceAll('{version}', targetVersion ?? '')
@@ -353,6 +383,32 @@ export function validatePlanActionCompleteness(plan) {
       if (frozen.branch !== expectedBranch) {
         failures.push(`unit "${unitId}" frozen branch does not match productionConfig.branchTemplate`);
       }
+      if (frozen.branchStrategy !== branchStrategy) {
+        failures.push(`unit "${unitId}" frozenSnapshot.branchStrategy does not match productionConfig.branchStrategy`);
+      }
+      if (['advance-existing-branch', 'initialize-default-branch'].includes(branchStrategy)) {
+        if (unit.previousPublicBaseline?.mode !== 'bound') {
+          failures.push(`unit "${unitId}" branch strategy "${branchStrategy}" requires a bound previous public baseline`);
+        }
+        if (!frozen.parentCommit || frozen.parentCommit !== unit.previousPublicBaseline?.commit) {
+          failures.push(`unit "${unitId}" frozenSnapshot.parentCommit does not match previous public baseline commit`);
+        }
+      } else if (frozen.parentCommit) {
+        failures.push(`unit "${unitId}" create-release-branch must not freeze a parentCommit`);
+      }
+      if (
+        branchStrategy === 'advance-existing-branch' &&
+        unit.previousPublicBaseline?.ref !== `refs/heads/${expectedBranch}`
+      ) {
+        failures.push(`unit "${unitId}" advance-existing-branch baseline ref does not match the target branch`);
+      }
+      if (branchStrategy === 'initialize-default-branch') {
+        if (productionConfig.setAsDefaultBranch !== true || !productionConfig.expectedCurrentDefaultBranch) {
+          failures.push(`unit "${unitId}" initialize-default-branch requires explicit default branch settings`);
+        }
+      } else if (productionConfig.setAsDefaultBranch === true) {
+        failures.push(`unit "${unitId}" setAsDefaultBranch is only valid for initialize-default-branch`);
+      }
     }
 
     // Required actions for this unit (always required)
@@ -411,10 +467,19 @@ export function validatePlanActionCompleteness(plan) {
             _checkRequired(action, 'parameters.branch', action.parameters?.branch, frozen?.branch, unitId, failures);
             _checkRequired(action, 'parameters.commit', action.parameters?.commit, frozen?.commit, unitId, failures);
             _checkRequired(action, 'parameters.tree', action.parameters?.tree, frozen?.tree, unitId, failures);
+            _checkRequired(action, 'parameters.branchStrategy', action.parameters?.branchStrategy, branchStrategy, unitId, failures);
             _checkRequired(action, 'parameters.githubHost', action.parameters?.githubHost, productionConfig.githubHost ?? 'github.com', unitId, failures);
             _checkRequired(action, 'expected.commit', action.expected?.commit, frozen?.commit, unitId, failures);
             _checkRequired(action, 'expected.tree', action.expected?.tree, frozen?.tree, unitId, failures);
             _checkRequired(action, 'expected.manifestDigest', action.expected?.manifestDigest, frozen?.manifestDigest, unitId, failures);
+            if (['advance-existing-branch', 'initialize-default-branch'].includes(branchStrategy)) {
+              _checkRequired(action, 'parameters.parentCommit', action.parameters?.parentCommit, frozen?.parentCommit, unitId, failures);
+            }
+            if (branchStrategy === 'advance-existing-branch') {
+              _checkRequired(action, 'parameters.expectedBaselineCommit', action.parameters?.expectedBaselineCommit, frozen?.parentCommit, unitId, failures);
+            } else if (action.parameters?.expectedBaselineCommit !== undefined) {
+              failures.push(`unit "${unitId}", action "${action.id}": unexpected parameters.expectedBaselineCommit`);
+            }
           } else {
             _checkRequired(action, 'expected.tag', action.expected?.tag, expectedTag, unitId, failures);
           }
@@ -692,6 +757,64 @@ export function validatePlanActionCompleteness(plan) {
         }
       }
     }
+
+    // set-default-branch: only required when productionConfig.setAsDefaultBranch is true
+    if (branchStrategy === 'initialize-default-branch') {
+      const oldBranch = productionConfig.expectedCurrentDefaultBranch;
+      const newBranch = frozen?.branch;
+      expectedCount++;
+      const expectedActionId = `set-default-branch-${unitId}`;
+      const branchActions = actions.filter(
+        (a) => a.unitId === unitId && a.type === 'set-default-branch',
+      );
+
+      if (branchActions.length === 0) {
+        failures.push(
+          `unit "${unitId}": productionConfig.setAsDefaultBranch is true but "set-default-branch" action is missing`,
+        );
+      } else if (branchActions.length > 1) {
+        failures.push(
+          `unit "${unitId}": duplicate set-default-branch actions (${branchActions.length} found, expected 1)`,
+        );
+      } else {
+        const action = branchActions[0];
+
+        if (action.id !== expectedActionId) {
+          failures.push(
+            `unit "${unitId}", action "${action.id}": id is "${action.id}", expected "${expectedActionId}"`,
+          );
+        }
+        if (action.unitId !== unitId) {
+          failures.push(
+            `unit "${unitId}", action "${action.id}": unitId is "${action.unitId}", expected "${unitId}"`,
+          );
+        }
+        if (action.adapter !== 'git-github') {
+          failures.push(
+            `unit "${unitId}", action "${action.id}": adapter is "${action.adapter}", expected "git-github"`,
+          );
+        }
+        if (action.status !== 'PENDING') {
+          failures.push(
+            `unit "${unitId}", action "${action.id}": status is "${action.status ?? '(missing)'}", expected "PENDING"`,
+          );
+        }
+
+        // Required parameters
+        _checkRequired(action, 'parameters.repo', action.parameters?.repo, publicRepo, unitId, failures);
+        _checkRequired(action, 'parameters.oldBranch', action.parameters?.oldBranch, oldBranch, unitId, failures);
+        _checkRequired(action, 'parameters.newBranch', action.parameters?.newBranch, newBranch, unitId, failures);
+        _checkRequired(action, 'parameters.expectedNewBranchCommit', action.parameters?.expectedNewBranchCommit, frozen?.commit, unitId, failures);
+        _checkRequired(action, 'parameters.githubHost', action.parameters?.githubHost, productionConfig.githubHost ?? 'github.com', unitId, failures);
+
+        // Required expected
+        _checkRequired(action, 'expected.defaultBranch', action.expected?.defaultBranch, newBranch, unitId, failures);
+        _checkRequired(action, 'expected.newBranchCommit', action.expected?.newBranchCommit, frozen?.commit, unitId, failures);
+        if (Object.keys(action.expected ?? {}).some((key) => !['defaultBranch', 'newBranchCommit'].includes(key))) {
+          failures.push(`unit "${unitId}", action "${action.id}": expected may only contain defaultBranch and newBranchCommit`);
+        }
+      }
+    }
   }
 
   // --- Strict count equality: actual must exactly match expected ---

package/src/core/previous-public-baseline.mjs

@@ -88,7 +88,7 @@ export async function observePreviousPublicBaseline({ baseline, observeFn, evide
  *   Evidence collector for audit trail.
  * @returns {Promise<{ consistent: true } | { consistent: false, error: string, detail?: Record<string, unknown> }>}
  */
-export async function reObservePreviousPublicBaseline({ baseline, observeFn, evidence }) {
+export async function reObservePreviousPublicBaseline({ baseline, observeFn, evidence, acceptedSuccessorCommits = [] }) {
   if (!baseline || typeof baseline !== 'object') {
     return { consistent: true };
   }
@@ -114,6 +114,26 @@ export async function reObservePreviousPublicBaseline({ baseline, observeFn, evi
       return { consistent: true };
     }
 
+    if (
+      result.status === 'drifted' &&
+      typeof result.actual === 'string' &&
+      acceptedSuccessorCommits.includes(result.actual)
+    ) {
+      evidence?.append({
+        phase: 're-observe-previous-public-baseline',
+        status: 'consistent-planned-successor',
+        repo,
+        ref,
+        baselineCommit: commit,
+        observedCommit: result.actual,
+      });
+      return {
+        consistent: true,
+        observed: { ...result },
+        state: 'planned-successor',
+      };
+    }
+
     // Drifted or unknown -- return soft failure for reconcile to handle
     return {
       consistent: false,