release-skill 0.5.0 → 0.5.1

package/bin/rules.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.contracts.rules",
-  "contractsVersion": "1.4.0",
+  "contractsVersion": "1.5.0",
   "budget": {
     "firstVersionMax": 20,
     "absoluteMax": 30,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -76,8 +76,8 @@
     "ajv-formats": "3.0.1",
     "libnpmpublish": "11.1.0",
     "npm-registry-fetch": "18.0.2",
-    "skill-family-contracts": "0.4.0",
-    "skill-family-harness-node": "0.4.0",
+    "skill-family-contracts": "0.5.0",
+    "skill-family-harness-node": "0.5.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/src/adapters/plugin-marketplace.mjs

@@ -2179,10 +2179,34 @@ export function createPluginMarketplaceAdapter(deps = {}) {
             // pluginRootForEntrySkill 在非 external 结构化 CLI 路径中已确定；
             // external 路径或 human-attestation（null）时回退到 snapshotDirReal。
             const pluginRootForSkill = pluginRootForEntrySkill || snapshotDirReal;
-            const entrySkillFile = resolve(pluginRootForSkill, 'skills', action.entrySkill, 'SKILL.md');
+            // Prefixed skill-directory fallback (0.5.1 entry-skill-prefix fix,
+            // D-ACA-30 platform_physical_name): some candidate builds name
+            // skill directories `skills/<plugin>-<entrySkill>/` instead of
+            // the unprefixed `skills/<entrySkill>/`. Resolve the unprefixed
+            // layout first; when it misses, retry with the plugin prefix.
+            let entrySkillFile = resolve(pluginRootForSkill, 'skills', action.entrySkill, 'SKILL.md');
+            let entrySkillExists = false;
             try {
               await stat(entrySkillFile);
+              entrySkillExists = true;
             } catch {
+              if (action.plugin) {
+                const prefixed = resolve(
+                  pluginRootForSkill,
+                  'skills',
+                  `${action.plugin}-${action.entrySkill}`,
+                  'SKILL.md',
+                );
+                try {
+                  await stat(prefixed);
+                  entrySkillFile = prefixed;
+                  entrySkillExists = true;
+                } catch {
+                  // both layouts miss; report below
+                }
+              }
+            }
+            if (!entrySkillExists) {
               const skillRel = relative(snapshotDirReal, entrySkillFile) || `skills/${action.entrySkill}/SKILL.md`;
               return createResult({
                 actionType,
@@ -3476,8 +3500,11 @@ export function createPluginMarketplaceAdapter(deps = {}) {
             });
           }
 
-          // Verify entry skill exists as a regular file in install dir
-          const entrySkillPath = resolve(installPath, 'skills', action.entrySkill, 'SKILL.md');
+          // Verify entry skill exists as a regular file in install dir.
+          // Prefixed skill-directory fallback (0.5.1 entry-skill-prefix fix):
+          // mirror the preflight resolution — `skills/<entrySkill>` first,
+          // then `skills/<plugin>-<entrySkill>` when the plugin is known.
+          let entrySkillPath = resolve(installPath, 'skills', action.entrySkill, 'SKILL.md');
           let entrySkillFound = false;
           try {
             const skillStat = await lstat(entrySkillPath);
@@ -3485,7 +3512,24 @@ export function createPluginMarketplaceAdapter(deps = {}) {
               entrySkillFound = true;
             }
           } catch {
-            // entry skill not found
+            // entry skill not found in unprefixed layout
+          }
+          if (!entrySkillFound && action.plugin) {
+            const prefixedPath = resolve(
+              installPath,
+              'skills',
+              `${action.plugin}-${action.entrySkill}`,
+              'SKILL.md',
+            );
+            try {
+              const skillStat = await lstat(prefixedPath);
+              if (skillStat.isFile() && !skillStat.isSymbolicLink()) {
+                entrySkillPath = prefixedPath;
+                entrySkillFound = true;
+              }
+            } catch {
+              // both layouts miss; report below
+            }
           }
 
           if (!entrySkillFound) {

package/src/adapters/push-snapshot.mjs

@@ -58,10 +58,16 @@ function validateAction(action) {
   githubRepositoryUrl(action.repo, action.githubHost);
 
   const validStrategies = ['create-release-branch', 'advance-existing-branch', 'initialize-default-branch'];
-  const strategy = action.branchStrategy ?? 'create-release-branch';
-  if (typeof strategy !== 'string' || !validStrategies.includes(strategy)) {
+  // Explicit strategy is required (0.5.1 chain hardening): the historical
+  // `?? 'create-release-branch'` default silently produced orphan root
+  // commits whenever a plan omitted the strategy — the root cause of the
+  // synthetic-date root commits in the public repositories. The plan layer
+  // now guarantees the value; a missing value here fails closed instead of
+  // degrading to the orphan-root channel.
+  if (typeof action.branchStrategy !== 'string' || !validStrategies.includes(action.branchStrategy)) {
     throw new Error(`branchStrategy must be one of: ${validStrategies.join(', ')}`);
   }
+  const strategy = action.branchStrategy;
   if (strategy === 'advance-existing-branch' || strategy === 'initialize-default-branch') {
     if (!action.parentCommit || typeof action.parentCommit !== 'string') {
       throw new Error(`${strategy} requires parentCommit`);
@@ -126,7 +132,8 @@ export function createPushSnapshotAdapter(deps = {}) {
           { shell: false },
         );
         const remoteTip = stdout.trim().split(/\s+/)[0] ?? '';
-        const strategy = action.branchStrategy ?? 'create-release-branch';
+        // Guaranteed by validateAction above (branchStrategy is required).
+        const strategy = action.branchStrategy;
 
         if (strategy === 'advance-existing-branch') {
           if (!remoteTip) {
@@ -173,7 +180,8 @@ export function createPushSnapshotAdapter(deps = {}) {
         });
         const gitDir = await inspectLocalObjects(action, context, exec);
         const remoteUrl = githubRepositoryUrl(action.repo, action.githubHost);
-        const strategy = action.branchStrategy ?? 'create-release-branch';
+        // Guaranteed by validateAction above (branchStrategy is required).
+        const strategy = action.branchStrategy;
 
         if (strategy === 'advance-existing-branch') {
           await exec(

package/src/commands/assess.mjs

@@ -709,6 +709,171 @@ async function checkRemotePrerequisites(root, config, offline) {
   return gaps;
 }
 
+/**
+ * Parse a semver-ish version string into comparable components.
+ *
+ * Accepts `major.minor.patch` with an optional `-prerelease` suffix (which
+ * sorts strictly below the same release triple). Returns null for anything
+ * that is not a version-shaped tag (candidate names like `0.1.27-candidate.2`
+ * parse fine; non-version tags are skipped).
+ *
+ * @param {string} version
+ * @returns {{ major: number, minor: number, patch: number, prerelease: string|null } | null}
+ */
+export function parseSemverVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(version);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null,
+  };
+}
+
+/**
+ * Compare two parsed semver values. Returns a negative/zero/positive number.
+ *
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} a
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} b
+ * @returns {number}
+ */
+export function compareSemverVersions(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.prerelease && !b.prerelease) return -1;
+  if (!a.prerelease && b.prerelease) return 1;
+  return 0;
+}
+
+/**
+ * Describe a version-sequence gap between an immediate predecessor and the
+ * target version, or null when the step is contiguous.
+ *
+ * A gap means some version between the two was never released (e.g. the
+ * historical 0.1.1 -> 0.1.3 jump with no v0.1.2 tag). Pre-release steps
+ * never count as gaps by themselves.
+ *
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} prev
+ * @param {{ major: number, minor: number, patch: number, prerelease: string|null }} target
+ * @returns {string|null}
+ */
+export function describeVersionSequenceGap(prev, target) {
+  if (prev.major !== target.major) {
+    return prev.major + 1 < target.major
+      ? `major ${prev.major}.x.x -> ${target.major}.x.x`
+      : null;
+  }
+  if (prev.minor !== target.minor) {
+    return prev.minor + 1 < target.minor
+      ? `minor ${prev.major}.${prev.minor}.x -> ${target.major}.${target.minor}.x`
+      : null;
+  }
+  if (prev.patch !== target.patch) {
+    return prev.patch + 1 < target.patch
+      ? `patch ${prev.major}.${prev.minor}.${prev.patch} -> ${target.major}.${target.minor}.${target.patch}`
+      : null;
+  }
+  return null;
+}
+
+/**
+ * Build a regex that extracts the version from a tag name following the
+ * unit's tagTemplate (`{version}` placeholder, regex-special characters
+ * escaped).
+ *
+ * @param {string} tagTemplate
+ * @returns {RegExp}
+ */
+export function buildTagVersionRegex(tagTemplate) {
+  const escaped = tagTemplate
+    .split('{version}')
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('(.+)');
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Check the public repository's release tag sequence for version jumps
+ * (0.5.1 chain hardening): when the immediate predecessor release is more
+ * than one version step below the current target version, register a
+ * warning-level gap `VERSION_SEQUENCE_GAP` (e.g. 0.1.1 -> 0.1.3 with no
+ * v0.1.2 tag). This never blocks: it records the observation for the human
+ * release planner.
+ *
+ * @param {string} root - Project root.
+ * @param {Object} config - The loaded project config.
+ * @returns {Promise<Object[]>} Array of warning gap entries.
+ */
+async function checkReleaseTagSequence(root, config) {
+  const gaps = [];
+  for (const unit of config.releaseUnits ?? []) {
+    const tagTemplate = unit.version?.tagTemplate;
+    if (!tagTemplate || !unit.publicRepo) continue;
+
+    const versionRegex = buildTagVersionRegex(tagTemplate);
+    const tagPattern = tagTemplate.replace('{version}', '*');
+
+    let stdout;
+    try {
+      ({ stdout } = await execFile(
+        'git',
+        ['ls-remote', `https://github.com/${unit.publicRepo}.git`, `refs/tags/${tagPattern}`],
+        { cwd: root, shell: false, encoding: 'utf8', timeout: 15_000 },
+      ));
+    } catch {
+      // Tag enumeration failure (network/auth/repo absent) is not a version
+      // gap and must not block; the remote-prerequisites npm check already
+      // reports unreachable registries where relevant.
+      continue;
+    }
+
+    let targetVersion;
+    try {
+      const pkg = JSON.parse(await readFile(resolve(root, unit.source, 'package.json'), 'utf8'));
+      targetVersion = pkg.version;
+    } catch {
+      continue; // package metadata issues are reported elsewhere
+    }
+    const targetParsed = parseSemverVersion(targetVersion);
+    if (!targetParsed) continue;
+
+    let previousParsed = null;
+    let previousTag = null;
+    for (const line of stdout.trim().split('\n')) {
+      if (!line) continue;
+      const tagName = line.split('\t')[1]?.replace(/^refs\/tags\//, '');
+      if (!tagName) continue;
+      const versionMatch = versionRegex.exec(tagName);
+      if (!versionMatch) continue;
+      const parsed = parseSemverVersion(versionMatch[1]);
+      if (!parsed) continue;
+      // Prereleases never qualify as the "previous release" predecessor.
+      if (parsed.prerelease) continue;
+      if (compareSemverVersions(parsed, targetParsed) >= 0) continue;
+      if (previousParsed === null || compareSemverVersions(parsed, previousParsed) > 0) {
+        previousParsed = parsed;
+        previousTag = tagName;
+      }
+    }
+
+    if (!previousParsed) continue;
+    const gap = describeVersionSequenceGap(previousParsed, targetParsed);
+    if (gap) {
+      gaps.push(createGap({
+        scope: GapScope.PROJECT,
+        category: GapCategory.REMOTE,
+        severity: Severity.WARNING,
+        code: 'VERSION_SEQUENCE_GAP',
+        message: `发布单元 "${unit.id}" 的版本序列存在跳号（${gap}，上一发布标签 ${previousTag}，目标版本 ${targetVersion}）：请确认中间版本未发布是否是有意为之；发布链仍会以链式历史推进，但跳过的版本不会补造标签`,
+        file: '.release-skill/project.yaml',
+      }));
+    }
+  }
+  return gaps;
+}
+
 /**
  * Perform a basic README structural check.
  *
@@ -967,6 +1132,12 @@ export async function assessProject(options) {
   const remoteGaps = await checkRemotePrerequisites(root, config, offline);
   allGaps.push(...remoteGaps);
 
+  // --- 7b. Release tag sequence (online only; warning, never blocking) ---
+  if (!offline) {
+    const tagSequenceGaps = await checkReleaseTagSequence(root, config);
+    allGaps.push(...tagSequenceGaps);
+  }
+
   // --- 8. README structure check ---
   const readmeGaps = await checkReadmeStructure(root, config);
   allGaps.push(...readmeGaps);

package/src/commands/hooks.mjs

@@ -28,7 +28,12 @@ export async function validateDeclaredHooks(options = {}) {
     clock: () => new Date().toISOString(),
   });
   const startedAt = new Date().toISOString();
-  await runDeclaredHooks(config, root, evidence, undefined, { hookCache });
+  await runDeclaredHooks(config, root, evidence, undefined, {
+    hookCache,
+    // Explicit env delivery (0.5.1 hook-env-delivery fix): same semantics as
+    // prepare — allowlisted keys are read from this explicit map only.
+    env: process.env,
+  });
   return {
     command: 'hooks validate',
     status: 'PASSED',

package/src/commands/prepare.mjs

@@ -243,6 +243,13 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
  * @param {object} [options]
  * @param {boolean} [options.hookCache=true] - When false (--no-hook-cache),
  *   every hook runs in full and the cache is neither read nor written.
+ * @param {Record<string, string>} [options.env] - Explicit environment map
+ *   merged into the hook context (`hookFn(hook, { root, env })`). The hook
+ *   runner's `buildFilteredEnv` reads `envAllowlist` keys exclusively from
+ *   this map (never from process.env), so the caller decides what is
+ *   injectable. Defaults to process.env at the prepare call site, which makes
+ *   allowlisted keys exported by the invoking shell reach the hook
+ *   subprocess.
  * @returns {Promise<void>}
  * @throws {ReleaseError} GATE_FAILED if any hook returns a non-zero exit code,
  *   throws, or declares a cacheInputs glob that matches no file.
@@ -294,7 +301,10 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
 
     let result;
     try {
-      result = await hookFn(hook, { root });
+      result = await hookFn(hook, {
+        root,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+      });
     } catch (err) {
       await evidence.append({
         phase: 'hooks',
@@ -1850,6 +1860,11 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'hooks', status: 'started' });
     await runDeclaredHooks(config, realRoot, evidence, options.runHookFn ?? runHook, {
       hookCache: options.hookCache,
+      // Explicit env delivery (0.5.1 hook-env-delivery fix): the hook runner
+      // reads envAllowlist keys exclusively from context.env, so the invoking
+      // shell's environment is injected here explicitly. Allowlist semantics
+      // are unchanged — only allowlisted keys from this map reach the child.
+      env: options.env ?? process.env,
     });
     await evidence.append({ phase: 'hooks', status: 'completed' });
 
@@ -2077,6 +2092,29 @@ export async function prepareRelease(options) {
       }
     };
     const observeDefaultBranch = options.observeDefaultBranchFn ?? defaultObserveDefaultBranchFn;
+    // CHAIN_GAP detection (0.5.1 chain hardening): when a unit declares
+    // previousPublicBaseline.mode=none (first-release semantics) but the
+    // public repository already carries release tags for the unit's
+    // tagTemplate, a subsequent release pretending to be the first would
+    // freeze a plan whose push-snapshot creates a new orphan root commit.
+    // Detection is online-only: `git ls-remote` on the tag pattern
+    // (tagTemplate with {version} → *). Any match proves a prior release.
+    const defaultPriorReleaseTagDetector = async (repo, tagPattern, { githubHost = 'github.com' } = {}) => {
+      try {
+        const { stdout } = await execFile(
+          'git',
+          ['ls-remote', `https://${githubHost}/${repo}.git`, `refs/tags/${tagPattern}`],
+          { shell: false, encoding: 'utf8', timeout: 30000 },
+        );
+        return { found: stdout.trim().length > 0 };
+      } catch (err) {
+        // Network/auth failure: unknown, not "no prior release". The caller
+        // records a warning and continues (consistent with the bound-baseline
+        // observer's unknown status); it never silently proves first release.
+        return { error: err.message };
+      }
+    };
+    const detectPriorReleaseTags = options.detectPriorReleaseTagsFn ?? defaultPriorReleaseTagDetector;
     const unitBaselineResults = new Map();
     for (let unitIndex = 0; unitIndex < configUnits.length; unitIndex += 1) {
       const unit = configUnits[unitIndex];
@@ -2120,6 +2158,50 @@ export async function prepareRelease(options) {
       });
 
       if (ppbConfig.mode === "none") {
+        // Chain-integrity gate (0.5.1, CHAIN_GAP): a production online
+        // prepare must not freeze a first-release plan for a repository that
+        // has already published. This is the orphan-root channel that caused
+        // the synthetic 2000-01-01 root commits in the historical public
+        // repositories: first releases used mode=none, push-snapshot degraded
+        // to create-release-branch with no parent, and every later release
+        // started a fresh lineage. Fail closed and demand a bound baseline
+        // pointing at the previous release commit instead.
+        if (production && !offline) {
+          const tagTemplate = unit.version?.tagTemplate;
+          const tagPattern = tagTemplate ? tagTemplate.replace('{version}', '*') : null;
+          if (tagPattern) {
+            const detection = await detectPriorReleaseTags(unit.publicRepo, tagPattern, {
+              githubHost: productionGithubHost,
+            });
+            if (detection.found) {
+              await evidence.append({
+                phase: "previous-public-baseline",
+                unitId: unit.id,
+                status: "blocking",
+                reason: "CHAIN_GAP",
+                repo: unit.publicRepo,
+                tagPattern,
+                guidance: "非首次发布：必须把 previousPublicBaseline 绑定到上一发布提交（mode=bound），不能以 mode=none 制造新的孤儿根提交",
+              });
+              throw new ReleaseError(
+                GATE_FAILED,
+                `unit "${unit.id}" previousPublicBaseline.mode=none but the public repository already has release tags matching "${tagPattern}" (CHAIN_GAP): bind the previous public release commit as a bound baseline`,
+                { unitId: unit.id, reason: 'CHAIN_GAP', repo: unit.publicRepo, tagPattern },
+              );
+            }
+            if (detection.error) {
+              await evidence.append({
+                phase: "previous-public-baseline",
+                unitId: unit.id,
+                status: "warning",
+                reason: "CHAIN_GAP_DETECTION_FAILED",
+                repo: unit.publicRepo,
+                tagPattern,
+                error: detection.error,
+              });
+            }
+          }
+        }
         unitBaselineResults.set(unit.id, {
           mode: "none",
           status: "consistent",

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/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' &&