release-skill 0.6.2 → 0.7.0

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,171 @@
+/**
+ * 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';
+import { redactUrlCredentialsIfPresent } from './git-url-policy.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.releaseWorkspaceRoot - Release workspace root (the
+ *   real project root; workspace addressing resolution + write exclusion).
+ * @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, releaseWorkspaceRoot, 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,
+        releaseWorkspaceRoot,
+        ...(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: redactUrlCredentialsIfPresent(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/evidence.mjs

@@ -10,6 +10,8 @@
 import { open, mkdir, writeFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 
+import { redactEmbeddedUrlCredentials } from './git-url-policy.mjs';
+
 /** Schema version for evidence events. */
 const SCHEMA_VERSION = 1;
 
@@ -66,11 +68,16 @@ export function redact(obj) {
   }
 
   if (typeof obj === 'string') {
+    // F-05: strip any embedded URL userinfo before the value reaches disk.
+    // Only credential-bearing URL spans are rewritten; ordinary strings and
+    // credential-free URLs pass through unchanged.
+    const urlRedacted = redactEmbeddedUrlCredentials(obj);
     for (const { prefix, label } of CREDENTIAL_PREFIXES) {
-      if (obj.startsWith(prefix)) {
+      if (urlRedacted.startsWith(prefix)) {
         return `[REDACTED:${label}]`;
       }
     }
+    return urlRedacted;
   }
 
   return obj;

package/src/core/git-url-policy.mjs

@@ -0,0 +1,214 @@
+/**
+ * Release-domain Git remote URL policy (architecture gap F-05, T5).
+ *
+ * The SINGLE boundary for every postPublish remote-write URL: allowed
+ * protocols, the Git path shape, and the remote-write grading. Consumers:
+ * core/postpublish.mjs (declaration re-validation), core/presets.mjs (preset
+ * registry config), core/preset-gitwrite.mjs + core/proposal-inbox.mjs
+ * (write transports), adapters/distribute-git.mjs (legacy target mirror).
+ * The root JSON schemas are only the first gate; this runtime policy is the
+ * final authority, so plans frozen by older schema versions cannot smuggle
+ * unsafe URLs through.
+ *
+ * Boundary rules (what this module is NOT):
+ * - Parsing is delegated to the standard WHATWG URL — this module expresses
+ *   release-domain POLICY over the parse result; it implements no generic
+ *   URL parser.
+ * - Credential redaction is delegated to the Foundation
+ *   `redactUrlCredentials` (skill-family-harness-node, FG-2) — this module
+ *   implements no generic redactor; it only decides WHEN the Foundation
+ *   redactor applies so non-URL strings are never collapsed into the opaque
+ *   placeholder.
+ *
+ * Fail-closed vocabulary: every rejection reason is a stable token, and
+ * failure text NEVER carries the original URL — a rejected URL may hold
+ * userinfo credentials, and echoing it would defeat the boundary.
+ *
+ * @module core/git-url-policy
+ */
+
+import {
+  redactUrlCredentials,
+  REDACTED_URL_PLACEHOLDER,
+} from 'skill-family-harness-node';
+
+/**
+ * Protocols allowed for postPublish remote writes: http(s) for real remotes,
+ * file: strictly as the test transport.
+ */
+export const GIT_REMOTE_PROTOCOLS = Object.freeze(['http:', 'https:', 'file:']);
+
+/**
+ * Remote-write grading (发布领域远端写分级): the protocol decides the grade —
+ * http(s) are real remote writes, file: is the test transport. Central here
+ * so no consumer re-derives grading from its own protocol regex.
+ */
+export const GIT_REMOTE_WRITE_GRADES = Object.freeze({
+  'http:': 'remote-write',
+  'https:': 'remote-write',
+  'file:': 'test-transport',
+});
+
+/** Rejection reason vocabulary; every entry is safe to surface (no URL). */
+export const GIT_REMOTE_URL_REASONS = Object.freeze({
+  NOT_A_STRING: 'not-a-string',
+  CONTROL_CHARACTERS: 'control-characters',
+  UNPARSEABLE: 'unparseable',
+  PROTOCOL_NOT_ALLOWED: 'protocol-not-allowed',
+  MISSING_HOST: 'missing-host',
+  CREDENTIALS_PRESENT: 'credentials-present',
+  QUERY_OR_FRAGMENT_REJECTED: 'query-or-fragment-rejected',
+  NOT_A_GIT_PATH: 'not-a-git-path',
+});
+
+/**
+ * Human-readable failure text per rejection reason. Deliberately carries NO
+ * part of the offending URL (a credential-bearing URL must never be echoed
+ * back through an error surface).
+ */
+const FAILURE_TEXT = Object.freeze({
+  [GIT_REMOTE_URL_REASONS.NOT_A_STRING]: 'must be a non-empty string',
+  [GIT_REMOTE_URL_REASONS.CONTROL_CHARACTERS]: 'contains control characters',
+  [GIT_REMOTE_URL_REASONS.UNPARSEABLE]:
+    'must be an absolute URL parseable by the standard URL parser',
+  [GIT_REMOTE_URL_REASONS.PROTOCOL_NOT_ALLOWED]:
+    'protocol must be http:, https:, or file: (file: is the test transport)',
+  [GIT_REMOTE_URL_REASONS.MISSING_HOST]: 'http(s) URLs must carry a host',
+  [GIT_REMOTE_URL_REASONS.CREDENTIALS_PRESENT]:
+    'must never carry embedded credentials (username/password) — credentials belong to the host git credential helper, never to the URL',
+  [GIT_REMOTE_URL_REASONS.QUERY_OR_FRAGMENT_REJECTED]:
+    'must carry no query or fragment',
+  [GIT_REMOTE_URL_REASONS.NOT_A_GIT_PATH]: 'pathname must end in .git',
+});
+
+/**
+ * Describe one rejection reason for error messages (always URL-free).
+ *
+ * @param {string} reason - One of GIT_REMOTE_URL_REASONS.
+ * @returns {string} Safe human-readable failure text.
+ */
+export function describeGitRemoteUrlFailure(reason) {
+  return FAILURE_TEXT[reason] ?? 'is not an allowed Git remote URL';
+}
+
+/**
+ * The runtime contract check for one postPublish remote-write URL:
+ * 1. non-empty string, no control characters (checked on the RAW value —
+ *    WHATWG parsing silently folds \t\r\n, so the raw check fails closed);
+ * 2. `new URL()` parse (the standard parser is the only parser);
+ * 3. protocol allowlist: http:, https:, file: (test transport);
+ * 4. http(s) must carry a host;
+ * 5. ALL protocols reject a non-empty username or password;
+ * 6. no query or fragment (a git remote URL is a bare location);
+ * 7. the PATHNAME ends in .git.
+ *
+ * @param {*} remoteUrl
+ * @returns {{ ok: true, protocol: string, grade: string }
+ *   | { ok: false, reason: string }} The verdict never carries the input.
+ */
+export function checkGitRemoteUrl(remoteUrl) {
+  if (typeof remoteUrl !== 'string' || remoteUrl.length === 0) {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.NOT_A_STRING };
+  }
+  if (/[\x00-\x1f\x7f]/.test(remoteUrl)) {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.CONTROL_CHARACTERS };
+  }
+  let url;
+  try {
+    url = new URL(remoteUrl);
+  } catch {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.UNPARSEABLE };
+  }
+  if (!GIT_REMOTE_PROTOCOLS.includes(url.protocol)) {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.PROTOCOL_NOT_ALLOWED };
+  }
+  if (url.protocol !== 'file:' && url.hostname === '') {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.MISSING_HOST };
+  }
+  if (url.username !== '' || url.password !== '') {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.CREDENTIALS_PRESENT };
+  }
+  if (url.search !== '' || url.hash !== '') {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.QUERY_OR_FRAGMENT_REJECTED };
+  }
+  if (!url.pathname.endsWith('.git')) {
+    return { ok: false, reason: GIT_REMOTE_URL_REASONS.NOT_A_GIT_PATH };
+  }
+  return { ok: true, protocol: url.protocol, grade: GIT_REMOTE_WRITE_GRADES[url.protocol] };
+}
+
+/**
+ * Boolean form of the policy check (cross-check skip decisions, probes).
+ *
+ * @param {*} remoteUrl
+ * @returns {boolean} True only for policy-allowed Git remote URLs.
+ */
+export function isAllowedGitRemoteUrl(remoteUrl) {
+  return checkGitRemoteUrl(remoteUrl).ok === true;
+}
+
+/**
+ * Remote-write grade for one policy-allowed URL; null when the URL does not
+ * pass the policy (grading never applies to rejected URLs).
+ *
+ * @param {*} remoteUrl
+ * @returns {'remote-write'|'test-transport'|null}
+ */
+export function resolveGitRemoteWriteGrade(remoteUrl) {
+  const verdict = checkGitRemoteUrl(remoteUrl);
+  return verdict.ok ? verdict.grade : null;
+}
+
+/**
+ * Guarded credential redaction for long-lived outputs (evidence, error
+ * messages/details, preset observations). Delegates the actual redaction to
+ * the Foundation `redactUrlCredentials`:
+ * - values that parse as an absolute URL carrying userinfo come back as the
+ *   Foundation's credential-free serialization;
+ * - unparseable `scheme://...@...` authority shapes cannot be proven
+ *   credential-free and fail closed to the opaque placeholder (the same
+ *   stance as the Foundation's degraded path);
+ * - every other value returns UNCHANGED (blindly applying the Foundation
+ *   redactor would collapse ordinary non-URL strings into the placeholder).
+ *
+ * @param {*} value
+ * @returns {*} The credential-free value (or the input, unchanged).
+ */
+export function redactUrlCredentialsIfPresent(value) {
+  if (typeof value !== 'string' || value.length === 0) return value;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]*@/.test(value)) {
+      return REDACTED_URL_PLACEHOLDER;
+    }
+    return value;
+  }
+  if (url.username === '' && url.password === '') return value;
+  return redactUrlCredentials(url);
+}
+
+/**
+ * Candidate URL-span tokenizer for prose (log lines, error messages). It only
+ * LOCATES spans shaped like `scheme://...`; the credential decision and the
+ * redaction itself are delegated to the standard URL parser + the Foundation
+ * redactor via redactUrlCredentialsIfPresent. This is what makes the error
+ * and evidence chokepoints safe "even if a validation misses" (F-05): a
+ * credential-bearing URL embedded mid-sentence cannot survive to disk.
+ */
+const URL_SPAN_RE = /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s'"<>`]+/g;
+
+/**
+ * Redact credential-bearing URL spans anywhere inside a string (whole value
+ * or embedded in prose). Credential-free spans and all non-URL text return
+ * byte-for-byte unchanged.
+ *
+ * @param {*} text
+ * @returns {*} The credential-free string (or the input, unchanged).
+ */
+export function redactEmbeddedUrlCredentials(text) {
+  if (typeof text !== 'string' || text.length === 0) return text;
+  if (!text.includes('://')) return text;
+  return text.replace(URL_SPAN_RE, (span) => redactUrlCredentialsIfPresent(span));
+}