release-skill 0.5.0 → 0.6.0

package/src/commands/ship.mjs

@@ -60,6 +60,7 @@ async function defaultDependencies() {
     publishModule,
     reconcileModule,
     verifyModule,
+    distributeModule,
     transportModule,
     metadataModule,
   ] = await Promise.all([
@@ -69,6 +70,7 @@ async function defaultDependencies() {
     import('./publish.mjs'),
     import('./reconcile.mjs'),
     import('./verify.mjs'),
+    import('./distribute.mjs'),
     import('../core/git-transport.mjs'),
     import('../core/release-metadata.mjs'),
   ]);
@@ -79,6 +81,7 @@ async function defaultDependencies() {
     publishRelease: publishModule.publishRelease,
     reconcileRelease: reconcileModule.reconcileRelease,
     verifyRelease: verifyModule.verifyRelease,
+    distributeRelease: distributeModule.distributeRelease,
     preflightGitTransports: transportModule.preflightGitTransports,
     updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
   };
@@ -102,6 +105,7 @@ function publicState(state) {
     ...(state.approvalSummary ? { approvalSummary: state.approvalSummary } : {}),
     ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
     ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
+    ...(state.distributeRunPath ? { distributeRunPath: state.distributeRunPath } : {}),
     ...(state.requirements ? { requirements: state.requirements } : {}),
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
@@ -301,10 +305,49 @@ export async function advanceShip(options = {}, injected = {}) {
   }
 
   if (state.status === 'PUBLISHED' || state.status === 'NEEDS_MANUAL_ATTESTATIONS') {
+    // Step 1: Check if postPublish requires distribution
+    const plan = JSON.parse(await readFile(state.planPath, 'utf8'));
+    const needsDistribution = plan.postPublish && plan.postPublish.targets && plan.postPublish.targets.length > 0;
+    
+    if (needsDistribution && deps.distributeRelease) {
+      state.status = 'DISTRIBUTING';
+      await writeJsonAtomic(statePath, state);
+      
+      try {
+        const distributed = await deps.distributeRelease({
+          sourceRunPath: state.sourceRunPath,
+          approvalPath: state.approvalPath,
+          adapterRegistry: options.adapterRegistry,
+          root,
+          dryRun: false,
+          planPath: state.planPath,
+        });
+        
+        state = {
+          ...state,
+          status: distributed.status,
+          distributeRunPath: distributed.distributeRunPath,
+          updatedAt: new Date().toISOString(),
+        };
+        await writeJsonAtomic(statePath, state);
+        
+        if (!distributed.checkpoints || distributed.checkpoints.some((cp) => cp.status === 'failed')) {
+          state.status = 'PARTIAL';
+          await writeJsonAtomic(statePath, state);
+          return publicState(state);
+        }
+      } catch (error) {
+        state.status = 'PARTIAL';
+        await writeJsonAtomic(statePath, state);
+        throw error;
+      }
+    }
+    
+    // Step 2: Verify (this will check for distributed run if distribution was required)
     try {
       const verified = await deps.verifyRelease({
         planPath: state.planPath,
-        sourceRunPath: state.sourceRunPath,
+        sourceRunPath: needsDistribution ? state.distributeRunPath : state.sourceRunPath,
         adapterRegistry: options.adapterRegistry,
         root,
         verificationGatesAuthorized: state.verificationGatesAuthorized === true,
@@ -315,6 +358,7 @@ export async function advanceShip(options = {}, injected = {}) {
         verifyRunPath: verified.runPath,
         requirements: undefined,
         manualFollowUps: verified.manualFollowUps ?? undefined,
+        baselineAdvance: verified.baselineAdvance ?? undefined,
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);

package/src/commands/verify.mjs

@@ -46,6 +46,13 @@ import {
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
+import {
+  deriveBaselineAdvances,
+  applyBaselineAdvances,
+  isWorktreeFileClean,
+  commitBaselineAdvance,
+} from '../core/baseline-advance.mjs';
+import { loadProjectConfig } from '../core/config.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
 import { resolveUnitScopedPath } from '../snapshot/public-path.mjs';
 import {
@@ -725,6 +732,95 @@ const defaultNpmExecutor = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Distribute run discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover sibling distribute runs from the same planDigest within .release-skill/runs.
+ * Only accept verified, non-symbolic-link directories matching distribute-* prefix.
+ */
+async function discoverDistributeRuns({ planPath, plan }) {
+  const planDir = dirname(planPath);
+  const releaseDir = basename(planDir) === 'plans' ? dirname(planDir) : planDir;
+  const runsDir = resolve(releaseDir, 'runs');
+  
+  try {
+    const runsDirStat = await lstat(runsDir);
+    if (runsDirStat.isSymbolicLink()) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'runs directory is a symbolic link; authority identity compromised',
+        { runsDir },
+      );
+    }
+    if (!runsDirStat.isDirectory()) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'runs path is not a directory',
+        { runsDir },
+      );
+    }
+    
+    const runsDirReal = realpathSync(runsDir);
+    const authorityDirReal = realpathSync(releaseDir);
+    if (!runsDirReal.startsWith(authorityDirReal + '/') && runsDirReal !== authorityDirReal) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'runs directory is not a real child of the plan authority directory',
+        { runsDir, runsDirReal, authorityDirReal },
+      );
+    }
+  } catch (err) {
+    if (err instanceof ReleaseError) throw err;
+    // runs directory doesn't exist — this is okay for optional distribution
+    return null;
+  }
+  
+  const candidates = [];
+  const entries = await readdir(runsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.name.startsWith('distribute-')) continue;
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'distribute-* candidate is a symbolic link or not a directory; authority identity compromised',
+        { entry: entry.name, runsDir },
+      );
+    }
+    const candidateDir = resolve(runsDir, entry.name);
+    const candidateStat = await lstat(candidateDir).catch(() => null);
+    if (!candidateStat || candidateStat.isSymbolicLink()) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'distribute-* candidate is a symbolic link; authority identity compromised',
+        { candidateDir, runsDir },
+      );
+    }
+    const candidateReal = realpathSync(candidateDir);
+    if (!candidateReal.startsWith(runsDir + '/') && candidateReal !== runsDir) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'distribute-* candidate real path is not contained in authority runs directory',
+        { candidateDir, candidateReal, runsDir },
+      );
+    }
+    const candidatePath = resolve(candidateDir, 'release-run.json');
+    try {
+      const candidate = await loadRun(candidatePath, { requireDigest: true });
+      if (candidate.command !== 'distribute') continue;
+      if (!candidate.planDigest) continue;
+      if (candidate.planDigest !== plan.digest) continue;
+      candidates.push(candidate);
+    } catch {
+      // Skip invalid candidates silently
+      continue;
+    }
+  }
+  
+  return candidates;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -758,6 +854,8 @@ export async function verifyRelease(options) {
     verificationGatesAuthorized: _verificationGatesAuthorized,
     gateEnv,
     previousVerifyRun,
+    execFn,
+    configPath: configPathOpt,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -866,6 +964,32 @@ export async function verifyRelease(options) {
       );
     }
 
+    // =======================================================================
+    // Step 2b: Check for postPublish distribution requirement
+    // =======================================================================
+    if (plan.postPublish && plan.postPublish.targets && plan.postPublish.targets.length > 0) {
+      await evidence.append({ phase: 'verify', step: 'distribute-run-discovery', status: 'started' });
+      
+      const distributeCandidates = await discoverDistributeRuns({ planPath, plan });
+      const distRunPath = (distributeCandidates ?? []).find((c) => c.status === 'DISTRIBUTED')?.runPath || null;
+      
+      await evidence.append({
+        phase: 'verify',
+        step: 'distribute-run-discovery',
+        status: 'checked',
+        foundCandidate: !!distRunPath,
+        distributeRunPath: distRunPath,
+      });
+      
+      if (!distRunPath) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `distribution required by plan.postPublish but no DISTRIBUTED run found; run release-skill distribute --plan ${planPath} --root ${root}`,
+          { requiredDistribution: true, evidenceEvent: 'distribute-run-missing' },
+        );
+      }
+    }
+
     if (plan.production) {
       if (!sourceRun.approvalPath || !sourceRun.approvalDigest) {
         throw new ReleaseError(
@@ -1678,6 +1802,57 @@ export async function verifyRelease(options) {
     };
     const persistedVerifyRun = await writeRunAtomic(verifyRunPath, verifyRunState);
 
+    // =======================================================================
+    // Baseline advance: move per-unit previousPublicBaseline to the commit
+    // that was just verified. Local bookkeeping only — no remote writes.
+    // Best-effort: a failure here must never demote VERIFIED, and the config
+    // is only auto-committed when the file was clean before the write, so a
+    // dirty worktree leaves the decision to the human.
+    // =======================================================================
+    let baselineAdvance = null;
+    const baselineAdvances = deriveBaselineAdvances(plan);
+    if (baselineAdvances.length > 0) {
+      try {
+        const configAbs = configPathOpt
+          ? (isAbsolute(configPathOpt) ? configPathOpt : join(root, configPathOpt))
+          : join(root, '.release-skill/project.yaml');
+        const cleanBefore = await isWorktreeFileClean({ root, filePath: configAbs, execFn });
+        const applyResult = await applyBaselineAdvances({
+          configPath: configAbs,
+          advances: baselineAdvances,
+          validateFn: async () => { await loadProjectConfig({ root, configPath: configAbs }); },
+        });
+        baselineAdvance = { ...applyResult, committed: false };
+        if (applyResult.changed && cleanBefore) {
+          const versionLabel = (plan.units ?? [])
+            .map((u) => `${u.id} v${u.targetVersion}`)
+            .join(', ');
+          await commitBaselineAdvance({
+            root,
+            filePath: configAbs,
+            message: `chore: advance previousPublicBaseline to published ${versionLabel}`,
+            execFn,
+          });
+          baselineAdvance.committed = true;
+        }
+        await evidence.append({
+          phase: 'verify',
+          step: 'baseline-advance',
+          status: applyResult.changed ? 'advanced' : 'already-current',
+          updatedUnits: applyResult.updatedUnits,
+          committed: baselineAdvance.committed,
+        });
+      } catch (err) {
+        baselineAdvance = { failed: true, error: err.message };
+        await evidence.append({
+          phase: 'verify',
+          step: 'baseline-advance',
+          status: 'failed',
+          error: { code: err.code, message: err.message },
+        });
+      }
+    }
+
     await evidence.finish({
       status: VERIFIED,
       planPath,
@@ -1697,6 +1872,7 @@ export async function verifyRelease(options) {
       smokeTest,
       gateResults: consumerGateResults,
       ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
+      ...(baselineAdvance ? { baselineAdvance } : {}),
     };
   } catch (err) {
     await evidence.append({

package/src/core/baseline-advance.mjs

@@ -0,0 +1,185 @@
+/**
+ * Baseline advance: after a release reaches VERIFIED, the project config's
+ * per-unit `previousPublicBaseline` must be advanced from the previous
+ * public commit to the commit that was just published. Doing this by hand
+ * is the most error-prone step in the release loop, so it is derived from
+ * the frozen plan (never recomputed from workspace state) and written back
+ * into `.release-skill/project.yaml` with comment preservation.
+ *
+ * Fail-safe by construction: any unit whose plan data is missing or
+ * malformed is skipped rather than guessed.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import YAML from 'yaml';
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+const execFileAsync = promisify(execFileCb);
+
+function defaultExec(command, args, options = {}) {
+  return execFileAsync(command, args, { shell: false, encoding: 'utf8', timeout: 120_000, ...options });
+}
+
+const SHA_RE = /^[a-f0-9]{40}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+
+/**
+ * Derive the baseline advances that a VERIFIED plan implies.
+ *
+ * For each unit with a `mode: bound` previousPublicBaseline, the published
+ * commit/tree/manifestDigest come from the unit's frozen push-snapshot
+ * action — the same values that were pushed to the public repo.
+ *
+ * @param {{ units?: Array<Record<string, unknown>>, externalActions?: Array<Record<string, unknown>> }} plan
+ *   The frozen release plan.
+ * @returns {Array<{ unitId: string, repo: string, previousCommit: string, commit: string, tree: string, manifestDigest: string }>}
+ *   One advance per unit that is behind its published commit. Units already
+ *   at the published commit (idempotent re-runs) produce no advance.
+ */
+export function deriveBaselineAdvances(plan) {
+  const advances = [];
+  for (const unit of plan?.units ?? []) {
+    const baseline = unit?.previousPublicBaseline;
+    if (!baseline || baseline.mode !== 'bound') continue;
+
+    const action = (plan?.externalActions ?? []).find((a) => (
+      a?.type === 'push-snapshot'
+      && a?.parameters?.publicRepo === unit.publicRepo
+    ));
+    const { commit, tree, manifestDigest } = action?.parameters ?? {};
+
+    if (!SHA_RE.test(commit ?? '') || !SHA_RE.test(tree ?? '') || !DIGEST_RE.test(manifestDigest ?? '')) {
+      continue;
+    }
+    if (baseline.commit === commit) continue;
+
+    advances.push({
+      unitId: unit.id,
+      repo: baseline.repo,
+      previousCommit: baseline.commit,
+      commit,
+      tree,
+      manifestDigest,
+    });
+  }
+  return advances;
+}
+
+/**
+ * Apply derived advances to the project config file, preserving comments and
+ * unrelated content by editing the YAML AST in place. When a `validateFn` is
+ * provided, the rewritten file is re-validated and the original content is
+ * restored if validation fails (the advance must never corrupt the config).
+ *
+ * @param {{ configPath: string, advances: Array<Record<string, unknown>>, validateFn?: (configPath: string) => Promise<void> }} opts
+ * @returns {Promise<{ changed: boolean, updatedUnits: string[] }>}
+ */
+export async function applyBaselineAdvances({ configPath, advances, validateFn }) {
+  if (!advances || advances.length === 0) {
+    return { changed: false, updatedUnits: [] };
+  }
+
+  let content;
+  try {
+    content = await readFile(configPath, 'utf8');
+  } catch (err) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `baseline advance cannot read project config: ${err.message}`,
+      { configPath, cause: err.code },
+    );
+  }
+
+  const doc = YAML.parseDocument(content);
+  const releaseUnits = doc.get('releaseUnits', true);
+  if (!YAML.isSeq(releaseUnits)) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'baseline advance requires a releaseUnits sequence in the project config',
+      { configPath },
+    );
+  }
+
+  const updatedUnits = [];
+  for (const advance of advances) {
+    const unitNode = releaseUnits.items.find((item) => (
+      YAML.isMap(item) && item.get('id') === advance.unitId
+    ));
+    if (!unitNode) continue;
+
+    let baselineNode = unitNode.get('previousPublicBaseline', true);
+    if (!YAML.isMap(baselineNode)) {
+      baselineNode = new YAML.YAMLMap();
+      unitNode.set('previousPublicBaseline', baselineNode);
+    }
+
+    let changed = false;
+    const setField = (key, value) => {
+      if (baselineNode.get(key) !== value) {
+        baselineNode.set(key, value);
+        changed = true;
+      }
+    };
+    setField('commit', advance.commit);
+    setField('tree', advance.tree);
+    setField('manifestDigest', advance.manifestDigest);
+
+    if (changed) updatedUnits.push(advance.unitId);
+  }
+
+  if (updatedUnits.length === 0) {
+    return { changed: false, updatedUnits: [] };
+  }
+
+  const next = doc.toString();
+  await writeFile(configPath, next, 'utf8');
+
+  if (typeof validateFn === 'function') {
+    try {
+      await validateFn(configPath);
+    } catch (err) {
+      // Restore the original content so a bad advance never corrupts config.
+      await writeFile(configPath, content, 'utf8');
+      throw new ReleaseError(
+        GATE_FAILED,
+        `baseline advance reverted: rewritten config failed validation: ${err.message}`,
+        { configPath, cause: err.message },
+      );
+    }
+  }
+
+  return { changed: true, updatedUnits };
+}
+
+/**
+ * Report whether a single file is clean in the git worktree (no staged or
+ * unstaged changes). Fails safe to `false` on any git error so that a
+ * non-repository or a broken git never authorizes an automatic commit.
+ *
+ * @param {{ root: string, filePath: string, execFn?: Function }} opts
+ * @returns {Promise<boolean>}
+ */
+export async function isWorktreeFileClean({ root, filePath, execFn }) {
+  const exec = typeof execFn === 'function' ? execFn : defaultExec;
+  try {
+    const { stdout } = await exec('git', ['status', '--porcelain', '--', filePath], { cwd: root });
+    return stdout.trim() === '';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Stage and commit only the config file. The caller is responsible for
+ * checking `isWorktreeFileClean` *before* writing so that this commit never
+ * sweeps in unrelated in-flight work.
+ *
+ * @param {{ root: string, filePath: string, message: string, execFn?: Function }} opts
+ * @returns {Promise<void>}
+ */
+export async function commitBaselineAdvance({ root, filePath, message, execFn }) {
+  const exec = typeof execFn === 'function' ? execFn : defaultExec;
+  await exec('git', ['add', '--', filePath], { cwd: root });
+  await exec('git', ['commit', '-m', message, '--', filePath], { cwd: root });
+}

package/src/core/baseline.mjs

@@ -146,7 +146,17 @@ function parseStatusPorcelainZ(statusOut) {
  * @returns {Promise<string>} Hex-encoded SHA-256 digest.
  */
 async function computeWorkspaceDigest(root) {
-  const opts = { cwd: root, shell: false, encoding: 'utf8' };
+  // 64 MiB upper bound (official fix 39c631f): `git ls-files -s -z` emits one
+  // line per tracked file and routinely exceeds Node's default 1 MiB
+  // execFile maxBuffer on large repositories (measured 8494 tracked files →
+  // 1,519,151 B stdout). Large enough for any realistic baseline, small
+  // enough to fail closed before exhausting memory.
+  const opts = {
+    cwd: root,
+    shell: false,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  };
 
   const [
     { stdout: stagedOut },

package/src/core/checkpoints.mjs

@@ -189,3 +189,28 @@ export function isRemoteWriteAction(actionType) {
 export function isMarketplaceAction(actionType) {
   return MARKETPLACE_ACTION_TYPES.has(actionType);
 }
+
+/**
+ * Post-publish distribution (distribute saga) checkpoint action types.
+ *
+ * These checkpoints are recorded in distribute run records; they never
+ * appear in plan externalActions and intentionally stay OUT of
+ * CHECKPOINT_ORDER / TIER_TABLE: the distribute saga schedules targets
+ * strictly sequentially in dependsOn order (shared payload + sha backfill),
+ * never through the publish/reconcile tier scheduler. If a distribute type
+ * ever leaked into a publish plan, groupActionsByTier would fail closed on
+ * it as an unknown type — exactly the desired behaviour.
+ */
+export const DISTRIBUTE_ACTION_TYPES = new Set([
+  'distribute-probe',
+  'distribute-mirror',
+]);
+
+/**
+ * 判断动作类型是否为发布后分发（distribute）动作。
+ * @param {string} actionType - 运行检查点中的动作类型
+ * @returns {boolean}
+ */
+export function isDistributeAction(actionType) {
+  return DISTRIBUTE_ACTION_TYPES.has(actionType);
+}

package/src/core/foundation-inflight.mjs

@@ -13,6 +13,13 @@
  * 本桥从 5 级相对路径 import（包外工作树引用）切换为包名 import
  * （'skill-family-harness-node'），随 npm 依赖发布，不再依赖 Foundation 工作树在旁。
  *
+ * 0.5.1 依赖提升：skill-family-contracts / skill-family-harness-node 由 0.4.0
+ * 提升至 0.5.0（npm latest，2026-08-16 发布）。harness-node 0.5.0 导出面已逐项
+ * 核对：publishFileExclusive（atomic.mjs）、acquireFilesystemLock /
+ * inspectFilesystemLock / releaseFilesystemLock / recoverFilesystemLock
+ * （token-lock.mjs）、HARNESS_ERROR_KINDS（errors.mjs）均在 index.mjs 导出面，
+ * 包名 import 无需改动。
+ *
  * 发布形态：包名 import 可直接用于包内 src（node_modules 解析），bundle
  * （bin/release-skill.bundle.mjs，esbuild 内联）保持自包含。
  *

package/src/core/plan.mjs

@@ -534,8 +534,18 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         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`);
+      } else if (branchStrategy === 'create-release-branch') {
+        // Chain-integrity gate (0.5.1): create-release-branch creates an
+        // orphan root commit (no parent). It is only legitimate for the
+        // FIRST release of a repository (previousPublicBaseline.mode=none).
+        // A later release using it would start a fresh lineage disconnected
+        // from the published history — the historical orphan-root channel.
+        if (unit.previousPublicBaseline?.mode === 'bound') {
+          failures.push(`unit "${unitId}" create-release-branch is only valid for first releases (previousPublicBaseline.mode=none), but a bound previous public baseline exists`);
+        }
+        if (frozen.parentCommit) {
+          failures.push(`unit "${unitId}" create-release-branch must not freeze a parentCommit`);
+        }
       }
       if (
         branchStrategy === 'advance-existing-branch' &&