@patronage/factory-ci 0.1.3 → 0.2.0

package/src/proof-reuse-gate.ts

@@ -0,0 +1,669 @@
+/**
+ * The GitHub-side **proof-reuse gate** (ADR 0022, #309, #317).
+ *
+ * It answers one question, before checkout and before install: may this job
+ * reuse the local verification the factory already published for *this exact
+ * head*? Refusing runs hosted CI; it never fails the candidate. Three
+ * repositories had independently grown their own answer to that question and
+ * had already drifted apart, so the answer lives here once, with the App
+ * identity, check name, step identity, output names, guard, and every trust
+ * predicate fixed rather than consumer-configurable.
+ *
+ * What a consumer chooses is only *what its guarded surface requires*: the
+ * plain profile command objects that surface selects. Everything else below is
+ * the same for every consumer and every surface.
+ */
+
+/**
+ * Escaped so the emitted text carries a GitHub Actions expression rather than
+ * this file carrying a JavaScript template hole.
+ */
+const githubExpression = (expression: string): string =>
+  `\${{ ${expression} }}`;
+
+/** A braced shell expansion that has to survive TypeScript interpolation. */
+const shellExpansion = (expression: string): string => `\${${expression}}`;
+
+/**
+ * Single-quote a value for the emitted script. Every non-literal value that
+ * reaches the script goes through this.
+ *
+ * `JSON.stringify` is *not* a shell quoter — it escapes `"` and `\` and leaves
+ * `'` untouched — so interpolating a JSON document straight into a
+ * single-quoted assignment lets one apostrophe in a profile command name close
+ * the assignment and run the remainder as shell. Names are charset-validated
+ * before they get here; this is the second layer, so the interpolation stays
+ * safe if that validation is ever loosened.
+ */
+const shellSingleQuote = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * The check run the gate reads. Fixed: `patronage-factory/pr-verify` is also
+ * postable as a *commit status* by any token with write access, so only the
+ * Checks API is ever consulted and only under this exact name.
+ */
+export const FACTORY_PROOF_GATE_CHECK_NAME = "patronage-factory/pr-verify";
+
+/**
+ * The Patronage Factory GitHub App, pinned (ADR 0022). A runner has no
+ * operator user config to read the producing App identity from, and the
+ * identity is a trust predicate, so it is not a repository variable a consumer
+ * can point somewhere else. Neither the id nor the slug is a secret: GitHub
+ * returns `app.id` on every check run it serves.
+ */
+export const FACTORY_PROOF_GATE_APP_ID = "4314840";
+
+/** Step id the guard condition refers to. */
+export const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
+
+/**
+ * The shell the gate runs under, and it is a correctness requirement rather
+ * than a preference.
+ *
+ * GitHub's default for a `run:` step is `bash -e {0}`: **errexit comes from
+ * the invocation, not from the script**, and no `set +e` in the script body
+ * can be relied on to express the intent because the abort happens at the
+ * failing command. The whole fail-open design below — every path reaching one
+ * final `GITHUB_OUTPUT` write, no `set -e` — is void under that default. It
+ * was: the gate died at a `read` returning 1 at EOF, two seconds in, with no
+ * stdout, no verdict and no `reason`, so reuse collapsed to never *and* the
+ * signal built to reveal that could not fire (#319).
+ *
+ * A `shell:` value containing `{0}` is used verbatim by the runner, so this
+ * form supplies no `-e`. The shorthand `shell: bash` must never be used here:
+ * it expands to `bash --noprofile --norc -eo pipefail {0}`. `pipefail` is set
+ * by the script itself.
+ *
+ * The script is additionally written to survive errexit anyway. Both layers
+ * are deliberate: this one states the contract, that one means a runner which
+ * ignores it still gets a decision.
+ */
+export const FACTORY_PROOF_GATE_SHELL = "bash --noprofile --norc {0}";
+
+/** Output the verdict is written to. `true` — and only `true` — skips. */
+export const FACTORY_PROOF_GATE_OUTPUT = "reuse-proof";
+
+/**
+ * Machine-readable refusal category. Fleet-status reads this: it is what makes
+ * a reuse-collapses-to-never regression visible instead of hidden behind
+ * fail-open, which by construction looks exactly like healthy full CI.
+ */
+export const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
+
+/**
+ * Recorded verification mode, when the gate could read one. Diagnostic
+ * metadata only — never an authorization condition (ADR 0022). A reduced-mode
+ * proof that executed every command the surface requires is reusable.
+ */
+export const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+
+/**
+ * Guard for every step the gate protects. Deliberately `!= 'true'` and not
+ * `== 'false'`: an unset, empty, or garbled output must run the suite.
+ */
+export const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT} != 'true'`;
+
+/**
+ * Pull requests only. A push to a protected branch must never skip: deploy
+ * gates wait for a green required check at the *merged* SHA, and no local
+ * proof was ever written for that tree.
+ */
+export const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
+
+/**
+ * The complete refusal vocabulary. Deliberately few, because these are the
+ * only distinctions the gate can honestly make from one Checks API read.
+ *
+ * - `proven`     a covering, passing, unambiguous proof for this exact head
+ * - `none`       no App-verified factory check run at this commit
+ * - `pending`    the newest generation had not completed when this job read it
+ * - `failed`     the newest generation records no pass
+ * - `unreadable` it passed but carries no binding for this repository and head
+ * - `incomplete` it passed but did not execute every required command
+ * - `ambiguous`  two newest generations share the greatest start time
+ * - `error`      the gate could not reach a decision (fail open)
+ *
+ * There is no `reduced`: mode stopped being an authorization condition in
+ * ADR 0022, so a narrower run that still executed every required command is
+ * indistinguishable from a full one *for this surface*, which is the point.
+ */
+export const FACTORY_PROOF_GATE_REASONS = [
+  "proven",
+  "none",
+  "pending",
+  "failed",
+  "unreadable",
+  "incomplete",
+  "ambiguous",
+  "error",
+] as const;
+
+export type FactoryProofGateReason =
+  (typeof FACTORY_PROOF_GATE_REASONS)[number];
+
+/**
+ * One entry of a consumer's `verification.commands` (ADR 0021). Only the two
+ * load-bearing fields are declared: `name` is the command *identity* the proof
+ * records in `executedCommands`, `command` is the string the static coverage
+ * assertion matches against the work a reused proof would skip.
+ */
+export interface ProofReuseCommand {
+  readonly command: string;
+  readonly name: string;
+}
+
+/**
+ * Command identities are baked into the emitted script, so their charset is a
+ * safety property, not a style rule. `surface` has always gone through
+ * `safeLabel` for this reason; `name` needs the same treatment.
+ *
+ * Deliberately a strict allow-list rather than a quote-escaper: a name is an
+ * identifier, and every identity across the fleet's profiles today is
+ * `[a-z0-9:-]`. Anything outside this — hostile or merely a stray apostrophe —
+ * makes the whole selection unusable, which degrades to the refusing script.
+ * A stray apostrophe reaching interpolation would otherwise kill the step with
+ * a bash syntax error *before* the single `GITHUB_OUTPUT` write, so reuse
+ * would collapse to never with no `reason` written at all — the silent
+ * regression the vocabulary exists to make visible.
+ */
+const COMMAND_IDENTITY = /^\w[\w.:@/-]*$/u;
+const COMMAND_IDENTITY_MAX_LENGTH = 120;
+
+const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
+  if (!(value && typeof value === "object")) {
+    return false;
+  }
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.command === "string" &&
+    entry.command.length > 0 &&
+    typeof entry.name === "string" &&
+    entry.name.length <= COMMAND_IDENTITY_MAX_LENGTH &&
+    COMMAND_IDENTITY.test(entry.name)
+  );
+};
+
+/**
+ * The command identities a guarded surface requires, derived from the profile
+ * command objects that surface selected. This is the single derivation: the
+ * gate script and the static coverage assertion both go through it, so a
+ * consumer can never have one notion of "required" at generation time and
+ * another at assertion time.
+ *
+ * `undefined` means the selection is unusable — not an array, empty, or
+ * carrying an entry whose `command` is blank or whose `name` is not a plain
+ * command identity. An empty required set would make *every* passing proof
+ * trivially covering, so it is never silently treated as "requires nothing";
+ * callers must refuse instead.
+ */
+export const proofReuseRequiredCommands = (
+  commands: readonly ProofReuseCommand[]
+): readonly string[] | undefined => {
+  if (!(Array.isArray(commands) && commands.length > 0)) {
+    return;
+  }
+  if (!commands.every(isProofReuseCommand)) {
+    return;
+  }
+  return [...new Set(commands.map(({ name }) => name))].toSorted();
+};
+
+/**
+ * jq program: every page of the Checks API result in, three sanitized lines
+ * (`reason`, `mode`, missing commands) out.
+ *
+ * The input is what `gh api --paginate` actually writes: the pages
+ * *concatenated* as a stream of top-level response objects, not merged into
+ * one document and not wrapped in an array. That is why the script invokes
+ * `jq -s` and why this program opens with `.[] | (.check_runs // [])[]`. A
+ * test double that emits `[{ "check_runs": [...] }]` instead is a different
+ * shape: `jq` fails with `Cannot index array with string ("check_runs")`, the
+ * script lands on `reason=error`, and — because the gate fails open — the
+ * result looks exactly like healthy full CI. Stub `gh` with a bare response
+ * object per page.
+ *
+ * `binding` recovers the machine-readable payload from `output.text`
+ * (preferred) or `output.summary`, which the factory writes as a fenced JSON
+ * document. Anything unparseable degrades to `null`, and therefore to a
+ * refusal.
+ *
+ * This is the *second* parser of that payload: `parsePrVerifyCheckPayload`
+ * (`software-factory/src/pr-verify-check-payload.ts`) regex-extracts the fenced
+ * block, while this one strips fence lines and `fromjson`s what remains. The
+ * one input that separates them is prose around the fence, which parses there
+ * and refuses here. Both halves of that are asserted in the test suite rather
+ * than asserted here in prose — the exact shape the renderer emits is proven,
+ * and the divergent shape is proven to fail safe. Two parsers of one payload
+ * can drift; what must not drift silently is which direction they drift in.
+ *
+ * Ordering is by `started_at` alone, normalized to whole seconds. Two
+ * generations that share the greatest start time are `ambiguous` rather than
+ * arbitrarily resolved: the gate cannot tell which one describes the tree, and
+ * silently picking either is exactly the kind of coin-flip authorization this
+ * whole mechanism exists to remove. Sub-second precision is dropped so
+ * `…:00Z` and `…:00.000Z` compare equal; two genuine verification generations
+ * starting within the same second at the same head is not a real state, and
+ * collapsing them errs toward refusing.
+ *
+ * The comparison is lexical, which is correct only for fixed-width UTC. A
+ * `+HH:MM` offset would sort by its literal text rather than by its instant,
+ * and an absent `started_at` would sort to the bottom. The Checks API returns
+ * neither today, so this is guarded rather than merely noted: every candidate
+ * must carry a canonical UTC timestamp, and one that does not makes the newest
+ * generation unestablishable, which is `ambiguous`. Refusing costs a hosted
+ * run; ranking an unorderable set could authorize the wrong one.
+ */
+const GATE_JQ = String.raw`
+def binding:
+  [ .output.text, .output.summary ]
+  | map(select(type == "string"))
+  | map(split("\n") | map(select(startswith("${"```"}") | not)) | join("\n"))
+  | map(. as $body | try ($body | fromjson) catch null)
+  | map(select(type == "object"))
+  | .[0];
+
+def startedAt: (.started_at // "") | tostring;
+
+def rankable:
+  test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$");
+
+[ .[]
+  | (.check_runs // [])[]
+  | select(.name == $name)
+  | select(((.app.id // "") | tostring) == $app)
+  | { started: startedAt,
+      status: (.status // ""),
+      conclusion: (.conclusion // ""),
+      binding: binding }
+] as $runs
+| ($runs | map(.started | rankable) | all) as $orderable
+| ($runs | map(.started | sub("\\.[0-9]+Z$"; "Z")) | max) as $newest
+| [ $runs[] | select((.started | sub("\\.[0-9]+Z$"; "Z")) == $newest) ] as $generation
+| (if ($runs | length) == 0 then ["none", "", ""]
+   elif ($orderable | not) then ["ambiguous", "", ""]
+   elif ($generation | length) != 1 then ["ambiguous", "", ""]
+   else
+     $generation[0] as $run
+     | (if ($run.binding | type) == "object" then $run.binding else {} end) as $proof
+     | (($proof.mode // "") | tostring) as $mode
+     | (($proof.executedCommands // []) | map(select(type == "string"))) as $executed
+     | ($required - $executed) as $missing
+     | (if $run.status != "completed" then "pending"
+        elif $run.conclusion != "success" then "failed"
+        elif (($run.binding | type) != "object")
+          or ($proof.kind != "pr-verify-proof-binding")
+          or ($proof.schemaVersion != 1)
+          or ($proof.headSha != $sha)
+          or ($proof.repository != $repository) then "unreadable"
+        elif $proof.outcome != "passed" then "failed"
+        elif ($required | length) == 0 then "incomplete"
+        elif ($missing | length) != 0 then "incomplete"
+        else "proven"
+        end) as $reason
+     | [$reason, $mode, ($missing | join(", "))]
+   end)
+| map(gsub("[\\r\\n\\t]"; " "))
+| join("\n")
+`.trim();
+
+/**
+ * Every refusal ends on the same line. `pr:verify` is the command that
+ * produces the proof this job looks for, so it is the corrective action
+ * whatever the refusal was.
+ *
+ * It is phrased as an option, not a reprimand. A pull request opened by hand
+ * has no factory proof and never will; the full suite running for it is the
+ * designed behavior, not a mistake to report.
+ */
+const CORRECTIVE_LINE =
+  "Run `psf pr:verify` before publishing to reuse local proof and avoid a duplicate server run.";
+
+/**
+ * Emitted when a consumer's command selection is unusable. Mirrors the
+ * retired hosted docs-only detector: a malformed profile slice degrades to the
+ * conservative answer at *runtime* rather than throwing at generation time,
+ * because the input is JSON that may be absent or reshaped. The loud signal is
+ * the static coverage assertion, plus `reason=error` on the step output.
+ */
+const UNUSABLE_SELECTION_SCRIPT = String.raw`{
+  printf '${FACTORY_PROOF_GATE_OUTPUT}=false\n'
+  printf '${FACTORY_PROOF_GATE_REASON_OUTPUT}=error\n'
+} >> "${shellExpansion("GITHUB_OUTPUT:-/dev/null")}"`;
+
+/** Surface labels reach markdown, so only a plain, bounded label survives. */
+const safeLabel = (surface: string): string => {
+  const cleaned = (typeof surface === "string" ? surface : "")
+    .replaceAll(/[^\w -]/gu, "")
+    .trim()
+    .slice(0, 60);
+  return cleaned.length > 0 ? cleaned : "verification";
+};
+
+const gateScript = (required: readonly string[], surface: string): string =>
+  String.raw`
+set -uo pipefail
+
+CHECK_NAME=${shellSingleQuote(FACTORY_PROOF_GATE_CHECK_NAME)}
+FACTORY_APP_ID=${shellSingleQuote(FACTORY_PROOF_GATE_APP_ID)}
+REQUIRED_COMMANDS=${shellSingleQuote(JSON.stringify(required))}
+SURFACE=${shellSingleQuote(surface)}
+
+reason=error
+detail=''
+mode=''
+missing=''
+
+# filter=all with full pagination is load-bearing (ADR 0022). GitHub's
+# default "latest" filter is ordered by completion, so a newer generation
+# that is still running can be hidden behind an older completed one — the
+# gate would then read a stale pass as current.
+if [ -z "${shellExpansion("HEAD_SHA:-")}" ]; then
+  detail='no pull request head SHA'
+elif [ -z "${shellExpansion("GITHUB_REPOSITORY:-")}" ]; then
+  detail='no repository name'
+elif ! response=$(gh api --method GET --paginate \
+    "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/check-runs" \
+    -f "check_name=$CHECK_NAME" \
+    -f filter=all \
+    -f per_page=100 2>&1); then
+  detail="checks API unreadable: $response"
+elif ! finding=$(printf '%s' "$response" | jq -r -s \
+    --arg name "$CHECK_NAME" \
+    --arg app "$FACTORY_APP_ID" \
+    --arg sha "$HEAD_SHA" \
+    --arg repository "$GITHUB_REPOSITORY" \
+    --argjson required "$REQUIRED_COMMANDS" \
+    '${GATE_JQ}' 2>&1); then
+  detail="unreadable proof binding: $finding"
+else
+  # Three separate reads, not one IFS split: tab is IFS whitespace, so a
+  # split would collapse the empty fields the vocabulary relies on.
+  #
+  # The trailing "|| :" on each read is load-bearing. "missing" is empty for
+  # every verdict except "incomplete", so jq's third field is the empty
+  # string, command substitution strips the trailing newline, and the third
+  # read reaches EOF -- having correctly assigned "" -- and returns 1. Under
+  # an errexit shell that return value kills the step before the single
+  # GITHUB_OUTPUT write below, which is exactly how this gate failed in
+  # hosted CI on every decidable verdict while every test passed (#319).
+  {
+    IFS= read -r reason || :
+    IFS= read -r mode || :
+    IFS= read -r missing || :
+  } <<< "$finding"
+  case "$reason" in
+    proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
+    *)
+      detail="unexpected gate result: $reason"
+      reason=error
+      ;;
+  esac
+fi
+
+# The binding is App-verified, but it still reaches markdown. Only a plain
+# lowercase token is quoted back; anything else is reported as unknown.
+case "$mode" in
+  '') ;;
+  *[!a-z-]*) mode='unknown' ;;
+esac
+
+verdict=false
+if [ "$reason" = 'proven' ]; then
+  verdict=true
+fi
+
+# detail can carry arbitrary gh or jq error text. Collapse it to one bounded
+# line so it cannot restructure the summary it is written into.
+detail=$(printf '%s' "$detail" | tr '\n\r\t' '   ' | cut -c1-240)
+missing=$(printf '%s' "$missing" | tr '\n\r\t' '   ' | cut -c1-240)
+
+SUMMARY="${shellExpansion("GITHUB_STEP_SUMMARY:-/dev/null")}"
+say() { printf '%s\n' "$1" >> "$SUMMARY"; }
+
+say "## Proof reuse: $SURFACE"
+say ''
+
+case "$reason" in
+  proven)
+    echo "Factory proof: reusing local verification of $HEAD_SHA; skipping the $SURFACE suite."
+    say "Skipped. The factory already verified this exact commit, so this job did not run the $SURFACE suite a second time."
+    say ''
+    say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
+    say "- Covers head: \`$HEAD_SHA\`"
+    say "- Recorded mode: \`$mode\` (diagnostic only), outcome \`passed\`."
+    ;;
+  none)
+    say 'Ran the full suite. No trusted factory proof covers this commit.'
+    say ''
+    say "The factory GitHub App has published no \`$CHECK_NAME\` check run at head \`$HEAD_SHA\`. Proof is keyed to the commit, so proof written for any other commit is not visible here. A pull request opened by hand carries no factory proof at all, which is normal."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  pending)
+    say 'Ran the full suite. The factory proof for this commit had not finished when this job read it.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` was still in progress. The gate reads one snapshot at job start and does not wait."
+    say ''
+    say "Let \`psf pr:verify\` finish before publishing, so its proof is on the commit before this job reads it."
+    ;;
+  failed)
+    say 'Ran the full suite. The factory proof for this commit records no pass.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` finished without a passing conclusion, so it establishes nothing about this tree."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  unreadable)
+    say 'Ran the full suite. The factory check run for this commit carries no proof this job can read.'
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but it carries no machine-readable binding naming this repository and this head, or one written to a schema this job does not recognize."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  incomplete)
+    say "Ran the full suite. The factory proof for this commit does not cover every command the $SURFACE surface requires."
+    say ''
+    say "The newest \`$CHECK_NAME\` check run at head \`$HEAD_SHA\` passed, but its \`executedCommands\` is missing: \`$missing\`"
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  ambiguous)
+    say 'Ran the full suite. The newest factory proof for this commit is ambiguous.'
+    say ''
+    say "Two \`$CHECK_NAME\` check runs at head \`$HEAD_SHA\` share the greatest start time, so there is no single newest generation to trust. The gate refuses rather than picking one."
+    say ''
+    say '${CORRECTIVE_LINE}'
+    ;;
+  *)
+    say 'Ran the full suite. The proof gate could not reach a decision.'
+    say ''
+    say 'The gate fails open by design: when it cannot tell whether proof exists, every command runs. Nothing about this pull request is implied.'
+    say ''
+    say "    $detail"
+    ;;
+esac
+say ''
+
+if [ "$verdict" != 'true' ]; then
+  echo "No reusable factory proof for ${shellExpansion("HEAD_SHA:-<unknown>")}; running the $SURFACE suite ($reason). $detail"
+fi
+
+# The only write. A crash before this line leaves the output unset, the guard
+# reads empty, and every guarded step runs — the fail-open path.
+{
+  printf '${FACTORY_PROOF_GATE_OUTPUT}=%s\n' "$verdict"
+  printf '${FACTORY_PROOF_GATE_REASON_OUTPUT}=%s\n' "$reason"
+  printf '${FACTORY_PROOF_GATE_MODE_OUTPUT}=%s\n' "$mode"
+} >> "${shellExpansion("GITHUB_OUTPUT:-/dev/null")}"
+`.trim();
+
+export interface FactoryProofGateOptions {
+  /**
+   * The profile command objects this guarded surface selected. A consumer with
+   * distinct core and docs jobs selects distinct sets, and each job's gate
+   * therefore requires a different coverage.
+   */
+  readonly commands: readonly ProofReuseCommand[];
+  /** Names the suite in the job summary. Changes no trust decision. */
+  readonly surface: string;
+}
+
+/**
+ * The gate script. Exported so it can be executed directly under test against
+ * a stubbed `gh`, rather than only asserted against as workflow text — the
+ * script is the security boundary, and asserting on generated YAML would leave
+ * its actual decisions untested.
+ *
+ * Note the deliberate absence of `set -e`: every failure path has to reach the
+ * final write, and that write must emit `false`. Omitting it is necessary but
+ * not sufficient — the runner supplies `-e` unless the step declares
+ * `FACTORY_PROOF_GATE_SHELL` — so the script is also written to reach that
+ * write under errexit, and the tests execute it both ways.
+ */
+export const factoryProofGateScript = ({
+  commands,
+  surface,
+}: FactoryProofGateOptions): string => {
+  const required = proofReuseRequiredCommands(commands);
+  return required
+    ? gateScript(required, safeLabel(surface))
+    : UNUSABLE_SELECTION_SCRIPT;
+};
+
+export interface FactoryProofGateStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<{
+    GH_TOKEN: string;
+    HEAD_SHA: string;
+  }>;
+  readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
+  readonly if: typeof FACTORY_PROOF_GATE_IF;
+  readonly name: string;
+  readonly run: string;
+  readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
+}
+
+/**
+ * The step itself, structurally accepted by gagen's `step()` without adding a
+ * gagen runtime dependency. It belongs first in the job it guards: one Checks
+ * API read with the default `GITHUB_TOKEN` (`checks: read`), no checkout, no
+ * install, so a proven head costs a runner nothing beyond job startup.
+ *
+ * A **step, not a job**, and that is not a style preference. A separate gate
+ * job that errored would leave the guarded job `skipped`, and a summary job
+ * that only fails on `failure`/`cancelled` would still report green — a Checks
+ * API outage would silently skip verification. As a step it fails open by
+ * construction: the step errors, the output is never written, the guard reads
+ * empty, and every command runs.
+ */
+export const factoryProofGateStep = (
+  options: FactoryProofGateOptions
+): FactoryProofGateStep =>
+  Object.freeze({
+    continueOnError: true as const,
+    env: Object.freeze({
+      GH_TOKEN: githubExpression("secrets.GITHUB_TOKEN"),
+      HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+    }),
+    id: FACTORY_PROOF_GATE_STEP_ID,
+    if: FACTORY_PROOF_GATE_IF,
+    name: "Check for factory proof of this head",
+    run: factoryProofGateScript(options),
+    // Never omit: the runner's default `run:` shell supplies `-e`, which
+    // voids the fail-open design. See FACTORY_PROOF_GATE_SHELL.
+    shell: FACTORY_PROOF_GATE_SHELL,
+  });
+
+export interface ProofReuseCoverageInput {
+  /** The same selection handed to the gate for this surface. */
+  readonly commands: readonly ProofReuseCommand[];
+  /**
+   * Skipped work covered under a different command string, keyed by the
+   * skipped string with the reason as its value. Deliberately explicit: a
+   * prose rationale for why some narrower command is "equivalent enough" is
+   * exactly what this assertion exists to force into the open.
+   */
+  readonly equivalents?: Readonly<Record<string, string>>;
+  /**
+   * The command strings the consumer's workflow would skip when the gate says
+   * `true`, already resolved to the leaves that actually run. Extracting them
+   * is the consumer's job: this package never parses workflow source, because
+   * doing so is what killed #288.
+   */
+  readonly skipped: readonly string[];
+  /** Names the surface in the failure message. */
+  readonly surface?: string;
+}
+
+export interface ProofReuseCoverageReport {
+  /** True only when the selection is usable *and* nothing is uncovered. */
+  readonly covered: boolean;
+  /** Command identities derived from the selection; empty when unusable. */
+  readonly requiredCommands: readonly string[];
+  /** Skipped command strings no selected profile command accounts for. */
+  readonly uncovered: readonly string[];
+}
+
+/**
+ * The static coverage assertion, as a report.
+ *
+ * Runtime command coverage is authoritative — the gate's `incomplete` refusal
+ * is the backstop that cannot be bypassed. This is the compile-time guard in
+ * front of it: it fails a consumer's build the moment a workflow skips work
+ * that no selected profile command runs, rather than letting the drift show up
+ * as CI quietly verifying nothing. The drift is real history: #227 wired a
+ * workspace member into CI while the profile never learned about it.
+ */
+export const proofReuseCoverage = ({
+  commands,
+  equivalents = {},
+  skipped,
+}: ProofReuseCoverageInput): ProofReuseCoverageReport => {
+  const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
+  const proven = new Set(
+    requiredCommands.length > 0
+      ? commands.map(({ command }) => command.trim())
+      : []
+  );
+  const uncovered = [
+    ...new Set(
+      (Array.isArray(skipped) ? skipped : [])
+        .map((command) => String(command).trim())
+        .filter(
+          (command) =>
+            command.length > 0 &&
+            // `Object.hasOwn`, never `in`: `in` walks the prototype chain, so
+            // a skipped command named `toString` or `constructor` would report
+            // itself as a declared equivalent of nothing. This assertion's only
+            // job is to fail loudly.
+            !(proven.has(command) || Object.hasOwn(equivalents, command))
+        )
+    ),
+  ].toSorted();
+
+  return Object.freeze({
+    covered: requiredCommands.length > 0 && uncovered.length === 0,
+    requiredCommands,
+    uncovered,
+  });
+};
+
+/** `proofReuseCoverage`, as a build failure. */
+export const assertProofReuseCoverage = (
+  input: ProofReuseCoverageInput
+): ProofReuseCoverageReport => {
+  const report = proofReuseCoverage(input);
+  if (report.covered) {
+    return report;
+  }
+
+  const surface = safeLabel(input.surface ?? "");
+  const problem =
+    report.requiredCommands.length === 0
+      ? "selects no usable profile commands, so any passing proof would trivially cover it"
+      : `skips work no selected profile command runs: ${report.uncovered.join(", ")}`;
+  throw new Error(
+    `Proof-reuse coverage failed: the ${surface} surface ${problem}. Add the command to software-factory.profile.json (and to this surface's selection), or stop skipping it.`
+  );
+};