@patronage/factory-ci 1.0.0-alpha.26 → 1.0.0-alpha.27

package/README.md

@@ -365,9 +365,8 @@ const coreCommands = profile.verification.commands.filter(
 );
 
 const core = job("core", {
-  // `checks: read` is all the default PR-only gate needs. Add
-  // `pull-requests: read` only with `reuse: "pull-request-and-default-branch"`,
-  // where the merge fallback (#611) looks up the producing pull request.
+  // `checks: read` is all the PR-only gate needs. It reads one Checks API
+  // endpoint and nothing else.
   permissions: { checks: "read", contents: "read" },
   steps: [
     step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
@@ -380,11 +379,9 @@ const core = job("core", {
 
 The **proof-reuse gate** decides whether a hosted job may reuse the local verification the factory already published for this exact head (ADR 0022). Refusing runs hosted CI; it never fails the candidate. The App identity, check name, step id, output names, guard, and every trust predicate are fixed here rather than consumer-configurable — three repositories had grown three answers to the same question and had already drifted.
 
-**The gate runs on pull requests only by default** (#863). A merge target's guarantee is about the whole tree, not the diff, and a candidate proof binds only the diff that candidate was scoped to. Every default-branch push therefore executes the full hosted suite, and the job needs only `checks: read`. #931 is the defect this default answers: a `main` push reused an impact-scoped candidate proof, executed no command, and left a red package unnoticed for three days.
+**The gate runs on pull requests only** (#863). A merge target's guarantee is about the whole tree, not the diff, and a candidate proof binds only the diff that candidate was scoped to. Every default-branch push therefore executes the full hosted suite, and the job needs only `checks: read`. #931 is the defect this answers: a `main` push reused an impact-scoped candidate proof, executed no command, and left a red package unnoticed for three days.
 
-`reuse` chooses which events may reuse proof (#873). It takes two values and nothing else, because the emitted condition is a trust predicate: a free-text override lets a consumer reuse proof on a ref nothing proved. `"pull-request"` is the default described above. `"pull-request-and-default-branch"` is the opt-out: it adds pushes to the default branch, and the consumer accepts that an impact-scoped candidate proof may gate a whole tree. Choose it when merge-target runner time matters more than that guarantee.
-
-Under the opt-out, a push run first reads proof at the pushed head. A squash merge mints a new commit, so when that direct read finds no generation at all, a **merge fallback** looks up the single merged pull request whose merge commit is the pushed head and reuses that PR head's proven check run — only when the merge commit's tree id equals the proven head's tree id, which makes the pushed content byte-identical to what was verified (a clean squash of an unchanged tip). Patch identity was considered and rejected as the comparator: `git patch-id` normalizes whitespace and ignores base motion, so an identical patch can still integrate into a tree nothing verified. No unique producing PR, an unreadable commit, a proof that is anything but proven, or tree drift from a dirty or stale merge all leave the direct refusal standing and run the full suite. The fallback needs `pull-requests: read` and `contents: read` on the job in addition to `checks: read`; a job that grants less loses only the fallback.
+There is no mode to choose. The emitted condition is a trust predicate, so the package owns it: the merge-target opt-out and its push-event merge fallback (#611) are deleted, and no consumer option can reuse proof outside a pull request.
 
 A proof is reusable only when the complete Checks API result (`filter=all`, every page) establishes one unambiguous newest generation by greatest `started_at`, produced by the pinned App for the exact repository and head, completed successfully with `outcome: passed`, and covering every command identity the guarded surface requires. Coverage is the union of `executedCommands` and commands released by `notRequiredCommands` only after the gate validates each release against that same proof binding's command-to-target map and identity-bound impact stamp. Missing, malformed, duplicated, affected, unknown, or differently bound release data refuses reuse and runs the hosted surface. `mode` is reported as diagnostic metadata, never authorized on: a reduced-mode proof whose executed and stamp-authorized released commands cover a surface is reusable.
 
@@ -489,6 +486,8 @@ Nothing is cached. The token is returned to the caller, which owns its lifetime
 
 `options` are all injectable seams: `fetch`, `now`, `readPrivateKey`, `transportAttempts`, and a `timeoutMs` per request (five seconds by default). Tests substitute the seams; production passes at most a timeout and a budget.
 
+Callers that must not receive the App's full installation grant pass `permissions` and `repositories` on the mint input. GitHub then issues a token covering only that subset. The Factory App broker uses `FACTORY_APP_BROKER_TOKEN_PERMISSIONS` (`checks: write`) and the one repository the Cursor OIDC claim authenticated (#949). Omitted, those fields keep the historical full-grant mint that operator PEM and Actions already use.
+
 ### Vitest suite profiling
 
 ```ts
@@ -679,7 +678,7 @@ import { ALCHEMY_BASELINE, assertAlchemyBaseline } from "@patronage/factory-ci";
 
 `ALCHEMY_BASELINE` is the exact `alchemy` and `effect` pair the fleet moves together on: `{ alchemy: "2.0.0-beta.76", effect: "4.0.0-rc.112" }`. It is a plain constant on the root entry — it imports neither package — so any consumer can read it without installing the `./alchemy` subpath's peers.
 
-`assertAlchemyBaseline({ packageJson })` is a consumer contract helper: it fails when the consumer's own `dependencies` or `devDependencies` pin `alchemy` or `effect` to anything other than the baseline. A package the consumer does not depend on at all is not drift — both are optional peers of the subpath, so a consumer that never imports it, such as this package's own CLI, carries neither and passes. The pin is exact, not a range: the fleet is pre-1.0 and moves together, so a range would let one project drift silently ahead of or behind the rest. `assertAlchemyBaseline` reads only the object it is handed; it never walks the filesystem or reads a lockfile. Call it from a consumer's own contract test, passing that consumer's parsed `package.json`.
+`assertAlchemyBaseline({ packageJson })` is a consumer contract helper: it fails when the consumer's own `dependencies` or `devDependencies` pin `alchemy` or `effect` to anything other than the baseline, and it fails when only one of the pair is present. Alchemy peers on Effect, so an unpinned auto-installed Effect can drift outside the baseline while a lone `alchemy` pin would otherwise pass. Both packages remaining absent is not drift — they are optional peers of the subpath, so a consumer that never imports it, such as this package's own CLI, carries neither and passes. The pin is exact, not a range: the fleet is pre-1.0 and moves together, so a range would let one project drift silently ahead of or behind the rest. `assertAlchemyBaseline` reads only the object it is handed; it never walks the filesystem or reads a lockfile. Call it from a consumer's own contract test, passing that consumer's parsed `package.json`.
 
 The baseline bumps only in a lockstep release: the same commit that bumps `@patronage/factory-ci`'s own `alchemy`/`effect` devDependencies and the `./alchemy` subpath's peer ranges (ADR 0031) also bumps `ALCHEMY_BASELINE`, so the constant a consumer's contract test checks against can never point at a version the subpath itself has moved past.
 

package/dist/.build-fingerprint.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "c63c213989e286a5baa59a9e2e2df1db05b55a0bc94208ecde13fb5a2384e5f0"
+  "fingerprint": "240e5f8f7ada26abe3ffc5e3041b19acbf4ded8c1e354c71ce669bdcc8b6e5a1"
 }

package/dist/alchemy/index.d.ts

@@ -342,8 +342,8 @@ declare class CloudflareCredentialUnavailableError extends Error {
   constructor(message?: string);
 }
 /**
- * Resolves the deploy's Cloudflare credential posture and proves the token
- * carries exactly the required permission groups.
+ * Resolves the deploy's Cloudflare credential posture and checks the token
+ * against the reviewed policy document.
  *
  * The check is: the environment matches the declared source, the credential
  * resolves, Cloudflare reports the token active, the reviewed policy names
@@ -351,6 +351,12 @@ declare class CloudflareCredentialUnavailableError extends Error {
  * the project expects, and the permission groups match the required list with
  * no group missing, extra, or repeated.
  *
+ * The permission groups come from the reviewed policy document, not from
+ * Cloudflare. This function never reads live permissions from the Cloudflare
+ * API. A token whose permissions changed after the review still passes, as
+ * long as Cloudflare reports it active and the document still matches its id.
+ * See issue #1010.
+ *
  * Throws on any failure. {@link CloudflareCredentialUnavailableError} means
  * Cloudflare could not be asked; every other error means the credential is
  * wrong. Nothing it throws, and nothing it returns, carries a secret value.
@@ -550,6 +556,12 @@ interface SecretNamePolicyOptions {
  * Longer values are replaced first, so a secret that contains another secret
  * leaves no fragment behind.
  *
+ * The policy replaces verbatim substrings of each named value only. A value
+ * that the output re-encodes passes through unredacted. URL-encoded,
+ * base64, and JSON-escaped forms are all such re-encodings. A project that
+ * prints a secret in one of those forms must not rely on this policy for it.
+ * See issue #1011.
+ *
  * An empty `names` list yields a pass-through function only when `values` is
  * also empty: a project with no secrets in its Alchemy output declares none,
  * and gets no redaction. Empty names beside a populated `values` map is

package/dist/alchemy/index.js

@@ -180,15 +180,18 @@ const LOCAL_PREVIEW_STAGES = (stage) => isLocalPreviewStage(stage);
 *
 * A `RegExp` with `g` or `y` advances `lastIndex` on every match, so the same
 * pattern answers "yes" and then "no" for the same stage. A policy that
-* alternates is worse than one that always refuses, so the flagged pattern is
-* copied without those flags rather than tested as given. The copy is built
-* only for a pattern that carries them.
+* alternates is worse than one that always refuses, so a flagged pattern is
+* tested through a fresh copy whose `lastIndex` starts at zero. The copy
+* carries the complete flags: `y` anchors the match at `lastIndex`, so
+* dropping it would let `/prod/y` accept a stage named `pre-prod` that the
+* project's own pattern rejects. The caller's own `RegExp` is never written
+* to, so a frozen one still works.
 */
-const statelessTest = (pattern, stage) => pattern.global || pattern.sticky ? new RegExp(pattern.source, pattern.flags.replaceAll(/[gy]/gu, "")).test(stage) : pattern.test(stage);
+const statelessTest$1 = (pattern, stage) => pattern.global || pattern.sticky ? new RegExp(pattern.source, pattern.flags).test(stage) : pattern.test(stage);
 const stageMatches = (matcher, stage) => {
 	if (typeof matcher === "function") return matcher(stage);
 	if (Array.isArray(matcher)) return matcher.includes(stage);
-	return statelessTest(matcher, stage);
+	return statelessTest$1(matcher, stage);
 };
 /** A matcher that accepts a stage any of `matchers` accepts. */
 const anyStage = (...matchers) => (stage) => matchers.some((matcher) => stageMatches(matcher, stage));
@@ -387,8 +390,8 @@ const resolveResolvedCredential = async (resolveCredential, environment) => {
 	}
 };
 /**
-* Resolves the deploy's Cloudflare credential posture and proves the token
-* carries exactly the required permission groups.
+* Resolves the deploy's Cloudflare credential posture and checks the token
+* against the reviewed policy document.
 *
 * The check is: the environment matches the declared source, the credential
 * resolves, Cloudflare reports the token active, the reviewed policy names
@@ -396,6 +399,12 @@ const resolveResolvedCredential = async (resolveCredential, environment) => {
 * the project expects, and the permission groups match the required list with
 * no group missing, extra, or repeated.
 *
+* The permission groups come from the reviewed policy document, not from
+* Cloudflare. This function never reads live permissions from the Cloudflare
+* API. A token whose permissions changed after the review still passes, as
+* long as Cloudflare reports it active and the document still matches its id.
+* See issue #1010.
+*
 * Throws on any failure. {@link CloudflareCredentialUnavailableError} means
 * Cloudflare could not be asked; every other error means the credential is
 * wrong. Nothing it throws, and nothing it returns, carries a secret value.
@@ -561,7 +570,21 @@ const routesReachable = (routes) => Array.isArray(routes) && routes.length > 0;
 const enrollsInAccess = (access) => access !== void 0 && access !== null;
 /** Is this Worker reachable from the internet by what the stack declares? */
 const publiclyReachable = ({ props }) => workersDevReachable(props.workersDev) || domainReachable(props.domain) || routesReachable(props.routes);
-const matchesAuthBindingName = (matcher, name) => matcher instanceof RegExp ? matcher.test(name) : matcher(name);
+/**
+* Test a pattern without carrying state between Workers.
+*
+* A `RegExp` with `g` or `y` advances `lastIndex` on every match, so the same
+* pattern answers "yes" for the first Worker and "no" for the second Worker
+* with the same binding name. A guard that alternates is worse than one that
+* always refuses, so a flagged pattern is tested through a fresh copy whose
+* `lastIndex` starts at zero. The copy carries the complete flags: `y`
+* anchors the match at `lastIndex`, so dropping it would let `/TOKEN/y`
+* credit a binding named `X_TOKEN` that the caller's pattern rejects. The
+* caller's own `RegExp` is never written to, so a frozen one still works.
+* Same isolation `stage-policy` already applies to stage names.
+*/
+const statelessTest = (pattern, name) => pattern.global || pattern.sticky ? new RegExp(pattern.source, pattern.flags).test(name) : pattern.test(name);
+const matchesAuthBindingName = (matcher, name) => matcher instanceof RegExp ? statelessTest(matcher, name) : matcher(name);
 /**
 * The Workers a Cloudflare Access application gates in production.
 *
@@ -661,6 +684,12 @@ const MINIMUM_REDACTABLE_SECRET_LENGTH = 8;
 * Longer values are replaced first, so a secret that contains another secret
 * leaves no fragment behind.
 *
+* The policy replaces verbatim substrings of each named value only. A value
+* that the output re-encodes passes through unredacted. URL-encoded,
+* base64, and JSON-escaped forms are all such re-encodings. A project that
+* prints a secret in one of those forms must not rely on this policy for it.
+* See issue #1011.
+*
 * An empty `names` list yields a pass-through function only when `values` is
 * also empty: a project with no secrets in its Alchemy output declares none,
 * and gets no redaction. Empty names beside a populated `values` map is

package/dist/index.d.ts

@@ -29,9 +29,12 @@ interface AssertAlchemyBaselineInput {
 }
 /**
  * Fails when the consumer's `alchemy` or `effect` pin differs from
- * {@link ALCHEMY_BASELINE}. A package the consumer does not depend on at all
- * is not drift — both packages are optional peers of the `./alchemy`
- * subpath, so a consumer that never touches it carries neither.
+ * {@link ALCHEMY_BASELINE}, or when only one of the pair is present.
+ * Alchemy peers on Effect, so an unpinned auto-installed Effect can drift
+ * outside the baseline while a lone `alchemy` pin would otherwise pass.
+ * Both packages remaining absent is not drift — they are optional peers of
+ * the `./alchemy` subpath, so a consumer that never touches it carries
+ * neither.
  *
  * Reads only the `packageJson` object it is handed; it never walks the
  * filesystem.
@@ -511,6 +514,35 @@ interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, Pin
  */
 declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
 //#endregion
+//#region src/cursor-oidc.d.ts
+/**
+ * Pinned Cursor OIDC trust predicates for the Factory App broker (#949).
+ *
+ * The broker verifies a Cursor-managed Cloud Agent JWT and mints a
+ * repo-scoped Factory App installation token. Audience, issuer, and JWKS are
+ * not consumer settings: a knob that pointed them elsewhere would be the
+ * whole mechanism undone, the same reason {@link FACTORY_PROOF_GATE_APP_ID}
+ * is pinned.
+ */
+/** Cursor's OIDC issuer. Tokens minted on the agent VM carry this `iss`. */
+declare const FACTORY_CURSOR_OIDC_ISSUER = "https://api.cursor.com";
+/** JWKS the broker uses to verify RS256 signatures. */
+declare const FACTORY_CURSOR_OIDC_JWKS_URL = "https://api.cursor.com/keys";
+/**
+ * Audience a Cursor-managed VM must mint with. The CLI and the broker share
+ * this string; Cursor does not allowlist audiences.
+ */
+declare const FACTORY_CURSOR_OIDC_AUDIENCE = "Factory";
+/**
+ * Runtime claim a Cursor-managed Cloud Agent VM always presents. Self-hosted
+ * workers are not this broker's callers.
+ */
+declare const FACTORY_CURSOR_OIDC_MANAGED_RUNTIME = "managed";
+/** HQ route that exchanges a verified Cursor OIDC JWT for an App token. */
+declare const FACTORY_APP_BROKER_PATH = "/api/factory-app/installation-token";
+/** Production broker origin. The CLI pins this; it is not profile-declared. */
+declare const FACTORY_APP_BROKER_ORIGIN = "https://hq.patronage.com";
+//#endregion
 //#region src/github-transport.d.ts
 /**
  * Bounded transport retries could not reach the GitHub App endpoint (#923).
@@ -545,6 +577,18 @@ declare class GitHubApiError extends Error {
   readonly status: number;
   constructor(status: number, statusText: string);
 }
+/**
+ * Installation-token permission subset. GitHub only grants permissions the
+ * App already has; a caller that wants least privilege names the subset here
+ * rather than taking the App's full installation grant (#949).
+ */
+interface GithubAppInstallationPermissions {
+  checks?: "read" | "write";
+}
+/** The Factory App broker's token: repo-scoped Checks write, nothing else. */
+declare const FACTORY_APP_BROKER_TOKEN_PERMISSIONS: {
+  readonly checks: "write";
+};
 interface GithubAppTokenOptions {
   /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
   fetch?: typeof fetch;
@@ -584,6 +628,18 @@ declare const githubAppJwt: (credentials: GithubAppCredentials, options?: Pick<G
 declare const mintInstallationToken: (input: {
   credentials: GithubAppCredentials;
   owner: string;
+  /**
+   * Installation permission subset. Omitted, GitHub grants the App's full
+   * installation permissions. The Factory App broker passes
+   * {@link FACTORY_APP_BROKER_TOKEN_PERMISSIONS}.
+   */
+  permissions?: GithubAppInstallationPermissions;
+  /**
+   * Repository names (not `owner/repo`) to bind the token to. Omitted, the
+   * token covers every repository the installation can reach. The broker
+   * always names the one repository the Cursor OIDC claim authenticated.
+   */
+  repositories?: readonly string[];
   repo: string;
 }, options?: GithubAppTokenOptions) => Promise<string>;
 //#endregion
@@ -658,13 +714,9 @@ declare const executeAlchemyEntry: (options: ExecuteAlchemyEntryOptions) => Prom
  *
  * It answers one question, before checkout and before install: may this job
  * reuse the local verification the factory already published for *this exact
- * head*? By default it asks that only on a pull request, so every
- * default-branch push executes the full hosted suite (#863). A consumer may
- * opt into `reuse: "pull-request-and-default-branch"`, where one fallback
- * extends "this exact head" to "this exact tree": a squash merge whose result
- * tree is byte-identical to the producing pull request's proven head tree
- * reuses that head's proof (#611). Refusing runs hosted CI; it never fails
- * the candidate. Three
+ * head*? It asks that only on a pull request, so every default-branch push
+ * executes the full hosted suite (#863). 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
@@ -742,70 +794,24 @@ declare const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
  */
 declare const FACTORY_PROOF_GATE_GUARD = "steps.factory-proof.outputs.reuse-proof != 'true'";
 /**
- * Pull requests, plus pushes to the merge target (#611) — the **opt-out**
- * condition a consumer gets with `reuse: "pull-request-and-default-branch"`.
- *
- * It buys runner time on the merge target and pays for it in coverage. No
- * local proof is ever written for a merged SHA, so the direct read finds
- * nothing after a squash merge. The push path therefore exists only together
- * with the merge fallback below: when no generation exists at the merged SHA,
- * the gate may look up the producing pull request and reuse its head proof,
- * but only when the merge result's tree is exactly the proven head's tree.
- * Deploy gates keep waiting for a green required check at the merged SHA; a
- * reused proof turns that check green through the same guarded steps a pull
- * request uses.
- *
- * The trade this mode accepts: a candidate's proof may be impact-scoped, and
- * an impact-scoped proof is a sound gate for the candidate and an unsound
- * gate for the merge target. #931 is that defect observed — a `main` push
- * reused a candidate proof, executed no command, and left a red package
- * unnoticed for three days. Choose this mode only when the consumer accepts
- * that risk for speed.
- *
- * The push side is deliberately the merge target only — the repository's
- * default branch — not every pushed branch. Which branches trigger a
- * consumer's workflow at all stays repository-owned; this condition only
- * keeps the gate from consulting proof on pushes that are not merges into
- * the default branch.
- */
-declare const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))";
-/**
- * Pull requests only — the **default** condition, and the condition a
- * consumer gets with `reuse: "pull-request"` (#873, default since #863).
+ * Pull requests only — the gate's single condition (#873, default since #863,
+ * the only mode since the merge-target opt-out was deleted).
  *
  * A merge target's guarantee is about the whole tree, not the diff. A
  * candidate proof only ever binds the diff the candidate was scoped to, so
  * reusing it on the merged commit proves less than the merge target needs.
- * Every default-branch push therefore executes the full hosted suite,
- * whatever proof exists. The mode also skips the push-event merge fallback,
- * so no push path can reuse proof even if the workflow reaches the step
- * through some other trigger.
+ * #931 is that defect observed — a `main` push reused a candidate proof,
+ * executed no command, and left a red package unnoticed for three days. Every
+ * default-branch push therefore executes the full hosted suite, whatever
+ * proof exists.
  *
  * Which branches trigger the workflow at all stays repository-owned. This
  * condition only keeps the gate from consulting proof outside a pull request.
  */
-declare const FACTORY_PROOF_GATE_PULL_REQUEST_IF = "github.event_name == 'pull_request'";
-/**
- * Which events may reuse proof.
- *
- * A two-value enum, not a free-text condition: a string lets a consumer write
- * a condition this package cannot reason about — one that reuses proof on an
- * unproven ref — and the emitted condition is a trust predicate. The consumer
- * chooses the mode; `factory-ci` owns what each mode emits.
- *
- * - `pull-request` (default) pull requests only. Default-branch pushes
- *   execute the full hosted suite, and the merge fallback is not emitted.
- * - `pull-request-and-default-branch` the opt-out: pull requests plus pushes
- *   to the merge target, with the merge fallback. It is faster on the merge
- *   target and it lets an impact-scoped candidate proof gate a whole tree
- *   (#931), so a consumer must ask for it.
- */
-type FactoryProofGateReuse = "pull-request" | "pull-request-and-default-branch";
+declare 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 its Checks API reads.
- * The merge fallback adds no words: a fallback that establishes nothing
- * leaves the direct read's refusal standing, with the specifics in `detail`.
  *
  * - `proven`     a covering, passing, unambiguous proof for this exact head
  * - `none`       no App-verified factory check run at this commit
@@ -884,13 +890,6 @@ interface FactoryProofGateOptions {
    * therefore requires a different coverage.
    */
   readonly commands: readonly ProofReuseCommand[];
-  /**
-   * Which events may reuse proof. Defaults to `"pull-request"`: every
-   * default-branch push executes the full hosted suite (#873, #863).
-   * `"pull-request-and-default-branch"` is the opt-out a consumer chooses for
-   * speed on the merge target, and it accepts #931's risk.
-   */
-  readonly reuse?: FactoryProofGateReuse;
   /** Names the suite in the job summary. Changes no trust decision. */
   readonly surface: string;
 }
@@ -908,7 +907,6 @@ interface FactoryProofGateOptions {
  */
 declare const factoryProofGateScript: ({
   commands,
-  reuse,
   surface
 }: FactoryProofGateOptions) => string;
 interface FactoryProofGateStep {
@@ -918,7 +916,7 @@ interface FactoryProofGateStep {
     HEAD_SHA: string;
   }>;
   readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
-  readonly if: typeof FACTORY_PROOF_GATE_IF | typeof FACTORY_PROOF_GATE_PULL_REQUEST_IF;
+  readonly if: typeof FACTORY_PROOF_GATE_IF;
   readonly name: string;
   readonly run: string;
   readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
@@ -927,14 +925,8 @@ interface FactoryProofGateStep {
  * The step itself, structurally accepted by gagen's `step()` without adding a
  * gagen runtime dependency. It belongs first in the job it guards: a few API
  * reads with the default `GITHUB_TOKEN`, no checkout, no install, so a proven
- * head costs a runner nothing beyond job startup. The default
- * `reuse: "pull-request"` emits neither the push clause nor the fallback, and
- * needs only `checks: read` (#873, #863). A consumer that opts into
- * `reuse: "pull-request-and-default-branch"` also runs the push-event merge
- * fallback, which reads the producing pull request (`pull-requests: read`)
- * and the two commit objects whose tree ids it compares (`contents: read`).
- * A job that grants less loses only the fallback — the failed read degrades
- * to the full suite.
+ * head costs a runner nothing beyond job startup. The step runs on pull
+ * requests only, so it needs only `checks: read` (#873, #863).
  *
  * 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
@@ -1715,4 +1707,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { ALCHEMY_BASELINE, type AlchemyBaselinePackageJson, type AssertAlchemyBaselineInput, type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID, FACTORY_MERGE_FREEZE_CHECK_NAME, FACTORY_MERGE_FREEZE_IF, FACTORY_MERGE_FREEZE_JOB_ID, FACTORY_MERGE_FREEZE_JOB_NAME, FACTORY_MERGE_FREEZE_PERMISSIONS, FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION, FACTORY_MERGE_TARGET_REF_CONDITION, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_PULL_REQUEST_IF, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryMergeFreezeJob, type FactoryMergeFreezeJobOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateReuse, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryRunnerDecision, type FactoryRunnerHome, type FactoryRunnerKind, type FactoryRunnerOverride, type FactoryVerifyRunner, type FactoryVerifyRunnerMismatch, type FactoryVerifyRunnerPolicyInput, type FactoryVerifyRunnerPolicyReport, type FactoryVerifyRunnerTable, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, GitHubAppTokenTransportError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, UPLOAD_ARTIFACT, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertAlchemyBaseline, assertProofReuseCoverage, assertVerifyRunnerPolicy, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryMergeFreezeJob, factoryMergeFreezeScript, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryVerifyRunner, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, verifyRunnerPolicy, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { ALCHEMY_BASELINE, type AlchemyBaselinePackageJson, type AssertAlchemyBaselineInput, type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_APP_BROKER_ORIGIN, FACTORY_APP_BROKER_PATH, FACTORY_APP_BROKER_TOKEN_PERMISSIONS, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_CURSOR_OIDC_AUDIENCE, FACTORY_CURSOR_OIDC_ISSUER, FACTORY_CURSOR_OIDC_JWKS_URL, FACTORY_CURSOR_OIDC_MANAGED_RUNTIME, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_MERGE_FREEZE_APP_TOKEN_STEP_ID, FACTORY_MERGE_FREEZE_CHECK_NAME, FACTORY_MERGE_FREEZE_IF, FACTORY_MERGE_FREEZE_JOB_ID, FACTORY_MERGE_FREEZE_JOB_NAME, FACTORY_MERGE_FREEZE_PERMISSIONS, FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION, FACTORY_MERGE_TARGET_REF_CONDITION, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryMergeFreezeJob, type FactoryMergeFreezeJobOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryRunnerDecision, type FactoryRunnerHome, type FactoryRunnerKind, type FactoryRunnerOverride, type FactoryVerifyRunner, type FactoryVerifyRunnerMismatch, type FactoryVerifyRunnerPolicyInput, type FactoryVerifyRunnerPolicyReport, type FactoryVerifyRunnerTable, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, GitHubAppTokenTransportError, type GithubAppCredentials, type GithubAppInstallationPermissions, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, UPLOAD_ARTIFACT, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertAlchemyBaseline, assertProofReuseCoverage, assertVerifyRunnerPolicy, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryMergeFreezeJob, factoryMergeFreezeScript, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryVerifyRunner, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, verifyRunnerPolicy, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };