@rightkit/release 0.6.3 → 0.6.5

package/release.mjs

@@ -11,6 +11,7 @@ import { validateRightKitCargoContract } from "./cargo-contract.mjs";
 import { assertCargoProfileContract } from "./cargo-profile-contract.mjs";
 import { assertQaAdoption, assertQaBackdoorContract } from "./qa-contract.mjs";
 import { assertLegalReleaseContract } from "./legal-contract.mjs";
+import { DECLARED_UNRELATED_POLICY, declaredUnrelatedRefusal, releaseArtifactPaths } from "./hosted-workflow-policy.mjs";
 import { assertNativeIosPrepareHasManifest, assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
 import { declaredCargoManifest, hasDefaultTauriManifest, resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
 import {
@@ -49,13 +50,17 @@ import { assertNoQaControl, assertNoWebBundleMocks } from "./qa-control-scan.mjs
 import { assertReleaseDependencies } from "./release-dependencies.mjs";
 import { assertNoForbiddenBuildFeatures } from "./qa-build-features.mjs";
 import { expandRecipeBuildCommands } from "./recipe-build.mjs";
-import { assertNoReleaseSwitches, commandTokens, localCrateDirsFromTree, resolveFeatureClosure, shippedRustTriples } from "./release-switch-scan.mjs";
+import { assertNoReleaseSwitches, commandTokens, localCrateDirsFromTree, resolveFeatureClosure, shippedRustTriples, validateNonShipped } from "./release-switch-scan.mjs";
 import { iosOwnershipScope, preflightOwnershipScope } from "./ownership-scope.mjs";
 import { devtoolsEvidence, resolveDevtoolsAllowance } from "./devtools-policy.mjs";
 import { runAndroidRelease, validateAndroidTarget } from "./android-release.mjs";
 import { runIosPackageRecipe } from "./ios-package-recipe.mjs";
 import { releaseSwitchInputs } from "./ios-build-context.mjs";
 import { productionBuildEnv, productionModeProblems } from "./production-mode.mjs";
+import { evaluatePrebuildGates } from "./prebuild-gates.mjs";
+import { releaseConfigFieldProblems } from "./release-config.mjs";
+import { describeRegistryError, formatNotRun, runAdmission } from "./admission.mjs";
+import { sccacheRefusal } from "./admission-host.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const HARDENING_SCAN = path.resolve(TOOL_ROOT, "hardeningscan.mjs");
@@ -128,11 +133,64 @@ const opts = {
   dryRun: false,
   skipChecks: false,
   doctor: false,
+  gates: false,
+  inspect: false,
+  strict: false,
   tier: null,
   resume: false,
   resumeFrom: null,
 };
 
+// E01: every independent problem of one run is collected and reported together; the doctor and the build share it.
+// `check` / `reject` record a finding and continue; a check whose input comes from a failed one is not run on that bad input
+// but reported as `not run because <check> failed` (one line, not a finding: the failed check is the one blocking problem of that
+// cause); a throw inside a check is a finding, never a crash. `fail` stays for what cannot continue (it prints what was
+// collected first). The build stops at one checkpoint (before the release lock, install, checks and compile) when any finding
+// exists, so no build step or other side effect ever follows a failed check.
+const problems = []; // { name, detail }
+const notRunLines = []; // what a failed check kept from running; reported beside the findings, never counted as one
+const failedChecks = new Set();
+// The three rows only the doctor owns (admission.mjs skips them in its own pass) are not admission findings, so nothing else puts
+// their id before the text. The doctor does, as it does for every admission row: `right-release: <row>: <text>`, the text the
+// build's controller prints after `right-release build: <row>: `.
+const DOCTOR_OWNED_ROWS = new Set(["rightkit-registry", "build-inputs", "dirty-inputs"]);
+function reject(name, detail) {
+  failedChecks.add(name);
+  problems.push({ name, detail: opts.doctor && DOCTOR_OWNED_ROWS.has(name) ? `${name}: ${detail}` : detail });
+}
+// A validator that runs inside a check() refuses with this instead of calling fail(): the check records it as a finding and the
+// doctor goes on to the next rule. `rowId` names the rule; `problems` lists every finding the rule has when it has more than one.
+class ReleaseRefusal extends Error {
+  constructor(message, rowId, found = [message]) {
+    super(message);
+    this.name = "ReleaseRefusal";
+    this.rowId = rowId;
+    this.problems = found;
+  }
+}
+function rejectBlocked(name, blockers, what = name) {
+  const blocker = blockers.find((candidate) => failedChecks.has(candidate));
+  if (!blocker) return false;
+  // The check counts as failed for the checks that read it (they are not run either), but it adds no problem of its own.
+  failedChecks.add(name);
+  notRunLines.push(`${what} not run because ${blocker} failed`);
+  return true;
+}
+async function check(name, after, run) {
+  if (rejectBlocked(name, after)) return { ok: false };
+  try {
+    return { ok: true, value: await run() };
+  } catch (error) {
+    if (error instanceof ReleaseRefusal) for (const detail of error.problems) reject(name, detail);
+    else reject(name, error instanceof Error ? error.message : `${name} threw a non-Error value: ${String(error)}`);
+    return { ok: false };
+  }
+}
+const printProblems = () => {
+  for (const problem of problems.splice(0)) console.error(`right-release: ${problem.detail}`);
+  for (const line of notRunLines.splice(0)) console.error(`right-release: ${line}`);
+};
+
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
   if (arg === "--") continue;
@@ -145,7 +203,11 @@ for (let i = 0; i < args.length; i++) {
   else if (arg === "--skip-checks") opts.skipChecks = true;
   else if (arg === "--skip-hardening") fail("--skip-hardening is forbidden; use exact artifact/source-bound hardeningAllowances");
   else if (arg === "--doctor") opts.doctor = true;
+  else if (arg === "--gates") opts.gates = true;
+  // The doctor applies the build's admission by default; --admission is the old spelling of that, kept so scripts still run.
   else if (arg === "--admission") opts.admission = true;
+  else if (arg === "--inspect") opts.inspect = true;
+  else if (arg === "--strict") opts.strict = true;
   else if (arg === "--resume") opts.resume = true;
   else if (arg === "--resume-from") { opts.resume = true; opts.resumeFrom = args[++i]; }
   else if (arg === "--tier") opts.tier = args[++i];
@@ -158,6 +220,9 @@ for (let i = 0; i < args.length; i++) {
   else usage(2, `unknown argument: ${arg}`);
 }
 
+if (opts.gates && !opts.doctor) usage(2, "--gates is valid only with --doctor");
+if ((opts.inspect || opts.strict) && !opts.doctor) usage(2, `${opts.inspect ? "--inspect" : "--strict"} is valid only with --doctor`);
+if (opts.inspect && opts.admission) usage(2, "--inspect and --admission contradict each other: --inspect lists newer RightKit versions as information, --admission refuses them");
 if (opts.upload) fail("combined build+upload was removed; run right-release build, then right-release upload --release <id> --tier patch|update");
 if (opts.tier && !TIERS.has(opts.tier)) usage(2, `invalid --tier: ${opts.tier} (expected patch|update)`);
 const MAC_RESUME_PHASES = ["prepackage", "sign", "package", "post-sign", "harden"];
@@ -179,9 +244,12 @@ if (opts.doctor) {
   if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
   doctorInvocation = { repoRoot, commit };
 }
-const config = (await import(pathToFileURL(configPath))).default;
+let config;
+try { config = (await import(pathToFileURL(configPath))).default; } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
 if (!config) usage(2, `config did not export default: ${configPath}`);
 if (config.schema !== 1) fail(`unsupported config schema: ${config.schema ?? "<missing>"} (expected 1)`);
+// Field-level config refusals (updater.keyFile: keys come from the OS credential provider) are listed with every other finding.
+for (const refusal of releaseConfigFieldProblems(config)) reject(refusal.name, refusal.detail);
 
 // Hosted-workflow policy patterns: defined before the top-level await below uses them.
 const SIGN_EXISTING_SECRETS = new Set(["APPLE_CERTIFICATE_BASE64", "APPLE_CERTIFICATE_PASSWORD", "APPLE_KEYCHAIN_PASSWORD"]);
@@ -205,7 +273,7 @@ const nativeFinalizer = resolveNativeFinalizerConfig(nativeAssembly);
 // (build-release.mjs). This worker, a resume and the upload consume only that admitted snapshot, through the release's own
 // state root and admission record; a snapshot from anywhere else is refused. The standalone doctor resolves live.
 const rightKitSnapshotFile = process.env[SNAPSHOT_ENV] || null;
-let rightKitResolution;
+let rightKitResolution = null; // null when the registry resolution failed (recorded as the `rightkit-registry` finding)
 try {
   const lockInventory = () => {
     try {
@@ -233,14 +301,15 @@ try {
     ownership: RIGHTKIT_OWNERSHIP,
     releaseVersion: VERSION,
     boundSnapshot,
-    // The doctor reports newer versions; run as the admission gate (--admission) it refuses a pin behind latest.
-    admission: opts.doctor && opts.admission,
+    // The doctor is the build's own admission: a pin behind latest is refused, as the build refuses it. --inspect is the
+    // informational view (newer versions are listed, not refused).
+    admission: opts.doctor && !opts.inspect,
   });
 } catch (error) {
-  if (!(error instanceof RightKitRegistryError)) throw error;
-  fail(`${config.app ?? path.basename(root)} ${error.recoverable ? "RECOVERABLE " : ""}${error.message}`);
+  rightKitResolution = null;
+  reject("rightkit-registry", describeRegistryError(error, config.app ?? path.basename(root)));
 }
-{
+if (rightKitResolution) {
   const { newer, tasks, warnings, notes } = rightKitResolution.freshness;
   const out = opts.doctor ? console.log : console.error;
   for (const line of newer) out(`right-release: newer RightKit version (informational): ${line}`);
@@ -248,88 +317,133 @@ try {
   for (const line of warnings) console.error(`right-release: WARNING ${line}`);
   for (const line of notes) console.error(`right-release: note ${line}`);
 }
-rightKitVerifiedNpm = rightKitResolution.verified.npm;
-// A SwiftPM app or a native iOS app without a package.json has no Node package contract to validate.
+if (rightKitResolution) rightKitVerifiedNpm = rightKitResolution.verified.npm;
+// The contracts below are independent of each other; the two that read the proven RightKit versions need the registry resolution.
+// A SwiftPM app or a native iOS app without a package.json has no Node package contract to validate. Each package rule is its
+// own finding (a failed one blocks only the rules that read its result), so one run lists every violation.
 if (!((nativeIos || resolveProjectType({ appRoot: root, config, target: config.targets?.[opts.platform] }) === "swiftpm") && !existsSync(path.join(root, "package.json")))) {
-  await validateRightKitPackageContract(root, config.app, config.hostedWorkflows);
-}
-validateRightKitCargoContract(root, mergeVerifiedVersions(RIGHTKIT_CARGO_ALLOWED, rightKitResolution.verified.cargo), config.app ?? path.basename(root));
+  const packageJson = await check("package-json", [], async () => JSON.parse(await readFile(path.join(root, "package.json"), "utf8")));
+  const packageLabel = () => config.app ?? packageJson.value?.name ?? "app";
+  await check("qa-backdoor-contract", ["package-json"], () => assertQaBackdoorContract(root, packageJson.value.scripts ?? {}));
+  await check("hosted-workflows", [], () => validateHostedWorkflowFiles(root, packageLabel(), config.hostedWorkflows, releaseArtifactPaths(config)));
+  await check("package-manager", ["package-json"], () => validatePackageManagerPin(packageJson.value, packageLabel()));
+  await check("package-workspace-scripts", ["package-json"], () => validateNoParentWorkspaceScripts(packageJson.value, packageLabel()));
+  await check("rightkit-pin-specs", ["package-json", "rightkit-registry"], () => validateRightKitPinSpecs(packageJson.value, packageLabel()));
+  await check("rightkit-release-supported", ["package-json", "rightkit-registry"], () => validateRightKitReleaseSupported(packageJson.value, packageLabel()));
+}
+await check("rightkit-cargo-contract", ["rightkit-registry"], () => {
+  validateRightKitCargoContract(root, mergeVerifiedVersions(RIGHTKIT_CARGO_ALLOWED, rightKitResolution.verified.cargo), config.app ?? path.basename(root));
+});
 // One standard dev profile and panic = "unwind" in every app (templates/cargo-profiles.toml).
-assertCargoProfileContract(root, config.app ?? path.basename(root));
+await check("cargo-profile-contract", [], () => assertCargoProfileContract(root, config.app ?? path.basename(root)));
 // RightKit QA is mandatory for every app (also SwiftPM apps without a package.json): no QA lane refuses the release.
-assertQaAdoption({ appRoot: root, app: config.app });
+await check("qa-adoption", [], () => assertQaAdoption({ appRoot: root, app: config.app }));
 let target = config.targets?.[opts.platform];
 // Declarative winPackage / macPackage (#345) expand to the same hook shape every gate below already checks.
-try { target = expandPackageRecipeTarget(target, { platform: opts.platform, appRoot: root, config }); } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
-if (!target) fail(`${config.app ?? "app"} has no ${opts.platform} release target`);
-const legalContract = config.legal
+// When it fails, `target` is not usable: every check that reads it is reported as not run because `target` failed.
+await check("target", [], () => {
+  let expanded;
+  try { expanded = expandPackageRecipeTarget(target, { platform: opts.platform, appRoot: root, config }); } catch (error) { throw new Error(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
+  if (!expanded) throw new Error(`${config.app ?? "app"} has no ${opts.platform} release target`);
+  target = expanded;
+});
+const legalCheck = await check("legal-contract", [], () => (config.legal
   ? assertLegalReleaseContract(root, config.legal, config.app ?? path.basename(root), opts.platform)
-  : null;
-if (target.signed !== true) {
-  fail(`${config.app ?? "app"} ${opts.platform} must declare signed: true; unsigned release targets are forbidden`);
-}
+  : null));
+const legalContract = legalCheck.ok ? legalCheck.value : null;
 let macSigning; // validated macOS sign.prePackageFiles / sign.nestedCode (mac only)
 let mediaSidecarConfig = null; // validated targets.<mac|win>.mediaSidecar (rightkit-ffmpeg decode sidecar)
-if (target.mediaSidecar !== undefined) {
-  if (opts.platform !== "mac" && opts.platform !== "win") fail(`${config.app ?? "app"} ${opts.platform} does not support mediaSidecar (mac and win only)`);
-  try { mediaSidecarConfig = validateMediaSidecarConfig(target.mediaSidecar, { platform: opts.platform }); } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
-}
 let externalBinConfig = null; // validated targets.<mac|win>.externalBin (generic Tauri externalBin sidecars, #270)
-if (target.externalBin !== undefined) {
-  if (opts.platform !== "mac" && opts.platform !== "win") fail(`${config.app ?? "app"} ${opts.platform} does not support externalBin (mac and win only)`);
-  try { externalBinConfig = validateExternalBinConfig(target.externalBin, { platform: opts.platform, reservedNames: mediaSidecarConfig?.tools ?? [] }); } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
-}
-if (opts.platform === "win") {
-  const isNsis = target.signingContract === WINDOWS_NSIS_SIGNING_CONTRACT;
-  const isPortable = target.signingContract === WINDOWS_PORTABLE_SIGNING_CONTRACT;
-  const isMsix = target.signingContract === MSIX_SIGNING_CONTRACT;
-  if (!isNsis && !isPortable && !isMsix) fail(`${config.app ?? "app"} win must declare signingContract: ${WINDOWS_NSIS_SIGNING_CONTRACT}, ${WINDOWS_PORTABLE_SIGNING_CONTRACT} or ${MSIX_SIGNING_CONTRACT}`);
-  if (isMsix) {
-    try { assertValidMsixTarget(target, config.app ?? "app"); } catch (error) { fail(error.message); }
-  } else {
-  if (!target.prePackage?.cmd) fail(`${config.app ?? "app"} win must declare prePackage for the raw EXE build`);
-  if (!target.sign?.prePackageFiles?.length) fail(`${config.app ?? "app"} win must declare at least one sign.prePackageFiles raw EXE`);
-  if (target.sign.prePackageFiles.some((file) => typeof file !== "string") || target.sign.nestedCode !== undefined) fail(`${config.app ?? "app"} win sign.prePackageFiles entries must be path strings; object entries and sign.nestedCode are macOS-only`);
-  if (isNsis && target.sign.prePackageFiles.length !== 1) fail(`${config.app ?? "app"} win NSIS must declare exactly one sign.prePackageFiles raw EXE`);
-  if (isNsis && !target.sign?.files?.length) fail(`${config.app ?? "app"} win NSIS must declare sign.files for installer signing`);
-  if (isNsis && target.sign.prePackageFiles.some((file) => target.sign.files.includes(file))) fail(`${config.app ?? "app"} win raw EXE and installer signing files must be distinct`);
-  if (isPortable && target.sign?.files?.length) fail(`${config.app ?? "app"} win portable release must sign every executable through sign.prePackageFiles and omit sign.files`);
-  }
-}
-if (opts.platform === "mac") {
-  if (target.signingContract !== MACOS_PORTABLE_SIGNING_CONTRACT) fail(`${config.app ?? "app"} mac must declare signingContract: ${MACOS_PORTABLE_SIGNING_CONTRACT}`);
-  if (!target.prePackage?.cmd) fail(`${config.app ?? "app"} mac must declare prePackage to materialize Developer ID signing files`);
-  if (!target.sign?.prePackageFiles?.length) fail(`${config.app ?? "app"} mac must declare at least one sign.prePackageFiles`);
-  const macSignConfig = mediaSidecarConfig || externalBinConfig
-    ? { ...target.sign, nestedCode: { ...(mediaSidecarConfig ? mediaSidecarNestedCode(mediaSidecarConfig) : {}), ...(externalBinConfig ? externalBinNestedCode(externalBinConfig) : {}), ...(target.sign.nestedCode ?? {}) } }
-    : target.sign;
-  try { macSigning = validateMacSigningConfig(macSignConfig, { root }); } catch (error) { fail(`${config.app ?? "app"} mac ${error.message}`); }
-  if (!target.notarize?.file) fail(`${config.app ?? "app"} mac must declare notarize.file`);
-  if (target.notarize.appBeforePackage && !target.notarize.app) fail(`${config.app ?? "app"} mac notarize.appBeforePackage requires notarize.app`);
-  if (target.notarize.staple === false && (target.notarize.app || /\.(dmg|pkg)$/i.test(target.notarize.file))) {
-    fail(`${config.app ?? "app"} mac notarize.staple: false applies only to an archive of bare executables (no notarize.app, not a .dmg/.pkg)`);
-  }
-  const swiftDmgError = swiftMacDmgConfigError({ target, projectType: resolveProjectType({ appRoot: root, config, target }), appName: config.app ?? "app" });
-  if (swiftDmgError) fail(swiftDmgError);
-  if (target.dmg && typeof target.dmg === "object" && target.dmg.spec !== undefined) {
-    try {
-      if (typeof target.dmg.spec !== "string" || !target.dmg.spec) throw new Error("dmg.spec must be a path string");
-      const specOptions = readDmgSpec(path.resolve(root, target.dmg.spec), { app: target.notarize.app });
-      for (const asset of [specOptions.background, specOptions.volumeIcon]) if (asset && !existsSync(asset)) throw new Error(`referenced file not found: ${asset}`);
-    } catch (error) { fail(`${config.app ?? "app"} mac targets.mac.dmg.spec: ${error.message}`); }
-  }
-}
 let androidTarget; // validated Android AAB target (android only; see android-release.mjs)
-if (opts.platform === "android") {
-  try { androidTarget = validateAndroidTarget(target, { root }); } catch (error) { fail(`${config.app ?? "app"} android ${error.message}`); }
-}
 let iosSpec; // validated iOS iosPackage spec (ios only; package-recipe-targets.mjs expands targets.ios, ios-package-recipe.mjs runs it)
-if (opts.platform === "ios") {
-  if (target.recipe?.kind !== "iosPackage") fail(`${config.app ?? "app"} ios must declare targets.ios.iosPackage; there is no hand-written iOS package script`);
-  iosSpec = target.recipe.spec;
-  if (nativeIos) { try { assertNativeIosPrepareHasManifest(iosSpec, config, root); } catch (error) { fail(`${config.app ?? "app"} ios ${error.message}`); } }
+const app = config.app ?? "app";
+// Everything below reads the expanded target. Each independent refusal is its own finding; a check that needs the output of
+// another (mac signing reads the sidecar config, the iOS prepare check reads the iOS spec) is not run (reported as such), never run on it.
+if (!rejectBlocked("target-checks", ["target"], "the target checks (signed, mediaSidecar, externalBin, publishBlocked and the platform signing and package contract)")) {
+  if (target.signed !== true) reject("target-signed", `${app} ${opts.platform} must declare signed: true; unsigned release targets are forbidden`);
+  if (target.mediaSidecar !== undefined) {
+    if (opts.platform !== "mac" && opts.platform !== "win") reject("media-sidecar", `${app} ${opts.platform} does not support mediaSidecar (mac and win only)`);
+    else await check("media-sidecar", [], () => {
+      try { mediaSidecarConfig = validateMediaSidecarConfig(target.mediaSidecar, { platform: opts.platform }); } catch (error) { throw new Error(`${app} ${opts.platform} ${error.message}`); }
+    });
+  }
+  if (target.externalBin !== undefined) {
+    if (opts.platform !== "mac" && opts.platform !== "win") reject("external-bin", `${app} ${opts.platform} does not support externalBin (mac and win only)`);
+    else await check("external-bin", ["media-sidecar"], () => {
+      try { externalBinConfig = validateExternalBinConfig(target.externalBin, { platform: opts.platform, reservedNames: mediaSidecarConfig?.tools ?? [] }); } catch (error) { throw new Error(`${app} ${opts.platform} ${error.message}`); }
+    });
+  }
+  if (opts.platform === "win") {
+    const isNsis = target.signingContract === WINDOWS_NSIS_SIGNING_CONTRACT;
+    const isPortable = target.signingContract === WINDOWS_PORTABLE_SIGNING_CONTRACT;
+    const isMsix = target.signingContract === MSIX_SIGNING_CONTRACT;
+    if (!isNsis && !isPortable && !isMsix) reject("win-signing-contract", `${app} win must declare signingContract: ${WINDOWS_NSIS_SIGNING_CONTRACT}, ${WINDOWS_PORTABLE_SIGNING_CONTRACT} or ${MSIX_SIGNING_CONTRACT}`);
+    if (isMsix) {
+      await check("win-msix", [], () => assertValidMsixTarget(target, app));
+    } else {
+      // The NSIS and portable rules below depend on which contract the target declares.
+      rejectBlocked("win-contract-rules", ["win-signing-contract"], "the win NSIS and portable rules (sign.files, distinct raw EXE and installer files)");
+      if (!target.prePackage?.cmd) reject("win-prepackage", `${app} win must declare prePackage for the raw EXE build`);
+      const rawFiles = target.sign?.prePackageFiles;
+      if (!rawFiles?.length) reject("win-sign-prepackage-files", `${app} win must declare at least one sign.prePackageFiles raw EXE`);
+      else {
+        if (rawFiles.some((file) => typeof file !== "string") || target.sign.nestedCode !== undefined) reject("win-sign-entries", `${app} win sign.prePackageFiles entries must be path strings; object entries and sign.nestedCode are macOS-only`);
+        if (isNsis && rawFiles.length !== 1) reject("win-nsis-raw-exe", `${app} win NSIS must declare exactly one sign.prePackageFiles raw EXE`);
+      }
+      if (isNsis && !target.sign?.files?.length) reject("win-nsis-sign-files", `${app} win NSIS must declare sign.files for installer signing`);
+      if (isNsis && rawFiles?.length && target.sign?.files?.length && rawFiles.some((file) => target.sign.files.includes(file))) reject("win-distinct-files", `${app} win raw EXE and installer signing files must be distinct`);
+      if (isPortable && target.sign?.files?.length) reject("win-portable-sign-files", `${app} win portable release must sign every executable through sign.prePackageFiles and omit sign.files`);
+    }
+  }
+  if (opts.platform === "mac") {
+    if (target.signingContract !== MACOS_PORTABLE_SIGNING_CONTRACT) reject("mac-signing-contract", `${app} mac must declare signingContract: ${MACOS_PORTABLE_SIGNING_CONTRACT}`);
+    if (!target.prePackage?.cmd) reject("mac-prepackage", `${app} mac must declare prePackage to materialize Developer ID signing files`);
+    if (!target.sign?.prePackageFiles?.length) reject("mac-sign-prepackage-files", `${app} mac must declare at least one sign.prePackageFiles`);
+    else if (!rejectBlocked("mac-signing", ["media-sidecar", "external-bin"], `${app} mac signing config validation (it reads the sidecar and externalBin configs)`)) {
+      await check("mac-signing", [], () => {
+        const macSignConfig = mediaSidecarConfig || externalBinConfig
+          ? { ...target.sign, nestedCode: { ...(mediaSidecarConfig ? mediaSidecarNestedCode(mediaSidecarConfig) : {}), ...(externalBinConfig ? externalBinNestedCode(externalBinConfig) : {}), ...(target.sign.nestedCode ?? {}) } }
+          : target.sign;
+        try { macSigning = validateMacSigningConfig(macSignConfig, { root }); } catch (error) { throw new Error(`${app} mac ${error.message}`); }
+      });
+    }
+    if (!target.notarize?.file) reject("mac-notarize-file", `${app} mac must declare notarize.file`);
+    else {
+      if (target.notarize.appBeforePackage && !target.notarize.app) reject("mac-notarize-app", `${app} mac notarize.appBeforePackage requires notarize.app`);
+      if (target.notarize.staple === false && (target.notarize.app || /\.(dmg|pkg)$/i.test(target.notarize.file))) {
+        reject("mac-notarize-staple", `${app} mac notarize.staple: false applies only to an archive of bare executables (no notarize.app, not a .dmg/.pkg)`);
+      }
+    }
+    await check("mac-swift-dmg", [], () => {
+      const swiftDmgError = swiftMacDmgConfigError({ target, projectType: resolveProjectType({ appRoot: root, config, target }), appName: app });
+      if (swiftDmgError) throw new Error(swiftDmgError);
+    });
+    if (target.dmg && typeof target.dmg === "object" && target.dmg.spec !== undefined && !rejectBlocked("mac-dmg-spec", ["mac-notarize-file"], `${app} mac targets.mac.dmg.spec validation (it reads notarize.app)`)) {
+      await check("mac-dmg-spec", [], () => {
+        try {
+          if (typeof target.dmg.spec !== "string" || !target.dmg.spec) throw new Error("dmg.spec must be a path string");
+          const specOptions = readDmgSpec(path.resolve(root, target.dmg.spec), { app: target.notarize.app });
+          for (const asset of [specOptions.background, specOptions.volumeIcon]) if (asset && !existsSync(asset)) throw new Error(`referenced file not found: ${asset}`);
+        } catch (error) { throw new Error(`${app} mac targets.mac.dmg.spec: ${error.message}`); }
+      });
+    }
+  }
+  if (opts.platform === "android") {
+    await check("android-target", [], () => {
+      try { androidTarget = validateAndroidTarget(target, { root }); } catch (error) { throw new Error(`${app} android ${error.message}`); }
+    });
+  }
+  if (opts.platform === "ios") {
+    if (target.recipe?.kind !== "iosPackage") reject("ios-target", `${app} ios must declare targets.ios.iosPackage; there is no hand-written iOS package script`);
+    else {
+      iosSpec = target.recipe.spec;
+      if (nativeIos) await check("ios-prepare-manifest", [], () => {
+        try { assertNativeIosPrepareHasManifest(iosSpec, config, root); } catch (error) { throw new Error(`${app} ios ${error.message}`); }
+      });
+    }
+  }
+  if (opts.upload && target.publishBlocked) reject("publish-blocked", `${app} ${opts.platform} publish blocked: ${target.publishBlocked}`);
 }
-if (opts.upload && target.publishBlocked) fail(`${config.app ?? "app"} ${opts.platform} publish blocked: ${target.publishBlocked}`);
 /**
  * Assemble preflight inputs from the app's own files. Kept here (not in
  * preflight.mjs) so the check module stays free of release.mjs's config shape.
@@ -377,16 +491,28 @@ function releasePreflight({ config, configPath, root, repoRoot, platform, native
 }
 
 if (opts.doctor) {
-  const { buildInputs, nativeLayout: resolvedNativeLayout, cargoLockPaths: pinnedCargoLocks } = resolveReleaseBuildInputs({
+  // Every check below is independent unless it names what it needs; a failed input blocks (never feeds) what reads it.
+  const inputs = await check("build-inputs", ["target"], () => resolveReleaseBuildInputs({
     repoRoot: doctorInvocation.repoRoot,
     appRoot: root,
     configPath,
     config,
     target,
+  }));
+  await check("dirty-inputs", ["build-inputs"], () => {
+    const dirtyInputs = dirtyBuildInputs(doctorInvocation.repoRoot, inputs.value.buildInputs, doctorInvocation.commit);
+    if (dirtyInputs.length > 0) throw new Error(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
   });
-  const dirtyInputs = dirtyBuildInputs(doctorInvocation.repoRoot, buildInputs, doctorInvocation.commit);
-  if (dirtyInputs.length > 0) {
-    fail(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
+  // The build's own admission rows (admission.mjs): the files the build would read and this machine, run with the texts and the
+  // rows the build runs before it takes its lock. The registry, the build inputs and the dirty inputs are this doctor's own steps.
+  let notRun = [];
+  const admission = await check("admission", ["target"], () => runAdmission({
+    root, repoRoot: doctorInvocation.repoRoot, configPath, config, platform: opts.platform, target, tiers: ["files", "host"],
+    mode: "doctor", skipDoctorOwned: true, skipChecks: opts.skipChecks, commit: doctorInvocation.commit,
+  }));
+  if (admission.ok) {
+    for (const finding of admission.value.findings) reject(finding.row, `${finding.row}: ${finding.detail}`);
+    notRun = admission.value.notRun;
   }
   console.log(`right-release ${VERSION}`);
   console.log(`config: ${configPath}`);
@@ -394,7 +520,7 @@ if (opts.doctor) {
   console.log(`platform: ${opts.platform}`);
   console.log(`tier: ${opts.tier ?? "<required for release/publish>"}`);
   console.log(`packageManager: ${config.packageManager}`);
-  console.log(`rightkit-registry: ${rightKitResolution.summary}`);
+  if (rightKitResolution) console.log(`rightkit-registry: ${rightKitResolution.summary}`);
   console.log(`workdir: ${workdir}`);
   console.log(`hardeningscan: ${HARDENING_SCAN}`);
   if (sccacheVersion) console.log(`sccache: ${sccacheVersion}`);
@@ -403,125 +529,81 @@ if (opts.doctor) {
     console.log(`legalAcceptance: ${legalContract.acceptanceVersion}`);
     console.log(`legalManifestSha256: ${legalContract.manifestSha256}`);
   }
-  if (target.sign?.files?.length) console.log(`sign: ${target.sign.files.join(", ")}`);
-  if (target.publishBlocked) console.log(`publishBlocked: ${target.publishBlocked}`);
+  if (!failedChecks.has("target")) {
+    if (target.sign?.files?.length) console.log(`sign: ${target.sign.files.join(", ")}`);
+    if (target.publishBlocked) console.log(`publishBlocked: ${target.publishBlocked}`);
+  }
   const managedRoot = process.env.RIGHTKIT_MANAGED_ROOT;
-  const installerCopyFindings = findInstallerCopyScripts({
-    appRoot: root,
-    workspaceRoot: process.env.RIGHTKIT_WORKSPACE_ROOT ?? path.resolve(doctorInvocation.repoRoot, ".."),
+  await check("artifact-storage", [], () => {
+    const installerCopyFindings = findInstallerCopyScripts({
+      appRoot: root,
+      workspaceRoot: process.env.RIGHTKIT_WORKSPACE_ROOT ?? path.resolve(doctorInvocation.repoRoot, ".."),
+    });
+    const storageFindings = [
+      ...installerCopyFindings,
+      ...findLargeRepositorySubdirectories({ appRoot: root, managedRoot, declared: config.storage?.declaredStores ?? [], thresholdBytes: Number(process.env.RIGHTKIT_ARTIFACT_STORAGE_THRESHOLD_BYTES ?? DEFAULT_STORAGE_THRESHOLD_BYTES) }),
+    ];
+    if (storageFindings.length) {
+      console.log("artifact-storage: report-only storage findings detected:");
+      for (const finding of storageFindings) console.log(`  - ${finding.path}: ${finding.reason}`);
+      throw new Error(`artifact-storage found ${storageFindings.length} repository storage finding(s); move outputs to RIGHT_RELEASE_ARTIFACT_DIR`);
+    } else console.log("artifact-storage: no installer-copy scripts detected");
   });
-  const storageFindings = [
-    ...installerCopyFindings,
-    ...findLargeRepositorySubdirectories({ appRoot: root, managedRoot, declared: config.storage?.declaredStores ?? [], thresholdBytes: Number(process.env.RIGHTKIT_ARTIFACT_STORAGE_THRESHOLD_BYTES ?? DEFAULT_STORAGE_THRESHOLD_BYTES) }),
-  ];
-  if (storageFindings.length) {
-    console.log("artifact-storage: report-only storage findings detected:");
-    for (const finding of storageFindings) console.log(`  - ${finding.path}: ${finding.reason}`);
-    fail(`artifact-storage found ${storageFindings.length} repository storage finding(s); move outputs to RIGHT_RELEASE_ARTIFACT_DIR`);
-  } else console.log("artifact-storage: no installer-copy scripts detected");
 
   // Config above, MACHINE below. Printing config never told anyone whether this
-  // box could finish a build; these checks do.
-  const checks = releasePreflight({ config, configPath, root, repoRoot: doctorInvocation.repoRoot, platform: opts.platform, nativeLayout: resolvedNativeLayout, pinnedCargoLocks });
-  console.log("preflight:");
-  console.log(formatPreflight(checks));
-  const failures = preflightFailures(checks);
-  if (failures.length > 0) {
-    fail(`preflight found ${failures.length} blocking problem(s); the build would fail on these`);
+  // box could finish a build; these checks do. The machine preflight reads the resolved build inputs, so it is
+  // BLOCKED when those could not be resolved.
+  let failures = [];
+  const machine = await check("preflight", ["target", "build-inputs"], () => {
+    const { nativeLayout: resolvedNativeLayout, cargoLockPaths: pinnedCargoLocks } = inputs.value;
+    return releasePreflight({ config, configPath, root, repoRoot: doctorInvocation.repoRoot, platform: opts.platform, nativeLayout: resolvedNativeLayout, pinnedCargoLocks });
+  });
+  if (machine.ok) {
+    console.log("preflight:");
+    console.log(formatPreflight(machine.value));
+    failures = preflightFailures(machine.value);
+  }
+  // --gates: run the build's pre-build source gates (release-switch scan, feature closure, release dependencies,
+  // devtools, production mode) over this app and report each finding as a FAIL row. They read the expanded target
+  // (and, on iOS, the iOS spec), so a failed one of those blocks them.
+  let gateFindings = [];
+  if (opts.gates) {
+    const blocker = ["target", ...(opts.platform === "ios" ? ["ios-target"] : [])].find((name) => failedChecks.has(name));
+    gateFindings = blocker
+      ? [{ name: "prebuild-gates", detail: `BLOCKED by ${blocker}` }]
+      : evaluatePrebuildGates({ root, config, target, platform: opts.platform, iosSpec, nativeIos, nativeAssembly, nativeFinalizer, strict: !opts.dryRun }).findings;
+  }
+  const configProblems = problems.length;
+  // The config findings (stderr, as every early refusal always was) and the gate rows (stdout) of this one run.
+  printProblems();
+  if (gateFindings.length) {
+    console.log(gateFindings.map((finding) => `  [FAIL] gate:${finding.name}: ${finding.detail}`).join("\n"));
+  }
+  // A row that could not run on this host is not a pass; --strict makes it a blocking problem.
+  for (const line of formatNotRun({ notRun })) console.error(`right-release: ${line}`);
+  const total = failures.length + gateFindings.length + configProblems + (opts.strict ? notRun.length : 0);
+  if (total > 0) {
+    console.error(`right-release: preflight found ${total} blocking problem(s); the build would fail on these`);
+    process.exit(1);
   }
   process.exit(0);
 }
 
 let prePackScanned = false; // set once a pre-pack payload scan has seen a native binary
-// Source-level layer of "no test-automation surface ships": refuse a release or update build whose build command
-// or app Cargo manifest enables devtools, qa-native, qa-control or dev-native (also in --dry-run).
-// DevTools: refused for every app except an allow-listed one that declares `devtools: "content-only"` (devtools-policy.mjs).
-let devtoolsAllowance = { mode: "denied" };
-// The Rust a build compiles is checked from the manifest it compiles: targets.<os>.cargoManifest, else the declared
-// nativeAssembly.cargoManifest. iosPackage.prepare commands run cargo for a native iOS app, so they are scanned like any build command.
-const switchInputs = releaseSwitchInputs({ appRoot: root, config, target, prepare: iosSpec?.prepare ?? [], nativeIos });
-if (switchInputs.problems.length) fail(`${config.app ?? "app"} ios release-switch scan cannot see what is built:\n- ${switchInputs.problems.join("\n- ")}`);
-try {
-  devtoolsAllowance = resolveDevtoolsAllowance({ config, root });
-  if (devtoolsAllowance.mode === "content-only") console.log(`right-release: devtools allowance recorded: ${JSON.stringify(devtoolsEvidence(devtoolsAllowance))}`);
-  assertNoForbiddenBuildFeatures({ root, tier: "release/update", devtools: devtoolsAllowance, cargoManifest: switchInputs.cargoManifest, manifest: config.releaseSwitches?.manifest, commands: [
-    ...switchInputs.commands,
-    { label: "target.prePackage", command: target.prePackage },
-    { label: "target.package", command: target.package },
-    { label: "nativeAssembly.packageHook", command: nativeAssembly?.packageHook },
-    { label: "nativeAssembly.finalizer", command: nativeFinalizer },
-    ...commandList(target.postSign).map((command, index) => ({ label: Array.isArray(target.postSign) ? `target.postSign[${index}]` : "target.postSign", command })),
-    { label: "target.gradle", command: target.gradle },
-  ] });
-} catch (error) { fail(error.message); }
-// M12: the frontend build resolves in production mode only (development-only conditional exports such as
-// `@rightkit/license/testing` never resolve). `run` pins NODE_ENV=production for build children; this refuses a
-// Vite config that lists the `development` resolve condition explicitly, which the pin cannot override.
-{
-  const modeProblems = productionModeProblems({ appRoot: root });
-  if (modeProblems.length) fail(`${config.app ?? "app"} release frontend is not production-only:\n- ${modeProblems.join("\n- ")}`);
-}
-
-// D4 (M21/M23) source layer: every environment/argument read in app source is registered in the app's switches.json and
-// every S1-S4 selector is compiled out of release. The inventory is `config.releaseSwitches.inventory` (relative to the
-// app root) or `switches.json`; a release without one fails (a dry run only checks one that exists).
-// The resolved feature graph (`cargo tree -e features`) is the AUTHORITATIVE test-mode check: it runs here, in the app
-// repository, for the release target, and a release that cannot run it fails (a dry run reports and continues).
-// The binary marker/name scan below is secondary evidence.
-const releaseSwitchInventoryPath = path.resolve(root, config.releaseSwitches?.inventory ?? "switches.json");
-const releaseSwitchInventoryText = existsSync(releaseSwitchInventoryPath) ? readFileSync(releaseSwitchInventoryPath, "utf8") : null;
-try {
-  // A `node recipe-build.mjs --plan <JSON>` prePackage hides each step's `--features` in one argument: the closure and the
-  // command token scan see every prepare / build / postBuild step (a plan that cannot be read or validated fails closed).
-  const closureCommands = [target.prePackage, target.package, nativeAssembly?.packageHook, nativeFinalizer, ...commandList(target.postSign), target.gradle, ...switchInputs.cargoCommands].filter(Boolean).flatMap((c) => expandRecipeBuildCommands(c, { root }));
-  assertReleaseDependencies({ root, config, target, commands: closureCommands });
-  let treeText;
-  try {
-    const closure = resolveFeatureClosure({
-      root,
-      manifest: config.releaseSwitches?.manifest,
-      cargoManifest: switchInputs.cargoManifest,
-      rust: config.releaseSwitches?.rust,
-      features: config.releaseSwitches?.features ?? [],
-      // The shipped triples (never "all": the build broker refuses it); evaluated on the raw config target.
-      triples: () => shippedRustTriples({ platform: opts.platform, target: config.targets?.[opts.platform] }),
-      commandTexts: closureCommands,
-    });
-    if (closure.skipped) console.log(`right-release: feature closure skipped (${closure.skipped})`);
-    else treeText = closure.treeText;
-  } catch (error) {
-    if (!opts.dryRun) throw error;
-    console.log(`right-release: dry run: ${error.message}`);
-  }
-  // remoteHost: rightkit-daemon `remote` is refused in the closure unless the app declares releaseSwitches.remoteHost: true.
-  // remoteLoopback: the daemon `remote-loopback` feature is a separate declaration (releaseSwitches.remoteLoopback: true); remoteHost does not cover it.
-  const closureInput = { treeText, devtools: devtoolsAllowance, remoteHost: config.releaseSwitches?.remoteHost, remoteLoopback: config.releaseSwitches?.remoteLoopback, commands: closureCommands.map((c) => commandTokens(c)) };
-  if (releaseSwitchInventoryText != null) {
-    // iOS: only what the iPhone app compiles — the Xcode project and its local packages, plus the local crates in the
-    // resolved aarch64-apple-ios cargo graph (feature-aware, unlike the ownership closure). Other targets walk the app root.
-    let sourceRoots;
-    if (opts.platform === "ios") {
-      const repoTop = git(root, ["rev-parse", "--show-toplevel"]);
-      // Swift side only: the Rust side is the resolved cargo graph below. The ownership scope also folds in the whole
-      // nativeAssembly workspace, which would scan crates (desktop tools, the TUI) the iPhone never links.
-      const swiftSide = (iosOwnershipScope({ repoRoot: repoTop, appRoot: root, target: config.targets?.ios }) ?? []).filter((dir) => dir !== ".rightkit").map((dir) => path.join(repoTop, dir));
-      sourceRoots = [...new Set([...swiftSide, ...localCrateDirsFromTree(treeText, repoTop)])].sort();
-      // A prepare step can stage sources from anywhere (a web bundle, a generated resource) into the app; its working directory must be
-      // inside the scanned roots, or the release fails instead of shipping what the scan never saw. Add the directory to ownershipScope.
-      for (const step of config.targets?.ios?.iosPackage?.prepare ?? []) {
-        const cwd = path.resolve(root, step?.cwd ?? ".");
-        if (!sourceRoots.some((dir) => cwd === dir || cwd.startsWith(dir + path.sep))) throw new Error(`source switch inventory: targets.ios.iosPackage.prepare runs in ${path.relative(repoTop, cwd) || "."}, outside the iOS scan roots (${sourceRoots.map((dir) => path.relative(repoTop, dir) || ".").join(", ")}); list that directory in targets.ios.ownershipScope`);
-      }
-      console.log(`right-release: source switch scan (ios): ${sourceRoots.map((dir) => path.relative(repoTop, dir) || ".").join(", ")}`);
-    }
-    assertNoReleaseSwitches({ ...closureInput, sourceRoot: root, sourceRoots, inventoryText: releaseSwitchInventoryText, appForbid: config.releaseSwitches?.forbid ?? [] }, "source switch inventory");
-  } else if (treeText != null || closureInput.commands.length) {
-    assertNoReleaseSwitches({ ...closureInput, appForbid: config.releaseSwitches?.forbid ?? [] }, "feature closure");
-  }
-  if (releaseSwitchInventoryText == null && !opts.dryRun) {
-    throw new Error(`source switch inventory: ${path.relative(root, releaseSwitchInventoryPath) || releaseSwitchInventoryPath} is missing; a release build needs the app's switches.json (see packages/release/README.md, "switches.json")`);
-  }
-} catch (error) { fail(error.message); }
+// One checkpoint for the build: every config finding of this run and every source-gate finding are reported together, and
+// nothing below (lock, install, checks, compile, signing) runs while any exists.
+// Source-level gates (release-switch scan, devtools, feature closure, release dependencies, production mode) live in
+// prebuild-gates.mjs so `doctor --gates` runs the exact same code in the same order. They read the expanded target (and the
+// iOS spec), so a failed one of those blocks them.
+const prebuildBlocker = ["target", ...(opts.platform === "ios" ? ["ios-target"] : [])].find((name) => failedChecks.has(name));
+const { findings: prebuildFindings, devtoolsAllowance, inventoryText: releaseSwitchInventoryText } = prebuildBlocker
+  ? { findings: [{ name: "prebuild-gates", detail: `BLOCKED by ${prebuildBlocker}` }], devtoolsAllowance: { mode: "denied" }, inventoryText: null }
+  : evaluatePrebuildGates({ root, config, target, platform: opts.platform, iosSpec, nativeIos, nativeAssembly, nativeFinalizer, strict: !opts.dryRun });
+if (problems.length || prebuildFindings.length) {
+  printProblems();
+  for (const finding of prebuildFindings) console.error(`right-release: ${finding.detail.startsWith("BLOCKED by ") ? `gate ${finding.name}: ` : ""}${finding.detail}`);
+  process.exit(1);
+}
 
 const releaseLock = acquireReleaseLock(root, config.app ?? path.basename(root), opts.platform, opts.tier);
 const mode = "package";
@@ -700,7 +782,8 @@ if (opts.platform === "win" && target.signingContract === WINDOWS_NSIS_SIGNING_C
   if (target.postSign) await runCommands(target.postSign, root);
   const updaterFiles = [...new Set((target.updater?.artifacts ?? []).map((artifact) => resolveReleaseArtifactPath(root, artifact.file)))];
   if (!updaterFiles.length) fail(`${config.app} win must declare updater.artifacts for post-code-signing minisign`);
-  await run("node", [SIGN_UPDATER, ...(opts.dryRun ? ["--dry-run"] : []), ...(target.updater?.keyFile ? ["--key-file", String(target.updater.keyFile)] : []), ...updaterFiles.flatMap((file) => ["--file", file])], root);
+  // The key comes from the OS credential provider inside sign-updater; targets.win.updater.keyFile is refused at config validation and never forwarded.
+  await run("node", [SIGN_UPDATER, ...(opts.dryRun ? ["--dry-run"] : []), ...updaterFiles.flatMap((file) => ["--file", file])], root);
 }
 
 if (target.postSign && opts.platform !== "win" && (opts.platform !== "mac" || runMacPhase("post-sign"))) {
@@ -822,7 +905,9 @@ function resolveReleaseArtifactPath(root, declared) {
 }
 
 function fail(message) {
+  printProblems();
   console.error(`right-release: ${message}`);
+  if (opts.doctor) console.error("right-release: doctor stopped here: this problem prevents the checks after it from running; fix it and run the doctor again to see the rest");
   process.exit(1);
 }
 
@@ -838,10 +923,7 @@ function assertSharedSccachePrerequisite() {
   const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
   const version = output.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
   const valid = result.status === 0 && version && isAtLeastVersion(version.slice(1).map(Number), [0, 15, 0]);
-  if (!valid) {
-    const found = version ? ` (found ${version[0]})` : "";
-    fail(`shared cache mode requires sccache >= 0.15.0${found}. Install with: cargo install sccache --locked; then verify: sccache --version`);
-  }
+  if (!valid) fail(sccacheRefusal(version?.[0]));
   return version[0];
 }
 
@@ -1097,38 +1179,49 @@ function commandTimeoutMs(command) {
     : undefined;
 }
 
-async function validateRightKitPackageContract(root, appName, hostedWorkflows) {
-  const packageJsonPath = path.join(root, "package.json");
-  const pkg = JSON.parse(await readFile(packageJsonPath, "utf8"));
-  const scripts = pkg.scripts ?? {};
-  assertQaBackdoorContract(root, scripts);
+// The workflow files of the repository, when it has any, against the hostedWorkflows policy.
+async function validateHostedWorkflowFiles(root, appName, hostedWorkflows, artifacts = []) {
   const workflowDir = path.join(root, ".github", "workflows");
-  if (existsSync(workflowDir)) {
-    const workflows = (await readdir(workflowDir)).sort();
-    if (workflows.length) {
-      await validateHostedWorkflows(root, appName ?? pkg.name ?? "app", workflows, hostedWorkflows);
-    }
-  }
+  if (!existsSync(workflowDir)) return;
+  const workflows = (await readdir(workflowDir)).sort();
+  if (workflows.length) await validateHostedWorkflows(root, appName, workflows, hostedWorkflows, artifacts);
+}
+
+function validatePackageManagerPin(pkg, appName) {
   if (pkg.packageManager !== RIGHTKIT_VERSIONS.packageManager) {
-    fail(`${appName ?? pkg.name ?? "app"} packageManager must be ${RIGHTKIT_VERSIONS.packageManager}, got ${pkg.packageManager ?? "<missing>"}`);
+    throw new ReleaseRefusal(`${appName} packageManager must be ${RIGHTKIT_VERSIONS.packageManager}, got ${pkg.packageManager ?? "<missing>"}`, "package-manager");
   }
-  if (JSON.stringify(scripts).includes("../tools/right-release") || JSON.stringify(scripts).includes("../rightkit/packages/release")) {
-    fail(`${appName ?? pkg.name ?? "app"} package.json must call the right-release bin, not parent-workspace release source`);
+}
+
+function validateNoParentWorkspaceScripts(pkg, appName) {
+  const scripts = JSON.stringify(pkg.scripts ?? {});
+  if (scripts.includes("../tools/right-release") || scripts.includes("../rightkit/packages/release")) {
+    throw new ReleaseRefusal(`${appName} package.json must call the right-release bin, not parent-workspace release source`, "package-workspace-scripts");
   }
+}
+
+// Every @rightkit/* dependency, each violation its own line of the finding.
+function validateRightKitPinSpecs(pkg, appName) {
+  const found = [];
   const rightKitDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
   for (const [name, specifier] of Object.entries(rightKitDeps).filter(([name]) => name.startsWith("@rightkit/"))) {
     if (FORBIDDEN_RIGHTKIT_SPEC.test(String(specifier))) {
-      fail(`${appName ?? pkg.name ?? "app"} ${name} must come from the published npm package, not ${specifier}`);
+      found.push(`${appName} ${name} must come from the published npm package, not ${specifier}`);
+      continue;
     }
     const allowed = RIGHTKIT_ALLOWED.get(name);
     if (allowed && !rightKitVerifiedNpm.get(name)?.has(specifier) && !rightKitVersionAllowed(allowed, specifier)) {
-      fail(`${appName ?? pkg.name ?? "app"} ${name} must be one of ${[...allowed].join(", ")}, got ${specifier}`);
+      found.push(`${appName} ${name} must be one of ${[...allowed].join(", ")}, got ${specifier}`);
     }
   }
+  if (found.length) throw new ReleaseRefusal(found.join("\n"), "rightkit-pin-specs", found);
+}
+
+function validateRightKitReleaseSupported(pkg, appName) {
   const releaseAllowed = RIGHTKIT_ALLOWED.get("@rightkit/release");
   const releaseSpecifier = pkg.devDependencies?.["@rightkit/release"];
   if (!releaseAllowed || !(rightKitVerifiedNpm.get("@rightkit/release")?.has(releaseSpecifier) || rightKitVersionAllowed(releaseAllowed, releaseSpecifier))) {
-    fail(`${appName ?? pkg.name ?? "app"} must depend on a supported @rightkit/release version in devDependencies`);
+    throw new ReleaseRefusal(`${appName} must depend on a supported @rightkit/release version in devDependencies`, "rightkit-release-supported");
   }
 }
 
@@ -1307,21 +1400,21 @@ async function signExistingRenderRefusal(root, manifest, source) {
 async function validateDeclaredWorkflowBlock(root, appName, manifest, declaredFiles) {
   const validator = (await loadRightKitCiModule(root, "workflows.mjs", "validateWorkflows"))?.validateWorkflows;
   const renderLanes = await loadRightKitCiRenderer(root);
-  if (!validator || !renderLanes) fail(`${appName} right-git-ci-only policy cannot verify .rightgit.json workflows: @rightkit/ci is not available (install @rightkit/ci as a devDependency)`);
+  if (!validator || !renderLanes) throw new ReleaseRefusal(`${appName} right-git-ci-only policy cannot verify .rightgit.json workflows: @rightkit/ci is not available (install @rightkit/ci as a devDependency)`, "hosted-workflows");
   const errors = [];
   validator(manifest, errors);
-  if (errors.length > 0) fail(`${appName} right-git-ci-only policy refuses the .rightgit.json workflows block: ${errors.join("; ")}`);
+  if (errors.length > 0) throw new ReleaseRefusal(`${appName} right-git-ci-only policy refuses the .rightgit.json workflows block: ${errors.join("; ")}`, "hosted-workflows");
   let rendered;
   try {
     rendered = renderLanes(manifest, root);
   } catch (error) {
-    fail(`${appName} right-git-ci-only policy cannot render the .rightgit.json workflows block: ${error.message}`);
+    throw new ReleaseRefusal(`${appName} right-git-ci-only policy cannot render the .rightgit.json workflows block: ${error.message}`, "hosted-workflows");
   }
   for (const file of declaredFiles) {
     const expected = rendered.find((entry) => entry.filename === file)?.content;
     const actual = await readFile(path.join(root, ".github", "workflows", file), "utf8");
     if (typeof expected !== "string" || actual.replace(/\r\n?/g, "\n") !== expected.replace(/\r\n?/g, "\n")) {
-      fail(`${appName} ${file} is not byte-for-byte the @rightkit/ci render of its .rightgit.json workflows entry (run right-git sync)`);
+      throw new ReleaseRefusal(`${appName} ${file} is not byte-for-byte the @rightkit/ci render of its .rightgit.json workflows entry (run right-git sync)`, "hosted-workflows");
     }
   }
 }
@@ -1330,7 +1423,7 @@ async function validateDeclaredWorkflowBlock(root, appName, manifest, declaredFi
 // `contents: read`, no other permissions key exists, no secrets reference, every `uses:` is commit-pinned, and every
 // checkout step sets persist-credentials: false. Steps are split on step-list indentation, not matched as free text.
 function declaredWorkflowPolicyRefusal(appName, workflow, source) {
-  const refuse = (why) => fail(`${appName} right-git managed ${workflow} violates the declared-workflow policy: ${why}`);
+  const refuse = (why) => { throw new ReleaseRefusal(`${appName} right-git managed ${workflow} violates the declared-workflow policy: ${why}`, "hosted-workflows"); };
   const lines = source.replace(/\r\n?/g, "\n").split("\n");
   const permissionsAt = lines.flatMap((line, i) => (/^\s*permissions\s*:/.test(line) ? [i] : []));
   if (permissionsAt.length !== 1 || lines[permissionsAt[0]] !== "permissions:" || lines[permissionsAt[0] + 1] !== "  contents: read" || /^ {2,}\S/.test(lines[permissionsAt[0] + 2] ?? "")) refuse("permissions must be exactly one top-level `contents: read`");
@@ -1353,16 +1446,25 @@ function declaredWorkflowPolicyRefusal(appName, workflow, source) {
   if (/^\s*(?:- )?uses:/m.test(lines.filter((l) => !steps.some((b) => b.includes(l))).join("\n"))) refuse("a uses: sits outside a step list");
 }
 
-async function validateHostedWorkflows(root, appName, workflows, policy) {
+async function validateHostedWorkflows(root, appName, workflows, policy, artifacts = []) {
+  // A repository that ships more than the released app (a monorepo's web or server pipeline) declares each workflow and why;
+  // none may reach a secret but GITHUB_TOKEN or run release machinery (hosted-workflow-policy.mjs).
+  if (policy !== null && typeof policy === "object" && policy.policy === DECLARED_UNRELATED_POLICY) {
+    const texts = new Map();
+    for (const file of workflows) texts.set(file, await readFile(path.join(root, ".github", "workflows", file), "utf8"));
+    const refusal = declaredUnrelatedRefusal({ declaration: policy, workflows, read: (file) => texts.get(file), artifacts });
+    if (refusal) throw new ReleaseRefusal(`${appName} ${DECLARED_UNRELATED_POLICY} hosted workflows refused: ${refusal}`, "hosted-workflows");
+    return;
+  }
   if (policy !== "right-git-ci-only") {
-    fail(`${appName} hosted workflow files are forbidden: ${workflows.join(", ")}`);
+    throw new ReleaseRefusal(`${appName} hosted workflow files are forbidden: ${workflows.join(", ")} (set hostedWorkflows to "right-git-ci-only", or to { policy: "${DECLARED_UNRELATED_POLICY}", files: { <file>: <reason> } } when they are a pipeline unrelated to the released app)`, "hosted-workflows");
   }
   const manifestPath = path.join(root, ".rightgit.json");
   let manifest;
   try {
     manifest = JSON.parse(await readFile(manifestPath, "utf8"));
   } catch {
-    fail(`${appName} right-git-ci-only policy requires a valid .rightgit.json`);
+    throw new ReleaseRefusal(`${appName} right-git-ci-only policy requires a valid .rightgit.json`, "hosted-workflows");
   }
   const lanes = manifest?.lanes;
   // Mirrors the `lanes` enum in @rightkit/ci manifest.schema.json.
@@ -1374,29 +1476,29 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
     || !(lanes.includes("ci") || lanes.includes("swift-check"))
     || new Set(lanes).size !== lanes.length
     || lanes.some((lane) => !safeLanes.has(lane))) {
-    fail(`${appName} right-git-ci-only policy requires compile=github-actions-only plus unique .rightgit.json lanes drawn from [${[...safeLanes].map((lane) => `"${lane}"`).join(", ")}] and including "ci" or "swift-check"`);
+    throw new ReleaseRefusal(`${appName} right-git-ci-only policy requires compile=github-actions-only plus unique .rightgit.json lanes drawn from [${[...safeLanes].map((lane) => `"${lane}"`).join(", ")}] and including "ci" or "swift-check"`, "hosted-workflows");
   }
   // Workflows declared under the manifest's `workflows` block (@rightkit/ci workflows.mjs: explicit `file`,
   // else `<name>.yml`) are managed files too, in addition to the lane files.
   const declaredWorkflows = manifest?.workflows;
   if (declaredWorkflows !== undefined && (declaredWorkflows === null || typeof declaredWorkflows !== "object" || Array.isArray(declaredWorkflows))) {
-    fail(`${appName} right-git-ci-only policy requires .rightgit.json workflows to be an object`);
+    throw new ReleaseRefusal(`${appName} right-git-ci-only policy requires .rightgit.json workflows to be an object`, "hosted-workflows");
   }
   const declaredFiles = Object.entries(declaredWorkflows ?? {}).map(([name, config]) => {
-    if (config === null || typeof config !== "object" || Array.isArray(config)) fail(`${appName} right-git-ci-only policy requires .rightgit.json workflows.${name} to be an object`);
+    if (config === null || typeof config !== "object" || Array.isArray(config)) throw new ReleaseRefusal(`${appName} right-git-ci-only policy requires .rightgit.json workflows.${name} to be an object`, "hosted-workflows");
     const file = typeof config?.file === "string" ? config.file : `${name}.yml`;
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,60}\.yml$/.test(file)) fail(`${appName} right-git-ci-only policy refuses workflow file name ${JSON.stringify(file)} declared by .rightgit.json`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,60}\.yml$/.test(file)) throw new ReleaseRefusal(`${appName} right-git-ci-only policy refuses workflow file name ${JSON.stringify(file)} declared by .rightgit.json`, "hosted-workflows");
     return file;
   });
   const expectedWorkflows = [...new Set([...lanes.map((lane) => `${lane}.yml`), ...declaredFiles])].sort();
   if (JSON.stringify(workflows) !== JSON.stringify(expectedWorkflows)) {
-    fail(`${appName} right-git-ci-only policy requires workflows declared by .rightgit.json; expected ${expectedWorkflows.join(", ")}, got: ${workflows.join(", ")}`);
+    throw new ReleaseRefusal(`${appName} right-git-ci-only policy requires workflows declared by .rightgit.json; expected ${expectedWorkflows.join(", ")}, got: ${workflows.join(", ")}`, "hosted-workflows");
   }
   if (declaredFiles.length > 0) await validateDeclaredWorkflowBlock(root, appName, manifest, declaredFiles);
   for (const workflow of expectedWorkflows) {
     const source = await readFile(path.join(root, ".github", "workflows", workflow), "utf8");
     if (!source.startsWith("# Managed by right-git")) {
-      fail(`${appName} ${workflow} is not marked as right-git managed`);
+      throw new ReleaseRefusal(`${appName} ${workflow} is not marked as right-git managed`, "hosted-workflows");
     }
     if (declaredFiles.includes(workflow)) declaredWorkflowPolicyRefusal(appName, workflow, source);
     const jobSpan = (jobName) => {
@@ -1483,7 +1585,7 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
       const reason = manifest?.signExisting && typeof manifest.signExisting === "object"
         ? (signExistingRefusal(source) ?? await signExistingRenderRefusal(root, manifest, source))
         : "the manifest declares no signExisting";
-      if (reason !== null) fail(`${appName} right-git managed sign-existing.yml is not the protected sign-existing shape: ${reason}`);
+      if (reason !== null) throw new ReleaseRefusal(`${appName} right-git managed sign-existing.yml is not the protected sign-existing shape: ${reason}`, "hosted-workflows");
       protectedSignExisting = true;
     }
     // @rightkit/ci `swift.privatePackages` credential: allowed only in the workflow/job pairs and on the
@@ -1526,7 +1628,7 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
       || refusedSecrets.length > 0) {
       const reasons = [...new Set(refusedSecrets)];
       const detail = reasons.length > 10 ? [...reasons.slice(0, 10), `${reasons.length - 10} more`] : reasons;
-      fail(`${appName} right-git managed ${workflow} requests release-capable permissions or secrets${detail.length > 0 ? `: ${detail.join("; ")}` : ""}`);
+      throw new ReleaseRefusal(`${appName} right-git managed ${workflow} requests release-capable permissions or secrets${detail.length > 0 ? `: ${detail.join("; ")}` : ""}`, "hosted-workflows");
     }
   }
 }