release-skill 0.6.0 → 0.6.1

package/package.json

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

package/references/05-evidence-and-errors.md

@@ -32,6 +32,7 @@
 | `NOT_DEFAULT` | 配置分支不是远端实际默认分支 | 默认分支在 prepare 后改变，或配置错误 | 人工确认远端默认分支，更新配置并重新 prepare |
 | `CONTENT_MISMATCH` | 远端默认分支缺少冻结源码内容 | README、版本源、公开映射输入的内容或 mode 不一致 | 人工 merge/adopt/reject；接受的内容进入默认分支后重试 publish |
 | `DIRTY_SOURCE_INPUT` | 源码输入闭包存在未提交变化 | `publicFiles.from` 或 `version.source` 有 staged、unstaged、untracked 变化 | 提交或撤销这些具体输入的变化后重新 prepare；无关 dirty 不受影响 |
+| `BUNDLE_STALE` | bundle 与其源码输入失步（fail-closed 前置门禁） | `bin/release-skill.bundle.mjs` 内嵌的源码摘要与当前 `src/` 摘要不一致，或 bundle/内嵌摘要缺失；在 prepare 加载 config 后的早期阶段检测，任何 workflow 均不可豁免 | 按错误提示在 release-skill 包根运行 `node scripts/build-bundle.mjs`（或 `pnpm build`）重建 bundle 后重新 prepare |
 
 **动作状态码** (adapter execute/observe/verify):
 

package/schemas/release-project.schema.json

@@ -873,6 +873,14 @@
           },
           "uniqueItems": true,
           "description": "Root-relative globs declaring the hook's full input set (source, scripts, config, lockfiles). The cache key fingerprints the content of every matched file; a glob that matches nothing fails closed. Must cover ALL inputs or the cache can return a false hit."
+        },
+        "testSelection": {
+          "type": "string",
+          "enum": [
+            "full",
+            "incremental"
+          ],
+          "description": "Only meaningful for the test hook: which test selection the hook command runs. Absence or 'full' means the hook runs the full suite, which prepare's built-in full-test freeze gate requires before the plan digest is computed. 'incremental' is reserved for a future preflight mode and is rejected at freeze time ('incremental selection is not allowed at freeze time'). Built-in gate; cannot be disabled by project overlays."
         }
       }
     },

package/scripts/build-bundle.mjs

@@ -21,6 +21,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
+import { computeBundleSourceDigest } from '../src/core/bundle-freshness.mjs';
 
 const CHECK_MODE = process.argv.includes('--check');
 
@@ -38,7 +39,12 @@ const OUTFILE = join(PKG_ROOT, 'bin', 'release-skill.bundle.mjs');
 // dependency: the Claude and Codex adapter closures ship the bundle at a
 // different depth with no package.json next to it, while the npm closure does.
 // Reading package.json here (build input) keeps the output deterministic.
-function buildBanner(pkgIdentity) {
+//
+// __bundleSourceDigest is the build-time digest of the bundle's source inputs
+// (src/, skills-src/, bin/release-skill-cli.mjs, package.json — algorithm in
+// src/core/bundle-freshness.mjs). prepare's BUNDLE_STALE gate recomputes the
+// digest and fails closed on any mismatch (2026-08-18 investigation §4.2).
+function buildBanner(pkgIdentity, sourceDigest) {
   return `\
 // --- release-skill bundle (deterministic build) ---
 // Compute package root from the bundle's own file location (import.meta.url).
@@ -51,6 +57,8 @@ const __bundlePkgRoot = __bundleResolve(__bundleDirname(__bundleFileURLToPath(im
 const __bundleRealRequire = __bundleCreateRequire(import.meta.url);
 // Package identity injected at build time — closure-independent --version probe.
 const __bundlePkg = Object.freeze(${JSON.stringify(pkgIdentity)});
+// Build-time source digest for the BUNDLE_STALE freshness gate (see above).
+const __bundleSourceDigest = "${sourceDigest}";
 `;
 }
 
@@ -164,7 +172,8 @@ async function buildBundle() {
   }
 
   const pkgJson = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf-8'));
-  const banner = buildBanner({ name: pkgJson.name, version: pkgJson.version });
+  const sourceDigest = await computeBundleSourceDigest(PKG_ROOT);
+  const banner = buildBanner({ name: pkgJson.name, version: pkgJson.version }, sourceDigest);
 
   const identity = Object.freeze({ name: pkgJson.name, version: pkgJson.version });
 

package/scripts/sync-public-files.mjs

@@ -232,6 +232,9 @@ async function collectEntries(packageRoot) {
   //                           a distribution artifact; the shipped bundle
   //                           inlines the adopted capability — matches the npm
   //                           pack closure contract)
+  //    - .release-skill/     (local release runtime state — runs, plans, locks;
+  //                           not in the package.json files whitelist, so it is
+  //                           never part of the npm pack closure)
   const baseFiles = allFiles.filter((f) => {
     if (f.startsWith('adapters/')) return false;
     if (f.startsWith('test/')) return false;
@@ -240,6 +243,7 @@ async function collectEntries(packageRoot) {
     if (f.startsWith('native/') && f.includes('/build/')) return false;
     if (f.startsWith('scripts/')) return false;
     if (f.startsWith('vendor/')) return false;
+    if (f.startsWith('.release-skill/')) return false;
     return true;
   });
 

package/src/commands/prepare.mjs

@@ -18,7 +18,7 @@
  * @module commands/prepare
  */
 
-import { resolve, relative, isAbsolute, normalize, dirname } from 'node:path';
+import { resolve, relative, isAbsolute, normalize, dirname, basename } from 'node:path';
 import { readFile, mkdir, readdir, realpath } from 'node:fs/promises';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -53,7 +53,10 @@ import {
   normalizeGitTimestamp,
   sealFrozenSnapshot,
 } from '../snapshot/frozen.mjs';
-import { ReleaseError, GATE_FAILED, CONFIG_INVALID, CONFIG_MISSING, FORBIDDEN_CONTENT_DETECTED, RELEASE_DOCS_STALE, DIRTY_SOURCE_INPUT } from '../core/errors.mjs';
+import { ReleaseError, GATE_FAILED, CONFIG_INVALID, CONFIG_MISSING, FORBIDDEN_CONTENT_DETECTED, RELEASE_DOCS_STALE, DIRTY_SOURCE_INPUT, BUNDLE_STALE } from '../core/errors.mjs';
+import { assertBundleFreshness } from '../core/bundle-freshness.mjs';
+import { PKG_ROOT } from '../core/pkg-root.mjs';
+import { writeFrozenMarker, FROZEN_MARKER_FILENAME } from '../core/frozen-marker.mjs';
 import {
   SOURCE_INPUT_ALGORITHM_VERSION,
   computeSourceInputClosure,
@@ -224,6 +227,40 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
 // Hooks execution
 // ---------------------------------------------------------------------------
 
+/** Maximum number of output lines preserved in a hook-failure tail. */
+const HOOK_OUTPUT_TAIL_MAX_LINES = 50;
+/** Maximum bytes preserved in a hook-failure tail. */
+const HOOK_OUTPUT_TAIL_MAX_BYTES = 8 * 1024;
+
+/**
+ * Bound a captured child-output stream to the tail that matters for triage:
+ * the last 50 lines, further capped at 8 KB — whichever is smaller.
+ *
+ * @param {string} [text] - Captured stdout/stderr text.
+ * @returns {string} The bounded tail ('' for empty/absent input).
+ */
+export function boundedOutputTail(text) {
+  if (typeof text !== 'string' || text.length === 0) return '';
+  let lines = text.split('\n');
+  // A trailing newline produces an empty final element; drop it so the line
+  // budget counts real output lines.
+  if (lines.length > 1 && lines[lines.length - 1] === '') {
+    lines = lines.slice(0, -1);
+  }
+  let tail = lines.slice(-HOOK_OUTPUT_TAIL_MAX_LINES);
+  let joined = tail.join('\n');
+  while (tail.length > 1 && Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
+    tail = tail.slice(1);
+    joined = tail.join('\n');
+  }
+  if (Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
+    // A single line exceeds the byte cap: keep the trailing bytes.
+    const buf = Buffer.from(joined, 'utf8');
+    joined = buf.subarray(buf.length - HOOK_OUTPUT_TAIL_MAX_BYTES).toString('utf8');
+  }
+  return joined;
+}
+
 /**
  * Run all declared project hooks in order: docs, build, test, typecheck.
  *
@@ -236,6 +273,13 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
  * Failures (non-zero exit or HOOK_TIMEOUT) are never cached. A `cacheInputs`
  * glob that matches nothing fails closed before the hook runs.
  *
+ * Failure output passthrough (2026-08-18 investigation §4.1): the executor
+ * already captures child stdout/stderr on non-zero exit; on failure this
+ * layer writes bounded tails into the hooks evidence event AND echoes them to
+ * the current process' stderr, so a failing hook is diagnosable on the
+ * terminal without opening evidence.jsonl. Success events carry no tails.
+ * Exit-code semantics are unchanged.
+ *
  * @param {object} config - The loaded project config.
  * @param {string} root - Absolute project root.
  * @param {object} evidence - The evidence writer.
@@ -251,7 +295,9 @@ export async function resolveAllUnitVersions(units, root, explicitVersion, evide
  *   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>}
+ * @returns {Promise<Array<{ name: string, completed: boolean, cached: boolean, testSelection: string | undefined }>>}
+ *   One record per declared hook that completed (fresh or cached replay).
+ *   Failures throw instead of returning a record.
  * @throws {ReleaseError} GATE_FAILED if any hook returns a non-zero exit code,
  *   throws, or declares a cacheInputs glob that matches no file.
  */
@@ -259,15 +305,24 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
   const hookOrder = ['docs', 'build', 'test', 'typecheck'];
   const hooks = config.hooks ?? {};
   const cacheEnabled = options.hookCache !== false;
+  const records = [];
 
   for (const name of hookOrder) {
     const hook = hooks[name];
     if (!hook) continue;
 
+    // Test-selection evidence (2026-08-18 investigation §4.4): the test hook
+    // records whether it ran the full suite. Absence of a declaration means
+    // 'full' — every existing config stays backward compatible.
+    const selectionField = name === 'test'
+      ? { testSelection: hook.testSelection === 'incremental' ? 'incremental' : 'full' }
+      : {};
+
     await evidence.append({
       phase: 'hooks',
       status: 'started',
       hookName: name,
+      ...selectionField,
     });
 
     // --- Incremental cache lookup (opt-in only; default zero change) ---
@@ -295,7 +350,9 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
           hookName: name,
           cached: true,
           cacheKey,
+          ...selectionField,
         });
+        records.push({ name, completed: true, cached: true, testSelection: selectionField.testSelection });
         continue;
       }
     }
@@ -312,6 +369,7 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
         status: 'failed',
         hookName: name,
         error: { code: err.code, message: err.message },
+        ...selectionField,
       });
       throw new ReleaseError(
         GATE_FAILED,
@@ -321,16 +379,29 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
     }
 
     if (result.exitCode !== 0) {
+      const stdoutTail = boundedOutputTail(result.stdout);
+      const stderrTail = boundedOutputTail(result.stderr);
+      // Echo the captured tails to the current process' stderr so a failing
+      // hook is diagnosable on the terminal without opening evidence.jsonl
+      // (2026-08-18 investigation §4.1). Exit-code semantics are untouched.
+      process.stderr.write(`[release-skill] hook "${name}" failed with exit code ${result.exitCode}\n`);
+      if (stdoutTail) {
+        process.stderr.write(`[release-skill] hook "${name}" stdout tail:\n${stdoutTail}\n`);
+      }
+      if (stderrTail) {
+        process.stderr.write(`[release-skill] hook "${name}" stderr tail:\n${stderrTail}\n`);
+      }
       await evidence.append({
         phase: 'hooks',
         status: 'failed',
         hookName: name,
         exitCode: result.exitCode,
         // Test runners usually emit the actionable failure summary at the
-        // end. Preserve bounded tails of both streams instead of the noisy
-        // compiler prelude at the beginning.
-        stdoutTail: result.stdout.slice(-4000),
-        stderrTail: result.stderr.slice(-4000),
+        // end. Preserve bounded tails (last 50 lines, capped at 8 KB) of both
+        // streams instead of the noisy compiler prelude at the beginning.
+        stdoutTail,
+        stderrTail,
+        ...selectionField,
       });
       throw new ReleaseError(
         GATE_FAILED,
@@ -364,8 +435,12 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
       status: 'completed',
       hookName: name,
       exitCode: 0,
+      ...selectionField,
     });
+    records.push({ name, completed: true, cached: false, testSelection: selectionField.testSelection });
   }
+
+  return records;
 }
 
 // ---------------------------------------------------------------------------
@@ -1744,6 +1819,7 @@ export async function prepareRelease(options) {
     production = false,
     workflow = 'full',
     observePreviousPublicBaselineFn,
+    testSelection = 'full',
   } = options ?? {};
 
   // --- Workflow profile (H5) ---
@@ -1761,6 +1837,24 @@ export async function prepareRelease(options) {
       { workflow },
     );
   }
+
+  // --- Test selection (2026-08-18 investigation §4.4, review §3.4) ---
+  // Design decision: prepare IS the freeze, so incremental test selection is
+  // rejected outright; the flag is reserved for a future preflight mode.
+  if (testSelection === 'incremental') {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'incremental selection is not allowed at freeze time',
+      { testSelection, reservedFor: 'preflight mode' },
+    );
+  }
+  if (testSelection !== 'full') {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `unknown testSelection "${testSelection}"; expected "full" or "incremental"`,
+      { testSelection },
+    );
+  }
   const trimmedWorkflow = workflow !== 'full';
   const skipDeclaredHooks = trimmedWorkflow;
   const skipSnapshotVerifyGates = trimmedWorkflow;
@@ -1845,6 +1939,44 @@ export async function prepareRelease(options) {
       });
     }
 
+    // --- Step 1-fresh: Bundle freshness gate (BUNDLE_STALE, fail-closed) ---
+    // 2026-08-18 investigation §4.2: a stale bin/release-skill.bundle.mjs
+    // used to surface only deep inside test hooks. Compare the deterministic
+    // source digest embedded in the bundle at build time with the current
+    // sources at the earliest stage — config loaded, before any hook.
+    // This gate is artifact-integrity class, NOT a code-class gate:
+    // docs/config/marketplace workflow trimming must never exempt it.
+    await evidence.append({ phase: 'bundle-freshness', status: 'started' });
+    const bundleFreshnessFn = options.bundleFreshnessFn ?? assertBundleFreshness;
+    let bundleFreshness;
+    try {
+      bundleFreshness = await bundleFreshnessFn(PKG_ROOT);
+    } catch (err) {
+      await evidence.append({
+        phase: 'bundle-freshness',
+        status: 'blocking',
+        reason: err.details?.reason ?? null,
+        error: { code: err.code, message: err.message },
+      });
+      throw err;
+    }
+    if (bundleFreshness?.applicable === false) {
+      // Installed distributions ship no mutable src/ next to the bundle;
+      // staleness is a source-checkout concern only.
+      await evidence.append({
+        phase: 'bundle-freshness',
+        status: 'not-applicable',
+        reason: bundleFreshness.reason,
+      });
+    } else {
+      await evidence.append({
+        phase: 'bundle-freshness',
+        status: 'completed',
+        algorithm: bundleFreshness?.algorithm ?? null,
+        sourceDigest: bundleFreshness?.sourceDigest ?? null,
+      });
+    }
+
     // --- Step 1a: Workflow configuration evidence ---
     // Records the deterministic trim set for docs/config/marketplace
     // workflows. The trim never weakens the retained gates; it only removes
@@ -1974,6 +2106,7 @@ export async function prepareRelease(options) {
     }
 
     // --- Step 3: Run declared hooks ---
+    let hookRecords = [];
     if (skipDeclaredHooks) {
       await evidence.append({
         phase: 'hooks',
@@ -1982,7 +2115,7 @@ export async function prepareRelease(options) {
       });
     } else {
       await evidence.append({ phase: 'hooks', status: 'started' });
-      await runDeclaredHooks(config, realRoot, evidence, options.runHookFn ?? runHook, {
+      hookRecords = 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
@@ -2608,6 +2741,59 @@ export async function prepareRelease(options) {
     // --- Step 7: Build plan object ---
     await evidence.append({ phase: 'plan-assembly', status: 'started' });
 
+    // --- Step 7-gate: Full-test freeze gate (hard gate) ---
+    // 2026-08-18 investigation §4.4 / review §3.4: "full test suite before
+    // freeze" is a HARD gate, not a convention. The plan digest may only be
+    // computed after a completed FULL-mode test hook exists in THIS run's
+    // evidence (fresh run or a cached replay of a successful full run).
+    // Built-in and read-only — like secret-scan, plan-digest binding, and
+    // approval, it cannot be disabled by project overlays. Workflows that
+    // trim declared hooks record the trim; projects declaring no test hook
+    // pass vacuously (nothing can run incrementally there).
+    if (skipDeclaredHooks) {
+      await evidence.append({
+        phase: 'full-test-gate',
+        status: 'skipped',
+        reason: `workflow "${workflow}" trims declared hooks`,
+      });
+    } else if (!config.hooks?.test) {
+      await evidence.append({
+        phase: 'full-test-gate',
+        status: 'not-declared',
+        reason: 'no test hook declared; nothing can run incrementally',
+      });
+    } else {
+      const testRecord = hookRecords.find((record) => record.name === 'test');
+      const satisfied = Boolean(
+        testRecord && testRecord.completed && testRecord.testSelection === 'full',
+      );
+      if (!satisfied) {
+        await evidence.append({
+          phase: 'full-test-gate',
+          status: 'blocking',
+          testSelection: testRecord?.testSelection ?? null,
+          cached: Boolean(testRecord?.cached),
+        });
+        throw new ReleaseError(
+          GATE_FAILED,
+          testRecord?.testSelection === 'incremental'
+            ? 'full-test freeze gate failed: incremental test selection cannot satisfy the freeze-time requirement of a completed full test run in this prepare run'
+            : 'full-test freeze gate failed: prepare requires a completed full-mode test hook in this run before the plan digest is computed',
+          {
+            gate: 'full-test-freeze',
+            testSelection: testRecord?.testSelection ?? null,
+            cached: Boolean(testRecord?.cached),
+          },
+        );
+      }
+      await evidence.append({
+        phase: 'full-test-gate',
+        status: 'completed',
+        testSelection: 'full',
+        cached: Boolean(testRecord.cached),
+      });
+    }
+
     // New prepares emit planVersion 2 (design: t1-2-digest-decoupling.md
     // §4.2/§7). Production freeze timestamps are derived deterministically
     // from the baseline headCommit's committer date, before the first frozen
@@ -3215,6 +3401,26 @@ export async function prepareRelease(options) {
       planDigest,
     });
 
+    // --- Write the FROZEN governance marker (§4.5 option 1) ---
+    // Mechanical maintenance only: the marker is a read-only gentlemen's-
+    // agreement signal for cross-repo writers (e.g. skill-family治理 tasks)
+    // that this workspace is mid-release. It is written ONLY after the plan
+    // is frozen, overwritten by every successful prepare, and cleared by
+    // verify only upon VERIFIED. A failed prepare never reaches this point.
+    await writeFrozenMarker(releaseDir, {
+      planDigest,
+      targetVersions: Object.fromEntries(
+        configUnits.map((unit, index) => [unit.id, resolvedVersions[index]]),
+      ),
+      createdAt: plan.createdAt,
+      runId: basename(runDir),
+    });
+    await evidence.append({
+      phase: 'frozen-marker',
+      status: 'written',
+      markerPath: `.release-skill/${FROZEN_MARKER_FILENAME}`,
+    });
+
     // --- Write summary ---
     await evidence.finish({
       status: 'PREPARED',

package/src/commands/verify.mjs

@@ -54,6 +54,7 @@ import {
 } from '../core/baseline-advance.mjs';
 import { loadProjectConfig } from '../core/config.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
+import { clearFrozenMarker } from '../core/frozen-marker.mjs';
 import { resolveUnitScopedPath } from '../snapshot/public-path.mjs';
 import {
   normalizeRegistry,
@@ -1802,6 +1803,27 @@ export async function verifyRelease(options) {
     };
     const persistedVerifyRun = await writeRunAtomic(verifyRunPath, verifyRunState);
 
+    // =======================================================================
+    // FROZEN marker retirement (2026-08-18 investigation §4.5 option 1):
+    // the release reached VERIFIED, so the freeze signal is cleared. Only
+    // this success path clears it — failed/PARTIAL verify runs never reach
+    // here and keep the marker. Best-effort: a removal failure must never
+    // demote VERIFIED.
+    // =======================================================================
+    try {
+      const removed = await clearFrozenMarker(join(root, '.release-skill'));
+      await evidence.append({
+        phase: 'frozen-marker',
+        status: removed ? 'cleared' : 'absent',
+      });
+    } catch (err) {
+      await evidence.append({
+        phase: 'frozen-marker',
+        status: 'clear-failed',
+        error: { code: err.code, message: err.message },
+      });
+    }
+
     // =======================================================================
     // Baseline advance: move per-unit previousPublicBaseline to the commit
     // that was just verified. Local bookkeeping only — no remote writes.