release-skill 0.5.1 → 0.6.1

package/src/commands/prepare.mjs

@@ -18,8 +18,8 @@
  * @module commands/prepare
  */
 
-import { resolve, relative, isAbsolute, normalize, dirname } from 'node:path';
-import { readFile, mkdir, realpath } from 'node:fs/promises';
+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,
@@ -67,6 +70,7 @@ import { createProductionPrepareRunDir } from '../core/run.mjs';
 import { PLATFORMS } from '../platforms/registry.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
 import { buildInstallationContract, computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from '../core/installation-contract.mjs';
+import { validatePostPublishDeclaration, PAYLOAD_SOURCE_TAG_WORKTREE } from '../core/postpublish.mjs';
 
 // ---------------------------------------------------------------------------
 // 安装契约常量
@@ -223,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.
  *
@@ -235,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.
@@ -250,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.
  */
@@ -258,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) ---
@@ -294,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;
       }
     }
@@ -311,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,
@@ -320,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,
@@ -363,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -1693,6 +1769,43 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
  *
  * @throws {ReleaseError} on any gate failure. No PREPARED plan is written.
  */
+
+/**
+ * Read the newest frozen plan from `.release-skill/plans/` (digest-addressed
+ * immutable plans written by writePlanImmutable). Used by the config workflow
+ * decision to compare public bytes (per-unit snapshotDigest) against the
+ * latest frozen state. Returns null when no readable plan exists.
+ *
+ * @param {string} root - project root directory
+ * @returns {Promise<{ plan: object, fileName: string } | null>}
+ */
+export async function readLatestFrozenPlan(root) {
+  const plansDir = resolve(root, '.release-skill', 'plans');
+  let files;
+  try {
+    files = await readdir(plansDir);
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const file of files.sort()) {
+    if (!file.endsWith('.json')) continue;
+    let plan;
+    try {
+      plan = JSON.parse(await readFile(resolve(plansDir, file), 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!plan || typeof plan !== 'object' || !Array.isArray(plan.units)) continue;
+    const ts = plan.createdAt ? new Date(plan.createdAt).getTime() : NaN;
+    const effectiveTs = Number.isFinite(ts) ? ts : 0;
+    if (!best || effectiveTs > best.ts) {
+      best = { plan, fileName: file, ts: effectiveTs };
+    }
+  }
+  return best ? { plan: best.plan, fileName: best.fileName } : null;
+}
+
 export async function prepareRelease(options) {
   const {
     root,
@@ -1704,9 +1817,50 @@ export async function prepareRelease(options) {
     hooksAuthorized,
     verificationGatesAuthorized,
     production = false,
+    workflow = 'full',
     observePreviousPublicBaselineFn,
+    testSelection = 'full',
   } = options ?? {};
 
+  // --- Workflow profile (H5) ---
+  // 'full' runs the complete gate set. 'docs', 'config' and 'marketplace'
+  // trim only code-class gates — declared hooks, snapshot-verify gates,
+  // source-authority closure, and skill-resource-closure — and record the
+  // trim as `workflowDecision` bound into the plan digest. All other gates
+  // (docs freshness, public surface, baseline, snapshots, remote checks,
+  // plan freeze, consumer-verify gates) run identically for every workflow.
+  const WORKFLOW_KINDS = new Set(['full', 'docs', 'config', 'marketplace']);
+  if (!WORKFLOW_KINDS.has(workflow)) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      `unknown workflow kind "${workflow}"; expected one of ${[...WORKFLOW_KINDS].sort().join(', ')}`,
+      { 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;
+  const skipSourceAuthorityClosure = trimmedWorkflow;
+  const skipSkillResourceClosure = trimmedWorkflow;
+
   // --- Validate root ---
   if (!root || typeof root !== 'string') {
     throw new ReleaseError(CONFIG_INVALID, 'root must be a non-empty string');
@@ -1785,6 +1939,66 @@ 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
+    // code-class gates that a non-code change surface cannot exercise.
+    await evidence.append({
+      phase: 'workflow',
+      status: 'configured',
+      workflowKind: workflow,
+      trimmedGates: trimmedWorkflow
+        ? ['declared-hooks', 'snapshot-verify-gates', 'source-authority-closure', 'skill-resource-closure']
+        : [],
+      retainedGates: [
+        'docs-freshness',
+        'public-surface',
+        'baseline',
+        'snapshots',
+        'remote-check',
+        'plan-freeze',
+        'consumer-verify',
+      ],
+    });
+
     // --- Step 1b: Resolve authoritative versions and gate release-document
     //     freshness BEFORE hook authorization ---
     // Authoritative versions resolve exactly once here and are reused by
@@ -1811,11 +2025,46 @@ export async function prepareRelease(options) {
       reasonTag: 'RELEASE_DOCS_STALE',
     });
 
+    // --- Step 1c: postPublish distribution declaration gate (R1/R2) ---
+    // The per-unit postPublish block drives the post-publish distribute
+    // command. Validate it here, before any hook, baseline, snapshot, remote
+    // check, or plan write, so an unsafe declaration fails closed with zero
+    // side effects. This is the runtime re-check on top of the config JSON
+    // schema: plans frozen by older schema versions must not be able to
+    // smuggle shell strings, option-like executables, or secret-ish env
+    // keys through. A plan binds exactly one declaration; multiple units
+    // declaring postPublish is a hard gate failure.
+    const postPublishDeclarations = configUnits
+      .map((unit, index) => ({ unit, index }))
+      .filter(({ unit }) => unit.postPublish !== undefined);
+    if (postPublishDeclarations.length > 1) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `multiple units declare postPublish (${postPublishDeclarations.map(({ unit }) => unit.id).join(', ')}); a release plan binds exactly one postPublish declaration`,
+        { unitIds: postPublishDeclarations.map(({ unit }) => unit.id) },
+      );
+    }
+    let postPublishDeclaration = null;
+    if (postPublishDeclarations.length === 1) {
+      const { unit, index } = postPublishDeclarations[0];
+      validatePostPublishDeclaration(unit.postPublish, { unitId: unit.id });
+      postPublishDeclaration = { unit, index };
+      await evidence.append({
+        phase: 'postpublish-declaration',
+        status: 'validated',
+        unitId: unit.id,
+        targetCount: unit.postPublish.targets.length,
+      });
+    }
+
     // --- Step 2: Hook authorization gate ---
     // Hooks are user-configured arbitrary local processes without filesystem
     // or network isolation. They may write outside the project, access local
     // credentials, or make network calls. The user must explicitly accept
     // these risks before any hook is executed.
+    // docs/config/marketplace workflows trim code-class hooks entirely
+    // (H5): a non-code change surface cannot exercise them, so they are
+    // recorded as skipped rather than authorized-and-run.
     const declaredHooks = Object.entries(config.hooks ?? {})
       .filter(([, hook]) => hook && hook.command)
       .map(([name, hook]) => ({
@@ -1829,7 +2078,7 @@ export async function prepareRelease(options) {
     // execution of configured commands. Old acknowledgement parameters
     // (--acknowledge-hook-side-effects, --acknowledge-gate-side-effects) are
     // accepted as no-effect compatibility inputs but are not required.
-    if (declaredHooks.length > 0) {
+    if (!skipDeclaredHooks && declaredHooks.length > 0) {
       await evidence.append({
         phase: 'hook-authorization',
         status: 'authorized',
@@ -1857,16 +2106,25 @@ export async function prepareRelease(options) {
     }
 
     // --- Step 3: Run declared hooks ---
-    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' });
+    let hookRecords = [];
+    if (skipDeclaredHooks) {
+      await evidence.append({
+        phase: 'hooks',
+        status: 'skipped',
+        reason: `workflow "${workflow}" trims code-class hooks; declared hooks: ${declaredHooks.length}`,
+      });
+    } else {
+      await evidence.append({ phase: 'hooks', status: 'started' });
+      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
+        // 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' });
+    }
 
     // --- Step 3b: Re-check release-document freshness AFTER hooks ---
     // Declared hooks run as arbitrary local processes; they may rewrite a
@@ -1968,7 +2226,7 @@ export async function prepareRelease(options) {
 
     let sourceAuthority = null;
     let sourceInputClosure = null;
-    if (production) {
+    if (production && !skipSourceAuthorityClosure) {
       if (!sourceRepository || typeof sourceRepository !== 'string') {
         throw new ReleaseError(
           CONFIG_MISSING,
@@ -2038,6 +2296,12 @@ export async function prepareRelease(options) {
         inputDigest: sourceInputClosure.digest,
         remoteObservation: offline ? 'unobserved-offline' : 'deferred-to-publish',
       });
+    } else if (production) {
+      await evidence.append({
+        phase: 'source-authority',
+        status: 'skipped',
+        reason: `workflow "${workflow}" trims the source-authority content closure gate`,
+      });
     }
 
     // --- Step 4: Capture Git baseline (AFTER hooks, so workspaceDigest
@@ -2358,24 +2622,38 @@ export async function prepareRelease(options) {
     // Snapshot gates always run on disposable writable copies. The public
     // snapshot authority is re-digested after every gate and is never exposed
     // as the gate working directory.
-    const snapshotGateResults = await runSnapshotVerificationGates({
-      gates: declaredVerificationGates,
-      unitResults,
-      runDir,
-      evidence,
-      env: options.gateEnv ?? process.env,
-    });
-    await evidence.append({
-      phase: 'snapshot-verify',
-      status: 'completed',
-      gateCount: snapshotGateResults.length,
-    });
+    // docs/config/marketplace workflows trim snapshot-verify gates (H5):
+    // they are declared code-class gates that a non-code change surface
+    // cannot exercise. Consumer-verify gates (phase 'consumer-verify') are
+    // NOT part of this skip — they run during verify regardless of workflow.
+    if (skipSnapshotVerifyGates) {
+      await evidence.append({
+        phase: 'snapshot-verify',
+        status: 'skipped',
+        reason: `workflow "${workflow}" trims snapshot-verify gates; declared gates: ${declaredVerificationGates.length}`,
+      });
+    } else {
+      const snapshotGateResults = await runSnapshotVerificationGates({
+        gates: declaredVerificationGates,
+        unitResults,
+        runDir,
+        evidence,
+        env: options.gateEnv ?? process.env,
+      });
+      await evidence.append({
+        phase: 'snapshot-verify',
+        status: 'completed',
+        gateCount: snapshotGateResults.length,
+      });
+    }
 
     // Bind the remote source-authority proof to the exact bytes that entered
     // the frozen snapshots, not merely to an earlier read of the workspace.
     // Then re-read the complete closure and dirty state once more so version
     // sources and non-snapshot closure entries cannot drift during prepare.
-    if (production) {
+    // Trimmed together with Step 3c when a docs/config/marketplace workflow
+    // skips the source-authority closure.
+    if (production && !skipSourceAuthorityClosure) {
       const snapshotSourceResult = verifySnapshotSourcesMatchClosure({
         closure: sourceInputClosure,
         unitResults,
@@ -2463,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
@@ -2502,59 +2833,72 @@ export async function prepareRelease(options) {
     // publish will re-verify, rather than the writable pre-freeze staging tree.
     // Non-production plans scan the final staging tree at the same point.
     // This gate is built in, read-only, and cannot be disabled by overlays.
+    // docs/config/marketplace workflows trim it (H5): the plan omits
+    // `skillResourceClosure` entirely, so publish's conditional re-check
+    // (guarded by plan.skillResourceClosure) and verify's receipt comparison
+    // both skip it consistently. The trim is recorded in workflowDecision.
     const skillResourceClosureResults = [];
-    for (const { unit, manifest } of unitResults) {
+    if (skipSkillResourceClosure) {
       await evidence.append({
         phase: 'skill-resource-closure',
-        status: 'started',
-        unitId: unit.id,
+        status: 'skipped',
+        reason: `workflow "${workflow}" trims the skill resource closure gate`,
+        unitCount: unitResults.length,
       });
+    } else {
+      for (const { unit, manifest } of unitResults) {
+        await evidence.append({
+          phase: 'skill-resource-closure',
+          status: 'started',
+          unitId: unit.id,
+        });
 
-      const closureResult = await checkSkillResourceClosure({
-        snapshotDir: manifest.outputDir,
-        host: 'root',
-      });
+        const closureResult = await checkSkillResourceClosure({
+          snapshotDir: manifest.outputDir,
+          host: 'root',
+        });
 
-      const receipt = createSkillResourceClosureReceipt(closureResult, { unitId: unit.id });
-      skillResourceClosureResults.push(receipt);
+        const receipt = createSkillResourceClosureReceipt(closureResult, { unitId: unit.id });
+        skillResourceClosureResults.push(receipt);
+
+        if (closureResult.findings.length > 0) {
+          await evidence.append({
+            phase: 'skill-resource-closure',
+            status: 'blocking',
+            unitId: unit.id,
+            findingCount: closureResult.findings.length,
+            findings: closureResult.findings.map((f) => ({
+              skill: f.skill,
+              line: f.line,
+              reference: f.reference,
+              classification: f.classification,
+              code: f.code,
+            })),
+          });
+          throw new ReleaseError(
+            GATE_FAILED,
+            `skill resource closure gate failed for unit "${unit.id}": ${closureResult.findings.length} finding(s)`,
+            {
+              unitId: unit.id,
+              findingCount: closureResult.findings.length,
+              findings: closureResult.findings,
+            },
+          );
+        }
 
-      if (closureResult.findings.length > 0) {
         await evidence.append({
           phase: 'skill-resource-closure',
-          status: 'blocking',
+          status: 'completed',
           unitId: unit.id,
-          findingCount: closureResult.findings.length,
-          findings: closureResult.findings.map((f) => ({
-            skill: f.skill,
-            line: f.line,
-            reference: f.reference,
-            classification: f.classification,
-            code: f.code,
-          })),
+          checkerVersion: closureResult.checkerVersion,
+          surfaceCount: receipt.surfaceCount,
+          skillCount: receipt.skillCount,
+          referenceCount: closureResult.referenceCount,
+          sourceOnlyCount: closureResult.sourceOnlyCount,
+          findingCount: 0,
+          receiptDigest: closureResult.receiptDigest,
         });
-        throw new ReleaseError(
-          GATE_FAILED,
-          `skill resource closure gate failed for unit "${unit.id}": ${closureResult.findings.length} finding(s)`,
-          {
-            unitId: unit.id,
-            findingCount: closureResult.findings.length,
-            findings: closureResult.findings,
-          },
-        );
       }
-
-      await evidence.append({
-        phase: 'skill-resource-closure',
-        status: 'completed',
-        unitId: unit.id,
-        checkerVersion: closureResult.checkerVersion,
-        surfaceCount: receipt.surfaceCount,
-        skillCount: receipt.skillCount,
-        referenceCount: closureResult.referenceCount,
-        sourceOnlyCount: closureResult.sourceOnlyCount,
-        findingCount: 0,
-        receiptDigest: closureResult.receiptDigest,
-      });
     }
 
     // Freeze external independent marketplace HEADs (production + online only):
@@ -2887,20 +3231,114 @@ export async function prepareRelease(options) {
     // 构建冻结分发映射：unitId -> frozen distributions
     const frozenDistributionsMap = new Map(units.map((u) => [u.id, u.distributions]));
 
-    const externalActions = buildExternalActions(unitResults, resolvedVersions, productionAssets, externalMarketplaceFreezes, frozenDistributionsMap);
+    let externalActions = buildExternalActions(unitResults, resolvedVersions, productionAssets, externalMarketplaceFreezes, frozenDistributionsMap);
 
     // Compute overall snapshot digest
     const overallSnapshotDigest = sha256Hex(snapshotDigests.join(':'));
 
+    // --- Step 6b: Workflow decision (H5) ---
+    // config workflow: compare per-unit snapshotDigests with the latest
+    // frozen plan. Identical public bytes → no publish path (all publish-class
+    // external actions are dropped from the plan, so approve/publish execute
+    // nothing). No comparable plan or any byte difference → publish-needed
+    // (fail-safe). The decision is bound into the plan digest as
+    // `workflowDecision`, making the trim immutable and auditable.
+    let workflowDecision = null;
+    if (workflow === 'config') {
+      const previousPlan = await readLatestFrozenPlan(realRoot);
+      let publishPath;
+      let decision;
+      if (!previousPlan) {
+        publishPath = 'publish-needed';
+        decision = 'indeterminable';
+      } else {
+        const prevDigests = new Map(
+          (previousPlan.plan.units ?? []).map((u) => [u.id, u.snapshotDigest]),
+        );
+        const unchanged =
+          units.length > 0 && units.every((u) => prevDigests.get(u.id) === u.snapshotDigest);
+        publishPath = unchanged ? 'no-publish-needed' : 'publish-needed';
+        decision = unchanged ? 'public-bytes-unchanged' : 'public-bytes-changed';
+      }
+      workflowDecision = {
+        workflowKind: workflow,
+        decision,
+        publishPath,
+        trimmedGates: [
+          'declared-hooks',
+          'snapshot-verify-gates',
+          'source-authority-closure',
+          'skill-resource-closure',
+        ],
+        ...(previousPlan ? { comparedPlan: previousPlan.fileName } : {}),
+      };
+      if (publishPath === 'no-publish-needed') {
+        externalActions = [];
+      }
+      await evidence.append({
+        phase: 'workflow-decision',
+        status: publishPath,
+        decision,
+        ...(previousPlan ? { comparedPlan: previousPlan.fileName } : {}),
+        actionCount: externalActions.length,
+      });
+    } else if (trimmedWorkflow) {
+      workflowDecision = {
+        workflowKind: workflow,
+        decision: 'code-gates-trimmed',
+        publishPath: 'publish-needed',
+        trimmedGates: [
+          'declared-hooks',
+          'snapshot-verify-gates',
+          'source-authority-closure',
+          'skill-resource-closure',
+        ],
+      };
+      await evidence.append({
+        phase: 'workflow-decision',
+        status: 'publish-needed',
+        decision: 'code-gates-trimmed',
+      });
+    }
+
     // Detect human consumer platforms (Kimi/CodeBuddy) in the plan.
     // When present, new plans mark them as non-blocking manual follow-up tasks.
     const hasHumanConsumerActions = externalActions.some(
       (a) => a.type === 'kimi-marketplace-install' || a.type === 'codebuddy-marketplace-install',
     );
 
+    // --- Fold the validated postPublish declaration into the frozen plan ---
+    // Bindings: tag (tagTemplate rendered at the resolved target version —
+    // the same computation create-tag will use), tagCommit (the frozen
+    // production asset commit the tag will point at; only production
+    // prepares can freeze it — distribute fails closed when it is absent),
+    // unitId (declaring unit), and payloadSource "tag-worktree" (R1 timing
+    // contract: payload may only come from the detached worktree at
+    // tagCommit, never from workspace state). planVersion 2 record-layer
+    // stripping does not strip this block, so every declaration detail is
+    // bound into the plan digest.
+    let frozenPostPublish = null;
+    if (postPublishDeclaration) {
+      const { unit, index } = postPublishDeclaration;
+      const { tag } = resolveProductionBranch(unit, resolvedVersions[index]);
+      frozenPostPublish = {
+        ...structuredClone(unit.postPublish),
+        tag,
+        ...(productionAssets ? { tagCommit: productionAssets[index].commit } : {}),
+        unitId: unit.id,
+        payloadSource: PAYLOAD_SOURCE_TAG_WORKTREE,
+      };
+    }
+
     const plan = {
       planVersion: 2,
       status: 'PREPARED',
+      // Workflow profile (H5): 'full' for the complete gate set;
+      // 'docs'/'config'/'marketplace' for trimmed code-class gates. Both
+      // fields are binding-layer (not stripped from the plan digest), so the
+      // trim is frozen immutably with the plan.
+      workflowKind: workflow,
+      ...(workflowDecision ? { workflowDecision } : {}),
       baseline: {
         gitTreeHash: baseline.gitTreeHash,
         headCommit: baseline.gitHead,
@@ -2910,14 +3348,18 @@ export async function prepareRelease(options) {
         capturedAt: baseline.capturedAt,
       },
       configDigest,
-      skillResourceClosure: {
-        checkerVersion: SKILL_RESOURCE_CHECKER_VERSION,
-        unitReceipts: skillResourceClosureResults,
-        totalSkillCount: skillResourceClosureResults.reduce((sum, item) => sum + item.skillCount, 0),
-        totalReferenceCount: skillResourceClosureResults.reduce((sum, item) => sum + item.referenceCount, 0),
-        totalSourceOnlyCount: skillResourceClosureResults.reduce((sum, item) => sum + item.sourceOnlyCount, 0),
-        totalFindingCount: 0,
-      },
+      ...(skillResourceClosureResults.length > 0
+        ? {
+            skillResourceClosure: {
+              checkerVersion: SKILL_RESOURCE_CHECKER_VERSION,
+              unitReceipts: skillResourceClosureResults,
+              totalSkillCount: skillResourceClosureResults.reduce((sum, item) => sum + item.skillCount, 0),
+              totalReferenceCount: skillResourceClosureResults.reduce((sum, item) => sum + item.referenceCount, 0),
+              totalSourceOnlyCount: skillResourceClosureResults.reduce((sum, item) => sum + item.sourceOnlyCount, 0),
+              totalFindingCount: 0,
+            },
+          }
+        : {}),
       verificationGates: config.verificationGates ?? [],
       snapshotDigest: overallSnapshotDigest,
       ...(hasHumanConsumerActions ? { humanConsumersStrategy: 'manualFollowUps' } : {}),
@@ -2929,6 +3371,7 @@ export async function prepareRelease(options) {
       } : {}),
       units,
       externalActions,
+      ...(frozenPostPublish ? { postPublish: frozenPostPublish } : {}),
       ...(sourceAuthority ? { sourceAuthority } : {}),
       createdAt: production ? createdAtTimestamp : (clock ? clock() : new Date().toISOString()),
     };
@@ -2958,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',
@@ -2968,6 +3431,8 @@ export async function prepareRelease(options) {
       unitCount: units.length,
       actionCount: externalActions.length,
       offline,
+      workflowKind: workflow,
+      ...(workflowDecision ? { workflowDecision } : {}),
       completedAt: (clock ? clock() : new Date().toISOString()),
     });