@patronage/factory-ci 1.0.0-alpha.13 → 1.0.0-alpha.16

package/README.md

@@ -165,6 +165,38 @@ The helper selects no action family or action version. Callers pass the explicit
 
 This is identity transport and validation only. The consumer still owns the `workflow_run` trigger and branch policy, job topology and runners, deploy credentials and environments, target declarations, commands, ordering, and convergence/no-op proof. None of those belong in the identity artifact or decision job.
 
+Candidate pull-request routing follows the same ownership line through `factoryCandidateImpactWorkflow` (#741). A generated Verify workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target)` expressions, so the profile's canonical impact declarations and dependency graph route the run instead of a repository-maintained path filter:
+
+```ts
+const impact = factoryCandidateImpactWorkflow({
+  targets: profile.impact?.targets.map(({ name }) => name) ?? [],
+});
+
+const decide = job("impact", {
+  // The lifecycle contract applies to the decision job too: a draft pull
+  // request runs no checkout, install, or classification.
+  if: factoryCandidateOrPushCondition(),
+  outputs: impact.decisionJobOutputs,
+  steps: [...setupSteps, impact.decisionStep],
+});
+
+const core = job("core", {
+  // Wrap the impact condition in `factoryCandidateOrPushCondition` as well:
+  // a skipped decision job is not `success`, so promotion out of draft
+  // re-demands every routed target. Impact routing narrows candidate work;
+  // it never widens the lifecycle.
+  if: factoryCandidateOrPushCondition(impact.demandedIf("core", "impact")),
+  needs: [decide],
+  // consumer-owned runner, surface commands, and credentials
+});
+```
+
+`demandedIf(target, decisionJob)` emits `always()` so a failed decision job still demands work, and it checks only the decision job's result. Declare the decision job as the routed job's only `needs`. A routed job with more prerequisites must add its own `needs.<job>.result == 'success'` clauses, because `always()` suppresses GitHub's implicit success gating for every dependency. The production decision seam has the same contract.
+
+Trust boundary: candidate routing is a cost control inside the pull request's own CI, not a merge-security control. A `pull_request` run executes the PR's workflow file and install scripts, so a hostile PR can already shape any of its own job outputs — with or without this seam, exactly as with a repository path filter. Merge admission never trusts these outputs: merge-target push verification stays full and unrouted, and the factory proof chain binds to commits, not to job conditions.
+
+The step calls `psf candidate:impact` with the pull request's exact `base` and `head` commits (`github.event.pull_request.base.sha` / `head.sha` by default) and classifies the merge-base-to-head delta. It is `continue-on-error`, and every generated target condition keeps work demanded unless the command succeeded, reported a usable decision, and explicitly withdrew that target — unreadable identity, malformed or unsupported graph data, and classifier refusal all route to full demand. The decision checkout must check out the exact head commit with full history (`fetchDepth: 0`, `ref` = the head SHA); the default merge-ref checkout refuses withdrawal because the head is not `HEAD`. Surface job names, runners, commands, and credentials stay with the consumer, and `factoryProductionImpactWorkflow` keeps its merge-push contract unchanged.
+
 ### Generated shell
 
 ```ts
@@ -207,7 +239,10 @@ const coreCommands = profile.verification.commands.filter(
 );
 
 const core = job("core", {
-  permissions: { checks: "read", contents: "read" },
+  // `pull-requests: read` serves the gate's default-branch merge fallback
+  // (#611). Without it the fallback's PR lookup fails and every merge push
+  // silently pays the full suite.
+  permissions: { checks: "read", contents: "read", "pull-requests": "read" },
   steps: [
     step(factoryProofGateStep({ commands: coreCommands, surface: "core" })),
     step(factoryProofTimingStartStep()),
@@ -219,6 +254,8 @@ 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 and on pushes to the default branch (#611). 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.
+
 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.
 
 The only thing a consumer chooses is **what its surface requires**, expressed as the plain profile command objects that surface selects — a repository with distinct core and docs jobs selects distinct sets and gets distinct required coverage. `proofReuseRequiredCommands()` is the single derivation both the gate and the assertion go through. Identities are baked into the emitted script, so they are held to a plain `[A-Za-z0-9_][\w.:@/-]*` allow-list and shell-quoted at the interpolation site; a selection carrying anything else is unusable and degrades to a gate that always refuses.
@@ -231,7 +268,9 @@ The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`.
 
 `assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Coverage is exact executable coverage. The deprecated `equivalents` input remains only for patch-release source compatibility and is ignored; prose cannot authorize a skip. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
 
-`factoryProofTimingStartStep()` and `factoryProofReuseSummaryStep()` replace consumer-local proof timing summaries without taking over workflow topology. Put the start step immediately after the gate and the summary step after the guarded work. The helpers keep the established `Start CI timing` / `Record proof-reuse timing` names and distinguish pull-request reuse, pull-request full fallback, and merge-target full execution where the PR-only gate is explicitly not applicable. Reuse links the exact source check and bound head; every path emits a cheap Actions notice. Both steps are `continue-on-error`: missing timing support or an unwritable presentation destination cannot change a required job's conclusion. These helpers change no trust predicate or guard.
+`factoryProofTimingStartStep()` and `factoryProofReuseSummaryStep()` replace consumer-local proof timing summaries without taking over workflow topology. Put the start step immediately after the gate and the summary step after the guarded work. The helpers keep the established `Start CI timing` / `Record proof-reuse timing` names and distinguish proof reuse, full fallback with the gate's reason, and pushes where the gate's step condition kept it off entirely. Reuse links the exact source check and bound head; every path emits a cheap Actions notice. Both steps are `continue-on-error`: missing timing support or an unwritable presentation destination cannot change a required job's conclusion. These helpers change no trust predicate or guard.
+
+The raw summary script builder and the internal `ci-timing` step-id and step-name constants are not exported. Only the two step builders above are public; every production caller already consumed them through the builders, so this is a same-prerelease narrowing rather than a behavior change (#686).
 
 ### Alchemy entries
 

package/dist/index.d.ts

@@ -318,7 +318,10 @@ 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*? Refusing runs hosted CI; it never fails the candidate. Three
+ * head*? On a push to the merge target 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
  * 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
@@ -396,14 +399,31 @@ 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 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.
+ * Pull requests, plus pushes to the merge target (#611).
+ *
+ * The gate was pull-request-only through 1.0.0-alpha.15: a push to a
+ * protected branch always ran the full suite, because no local proof is ever
+ * written for the merged SHA. That still holds for the *direct* read — a
+ * squash merge mints a new commit — which is why the push path 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 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'";
+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))";
 /**
  * The complete refusal vocabulary. Deliberately few, because these are the
- * only distinctions the gate can honestly make from one Checks API read.
+ * 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
@@ -515,9 +535,13 @@ 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: 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.
+ * 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. A pull request needs
+ * `checks: read`; the push-event merge fallback additionally 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.
  *
  * 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
@@ -586,9 +610,6 @@ interface FactoryProofTimingStartStep {
   readonly run: string;
 }
 declare const factoryProofTimingStartStep: () => FactoryProofTimingStartStep;
-declare const factoryProofReuseSummaryScript: ({
-  surface
-}: FactoryProofReusePresentationOptions) => string;
 interface FactoryProofReuseSummaryStep {
   readonly continueOnError: true;
   readonly env: Readonly<Record<string, string>>;
@@ -598,6 +619,42 @@ interface FactoryProofReuseSummaryStep {
 }
 declare const factoryProofReuseSummaryStep: (options: FactoryProofReusePresentationOptions) => FactoryProofReuseSummaryStep;
 //#endregion
+//#region src/candidate-impact-workflow.d.ts
+declare const FACTORY_CANDIDATE_IMPACT_STEP_ID = "candidate_impact";
+declare const FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT = "decision";
+declare const FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT = "basis";
+declare const FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+interface FactoryCandidateImpactWorkflowOptions {
+  readonly base?: string;
+  readonly cli?: string;
+  readonly head?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+interface FactoryCandidateImpactWorkflow {
+  /** Outputs for a caller-owned decision job that subsequent jobs may consume. */
+  readonly decisionJobOutputs: Readonly<Record<string, string>>;
+  readonly decisionStep: WorkflowStep;
+  /** A fail-open condition: only an explicit usable withdrawal skips work. */
+  readonly demandedIf: (targetName: string, decisionJob?: string) => string;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+/**
+ * Generate the factory-owned candidate routing seam for a consumer
+ * pull-request workflow (#741). The decision step calls
+ * `psf candidate:impact` with the pull request's exact base/head commits, so
+ * the canonical profile impact declarations and dependency graph route the
+ * run — never a second path matcher. Consumers retain jobs, surface names,
+ * runners, commands, and credentials; this artifact supplies only the
+ * decision step and per-target withdrawal conditions. Target output keys are
+ * the same stable contract the production decision seam writes.
+ *
+ * The decision checkout must have the exact head commit checked out and the
+ * base commit reachable (`fetchDepth: 0`, `ref` = the head SHA); anything
+ * else refuses withdrawal and keeps every target demanded.
+ */
+declare const factoryCandidateImpactWorkflow: (options: FactoryCandidateImpactWorkflowOptions) => FactoryCandidateImpactWorkflow;
+//#endregion
 //#region src/production-impact-workflow.d.ts
 declare const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 declare const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -630,12 +687,6 @@ declare const factoryProductionImpactWorkflow: (options: FactoryProductionImpact
 //#endregion
 //#region src/push-identity-workflow.d.ts
 declare const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
-declare const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
-declare const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID = "factory_push_identity_record";
-declare const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID = "factory_push_identity_lookup";
-declare const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID = "factory_push_identity_download";
-declare const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID = "factory_push_identity_checkout";
-declare const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
 /** Versioned document uploaded by a push-triggered verification run. */
 interface FactoryPushIdentityEnvelope {
   readonly after: string;
@@ -965,4 +1016,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PROOF_TIMING_START_STEP_NAME, FACTORY_PROOF_TIMING_STEP_ID, FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME, FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX, FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID, FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID, FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID, FACTORY_PUSH_IDENTITY_RECORD_STEP_ID, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID, 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 FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, 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, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, 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 FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, 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, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/dist/index.js

@@ -429,7 +429,10 @@ const executeAlchemyEntry = async (options) => {
 *
 * 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
+* head*? On a push to the merge target 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
 * 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
@@ -526,14 +529,31 @@ const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 */
 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.
+* Pull requests, plus pushes to the merge target (#611).
+*
+* The gate was pull-request-only through 1.0.0-alpha.15: a push to a
+* protected branch always ran the full suite, because no local proof is ever
+* written for the merged SHA. That still holds for the *direct* read — a
+* squash merge mints a new commit — which is why the push path 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 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.
 */
-const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
+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))";
 /**
 * The complete refusal vocabulary. Deliberately few, because these are the
-* only distinctions the gate can honestly make from one Checks API read.
+* 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
@@ -648,8 +668,8 @@ const resolveProofReuseCommands = (catalog, names, selectionLabel) => names.map(
 	};
 });
 /**
-* jq program: every page of the Checks API result in, three sanitized lines
-* (`reason`, `mode`, uncovered commands) out.
+* jq program: every page of the Checks API result in, four sanitized lines
+* (`reason`, `mode`, uncovered commands, source URL) out.
 *
 * The input is what `gh api --paginate` actually writes: the pages
 * *concatenated* as a stream of top-level response objects, not merged into
@@ -838,31 +858,43 @@ detail=''
 mode=''
 missing=''
 source_url=''
+proof_head="${shellExpansion$1("HEAD_SHA:-")}"
+merge_note=''
 
+# One proof lookup at one commit. Sets lookup_reason / lookup_mode /
+# lookup_missing / lookup_url, or lookup_detail when the read itself
+# failed. Always returns 0: every caller must reach the single
+# GITHUB_OUTPUT write below whatever this function meets.
+#
 # 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$1("HEAD_SHA:-")}" ]; then
-  detail='no pull request head SHA'
-elif [ -z "${shellExpansion$1("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
+gate_lookup() {
+  lookup_reason=error
+  lookup_mode=''
+  lookup_missing=''
+  lookup_url=''
+  lookup_detail=''
+  if ! lookup_response=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$1/check-runs" \
+      -f "check_name=$CHECK_NAME" \
+      -f filter=all \
+      -f per_page=100 2>&1); then
+    lookup_detail="checks API unreadable: $lookup_response"
+    return 0
+  fi
+  if ! lookup_finding=$(printf '%s' "$lookup_response" | jq -r -s \
+      --arg name "$CHECK_NAME" \
+      --arg app "$FACTORY_APP_ID" \
+      --arg sha "$1" \
+      --arg repository "$GITHUB_REPOSITORY" \
+      --argjson required "$REQUIRED_COMMANDS" \
+      '${GATE_JQ}' 2>&1); then
+    lookup_detail="unreadable proof binding: $lookup_finding"
+    return 0
+  fi
+  # Four 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
@@ -873,18 +905,106 @@ else
   # 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 || :
-    IFS= read -r source_url || :
-  } <<< "$finding"
-  case "$reason" in
+    IFS= read -r lookup_reason || :
+    IFS= read -r lookup_mode || :
+    IFS= read -r lookup_missing || :
+    IFS= read -r lookup_url || :
+  } <<< "$lookup_finding"
+  case "$lookup_reason" in
     proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
     *)
-      detail="unexpected gate result: $reason"
-      reason=error
+      lookup_detail="unexpected gate result: $lookup_reason"
+      lookup_reason=error
       ;;
   esac
+  return 0
+}
+
+if [ -z "${shellExpansion$1("HEAD_SHA:-")}" ]; then
+  detail='no verification head SHA'
+elif [ -z "${shellExpansion$1("GITHUB_REPOSITORY:-")}" ]; then
+  detail='no repository name'
+else
+  gate_lookup "$HEAD_SHA"
+  reason="$lookup_reason"
+  detail="$lookup_detail"
+  mode="$lookup_mode"
+  missing="$lookup_missing"
+  source_url="$lookup_url"
+fi
+
+# Merge fallback (#611). A squash merge mints a new commit, so the direct
+# read at a pushed merge-target head finds nothing even when the factory
+# proved the producing pull request head. Only when the direct read found no
+# generation at all on a push event, look up the producing pull request and
+# reuse its head proof — and 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
+# produce an integrated tree that was never tested. Everything else — no
+# unique merged producing PR, an unreadable commit, a proof that is anything
+# but proven, or tree drift from a dirty or stale merge — leaves the direct
+# "none" refusal standing, so the full suite runs (fail open).
+if [ "$reason" = 'none' ] && [ "${shellExpansion$1("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  producing_head=''
+  merge_tree=''
+  head_tree=''
+  if ! producing_pulls=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
+      -f per_page=100 2>&1); then
+    detail="producing pull request unreadable: $producing_pulls"
+  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
+      --arg sha "$HEAD_SHA" \
+      '[ add[]?
+         | select((.merged_at // null) != null)
+         | select((.merge_commit_sha // "") == $sha)
+         | ((.head.sha // "") | tostring) ]
+       | if length == 1 then .[0] else "" end' 2>&1); then
+    detail="producing pull request unreadable: $producing_head"
+    producing_head=''
+  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='no single merged producing pull request at this commit'
+    producing_head=''
+  elif ! merge_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
+    detail="merge commit unreadable: $merge_commit"
+  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="merge commit unreadable: $merge_tree"
+    merge_tree=''
+  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='merge commit carries no readable tree id'
+    merge_tree=''
+  elif ! head_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
+    detail="producing head commit unreadable: $head_commit"
+  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="producing head commit unreadable: $head_tree"
+    head_tree=''
+  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='producing head commit carries no readable tree id'
+    head_tree=''
+  elif [ "$merge_tree" != "$head_tree" ]; then
+    detail='tree drift: the merge result is not the proven head tree'
+    merge_tree=''
+  fi
+  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
+      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
+      && [ "$merge_tree" = "$head_tree" ]; then
+    gate_lookup "$producing_head"
+    if [ "$lookup_reason" = 'proven' ]; then
+      reason=proven
+      mode="$lookup_mode"
+      missing=''
+      source_url="$lookup_url"
+      proof_head="$producing_head"
+      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
+    else
+      detail="producing pull request proof not reusable ($lookup_reason)"
+    fi
+  fi
 fi
 
 # The binding is App-verified, but it still reaches markdown. Only a plain
@@ -915,21 +1035,28 @@ 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."
+    echo "Factory proof: reusing local verification of $proof_head; skipping the $SURFACE suite."
+    say "Skipped. The factory already verified this exact content, so this job did not run the $SURFACE suite a second time."
     say ''
     if [ -n "$source_url" ]; then
       say "- Reused proof: [\`$CHECK_NAME\`]($source_url), published by the pinned factory GitHub App."
     else
       say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
     fi
-    say "- Covers head: \`$HEAD_SHA\`"
+    say "- Covers head: \`$proof_head\`"
+    if [ -n "$merge_note" ]; then
+      say "- Merge-target reuse: $merge_note."
+    fi
     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."
+    if [ -n "$detail" ]; then
+      say ''
+      say "- Merge fallback: $detail"
+    fi
     say ''
     say '${CORRECTIVE_LINE}'
     ;;
@@ -1009,9 +1136,13 @@ const factoryProofGateScript = ({ commands, surface }) => {
 };
 /**
 * 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.
+* 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. A pull request needs
+* `checks: read`; the push-event merge fallback additionally 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.
 *
 * 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
@@ -1024,7 +1155,7 @@ const factoryProofGateStep = (options) => Object.freeze({
 	continueOnError: true,
 	env: Object.freeze({
 		GH_TOKEN: githubExpression$1("secrets.GITHUB_TOKEN"),
-		HEAD_SHA: githubExpression$1("github.event.pull_request.head.sha")
+		HEAD_SHA: githubExpression$1("github.event.pull_request.head.sha || github.sha")
 	}),
 	id: FACTORY_PROOF_GATE_STEP_ID,
 	if: FACTORY_PROOF_GATE_IF,
@@ -1090,11 +1221,15 @@ say() { printf '%s\n' "$1" >> "$SUMMARY"; }
 say '## ${label} timing'
 say ''
 
-if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ] && [ -z "${shellExpansion("PROOF_REASON:-")}" ]; then
+  # The gate runs on pushes to the merge target (#611). A push run with no
+  # recorded reason is one where the gate step's condition kept it off
+  # entirely (a non-merge-target ref), so the full suite ran with no
+  # reuse decision.
   say '- Path: merge-target full execution'
-  say '- Proof-reuse gate: not applicable on merge-target runs; the full suite ran.'
+  say '- Proof-reuse gate: did not run on this ref; the full suite ran.'
   say "- Verified head: \`${shellExpansion("GITHUB_SHA:-unknown")}\`"
-  echo "::notice title=Factory proof reuse::Proof reuse is not applicable on merge-target runs; the full ${label} suite executed."
+  echo "::notice title=Factory proof reuse::The proof-reuse gate did not run on this ref; the full ${label} suite executed."
 elif [ "${shellExpansion("PROOF_REUSED:-")}" = 'true' ]; then
   say '- Path: trusted local proof reused'
   if [ -n "${shellExpansion("PROOF_SOURCE_URL:-")}" ]; then
@@ -1121,7 +1256,7 @@ const factoryProofReuseSummaryStep = (options) => Object.freeze({
 	continueOnError: true,
 	env: Object.freeze({
 		CI_STARTED_MS: githubExpression(`steps.${FACTORY_PROOF_TIMING_STEP_ID}.outputs.started_ms`),
-		PROOF_HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+		PROOF_HEAD_SHA: githubExpression("github.event.pull_request.head.sha || github.sha"),
 		PROOF_MODE: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_MODE_OUTPUT}`),
 		PROOF_REASON: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_REASON_OUTPUT}`),
 		PROOF_REUSED: githubExpression(`steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT}`),
@@ -1138,7 +1273,7 @@ const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
 const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
 const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
 const OUTPUT_NAME_PATTERN = /[^a-z0-9_]+/gu;
-const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+const shellQuote$1 = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
 /** Stable GitHub-output key for one declared target. */
 const productionImpactTargetOutput = (targetName) => {
 	const normalized = targetName.toLowerCase().replaceAll(OUTPUT_NAME_PATTERN, "_").replaceAll(/^_+|_+$/gu, "");
@@ -1157,7 +1292,7 @@ const factoryProductionImpactWorkflow = (options) => {
 	const before = options.before ?? `\${{ github.event.before }}`;
 	const after = options.after ?? `\${{ github.sha }}`;
 	const cli = options.cli ?? "pnpm exec psf";
-	const profile = options.profilePath ? ` --profile ${shellQuote(options.profilePath)}` : "";
+	const profile = options.profilePath ? ` --profile ${shellQuote$1(options.profilePath)}` : "";
 	const decisionStep = {
 		continueOnError: true,
 		env: {
@@ -1187,6 +1322,62 @@ const factoryProductionImpactWorkflow = (options) => {
 	});
 };
 //#endregion
+//#region src/candidate-impact-workflow.ts
+const FACTORY_CANDIDATE_IMPACT_STEP_ID = "candidate_impact";
+const FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT = "decision";
+const FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT = "basis";
+const FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+/**
+* Generate the factory-owned candidate routing seam for a consumer
+* pull-request workflow (#741). The decision step calls
+* `psf candidate:impact` with the pull request's exact base/head commits, so
+* the canonical profile impact declarations and dependency graph route the
+* run — never a second path matcher. Consumers retain jobs, surface names,
+* runners, commands, and credentials; this artifact supplies only the
+* decision step and per-target withdrawal conditions. Target output keys are
+* the same stable contract the production decision seam writes.
+*
+* The decision checkout must have the exact head commit checked out and the
+* base commit reachable (`fetchDepth: 0`, `ref` = the head SHA); anything
+* else refuses withdrawal and keeps every target demanded.
+*/
+const factoryCandidateImpactWorkflow = (options) => {
+	const targetOutputs = Object.fromEntries(options.targets.map((target) => [target, productionImpactTargetOutput(target)]));
+	if (new Set(Object.values(targetOutputs)).size !== options.targets.length) throw new Error("Impact target names must map to distinct GitHub output keys.");
+	const base = options.base ?? `\${{ github.event.pull_request.base.sha }}`;
+	const head = options.head ?? `\${{ github.event.pull_request.head.sha }}`;
+	const cli = options.cli ?? "pnpm exec psf";
+	const profile = options.profilePath ? ` --profile ${shellQuote(options.profilePath)}` : "";
+	const decisionStep = {
+		continueOnError: true,
+		env: {
+			FACTORY_BASE_SHA: base,
+			FACTORY_HEAD_SHA: head
+		},
+		id: FACTORY_CANDIDATE_IMPACT_STEP_ID,
+		name: "Classify candidate impact",
+		run: `${cli} candidate:impact --base "$FACTORY_BASE_SHA" --head "$FACTORY_HEAD_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`
+	};
+	return Object.freeze({
+		decisionJobOutputs: Object.freeze({
+			basis: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT} }}`,
+			decision: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} }}`,
+			unsubscribed_paths: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT} }}`,
+			...Object.fromEntries(Object.values(targetOutputs).map((output) => [output, `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${output} }}`]))
+		}),
+		decisionStep: Object.freeze(decisionStep),
+		demandedIf: (targetName, decisionJob) => {
+			const output = targetOutputs[targetName];
+			if (output === void 0) throw new Error(`Unknown candidate impact target "${targetName}".`);
+			const source = decisionJob ? `needs.${decisionJob}` : `steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}`;
+			const condition = `${source}.${decisionJob ? "result" : "outcome"} != 'success' || ${source}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
+			return decisionJob ? `always() && (${condition})` : condition;
+		},
+		targetOutputs: Object.freeze(targetOutputs)
+	});
+};
+//#endregion
 //#region src/push-identity-workflow.ts
 const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
 const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
@@ -2254,4 +2445,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PROOF_TIMING_START_STEP_NAME, FACTORY_PROOF_TIMING_STEP_ID, FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME, FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX, FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID, FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID, FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID, FACTORY_PUSH_IDENTITY_RECORD_STEP_ID, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, 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_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.16",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",

package/src/candidate-impact-workflow.ts

@@ -0,0 +1,103 @@
+import type { WorkflowStep } from "./factory-workflow.ts";
+import { productionImpactTargetOutput } from "./production-impact-workflow.ts";
+
+export const FACTORY_CANDIDATE_IMPACT_STEP_ID = "candidate_impact";
+export const FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT = "decision";
+export const FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT = "basis";
+export const FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT =
+  "unsubscribed_paths";
+
+const shellQuote = (value: string): string =>
+  `'${value.replaceAll("'", `'"'"'`)}'`;
+
+export interface FactoryCandidateImpactWorkflowOptions {
+  readonly base?: string;
+  readonly cli?: string;
+  readonly head?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+
+export interface FactoryCandidateImpactWorkflow {
+  /** Outputs for a caller-owned decision job that subsequent jobs may consume. */
+  readonly decisionJobOutputs: Readonly<Record<string, string>>;
+  readonly decisionStep: WorkflowStep;
+  /** A fail-open condition: only an explicit usable withdrawal skips work. */
+  readonly demandedIf: (targetName: string, decisionJob?: string) => string;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+
+/**
+ * Generate the factory-owned candidate routing seam for a consumer
+ * pull-request workflow (#741). The decision step calls
+ * `psf candidate:impact` with the pull request's exact base/head commits, so
+ * the canonical profile impact declarations and dependency graph route the
+ * run — never a second path matcher. Consumers retain jobs, surface names,
+ * runners, commands, and credentials; this artifact supplies only the
+ * decision step and per-target withdrawal conditions. Target output keys are
+ * the same stable contract the production decision seam writes.
+ *
+ * The decision checkout must have the exact head commit checked out and the
+ * base commit reachable (`fetchDepth: 0`, `ref` = the head SHA); anything
+ * else refuses withdrawal and keeps every target demanded.
+ */
+export const factoryCandidateImpactWorkflow = (
+  options: FactoryCandidateImpactWorkflowOptions
+): FactoryCandidateImpactWorkflow => {
+  const targetOutputs = Object.fromEntries(
+    options.targets.map((target) => [
+      target,
+      productionImpactTargetOutput(target),
+    ])
+  );
+  if (new Set(Object.values(targetOutputs)).size !== options.targets.length) {
+    throw new Error(
+      "Impact target names must map to distinct GitHub output keys."
+    );
+  }
+
+  const base = options.base ?? `\${{ github.event.pull_request.base.sha }}`;
+  const head = options.head ?? `\${{ github.event.pull_request.head.sha }}`;
+  const cli = options.cli ?? "pnpm exec psf";
+  const profile = options.profilePath
+    ? ` --profile ${shellQuote(options.profilePath)}`
+    : "";
+  const decisionStep: WorkflowStep = {
+    continueOnError: true,
+    env: {
+      FACTORY_BASE_SHA: base,
+      FACTORY_HEAD_SHA: head,
+    },
+    id: FACTORY_CANDIDATE_IMPACT_STEP_ID,
+    name: "Classify candidate impact",
+    run: `${cli} candidate:impact --base "$FACTORY_BASE_SHA" --head "$FACTORY_HEAD_SHA" --github-output "$GITHUB_OUTPUT" --github-summary "$GITHUB_STEP_SUMMARY"${profile}`,
+  };
+
+  return Object.freeze({
+    decisionJobOutputs: Object.freeze({
+      basis: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT} }}`,
+      decision: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} }}`,
+      unsubscribed_paths: `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT} }}`,
+      ...Object.fromEntries(
+        Object.values(targetOutputs).map((output) => [
+          output,
+          `\${{ steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}.outputs.${output} }}`,
+        ])
+      ),
+    }),
+    decisionStep: Object.freeze(decisionStep),
+    demandedIf: (targetName: string, decisionJob?: string) => {
+      const output = targetOutputs[targetName];
+      if (output === undefined) {
+        throw new Error(`Unknown candidate impact target "${targetName}".`);
+      }
+      const source = decisionJob
+        ? `needs.${decisionJob}`
+        : `steps.${FACTORY_CANDIDATE_IMPACT_STEP_ID}`;
+      const outcome = decisionJob ? "result" : "outcome";
+      const condition = `${source}.${outcome} != 'success' || ${source}.outputs.${FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT} != 'usable' || ${source}.outputs.${output} != 'withdrawn'`;
+      return decisionJob ? `always() && (${condition})` : condition;
+    },
+    targetOutputs: Object.freeze(targetOutputs),
+  });
+};

package/src/index.ts

@@ -82,13 +82,18 @@ export {
   type FactoryProofReusePresentationOptions,
   type FactoryProofReuseSummaryStep,
   type FactoryProofTimingStartStep,
-  FACTORY_PROOF_TIMING_START_STEP_NAME,
-  FACTORY_PROOF_TIMING_STEP_ID,
-  FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME,
-  factoryProofReuseSummaryScript,
   factoryProofReuseSummaryStep,
   factoryProofTimingStartStep,
 } from "./proof-reuse-presentation.ts";
+export {
+  FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT,
+  FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT,
+  FACTORY_CANDIDATE_IMPACT_STEP_ID,
+  FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT,
+  type FactoryCandidateImpactWorkflow,
+  type FactoryCandidateImpactWorkflowOptions,
+  factoryCandidateImpactWorkflow,
+} from "./candidate-impact-workflow.ts";
 export {
   FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT,
   FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
@@ -100,13 +105,7 @@ export {
   productionImpactTargetOutput,
 } from "./production-impact-workflow.ts";
 export {
-  FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX,
-  FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID,
-  FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID,
-  FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID,
-  FACTORY_PUSH_IDENTITY_RECORD_STEP_ID,
   FACTORY_PUSH_IDENTITY_SCHEMA_VERSION,
-  FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID,
   type FactoryPushIdentityConsumer,
   type FactoryPushIdentityConsumerOptions,
   type FactoryPushIdentityDisposition,

package/src/proof-reuse-gate.ts

@@ -3,7 +3,10 @@
  *
  * 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
+ * head*? On a push to the merge target 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
  * 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
@@ -117,15 +120,33 @@ export const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 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.
+ * Pull requests, plus pushes to the merge target (#611).
+ *
+ * The gate was pull-request-only through 1.0.0-alpha.15: a push to a
+ * protected branch always ran the full suite, because no local proof is ever
+ * written for the merged SHA. That still holds for the *direct* read — a
+ * squash merge mints a new commit — which is why the push path 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 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.
  */
-export const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
+export 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))";
 
 /**
  * The complete refusal vocabulary. Deliberately few, because these are the
- * only distinctions the gate can honestly make from one Checks API read.
+ * 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
@@ -282,8 +303,8 @@ export const resolveProofReuseCommands = (
   });
 
 /**
- * jq program: every page of the Checks API result in, three sanitized lines
- * (`reason`, `mode`, uncovered commands) out.
+ * jq program: every page of the Checks API result in, four sanitized lines
+ * (`reason`, `mode`, uncovered commands, source URL) out.
  *
  * The input is what `gh api --paginate` actually writes: the pages
  * *concatenated* as a stream of top-level response objects, not merged into
@@ -481,31 +502,43 @@ detail=''
 mode=''
 missing=''
 source_url=''
-
+proof_head="${shellExpansion("HEAD_SHA:-")}"
+merge_note=''
+
+# One proof lookup at one commit. Sets lookup_reason / lookup_mode /
+# lookup_missing / lookup_url, or lookup_detail when the read itself
+# failed. Always returns 0: every caller must reach the single
+# GITHUB_OUTPUT write below whatever this function meets.
+#
 # 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
+gate_lookup() {
+  lookup_reason=error
+  lookup_mode=''
+  lookup_missing=''
+  lookup_url=''
+  lookup_detail=''
+  if ! lookup_response=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$1/check-runs" \
+      -f "check_name=$CHECK_NAME" \
+      -f filter=all \
+      -f per_page=100 2>&1); then
+    lookup_detail="checks API unreadable: $lookup_response"
+    return 0
+  fi
+  if ! lookup_finding=$(printf '%s' "$lookup_response" | jq -r -s \
+      --arg name "$CHECK_NAME" \
+      --arg app "$FACTORY_APP_ID" \
+      --arg sha "$1" \
+      --arg repository "$GITHUB_REPOSITORY" \
+      --argjson required "$REQUIRED_COMMANDS" \
+      '${GATE_JQ}' 2>&1); then
+    lookup_detail="unreadable proof binding: $lookup_finding"
+    return 0
+  fi
+  # Four 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
@@ -516,18 +549,106 @@ else
   # 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 || :
-    IFS= read -r source_url || :
-  } <<< "$finding"
-  case "$reason" in
+    IFS= read -r lookup_reason || :
+    IFS= read -r lookup_mode || :
+    IFS= read -r lookup_missing || :
+    IFS= read -r lookup_url || :
+  } <<< "$lookup_finding"
+  case "$lookup_reason" in
     proven | none | pending | failed | unreadable | incomplete | ambiguous) ;;
     *)
-      detail="unexpected gate result: $reason"
-      reason=error
+      lookup_detail="unexpected gate result: $lookup_reason"
+      lookup_reason=error
       ;;
   esac
+  return 0
+}
+
+if [ -z "${shellExpansion("HEAD_SHA:-")}" ]; then
+  detail='no verification head SHA'
+elif [ -z "${shellExpansion("GITHUB_REPOSITORY:-")}" ]; then
+  detail='no repository name'
+else
+  gate_lookup "$HEAD_SHA"
+  reason="$lookup_reason"
+  detail="$lookup_detail"
+  mode="$lookup_mode"
+  missing="$lookup_missing"
+  source_url="$lookup_url"
+fi
+
+# Merge fallback (#611). A squash merge mints a new commit, so the direct
+# read at a pushed merge-target head finds nothing even when the factory
+# proved the producing pull request head. Only when the direct read found no
+# generation at all on a push event, look up the producing pull request and
+# reuse its head proof — and 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
+# produce an integrated tree that was never tested. Everything else — no
+# unique merged producing PR, an unreadable commit, a proof that is anything
+# but proven, or tree drift from a dirty or stale merge — leaves the direct
+# "none" refusal standing, so the full suite runs (fail open).
+if [ "$reason" = 'none' ] && [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+  producing_head=''
+  merge_tree=''
+  head_tree=''
+  if ! producing_pulls=$(gh api --method GET --paginate \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
+      -f per_page=100 2>&1); then
+    detail="producing pull request unreadable: $producing_pulls"
+  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
+      --arg sha "$HEAD_SHA" \
+      '[ add[]?
+         | select((.merged_at // null) != null)
+         | select((.merge_commit_sha // "") == $sha)
+         | ((.head.sha // "") | tostring) ]
+       | if length == 1 then .[0] else "" end' 2>&1); then
+    detail="producing pull request unreadable: $producing_head"
+    producing_head=''
+  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='no single merged producing pull request at this commit'
+    producing_head=''
+  elif ! merge_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
+    detail="merge commit unreadable: $merge_commit"
+  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="merge commit unreadable: $merge_tree"
+    merge_tree=''
+  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='merge commit carries no readable tree id'
+    merge_tree=''
+  elif ! head_commit=$(gh api --method GET \
+      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
+    detail="producing head commit unreadable: $head_commit"
+  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
+      '(.commit.tree.sha // "") | tostring' 2>&1); then
+    detail="producing head commit unreadable: $head_tree"
+    head_tree=''
+  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
+    detail='producing head commit carries no readable tree id'
+    head_tree=''
+  elif [ "$merge_tree" != "$head_tree" ]; then
+    detail='tree drift: the merge result is not the proven head tree'
+    merge_tree=''
+  fi
+  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
+      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
+      && [ "$merge_tree" = "$head_tree" ]; then
+    gate_lookup "$producing_head"
+    if [ "$lookup_reason" = 'proven' ]; then
+      reason=proven
+      mode="$lookup_mode"
+      missing=''
+      source_url="$lookup_url"
+      proof_head="$producing_head"
+      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
+    else
+      detail="producing pull request proof not reusable ($lookup_reason)"
+    fi
+  fi
 fi
 
 # The binding is App-verified, but it still reaches markdown. Only a plain
@@ -558,21 +679,28 @@ 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."
+    echo "Factory proof: reusing local verification of $proof_head; skipping the $SURFACE suite."
+    say "Skipped. The factory already verified this exact content, so this job did not run the $SURFACE suite a second time."
     say ''
     if [ -n "$source_url" ]; then
       say "- Reused proof: [\`$CHECK_NAME\`]($source_url), published by the pinned factory GitHub App."
     else
       say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
     fi
-    say "- Covers head: \`$HEAD_SHA\`"
+    say "- Covers head: \`$proof_head\`"
+    if [ -n "$merge_note" ]; then
+      say "- Merge-target reuse: $merge_note."
+    fi
     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."
+    if [ -n "$detail" ]; then
+      say ''
+      say "- Merge fallback: $detail"
+    fi
     say ''
     say '${CORRECTIVE_LINE}'
     ;;
@@ -683,9 +811,13 @@ export 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: 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.
+ * 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. A pull request needs
+ * `checks: read`; the push-event merge fallback additionally 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.
  *
  * 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
@@ -701,7 +833,12 @@ export const factoryProofGateStep = (
     continueOnError: true as const,
     env: Object.freeze({
       GH_TOKEN: githubExpression("secrets.GITHUB_TOKEN"),
-      HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+      // On a pull request the verified head is the PR branch tip; on a push
+      // there is no pull_request payload and `github.sha` is the pushed
+      // merge-target head the fallback resolves from (#611).
+      HEAD_SHA: githubExpression(
+        "github.event.pull_request.head.sha || github.sha"
+      ),
     }),
     id: FACTORY_PROOF_GATE_STEP_ID,
     if: FACTORY_PROOF_GATE_IF,

package/src/proof-reuse-presentation.ts

@@ -21,10 +21,9 @@ const safeLabel = (surface: string): string => {
   return cleaned.length > 0 ? cleaned : "verification";
 };
 
-export const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
-export const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
-export const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME =
-  "Record proof-reuse timing";
+const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME = "Record proof-reuse timing";
 
 export interface FactoryProofReusePresentationOptions {
   /** Human-readable name of the guarded suite. */
@@ -47,7 +46,7 @@ export const factoryProofTimingStartStep = (): FactoryProofTimingStartStep =>
 printf 'started_ms=%s\n' "$started_ms" >> "$GITHUB_OUTPUT"`,
   });
 
-export const factoryProofReuseSummaryScript = ({
+const factoryProofReuseSummaryScript = ({
   surface,
 }: FactoryProofReusePresentationOptions): string => {
   const label = safeLabel(surface);
@@ -60,11 +59,15 @@ say() { printf '%s\n' "$1" >> "$SUMMARY"; }
 say '## ${label} timing'
 say ''
 
-if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
+if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ] && [ -z "${shellExpansion("PROOF_REASON:-")}" ]; then
+  # The gate runs on pushes to the merge target (#611). A push run with no
+  # recorded reason is one where the gate step's condition kept it off
+  # entirely (a non-merge-target ref), so the full suite ran with no
+  # reuse decision.
   say '- Path: merge-target full execution'
-  say '- Proof-reuse gate: not applicable on merge-target runs; the full suite ran.'
+  say '- Proof-reuse gate: did not run on this ref; the full suite ran.'
   say "- Verified head: \`${shellExpansion("GITHUB_SHA:-unknown")}\`"
-  echo "::notice title=Factory proof reuse::Proof reuse is not applicable on merge-target runs; the full ${label} suite executed."
+  echo "::notice title=Factory proof reuse::The proof-reuse gate did not run on this ref; the full ${label} suite executed."
 elif [ "${shellExpansion("PROOF_REUSED:-")}" = 'true' ]; then
   say '- Path: trusted local proof reused'
   if [ -n "${shellExpansion("PROOF_SOURCE_URL:-")}" ]; then
@@ -105,7 +108,11 @@ export const factoryProofReuseSummaryStep = (
       CI_STARTED_MS: githubExpression(
         `steps.${FACTORY_PROOF_TIMING_STEP_ID}.outputs.started_ms`
       ),
-      PROOF_HEAD_SHA: githubExpression("github.event.pull_request.head.sha"),
+      // PR runs bind to the PR branch tip; push runs to the pushed merge-target
+      // head, which is what the gate's merge fallback resolved from (#611).
+      PROOF_HEAD_SHA: githubExpression(
+        "github.event.pull_request.head.sha || github.sha"
+      ),
       PROOF_MODE: githubExpression(
         `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_MODE_OUTPUT}`
       ),