release-skill 0.6.2 → 0.6.3

package/src/core/derived-artifact-gates.mjs

@@ -0,0 +1,258 @@
+/**
+ * Version-sensitive derived-artifact fast pre-gates (O1, 2026-08-18
+ * release-cycle investigation §3.2).
+ *
+ * In the 0.6.1 cycle two prepares burned the full ~80s test hook before
+ * surfacing drift that a sub-second check could have caught: adapter trees
+ * out of sync with skills-src/, and self-bootstrap fact pins still bound to
+ * the previous version. This module promotes those two exact checks to
+ * prepare's earliest stage, alongside the bundle freshness gate:
+ *
+ * - adapter gate: runs `scripts/build-adapters.mjs --check` (drift list,
+ *   exit 1 on drift — the same supported check the scripts surface offers);
+ * - fact-pin gate: runs the version fact pins of
+ *   `test/release-docs-self-bootstrap.test.mjs` — exactly its hermetic
+ *   section 1 (`[self-bootstrap 1*]`: byte-level version assertions plus the
+ *   in-process read-only planner), scoped via `--test-name-pattern`.
+ *
+ * Both promote the CANONICAL check logic — the gate and the full pipeline
+ * can never disagree about what "in sync" means. The facts gate is scoped to
+ * the suite's hermetic fact-pin section deliberately: the suite's remaining
+ * sections shell out to npm/git and drive fixture prepares, which would make
+ * a "fast pre-gate" slow, recursive, and brittle under toolchain-shimming
+ * fixtures (a prepare invoked with a shimmed `npm` would crash the gate
+ * child and false-report drift). Those sections remain the full test hooks'
+ * job — this gate never replaces them. Every failure message therefore
+ * states the boundary explicitly: this is a fast pre-gate and does NOT
+ * replace the full test hooks（快速前置，不替代全量测试）.
+ *
+ * Spawn hygiene: the child environment drops NODE_TEST_CONTEXT. When prepare
+ * itself runs inside a node:test harness, the runner exports that variable,
+ * and an inheriting `node --test` child then prints "run() is being called
+ * recursively ... skipping running files" and exits 0 — a false pass this
+ * gate must never report as fresh. Production prepare runs in a plain shell
+ * where the variable is absent, so the sanitization is a pure hardening.
+ *
+ * Recursion guard: the facts gate spawns the very suite whose fixture
+ * prepares call prepareRelease — an unguarded child would re-enter the gate
+ * and recurse without bound (every level waits on its own child until the
+ * 300s timeouts cascade). Gate children therefore carry
+ * RELEASE_SKILL_FACTS_GATE_ACTIVE; a facts gate running under the marker
+ * records not-applicable (reason nested-gate-run) and spawns nothing. Only
+ * the facts gate needs the guard: the adapter child (build-adapters --check)
+ * never calls prepareRelease. The outermost prepare still enforces both
+ * gates; only the verification run itself is exempt.
+ *
+ * Applicability mirrors bundle-freshness: installed distributions ship
+ * neither the build scripts nor the test file, so the gates record
+ * not-applicable there; a source checkout is always gated.
+ *
+ * @module core/derived-artifact-gates
+ */
+
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { ReleaseError, DERIVED_ARTIFACT_STALE } from './errors.mjs';
+import { boundedOutputTail } from './bounded-output.mjs';
+
+const defaultExecFile = promisify(execFileCb);
+
+/**
+ * Exact bilingual note every pre-gate failure carries: the gates are a fast
+ * front line and never a substitute for the full test hooks.
+ */
+export const DERIVED_ARTIFACT_PREGATE_NOTE =
+  'This is a fast pre-gate and does not replace the full test hooks（快速前置，不替代全量测试）.';
+
+/** One-click derived-artifact sync suggested by every drift remediation (O2). */
+export const DERIVED_SYNC_COMMAND = 'node scripts/sync-derived-artifacts.mjs';
+
+/**
+ * Marker every gate child carries. A facts gate running under it is part of
+ * the verification run itself and records not-applicable instead of
+ * re-spawning the suite (recursion guard, see module docs).
+ */
+export const FACTS_GATE_NESTED_ENV = 'RELEASE_SKILL_FACTS_GATE_ACTIVE';
+
+/** Gate descriptors: marker file (applicability), argv, remediation text. */
+const GATES = Object.freeze({
+  adapters: Object.freeze({
+    artifact: 'adapters',
+    marker: join('scripts', 'build-adapters.mjs'),
+    argv: (pkgRoot) => [join(pkgRoot, 'scripts', 'build-adapters.mjs'), '--check'],
+    timeoutMs: 120000,
+    remediation:
+      'Rebuild the existing adapters with: node scripts/build-adapters.mjs --apply ' +
+      `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
+  }),
+  'self-bootstrap-facts': Object.freeze({
+    artifact: 'self-bootstrap-facts',
+    marker: join('test', 'release-docs-self-bootstrap.test.mjs'),
+    // Hermetic fact-pin section only (see module docs): byte-level version
+    // facts + in-process planner — no npm/git, no fixture prepares.
+    argv: (pkgRoot) => [
+      '--test',
+      '--test-name-pattern',
+      '\\[self-bootstrap 1',
+      join(pkgRoot, 'test', 'release-docs-self-bootstrap.test.mjs'),
+    ],
+    timeoutMs: 120000,
+    remediation:
+      'Refresh the derived documents and version points first ' +
+      `(workspace root: ${DERIVED_SYNC_COMMAND}); if the pins still fail, update the fact pins deliberately — ` +
+      'the gate never edits sources or test pins itself.',
+  }),
+});
+
+async function isFile(path) {
+  try {
+    return (await lstat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run one derived-artifact check (pure decision, never throws).
+ *
+ * @param {'adapters' | 'self-bootstrap-facts'} kind - Gate to run.
+ * @param {string} pkgRoot - Absolute package root of the running checkout.
+ * @param {object} [options]
+ * @param {Function} [options.execFileFn] - execFile seam (tests).
+ * @param {number} [options.timeoutMs] - Child timeout override.
+ * @returns {Promise<{
+ *   applicable: boolean,
+ *   fresh?: boolean,
+ *   reason?: string,
+ *   artifact?: string,
+ *   exitCode?: number | null,
+ *   stdoutTail?: string,
+ *   stderrTail?: string,
+ *   durationMs?: number,
+ * }>} stdoutTail/stderrTail are bounded and present on BOTH outcomes —
+ * on the fresh path they prove the child really executed (e.g. the facts
+ * gate carries the child suite's own `ℹ tests N` summary).
+ */
+export async function checkDerivedArtifactGate(kind, pkgRoot, options = {}) {
+  const gate = GATES[kind];
+  if (!gate) {
+    throw new ReleaseError(DERIVED_ARTIFACT_STALE, `unknown derived-artifact gate: ${kind}`, { kind });
+  }
+  const execFileFn = options.execFileFn ?? defaultExecFile;
+
+  if (kind === 'self-bootstrap-facts' && process.env[FACTS_GATE_NESTED_ENV]) {
+    // Recursion guard: this prepare runs inside a gate child (the suite the
+    // facts gate itself spawns). Re-spawning would recurse without bound;
+    // the outermost prepare already enforces the gate for this checkout.
+    return { applicable: false, reason: 'nested-gate-run', artifact: gate.artifact };
+  }
+
+  if (!(await isFile(join(pkgRoot, gate.marker)))) {
+    // Installed distributions ship neither the build scripts nor the test
+    // file; drift is a source-checkout concern only (bundle-freshness rule).
+    return { applicable: false, reason: 'installed-layout', artifact: gate.artifact };
+  }
+
+  const startedAt = Date.now();
+  // Never hand the child a test-runner context: under a nested node:test
+  // harness NODE_TEST_CONTEXT makes `node --test` skip all files and exit 0,
+  // which this gate must not report as fresh (false pass).
+  const childEnv = { ...process.env };
+  delete childEnv.NODE_TEST_CONTEXT;
+  childEnv[FACTS_GATE_NESTED_ENV] = '1';
+  try {
+    const { stdout, stderr } = await execFileFn(process.execPath, gate.argv(pkgRoot), {
+      cwd: pkgRoot,
+      shell: false,
+      encoding: 'utf8',
+      timeout: options.timeoutMs ?? gate.timeoutMs,
+      env: childEnv,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return {
+      applicable: true,
+      fresh: true,
+      artifact: gate.artifact,
+      stdoutTail: boundedOutputTail(stdout ?? ''),
+      stderrTail: boundedOutputTail(stderr ?? ''),
+      durationMs: Date.now() - startedAt,
+    };
+  } catch (err) {
+    // Timeout / spawn failure fail closed too: an undecidable gate is drift.
+    const stdoutTail = boundedOutputTail(err?.stdout ?? '');
+    const stderrTail = boundedOutputTail(err?.stderr ?? err?.message ?? '');
+    return {
+      applicable: true,
+      fresh: false,
+      reason: err?.killed || err?.code === 'ETIMEDOUT' ? 'timeout' : 'drift',
+      artifact: gate.artifact,
+      exitCode: typeof err?.code === 'number' ? err.code : null,
+      stdoutTail,
+      stderrTail,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+}
+
+/** Adapter freshness decision (build-adapters --check). */
+export function checkAdapterFreshness(pkgRoot, options = {}) {
+  return checkDerivedArtifactGate('adapters', pkgRoot, options);
+}
+
+/** Self-bootstrap fact-pin decision (single-file test). */
+export function checkSelfBootstrapFacts(pkgRoot, options = {}) {
+  return checkDerivedArtifactGate('self-bootstrap-facts', pkgRoot, options);
+}
+
+async function assertGate(kind, pkgRoot, options = {}) {
+  const result = await checkDerivedArtifactGate(kind, pkgRoot, options);
+  if (!result.applicable || result.fresh) {
+    return result;
+  }
+  const gate = GATES[kind];
+  const subject = kind === 'adapters'
+    ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
+    : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+  throw new ReleaseError(
+    DERIVED_ARTIFACT_STALE,
+    `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE} ${gate.remediation}`,
+    {
+      artifact: result.artifact,
+      reason: result.reason,
+      exitCode: result.exitCode,
+      stdoutTail: result.stdoutTail,
+      stderrTail: result.stderrTail,
+      durationMs: result.durationMs,
+    },
+  );
+}
+
+/**
+ * Fail-closed adapter pre-gate used by prepare's earliest stage.
+ * Not-applicable layouts return quietly; drift throws DERIVED_ARTIFACT_STALE.
+ *
+ * @param {string} pkgRoot - Absolute package root.
+ * @param {object} [options] - execFileFn/timeoutMs seams (tests).
+ * @returns {Promise<object>} The gate decision.
+ * @throws {ReleaseError} DERIVED_ARTIFACT_STALE on drift/timeout.
+ */
+export function assertAdapterFreshness(pkgRoot, options = {}) {
+  return assertGate('adapters', pkgRoot, options);
+}
+
+/**
+ * Fail-closed self-bootstrap fact-pin pre-gate used by prepare's earliest
+ * stage. Not-applicable layouts return quietly; drift throws
+ * DERIVED_ARTIFACT_STALE.
+ *
+ * @param {string} pkgRoot - Absolute package root.
+ * @param {object} [options] - execFileFn/timeoutMs seams (tests).
+ * @returns {Promise<object>} The gate decision.
+ * @throws {ReleaseError} DERIVED_ARTIFACT_STALE on drift/timeout.
+ */
+export function assertSelfBootstrapFacts(pkgRoot, options = {}) {
+  return assertGate('self-bootstrap-facts', pkgRoot, options);
+}

package/src/core/docs-refresh-preset.mjs

@@ -0,0 +1,167 @@
+/**
+ * docs-refresh preset: refresh one or more independent docs repositories
+ * (v0.6.3 R4, design §2.5).
+ *
+ * GitHub-Pages-style docs sites live in their own repositories. One
+ * declaration refreshes ALL of them (config.repositories array) from the
+ * frozen release payload:
+ *
+ * - config.mappings copies payload files into the docs repository
+ *   (from = payload-relative source, to = repository-relative destination);
+ *   an optional per-mapping versionMarker placeholder is replaced with the
+ *   frozen release version while writing (version-marker replacement);
+ * - config.gates (argument arrays, R1 hook runner) run inside each docs
+ *   repository AFTER the write and BEFORE any commit/push — the docs build
+ *   gate; a failing gate leaves zero remote side effects;
+ * - every repository is committed with the frozen bot identity and pushed
+ *   (never --force); byte-identical content -> NO_CHANGE (idempotent).
+ *
+ * Payload requirement: mappings read the materialized payload, which only
+ * exists in the distribute phase (§2.3 contexts carry payloadDir there); a
+ * postVerify-phase declaration fails closed with a clear message.
+ *
+ * @module core/docs-refresh-preset
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { applyDownstreamGitChange } from './preset-gitwrite.mjs';
+
+/**
+ * Assert `from` stays inside the materialized payload directory (declaration
+ * validation guarantees a safe relative shape; this is the execution-time
+ * re-check).
+ */
+function resolvePayloadSource(payloadDir, from) {
+  const sourcePath = resolve(payloadDir, from);
+  const rel = relative(payloadDir, sourcePath);
+  if (rel === '' || isAbsolute(rel) || rel === '..'
+    || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `docs-refresh mapping source "${from}" escapes the payload directory`,
+      { from },
+    );
+  }
+  return sourcePath;
+}
+
+/**
+ * Execute one docs-refresh preset hook end-to-end: for every declared docs
+ * repository, copy the mapped payload files (version-marker replacement),
+ * run the docs build gates, and push. Shared by distribute and postVerify
+ * (payload requirement effectively binds it to the distribute phase).
+ *
+ * @param {object} params
+ * @param {object} params.hook - Declared hook entry (config bound).
+ * @param {object} params.contextProjection - The §2.3 context projection.
+ * @param {object} params.commitIdentity - Frozen commitIdentity.
+ * @param {string} params.payloadDir - Materialized payload directory
+ *   (distribute phase; postVerify contexts never carry it).
+ * @param {string} params.root - Release workspace root.
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @param {Function} [params.hookRunner] - Injectable gate runner (tests).
+ * @returns {Promise<{ status: string, observation: object,
+ *   observations: object[], mode: string }>}
+ */
+export async function executeDocsRefreshHook(params) {
+  const { hook, contextProjection, commitIdentity, payloadDir, root, exec, hookRunner } = params ?? {};
+  const config = hook?.config;
+  const repositories = config?.repositories;
+  if (!Array.isArray(repositories) || repositories.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'docs-refresh requires a non-empty config.repositories array');
+  }
+  const mappings = config?.mappings;
+  if (!Array.isArray(mappings) || mappings.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'docs-refresh requires a non-empty config.mappings array');
+  }
+  if (typeof payloadDir !== 'string' || payloadDir.length === 0) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'docs-refresh copies files from the materialized payload, which only exists in the distribute phase; declare phase: distribute (the default) instead of postVerify',
+      {},
+    );
+  }
+
+  const unitId = contextProjection?.unitId ?? 'unknown';
+  const version = contextProjection?.version ?? 'unknown';
+  const gates = config?.gates ?? [];
+
+  // Deterministic per-mapping write. Binary-safe copy; the version-marker
+  // replacement (when declared) treats the file as UTF-8 text.
+  const mutate = async (worktree) => {
+    for (const mapping of mappings) {
+      const sourcePath = resolvePayloadSource(payloadDir, mapping.from);
+      let content = await readFile(sourcePath).catch(() => null);
+      if (content === null) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `docs-refresh mapping source "${mapping.from}" is missing from the materialized payload`,
+          { from: mapping.from },
+        );
+      }
+      if (typeof mapping.versionMarker === 'string' && mapping.versionMarker.length > 0) {
+        const text = content.toString('utf8');
+        content = Buffer.from(text.split(mapping.versionMarker).join(version), 'utf8');
+      }
+      const destination = join(worktree, mapping.to);
+      await mkdir(dirname(destination), { recursive: true });
+      await writeFile(destination, content);
+    }
+  };
+
+  const observations = [];
+  let anyChange = false;
+  for (const [index, target] of repositories.entries()) {
+    let result;
+    try {
+      result = await applyDownstreamGitChange({
+        target,
+        commitIdentity,
+        commitSubject: `release-skill docs-refresh ${unitId} ${version}`,
+        mutate,
+        gates,
+        contextProjection,
+        root,
+        ...(exec !== undefined ? { exec } : {}),
+        ...(hookRunner !== undefined ? { hookRunner } : {}),
+      });
+    } catch (err) {
+      throw new ReleaseError(
+        err?.code ?? GATE_FAILED,
+        `docs-refresh repository ${index + 1} of ${repositories.length} failed: ${err?.message ?? err}`,
+        { repositoryIndex: index, ...(err?.details ?? {}) },
+      );
+    }
+    observations.push({
+      repositoryIndex: index,
+      ...(typeof target.remoteUrl === 'string' ? { remoteUrl: target.remoteUrl } : {}),
+      ...(typeof target.workspace === 'string' ? { workspace: target.workspace } : {}),
+      branch: target.branch,
+      ...(result.observation ?? {}),
+    });
+    if (result.status === 'EXECUTED') anyChange = true;
+  }
+
+  if (!anyChange) {
+    return {
+      status: 'NO_CHANGE',
+      mode: 'no-change',
+      observation: { mode: 'no-change' },
+      observations,
+    };
+  }
+  const firstPushed = observations.find((entry) => entry.mode === 'pushed');
+  return {
+    status: 'EXECUTED',
+    mode: 'pushed',
+    observation: {
+      mode: 'pushed',
+      ...(firstPushed?.pushedCommit ? { pushedCommit: firstPushed.pushedCommit } : {}),
+      repositoryCount: repositories.length,
+    },
+    observations,
+  };
+}

package/src/core/errors.mjs

@@ -95,6 +95,8 @@ const EXIT_CODE_MAP = Object.freeze({
   CONTENT_MISMATCH: 52,
   DIRTY_SOURCE_INPUT: 53,
   BUNDLE_STALE: 54,
+  POSTPUBLISH_HOOK_INVALID: 55,
+  DERIVED_ARTIFACT_STALE: 56,
 });
 
 // ---- Error code constants ----
@@ -144,6 +146,8 @@ export const NOT_DEFAULT = 'NOT_DEFAULT';
 export const CONTENT_MISMATCH = 'CONTENT_MISMATCH';
 export const DIRTY_SOURCE_INPUT = 'DIRTY_SOURCE_INPUT';
 export const BUNDLE_STALE = 'BUNDLE_STALE';
+export const POSTPUBLISH_HOOK_INVALID = 'POSTPUBLISH_HOOK_INVALID';
+export const DERIVED_ARTIFACT_STALE = 'DERIVED_ARTIFACT_STALE';
 
 /**
  * Typed error for release-skill operations.

package/src/core/hooks.mjs

@@ -197,6 +197,10 @@ function buildFilteredEnv(envAllowlist, contextEnv) {
  * @param {Object} context
  * @param {string} context.root           - Absolute project root.
  * @param {Record<string, string>} [context.env] - Extra env variables.
+ * @param {Record<string, string>} [context.injectEnv] - Always-injected
+ *   contract variables (merged AFTER allowlist filtering; used by the
+ *   postPublish hook context contract RELEASE_SKILL_POSTPUBLISH_CONTEXT).
+ *   Keys must match /^[A-Z_][A-Z0-9_]*$/, values must be strings.
  *
  * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
  *
@@ -233,6 +237,30 @@ export async function runHook(hook, context) {
   // --- Build safe environment ---
   const env = buildFilteredEnv(envAllowlist, context.env);
 
+  // --- Always-injected contract variables (postPublish context, v0.6.3 R1).
+  // Merged after allowlist filtering: declarations cannot be mutated to carry
+  // the context variable, and the runner must not depend on envAllowlist.
+  if (context.injectEnv !== undefined) {
+    if (!context.injectEnv || typeof context.injectEnv !== 'object' || Array.isArray(context.injectEnv)) {
+      throw new ReleaseError('INVALID_HOOK', 'context.injectEnv must be a plain object');
+    }
+    for (const [key, value] of Object.entries(context.injectEnv)) {
+      if (!ENV_KEY_PATTERN.test(key)) {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          `context.injectEnv key "${key}" must match /^[A-Z_][A-Z0-9_]*$/`,
+        );
+      }
+      if (typeof value !== 'string') {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          `context.injectEnv value for "${key}" must be a string`,
+        );
+      }
+      env[key] = value;
+    }
+  }
+
   // --- Set up timeout ---
   const executable = command[0];
   const args = command.slice(1);

package/src/core/marketplace-registry-entry.mjs

@@ -0,0 +1,174 @@
+/**
+ * marketplace-registry-entry preset: direct-edit downstream registry entry
+ * update (v0.6.3 R4, design §2.5).
+ *
+ * For downstream marketplaces WITHOUT their own governance/render pipeline:
+ * locate the registry entry by config.entryKey inside config.registryPath,
+ * update the declared fieldsFromPlan from the FROZEN plan values (§2.3
+ * context projection), run the declared downstream gates (argument arrays via
+ * the R1 hook runner), then push. Hubs with their own governance use
+ * proposal-inbox instead.
+ *
+ * Registry document shape (canonical, validated fail-closed):
+ * { "entries": [ { "key": "<entryKey>", ...fields } ] }
+ * - a missing registry file, a missing/malformed `entries` array, or a
+ *   missing entry key is REMOTE_CONFLICT: the downstream state disagrees
+ *   with the declaration and a human decides (nothing is ever invented);
+ * - the updated document is serialized deterministically (2-space indent +
+ *   trailing newline): byte-identical output -> NO_CHANGE (idempotent);
+ * - every other entry and field is preserved untouched.
+ *
+ * fieldsFromPlan maps entry field -> §2.3 context field; only frozen plan
+ * values are ever written (version/tag/commit/tree/manifestDigest/planDigest/
+ * publishedAt/unitId). A source value absent from the frozen plan fails
+ * closed before any write.
+ *
+ * @module core/marketplace-registry-entry
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { ReleaseError, GATE_FAILED, REMOTE_CONFLICT } from './errors.mjs';
+import { FIELDS_FROM_PLAN_SOURCES } from './presets.mjs';
+import { applyDownstreamGitChange } from './preset-gitwrite.mjs';
+
+export { FIELDS_FROM_PLAN_SOURCES };
+
+/**
+ * Apply the frozen-plan field update to one registry document. Pure and
+ * deterministic: returns the updated document, or throws when the document
+ * shape or the entry disagrees with the declaration.
+ *
+ * @param {object} registry - Parsed registry document.
+ * @param {object} params - { entryKey, fieldsFromPlan, contextProjection }.
+ * @returns {object} The updated registry document (new object).
+ * @throws {ReleaseError} REMOTE_CONFLICT when the entry cannot be located;
+ *   GATE_FAILED when a frozen source value is missing.
+ */
+export function updateRegistryEntry(registry, params) {
+  const { entryKey, fieldsFromPlan, contextProjection } = params ?? {};
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new ReleaseError(REMOTE_CONFLICT, 'marketplace registry file is not a JSON object; human decision required', {});
+  }
+  if (!Array.isArray(registry.entries)) {
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      'marketplace registry file carries no "entries" array; the marketplace-registry-entry preset expects { "entries": [ { "key": ... } ] }',
+      {},
+    );
+  }
+  const entryIndex = registry.entries.findIndex(
+    (entry) => entry && typeof entry === 'object' && !Array.isArray(entry) && entry.key === entryKey,
+  );
+  if (entryIndex < 0) {
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      `marketplace registry entry "${entryKey}" not found; registering a new entry requires a human decision`,
+      { entryKey },
+    );
+  }
+
+  const updated = JSON.parse(JSON.stringify(registry)); // deep, order-stable copy
+  const entry = updated.entries[entryIndex];
+  for (const [entryField, sourceField] of Object.entries(fieldsFromPlan)) {
+    const value = contextProjection?.[sourceField];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `fieldsFromPlan."${entryField}" maps to context field "${sourceField}" which the frozen plan does not provide`,
+        { entryField, sourceField },
+      );
+    }
+    entry[entryField] = value;
+  }
+  return updated;
+}
+
+/** Deterministic registry serialization (byte-stable NO_CHANGE detection). */
+export function serializeRegistry(registry) {
+  return `${JSON.stringify(registry, null, 2)}\n`;
+}
+
+/**
+ * Execute one marketplace-registry-entry preset hook end-to-end: read the
+ * downstream registry, apply the frozen-plan update, run the downstream
+ * gates, and push (never --force). Shared by distribute and postVerify.
+ *
+ * @param {object} params
+ * @param {object} params.hook - Declared hook entry (config bound).
+ * @param {object} params.contextProjection - The §2.3 context projection.
+ * @param {object} params.commitIdentity - Frozen commitIdentity.
+ * @param {string} params.root - Release workspace root.
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @param {Function} [params.hookRunner] - Injectable gate runner (tests).
+ * @returns {Promise<{ status: string, observation: object, registryPath: string }>}
+ */
+export async function executeMarketplaceRegistryEntryHook(params) {
+  const { hook, contextProjection, commitIdentity, root, exec, hookRunner } = params ?? {};
+  const config = hook?.config;
+  const target = config?.target;
+  if (!target || typeof target.branch !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires config.target with a branch');
+  }
+  const registryPath = config?.registryPath ?? 'registry.json';
+  const entryKey = config?.entryKey;
+  const fieldsFromPlan = config?.fieldsFromPlan;
+  if (typeof entryKey !== 'string' || entryKey.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires config.entryKey');
+  }
+  if (!fieldsFromPlan || typeof fieldsFromPlan !== 'object' || Object.keys(fieldsFromPlan).length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires a non-empty config.fieldsFromPlan');
+  }
+
+  const unitId = contextProjection?.unitId ?? 'unknown';
+  const version = contextProjection?.version ?? 'unknown';
+
+  let currentText = null;
+  const mutate = async (worktree) => {
+    const absoluteRegistry = join(worktree, registryPath);
+    let raw;
+    try {
+      raw = await readFile(absoluteRegistry, 'utf8');
+    } catch {
+      throw new ReleaseError(
+        REMOTE_CONFLICT,
+        `marketplace registry file "${registryPath}" is missing in the downstream repository; creating it requires a human decision`,
+        { registryPath },
+      );
+    }
+    currentText = raw;
+    let registry;
+    try {
+      registry = JSON.parse(raw);
+    } catch {
+      throw new ReleaseError(
+        REMOTE_CONFLICT,
+        `marketplace registry file "${registryPath}" is not valid JSON; human decision required`,
+        { registryPath },
+      );
+    }
+    const updated = updateRegistryEntry(registry, { entryKey, fieldsFromPlan, contextProjection });
+    const serialized = serializeRegistry(updated);
+    if (serialized === currentText) {
+      // Leave the file untouched: the staged tree stays equal to the tip and
+      // the shared lifecycle reports NO_CHANGE.
+      return;
+    }
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(absoluteRegistry, serialized);
+  };
+
+  const result = await applyDownstreamGitChange({
+    target,
+    commitIdentity,
+    commitSubject: `release-skill marketplace-registry-entry ${unitId} ${version} (${entryKey})`,
+    mutate,
+    gates: config?.gates ?? [],
+    contextProjection,
+    root,
+    ...(exec !== undefined ? { exec } : {}),
+    ...(hookRunner !== undefined ? { hookRunner } : {}),
+  });
+  return { ...result, registryPath };
+}