@patronage/software-factory 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.ts

@@ -1,8 +1,98 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { Command } from "commander";
 import { z } from "zod";
-import { readFile } from "node:fs/promises";
+import { PreviewProofRegistration } from "@patronage/factory-ci";
 
+//#region src/review-rungs.d.ts
+declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
+type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
+declare namespace boundary_manifest_d_exports {
+  export { BOUNDARY_CLOSEOUT_DEFAULT_RUNG, BOUNDARY_MANIFEST_SCHEMA_VERSION, BoundaryManifest, BoundaryManifestExtraction, BoundaryManifestParse, FACTORY_BOUNDARY_FENCE_LANG, boundaryManifestSchema, closeoutRungFor, extractBoundaryManifestBlock, manifestContentHash, parseBoundaryManifest, rungMeetsMinimum, specContentHash };
+}
+declare const FACTORY_BOUNDARY_FENCE_LANG = "factory-boundary";
+declare const BOUNDARY_MANIFEST_SCHEMA_VERSION = 1;
+declare const BOUNDARY_CLOSEOUT_DEFAULT_RUNG: EvidenceReviewRung;
+declare const rungMeetsMinimum: (rung: EvidenceReviewRung, minimum: EvidenceReviewRung) => boolean;
+declare const boundaryManifestBaseSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  closeout: z.ZodOptional<z.ZodObject<{
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+  declaredBy: z.ZodString;
+  integrationBranch: z.ZodOptional<z.ZodString>;
+  schemaVersion: z.ZodLiteral<1>;
+  topology: z.ZodEnum<{
+    flagged: "flagged";
+    "each-to-main": "each-to-main";
+    stacked: "stacked";
+    "each-to-epic": "each-to-epic";
+  }>;
+  waves: z.ZodArray<z.ZodObject<{
+    autoMerge: z.ZodOptional<z.ZodBoolean>;
+    issues: z.ZodArray<z.ZodNumber>;
+    name: z.ZodString;
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+declare const boundaryManifestSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  closeout: z.ZodOptional<z.ZodObject<{
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+  declaredBy: z.ZodString;
+  integrationBranch: z.ZodOptional<z.ZodString>;
+  schemaVersion: z.ZodLiteral<1>;
+  topology: z.ZodEnum<{
+    flagged: "flagged";
+    "each-to-main": "each-to-main";
+    stacked: "stacked";
+    "each-to-epic": "each-to-epic";
+  }>;
+  waves: z.ZodArray<z.ZodObject<{
+    autoMerge: z.ZodOptional<z.ZodBoolean>;
+    issues: z.ZodArray<z.ZodNumber>;
+    name: z.ZodString;
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+type BoundaryManifest = z.infer<typeof boundaryManifestBaseSchema>;
+type BoundaryManifestExtraction = {
+  ok: true;
+  blockText: string;
+} | {
+  ok: false;
+  error: string;
+};
+declare const extractBoundaryManifestBlock: (issueBody: string) => BoundaryManifestExtraction;
+declare const manifestContentHash: (blockText: string) => string;
+declare const specContentHash: (issueBody: string) => string;
+type BoundaryManifestParse = {
+  ok: true;
+  manifest: BoundaryManifest;
+  manifestHash: string;
+} | {
+  ok: false;
+  error: string;
+};
+declare const parseBoundaryManifest: (issueBody: string) => BoundaryManifestParse;
+declare const closeoutRungFor: (manifest: BoundaryManifest) => EvidenceReviewRung;
+//#endregion
 //#region src/github-issue-comments.d.ts
 interface GithubIssueCommentApi {
   body: string;
@@ -127,6 +217,24 @@ declare const selectBoundaryReviewProof: (comments: GithubIssueComment[], bounda
 declare const boundaryReviewProofAuthorsSeen: (comments: GithubIssueComment[], boundary: string) => string[];
 declare const undispositionedBlockingFindings: (proof: BoundaryReviewProof) => string[];
 //#endregion
+//#region src/boundary-membership-graph.d.ts
+/** The boundary-manifest wave demand that applies to one pull request. */
+interface WaveReviewDemand {
+  autoMerge: boolean;
+  review: EvidenceReviewRung;
+  wave: string;
+}
+interface BoundaryPullRequestRef {
+  baseRefName?: string;
+  headRefOid?: string;
+  headRefName?: string;
+  mergeCommitOid?: string;
+  /** GitHub's merge timestamp; the merge-ordering fact topology reads (#821). */
+  mergedAt?: string;
+  number: number;
+  state: "OPEN" | "CLOSED" | "MERGED";
+}
+//#endregion
 //#region src/hq-ingest-sink.d.ts
 interface HqIngestDependencies {
   /**
@@ -145,8 +253,6 @@ interface HqIngestDependencies {
    * `timeoutMs`: see the note there.
    */
   journalFlushBudgetMs?: number;
-  /** @deprecated Legacy sidecars are now streamed directly; retained for API compatibility. */
-  sidecarReclaimMs?: number;
   /**
    * Setup budget for callers that own the process lifetime — honored AS GIVEN,
    * above the `DEFAULT_HQ_INGEST_TIMEOUT_MS` ceiling that clamps `timeoutMs`.
@@ -182,14 +288,17 @@ interface HqSpoolEntryOutcome {
   detail?: string;
   eventId: string;
   kind: string;
+  /**
+   * `true` when HQ refused the content as schema-invalid (HTTP 422, #739).
+   * The same bytes get the same verdict on every retry under the current
+   * ingest schema, so retrying without a schema change cannot succeed.
+   * Distinct from `undeliverable`: an HQ schema fix can still admit these
+   * bytes, so eviction is an operator decision (`hq:flush --evict-permanent`),
+   * never automatic.
+   */
+  permanent?: boolean;
   spool: string;
   /**
-   * `migrated` belongs to the legacy JSONL journal only: the row was moved
-   * into the current spool without being delivered. The spool pass that runs
-   * after it in the same drain supersedes that line with a real outcome when
-   * it gets to the row; a `migrated` line that survives the run means the row
-   * is still waiting.
-   *
    * `undeliverable` is the one terminal verdict (#445). Every other status
    * describes a moment: HQ was unreachable, HQ refused this content today, the
    * row moved. Retrying is meaningful for all of them. A wrong-origin entry is
@@ -198,15 +307,20 @@ interface HqSpoolEntryOutcome {
    * run. Leaving it spooled asks the operator to retry something that provably
    * cannot succeed, and the count it inflates is the one doctor goes red on.
    */
-  status: "delivered" | "duplicate" | "migrated" | "rejected" | "undeliverable" | "unreachable";
+  status: "delivered" | "duplicate" | "rejected" | "undeliverable" | "unreachable";
 }
 interface HqSpoolFlushInput {
   clientId: string;
   clientSecret: string;
-  /** Repository root whose legacy `.factory-memory` spool is also drained. */
-  cwd: string;
   /** The profile's HQ origin; entries recorded against another are refused. */
   endpoint: string;
+  /**
+   * Disposition schema-permanent rejections (HTTP 422) in place with the
+   * `.undeliverable` suffix instead of retaining them (#739). Operator
+   * opt-in: a later HQ schema fix can still admit the same bytes, so the
+   * drain never evicts on its own.
+   */
+  evictPermanentRejections?: boolean;
   /** Operator-named spool directories; replaces the default two locations. */
   explicitDirectories?: string[];
   repository: HqSpoolRepository;
@@ -239,13 +353,13 @@ interface HqSpoolFlushSummary {
 interface HqSpoolWorkCount {
   /**
    * The earliest moment learned across pending spool files (their own write
-   * time) and legacy journal rows (their own `failedAt`). Absent only when
+   * time). Absent only when
    * `pending` is `0`, or when every timestamp source was unreadable within
    * budget — an estimate for doctor's remediation message (#394), never a
    * precise audit trail.
    */
   oldestQueuedAt?: string;
-  /** Spooled events and replayable journals waiting in the locations below. */
+  /** Spooled events waiting in the locations below. */
   pending: number;
   /** Locations that exist and hold spooled work. */
   spools: string[];
@@ -266,7 +380,7 @@ interface HqSpoolWorkCount {
  * same locations `flushHqSpool` drains are inspected here, read-only: no
  * directory is created, nothing is secured, and nothing is delivered.
  */
-declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "cwd" | "explicitDirectories" | "repository">, dependencies?: {
+declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "explicitDirectories" | "repository">, dependencies?: {
   budgetMs?: number;
   env?: NodeJS.ProcessEnv;
 }): Promise<HqSpoolWorkCount>;
@@ -275,7 +389,7 @@ interface HqSpoolOrphan {
   /** The `hq-retry-spool` directory itself, ready to pass to `--dir`. */
   directory: string;
   oldestQueuedAt?: string;
-  /** Spooled events and journal rows waiting there. */
+  /** Spooled events waiting there. */
   pending: number;
   /**
    * The location exists but could not be listed. As everywhere else in this
@@ -522,10 +636,82 @@ declare const FollowUpActionSchema: z.ZodType<FollowUpAction>;
 declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
 type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
 //#endregion
+//#region src/impact-stamp.d.ts
+/**
+ * The recorded stamp. `targets` satisfies the completeness invariant: every
+ * target the profile declares is present, each with its exact basis — never
+ * silently absent. `basis: "conservative"` means an unmodelled or unprovable
+ * input widened every target to full impact.
+ */
+declare const impactStampSchema: z.ZodObject<{
+  basis: z.ZodEnum<{
+    "target-scoped": "target-scoped";
+    conservative: "conservative";
+  }>;
+  inertPaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  reasons: z.ZodArray<z.ZodString>;
+  stampVersion: z.ZodLiteral<3>;
+  targets: z.ZodArray<z.ZodObject<{
+    basis: z.ZodString;
+    impact: z.ZodEnum<{
+      affected: "affected";
+      "not-affected": "not-affected";
+    }>;
+    name: z.ZodString;
+  }, z.core.$strip>>;
+  unsubscribedPaths: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type ImpactStamp = z.infer<typeof impactStampSchema>;
+/**
+ * The surfaces that consume the stamp. One classification, consumed
+ * everywhere (#430): every surface routes through
+ * {@link impactStampScopeDecision}, so no surface can be more trusting than
+ * another, and no surface re-derives path rules of its own. The value only
+ * selects the wording of the conservative floor a refusal falls back to.
+ */
+declare const IMPACT_SCOPE_SURFACES: {
+  readonly demand: "full demand floor";
+  readonly "preview-lifecycle": "full preview-lifecycle floor";
+  readonly "verification-battery": "full verification-battery floor";
+};
+type ImpactScopeSurface = keyof typeof IMPACT_SCOPE_SURFACES;
+interface ImpactScopeDecision {
+  reason: string;
+  /** True ⇒ this target's work is provably unreachable and may be released. */
+  scoped: boolean;
+}
+/**
+ * Whether a trusted stamp RELEASES one target-scoped unit of work — an
+ * external proof demand (#542 wave 2), a verification-battery command, or a
+ * preview (Alchemy) lifecycle stack (#430 wave 3).
+ *
+ * The only release path is a `target-scoped` stamp of exactly this build's
+ * stamp version whose target entry for exactly this name is provably
+ * `not-affected`. Every other input — no trusted stamp, an unknown stamp
+ * version, a conservative stamp, a name the stamp does not classify, or an
+ * `affected` verdict — keeps today's full-work floor. Work only ever gets
+ * released, never added or satisfied: this function can withdraw a demand, it
+ * can never certify one.
+ *
+ * Identity binding is the CALLER's precondition: pass only a stamp computed
+ * for, or read from a pr:verify proof bound to, the current candidate (see
+ * `trustedImpactStamp` in `pr-readiness/verification-proof.ts`); pass
+ * `undefined` otherwise.
+ */
+declare const impactStampScopeDecision: ({
+  stamp,
+  surface,
+  targetName
+}: {
+  stamp: ImpactStamp | undefined;
+  surface: ImpactScopeSurface;
+  targetName: string;
+}) => ImpactScopeDecision;
+//#endregion
 //#region src/profile.d.ts
 declare const DEFAULT_FACTORY_REPOSITORY = "unknown/unknown";
-/** The one profile shape this build accepts (ADR 0023, #318, #351). */
-declare const PROFILE_SCHEMA_VERSION = 5;
+/** The one profile shape this build accepts (ADR 0023, #318, #351, #742). */
+declare const PROFILE_SCHEMA_VERSION = 6;
 declare const factoryProjectProfileSchema: z.ZodObject<{
   $schema: z.ZodOptional<z.ZodString>;
   extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -534,18 +720,17 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     endpoint: z.ZodIntersection<z.ZodString, z.ZodString>;
   }, z.core.$strict>>;
   impact: z.ZodOptional<z.ZodObject<{
+    inert: z.ZodOptional<z.ZodArray<z.ZodString>>;
     targets: z.ZodArray<z.ZodObject<{
       importers: z.ZodArray<z.ZodString>;
       name: z.ZodString;
       paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
   }, z.core.$strict>>;
-  proof: z.ZodObject<{
-    classificationPolicy: z.ZodObject<{
-      docsOnly: z.ZodDefault<z.ZodArray<z.ZodString>>;
-      trivial: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>;
-  }, z.core.$strict>;
+  lifecycleContract: z.ZodOptional<z.ZodObject<{
+    command: z.ZodString;
+    jobName: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
   repository: z.ZodObject<{
     name: z.ZodString;
     owner: z.ZodString;
@@ -554,7 +739,6 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     name: z.ZodString;
     scope: z.ZodOptional<z.ZodObject<{
       classifications: z.ZodArray<z.ZodEnum<{
-        trivial: "trivial";
         "docs/process-only": "docs/process-only";
         "non-trivial": "non-trivial";
       }>>;
@@ -565,7 +749,7 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
       paths: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
   }, z.core.$strict>>;
-  schemaVersion: z.ZodLiteral<5>;
+  schemaVersion: z.ZodLiteral<6>;
   verification: z.ZodObject<{
     commands: z.ZodArray<z.ZodObject<{
       command: z.ZodString;
@@ -658,9 +842,7 @@ interface LoadUserConfigResult {
 //#endregion
 //#region src/github-check-runs.d.ts
 declare const FACTORY_CHECK_NAMES: {
-  readonly boundary: "patronage-factory/boundary";
   readonly "pr-ready": "patronage-factory/pr-ready";
-  readonly "pr-review": "patronage-factory/pr-review";
   readonly "pr-verify": "patronage-factory/pr-verify";
 };
 type FactoryCheckGate = keyof typeof FACTORY_CHECK_NAMES;
@@ -675,12 +857,6 @@ interface PublishFactoryCheckInput {
    * `hqLaneRefBaseUrlFromProfile` — the same source as the HQ gate sink.
    */
   hqLaneBaseUrl?: string;
-  /**
-   * Explicit issue/PR number for the HQ lane ref, used when the check run is not
-   * PR-scoped (e.g. an epic boundary check keyed by its epic issue). Falls back
-   * to `pr`, then to the checkout's PR, when omitted.
-   */
-  laneRefNumber?: number;
   owner: string;
   pr?: number;
   proof: unknown;
@@ -753,8 +929,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    stale: "stale";
     active: "active";
+    stale: "stale";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -879,10 +1055,6 @@ interface ReviewLadderPolicy {
 }
 declare const resolveReviewLadderPolicy: () => ReviewLadderPolicy;
 //#endregion
-//#region src/review-rungs.d.ts
-declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
-type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
-//#endregion
 //#region src/review-ladder-ledger.d.ts
 type LadderCycleStage = "interior" | "gate";
 interface LadderCycleRef {
@@ -1113,7 +1285,7 @@ interface PrReviewProof {
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
   reviewRequirement?: {
-    reason: "no-applicable-mode";
+    reason: "no-applicable-mode" | "faithful-merge";
     status: "not-required";
   };
   reviews: PrReviewResult[];
@@ -1134,8 +1306,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
   baseSha: z.ZodString;
   blockingReasons: z.ZodArray<z.ZodString>;
   classification: z.ZodEnum<{
-    trivial: "trivial";
     "docs/process-only": "docs/process-only";
+    trivial: "trivial";
     "non-trivial": "non-trivial";
   }>;
   externalChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1148,8 +1320,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodObject<{
       classifications: z.ZodArray<z.ZodEnum<{
-        trivial: "trivial";
         "docs/process-only": "docs/process-only";
+        trivial: "trivial";
         "non-trivial": "non-trivial";
       }>>;
     }, z.core.$strict>>;
@@ -1252,9 +1424,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1264,9 +1436,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1277,8 +1449,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      passed: "passed";
       stale: "stale";
+      passed: "passed";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1340,659 +1512,203 @@ declare const isHostedVerifyCheck: (check: StatusCheckRollup) => boolean;
 declare const hostedVerifyCheckState: (rollup: StatusCheckRollup[] | undefined) => CheckState;
 declare const statusCheckState: (rollup: StatusCheckRollup[] | undefined, exclude?: (check: StatusCheckRollup) => boolean) => CheckState;
 //#endregion
-//#region src/pr-ready.d.ts
-interface PrReadyArgs extends LoadProjectProfileInput {
-  authoringSessionIds?: string[];
-  base: string;
-  epic?: number;
-  json?: boolean;
-  output?: string;
-  report?: boolean;
-  pr: number;
-  reviewProof?: string;
-  throwWhenBlocked?: boolean;
-  verifyProof?: string;
+//#region src/github-app-client.d.ts
+interface FactoryAppRequest {
+  body?: unknown;
+  headers?: Readonly<Record<string, string>>;
+  method: "DELETE" | "GET" | "PATCH" | "POST";
+  owner: string;
+  path: string;
+  repo: string;
 }
-interface GitHubPullRequest {
-  /**
-   * GitHub's live auto-merge enablement, or `null` when nothing is scheduled.
-   *
-   * Required, not optional (#515 review). `gh pr view --json autoMergeRequest`
-   * always returns the key — explicitly `null` when nothing is scheduled — and
-   * errors loudly on a field name it does not know, so there is no shape where
-   * the real CLI omits it. But `fetchPullRequest` is injectable, and an
-   * implementation that left the field out would silently disable the
-   * `boundary-wave` refusal that stops an epicless run from greening a
-   * candidate GitHub is already scheduled to merge. Requiring it makes the
-   * compiler enforce what `gh` already promises.
-   */
-  autoMergeRequest: {
-    enabledAt?: string;
-  } | null;
-  baseRefName: string;
-  baseRefOid: string;
+interface FactoryAppExchange<T = unknown> {
+  readonly etag?: string;
+  readonly json: T;
+  readonly status: number;
+}
+//#endregion
+//#region src/github-pr-status-comment.d.ts
+interface UpsertFactoryPrStatusCommentInput {
   body: string;
-  headRefOid: string;
-  isDraft: boolean;
-  mergeStateStatus: string;
-  mergeable: string;
-  number: number;
-  reviewDecision: string | null;
-  statusCheckRollup?: StatusCheckRollup[];
-  title: string;
-  unresolvedReviewThreads: number;
+  /** ISO instant at which this presentation was observed. */
+  observedAt?: string;
+  owner: string;
+  pr: number;
+  repo: string;
+}
+interface UpsertFactoryPrStatusCommentDependencies {
+  request?: (input: FactoryAppRequest) => Promise<FactoryAppExchange>;
+  requestJson?: (input: FactoryAppRequest) => Promise<unknown>;
+}
+interface UpsertFactoryPrStatusCommentResult {
+  action: "created" | "updated";
+  commentId: number;
   url: string;
 }
-interface PrReadyProof {
-  schemaVersion: 3;
+declare function upsertFactoryPrStatusComment(input: UpsertFactoryPrStatusCommentInput, dependencies?: UpsertFactoryPrStatusCommentDependencies): Promise<UpsertFactoryPrStatusCommentResult>;
+//#endregion
+//#region src/catch-up-recognition-record.d.ts
+interface CatchUpRecognition {
+  /** The ref the candidate targets, as the recognizing command resolved it. */
+  baseRef: string;
+  /** The live target tip at recognition time; the head's first parent. */
+  baseTipSha: string;
+  /** The head's second parent: the admitted base-side content merged in. */
+  mergedParentSha: string;
   /**
-   * What GitHub actually did when this run armed native auto-merge (#477).
-   * Present exactly when a ready wave authorizes machine merge and arming ran;
-   * read back from the PR rather than inferred from the invocation, because `gh pr merge
-   * --auto` arms, merges, or does nothing with the same exit code and the same
-   * empty output. `not-armed` means the candidate is admitted but nothing will
-   * merge it, and `followUp` carries the re-dispatch.
+   * The tree `git merge-tree --write-tree` produced for the two parents. It
+   * equals the head's own tree; that equality is the faithfulness proof.
    */
-  arming?: {
-    detail?: string;
-    headSha: string;
-    outcome: "armed" | "merged" | "not-armed";
-  };
-  /**
-   * Why this run blocked, one entry per refusing demand (#391): `code` is the
-   * demand key from the resolver's vocabulary, `detail` the one-sentence
-   * refusal. Same refusals as `blockingReasons`, in the same order — the
-   * analyzable projection of a flat string list, so a wall of blocked proofs
-   * on one PR can be counted by cause. Absent when nothing blocked.
-   */
-  blockedReasons?: BlockedReason[];
-  blockingReasons: string[];
-  humanBlockingReasons: string[];
-  command: "patronage-factory pr:ready";
-  /**
-   * Machine-safe arg array for the obvious next action (#523): when `ready`
-   * but arming did not take effect, a `pr:ready` re-dispatch (idempotent on
-   * an unchanged head); otherwise the `gh pr ready` undraft repair or the
-   * `pr:verify` re-run that the blocking reasons name (re-verify the head,
-   * then re-run pr:ready). Same `argv` shape `factory:delegate --print`
-   * emits. Optional and purely additive.
-   */
-  followUp?: FollowUpAction;
-  /**
-   * `ledger.headSha` is the evaluated head SHA: the GitHub `pr.headRefOid`
-   * captured at evaluation time (not a local git read), recorded explicitly
-   * so merge-time identity checks are a pure comparison against the live
-   * pushed HEAD, not a re-derivation. See the ledger schema.
-   */
-  ledger: ManagedReadinessLedger;
-  /**
-   * Actionable facts that did not block (#477): a settling merge-freeze
-   * generation that permitted readiness and any authorized arming with a
-   * notice, an admitted-but-unscheduled false boundary wave, and how each
-   * waived demand reads to a human. Absent when there are none.
-   */
-  notices?: string[];
-  /** Committed profile blob evaluated by readiness. Required for merge. */
-  profileBlobSha?: string;
-  /** Checkout-relative committed profile path evaluated by readiness. */
-  profilePath?: string;
-  repairs: ReadinessRepair[];
-  /** Trusted checkout repository used for all GitHub reads and writes. */
-  repository?: string;
-  status: ReadinessStatus;
-  /**
-   * Demands that were in force, were NOT met, and were waived by the operator
-   * (#354, moved here from the merge-time proof by #477). Each entry carries
-   * the demand's refusals verbatim, so a waived demand can never read as a met
-   * one; readiness proceeds on the recorded operator act, not on evidence.
-   */
-  waivedDemands?: WaivedDemand[];
+  mergedTreeSha: string;
+  /** The ref that proves the second parent is admitted content. */
+  upstreamRef: string;
 }
-interface PrReadyDependencies {
-  /**
-   * Arms GitHub native auto-merge only for a passing boundary wave that
-   * authorizes machine merge (#477). Defaults to the real `gh pr merge --auto`
-   * call plus the read-back that says what actually happened.
-   */
-  armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
-  github?: {
-    fetchClosingPullRequests?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => {
-      number: number;
-    }[];
-    fetchIssueBody?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => string;
-    fetchPullRequest: (input: {
-      owner: string;
-      repo: string;
-      pr: number;
-    }) => GitHubPullRequest;
-  };
-  git?: PrReadyGitDependencies;
-  hq?: HqIngestDependencies;
-  /**
-   * The authoritative merge-freeze reader (#477). Defaults to the pinned-App
-   * GitHub check-run authority — readiness is a control, so an absent
-   * dependency must not mean an unread freeze.
-   */
-  mergeFreeze?: Pick<MergeFreezeAuthority, "readGeneration">;
+//#endregion
+//#region src/pr-verify-proof-contract.d.ts
+declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [1, 2, 3, 4];
+type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
+interface PrVerifyCommandResult {
+  command: string;
+  description: string;
   /**
-   * Awaited publication of the branded check, which is a source-pinned
-   * required check rather than a mirror (#477). Returns true only when the
-   * App-owned run landed. Defaults to `ensureFactoryCheckRunPublished`.
-   *
-   * `pr:ready` has no other publication seam, and this one cannot express a
-   * non-terminal run (#526): `status` is omitted from the input, so every run
-   * readiness creates is completed with a conclusion. A `pr:ready` invocation
-   * therefore cannot leave a run holding the source-pinned required check
-   * open, which is a permanent block on the pull request (#524).
+   * Epic #550 wave 3 (#430): the profile's declared impact target for this
+   * command, recorded from v4 on. It is the proof's own command→target
+   * mapping: a `notRequiredCommands` entry must name the target recorded HERE
+   * for the same command, so a withholding cannot point at whichever released
+   * target happens to be convenient. Absent for a command the profile does
+   * not scope, and for v1–v3 proofs, which predate the field.
    */
-  publishFinalCheckRun?: (input: Omit<PublishFactoryCheckInput, "status"> & {
-    conclusion: "failure" | "success";
-  }) => Promise<boolean> | boolean;
-  /** Injectable delay for the UNKNOWN-mergeable brief poll (tests). */
-  sleep?: (ms: number) => Promise<void>;
+  impactTarget?: string;
+  name: string;
+  scope: "always" | "docs-only" | "trivial" | "full";
 }
-interface PrReadyGitDependencies {
-  canResolveCommit: (cwd: string, sha: string) => boolean;
-  changedFiles: (cwd: string, base: string, headSha?: string) => string[];
-  checkoutRepository: (cwd: string) => CheckoutRepository;
-  currentHeadSha: (cwd: string) => string;
-  mergeBaseSha: (cwd: string, base: string) => string;
-  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-  resolveCommitSha: (cwd: string, ref: string) => string | undefined;
-  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-  stablePatchId: (cwd: string, base: string) => string;
+interface PrVerifyExecutedCommand {
+  command: string;
+  counts?: {
+    testFiles?: number;
+    tests?: number;
+  };
+  durationMs: number;
+  exitCode: number;
+  name: string;
+  scope: "always" | "docs-only" | "trivial" | "full";
 }
-declare function validatePrReadyProof(value: unknown): PrReadyProof;
-declare function readPrReadyProof(filePath: string): PrReadyProof;
-declare function runPrReady(args: PrReadyArgs, dependencies?: PrReadyDependencies): Promise<PrReadyProof>;
-//#endregion
-//#region src/impact-stamp.d.ts
-/**
- * The recorded stamp. `targets` satisfies the completeness invariant: every
- * target the profile declares is present, each with its exact basis — never
- * silently absent. `basis: "conservative"` means an unmodelled or unprovable
- * input widened every target to full impact.
- */
-declare const impactStampSchema: z.ZodObject<{
-  basis: z.ZodEnum<{
-    "target-scoped": "target-scoped";
-    conservative: "conservative";
-  }>;
-  reasons: z.ZodArray<z.ZodString>;
-  stampVersion: z.ZodLiteral<2>;
-  targets: z.ZodArray<z.ZodObject<{
-    basis: z.ZodString;
-    impact: z.ZodEnum<{
-      affected: "affected";
-      "not-affected": "not-affected";
-    }>;
-    name: z.ZodString;
-  }, z.core.$strip>>;
-}, z.core.$strip>;
-type ImpactStamp = z.infer<typeof impactStampSchema>;
 /**
- * The surfaces that consume the stamp. One classification, consumed
- * everywhere (#430): every surface routes through
- * {@link impactStampScopeDecision}, so no surface can be more trusting than
- * another, and no surface re-derives path rules of its own. The value only
- * selects the wording of the conservative floor a refusal falls back to.
+ * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
+ * candidate cannot reach, so the battery did not run it.
+ *
+ * The completeness invariant lives in the pairing: `verificationCommands`
+ * records every command the resolved mode selected, `executedCommands` records
+ * what ran, and this list records the rest WITH the stamp's own basis. A
+ * withheld stack is therefore never silently absent from the proof — it is
+ * present, named, and explained.
  */
-declare const IMPACT_SCOPE_SURFACES: {
-  readonly demand: "full demand floor";
-  readonly "preview-lifecycle": "full preview-lifecycle floor";
-  readonly "verification-battery": "full verification-battery floor";
-};
-type ImpactScopeSurface = keyof typeof IMPACT_SCOPE_SURFACES;
-interface ImpactScopeDecision {
-  reason: string;
-  /** True ⇒ this target's work is provably unreachable and may be released. */
-  scoped: boolean;
+interface PrVerifyNotRequiredCommand {
+  basis: string;
+  impactTarget: string;
+  name: string;
 }
 /**
- * Whether a trusted stamp RELEASES one target-scoped unit of work — an
- * external proof demand (#542 wave 2), a verification-battery command, or a
- * preview (Alchemy) lifecycle stack (#430 wave 3).
- *
- * The only release path is a `target-scoped` stamp of exactly this build's
- * stamp version whose target entry for exactly this name is provably
- * `not-affected`. Every other input — no trusted stamp, an unknown stamp
- * version, a conservative stamp, a name the stamp does not classify, or an
- * `affected` verdict — keeps today's full-work floor. Work only ever gets
- * released, never added or satisfied: this function can withdraw a demand, it
- * can never certify one.
- *
- * Identity binding is the CALLER's precondition: pass only a stamp computed
- * for, or read from a pr:verify proof bound to, the current candidate (see
- * `trustedImpactStamp` in `pr-readiness/verification-proof.ts`); pass
- * `undefined` otherwise.
+ * Epic #758 (#762): a consumer package a stamp-scoped selection skipped, and
+ * why. Bound to the proof's stamp identity — the field is v4-only (the same
+ * window that can carry `impactStamp`) and refused when the proof records no
+ * stamp. The factory does not write this list; consumers do.
  */
-declare const impactStampScopeDecision: ({
-  stamp,
-  surface,
-  targetName
-}: {
-  stamp: ImpactStamp | undefined;
-  surface: ImpactScopeSurface;
-  targetName: string;
-}) => ImpactScopeDecision;
-//#endregion
-//#region src/required-check-policy.d.ts
-declare const EVIDENCE_CHECK_TYPES: readonly ["review", "verify"];
-type EvidenceCheckType = (typeof EVIDENCE_CHECK_TYPES)[number];
-declare const requiredCheckScopeSchema: z.ZodObject<{
-  classifications: z.ZodArray<z.ZodEnum<{
-    trivial: "trivial";
-    "docs/process-only": "docs/process-only";
-    "non-trivial": "non-trivial";
-  }>>;
-}, z.core.$strict>;
-type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
-interface RequiredCheckScopeContext {
-  classification: DiffClassification | undefined;
-  impactStamp?: ImpactStamp;
-}
-interface ScopeDecision {
-  inScope: boolean;
-  reason: string;
-}
-declare const requiredCheckInScope: ({
-  context,
-  scope
-}: {
-  context: RequiredCheckScopeContext;
-  scope?: RequiredCheckScope;
-}) => ScopeDecision;
-interface RequiredCheck {
+interface PrVerifyNotDemandedRecord {
+  basis: string;
   name: string;
-  checkType: EvidenceCheckType;
-  scope?: RequiredCheckScope;
 }
-//#endregion
-//#region src/factory-session.d.ts
-declare const resolveAuthoringSessionIds: ({
-  override,
-  recorded
-}: {
-  override?: string[];
-  recorded?: string;
-}) => string[];
-declare namespace external_evidence_d_exports {
-  export { EVIDENCE_CHECK_TYPES, EVIDENCE_DIR, EVIDENCE_ENVELOPE_SCHEMA_VERSION, EVIDENCE_REVIEW_RUNGS, EvidenceCandidateIdentity, EvidenceCheckType, EvidenceEnvelope, EvidenceEnvelopeParse, EvidenceReviewRung, IndependenceResult, LoadedEvidenceEnvelope, RequiredCheck, RequiredCheckEvaluation, RequiredCheckEvaluationInput, RequiredCheckOutcome, RequiredCheckScope, RequiredCheckScopeContext, ScopeDecision, boundFailingCheckNames, evaluateRequiredChecks, evidenceBindingFresh, evidenceEnvelopeSchema, evidenceReviewIndependence, loadEvidenceEnvelopes, parseEvidenceEnvelope, requiredCheckInScope, requiredCheckScopeSchema, resolveAuthoringSessionIds };
-}
-declare const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
-declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
-  check: z.ZodString;
-  checkType: z.ZodEnum<{
-    review: "review";
-    verify: "verify";
-  }>;
-  findingsPointer: z.ZodOptional<z.ZodString>;
-  headSha: z.ZodString;
-  mergeBaseSha: z.ZodString;
-  model: z.ZodOptional<z.ZodString>;
-  outcome: z.ZodEnum<{
-    pass: "pass";
-    fail: "fail";
-  }>;
-  patchId: z.ZodString;
-  policyVersion: z.ZodOptional<z.ZodString>;
-  producer: z.ZodString;
-  requestId: z.ZodOptional<z.ZodString>;
-  rung: z.ZodOptional<z.ZodEnum<{
-    oracle: "oracle";
-    "independent-model": "independent-model";
-    human: "human";
-  }>>;
-  schemaVersion: z.ZodLiteral<1>;
-  sessionId: z.ZodOptional<z.ZodString>;
-  timestamp: z.ZodOptional<z.ZodISODateTime>;
-}, z.core.$loose>;
-declare const evidenceEnvelopeSchema: z.ZodObject<{
-  check: z.ZodString;
-  checkType: z.ZodEnum<{
-    review: "review";
-    verify: "verify";
-  }>;
-  findingsPointer: z.ZodOptional<z.ZodString>;
-  headSha: z.ZodString;
-  mergeBaseSha: z.ZodString;
-  model: z.ZodOptional<z.ZodString>;
-  outcome: z.ZodEnum<{
-    pass: "pass";
-    fail: "fail";
-  }>;
-  patchId: z.ZodString;
-  policyVersion: z.ZodOptional<z.ZodString>;
-  producer: z.ZodString;
-  requestId: z.ZodOptional<z.ZodString>;
-  rung: z.ZodOptional<z.ZodEnum<{
-    oracle: "oracle";
-    "independent-model": "independent-model";
-    human: "human";
-  }>>;
-  schemaVersion: z.ZodLiteral<1>;
-  sessionId: z.ZodOptional<z.ZodString>;
-  timestamp: z.ZodOptional<z.ZodISODateTime>;
-}, z.core.$loose>;
-type EvidenceEnvelope = z.infer<typeof evidenceEnvelopeBaseSchema>;
-type EvidenceEnvelopeParse = {
-  ok: true;
-  envelope: EvidenceEnvelope;
-} | {
-  ok: false;
-  error: string;
-};
-declare const parseEvidenceEnvelope: (raw: unknown) => EvidenceEnvelopeParse;
-interface EvidenceCandidateIdentity {
+interface PrVerifyProof {
+  schemaVersion: PrVerifySchemaVersion;
+  authoringSession?: string;
+  base: string;
+  baselineFullProofs?: {
+    base: string;
+    changedFiles: string[];
+    headSha: string;
+    profilePath: string;
+    projectKey: string;
+    repository: string;
+  }[];
+  catchUpRecognition?: CatchUpRecognition;
+  changedFiles: string[];
+  classification: DiffClassification;
+  classificationReasons: string[];
+  command: "patronage-factory pr:verify";
+  durationMs: number;
+  endedAt: string;
+  executedCommands?: PrVerifyExecutedCommand[];
   headSha: string;
-  patchId: string;
-  mergeBaseSha: string;
+  impactStamp?: ImpactStamp;
+  mode: ResolvedPrVerifyMode;
+  mergeBaseSha?: string;
+  notDemandedRecords?: PrVerifyNotDemandedRecord[];
+  notRequiredCommands?: PrVerifyNotRequiredCommand[];
+  outcome?: "aborted" | "passed";
+  patchId?: string;
+  profilePath: string;
+  projectKey: string;
+  repository: string;
+  startedAt: string;
+  verificationCommands: PrVerifyCommandResult[];
 }
-declare const evidenceBindingFresh: ({
-  candidate,
-  envelope
-}: {
-  candidate: EvidenceCandidateIdentity;
-  envelope: EvidenceEnvelope;
-}) => boolean;
-interface IndependenceResult {
-  independent: boolean;
-  reason?: "no-session" | "unknown-authoring-identity" | "same-session";
+type PrVerifyBaselineFullProof = NonNullable<PrVerifyProof["baselineFullProofs"]>[number];
+declare function validatePrVerifyProof(value: unknown): PrVerifyProof;
+declare namespace verification_proof_d_exports {
+  export { PrVerifyBaselineFullProof, PrVerifyCommandResult, PrVerifyExecutedCommand, PrVerifyNotDemandedRecord, PrVerifyNotRequiredCommand, PrVerifyProof, PrVerifySchemaVersion, ResolvedPrVerifyMode, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, VerificationHeadShas, VerificationProofState, VerifiedHeadShas, prVerifyFullHeadShasForDiff, prVerifyProofHeadShas, readPrVerifyProof, resolveVerifyProofApplicability, trustedCatchUpRecognition, trustedImpactStamp, validatePrVerifyProof, verificationProofApplicabilityFor, verificationProofBlockingReason, verificationProofForReadiness, verificationProofStateFor, verifyProofIdentityMatches, verifyProofPassed };
 }
-declare const evidenceReviewIndependence: ({
-  authoringSessionIds,
-  envelope
+interface VerifiedHeadShas {
+  docsOnlyVerifiedHeadShas: string[];
+  trivialVerifiedHeadShas: string[];
+  verifiedHeadShas: string[];
+}
+type VerificationHeadShas = {
+  explicitFailure: true;
+} | VerifiedHeadShas;
+declare function readPrVerifyProof(filePath: string): PrVerifyProof;
+declare const verifyProofPassed: (proof: PrVerifyProof) => boolean;
+declare const prVerifyProofHeadShas: (proof: PrVerifyProof | undefined, creditedHeadSha?: string) => VerifiedHeadShas;
+declare const verifyProofIdentityMatches: ({
+  currentIdentity,
+  proof
 }: {
-  authoringSessionIds: string[];
-  envelope: EvidenceEnvelope;
-}) => IndependenceResult;
-type LoadedEvidenceEnvelope = {
-  ok: true;
-  envelope: EvidenceEnvelope;
-  path: string;
-} | {
-  check?: string;
-  error: string;
-  ok: false;
-  path: string;
-};
+  currentIdentity?: {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  proof?: PrVerifyProof;
+}) => boolean;
 /**
- * Every check name with a current, candidate-bound FAILING envelope on disk.
- *
- * The wave-3 scoping veto input. Callers pass the resolved set to
- * `planVerificationBattery` / `planPreviewLifecycle`, which stay pure — the
- * planners decide, they never read the filesystem.
+ * Wave-2 consumption (#542): the recorded impact stamp, released for demand
+ * resolution ONLY when it is identity-bound to the current candidate — the
+ * proof passed, and its recorded headSha AND patchId both name exactly this
+ * candidate (the same identities the proof already binds). Everything else —
+ * no proof, an aborted run, a stale head, a moved patch id, a pre-stamp proof
+ * — returns `undefined`, and the consumer keeps today's full-demand floor.
  *
- * `checkType` is the caller's, not a guess: schema-v5 requiredChecks are
- * verify-only (`resolveProfileRequiredChecks`), so a scoping caller passes
- * `"verify"` and matches exactly the pair wave 2 evaluates.
+ * Deliberately stricter than verify-once applicability (which tolerates a
+ * head-only or patch-id-only match): a stamp narrows external demands, so it
+ * is trusted only on an exact double binding, fail closed.
  */
-declare const boundFailingCheckNames: ({
+declare const trustedImpactStamp: ({
   candidate,
-  checkType,
-  envelopes
+  proof
 }: {
-  candidate: EvidenceCandidateIdentity;
-  checkType: EvidenceCheckType;
-  envelopes: LoadedEvidenceEnvelope[];
-}) => string[];
-interface RequiredCheckEvaluationInput {
-  authoringSessionIds: string[];
-  candidate: EvidenceCandidateIdentity;
-  envelopes: LoadedEvidenceEnvelope[];
-  requiredChecks: RequiredCheck[];
-  scopeContext: RequiredCheckScopeContext;
-}
-interface RequiredCheckOutcome {
-  name: string;
-  checkType: EvidenceCheckType;
-  status: "satisfied" | "unmet" | "out-of-scope";
-  inScope: boolean;
-  scopeReason: string;
-  scope?: RequiredCheckScope;
-  reason?: string;
-  matchedPath?: string;
-}
-interface RequiredCheckEvaluation {
-  outcomes: RequiredCheckOutcome[];
-  blockingReasons: string[];
-}
-declare const evaluateRequiredChecks: ({
-  authoringSessionIds,
-  candidate,
-  envelopes,
-  requiredChecks,
-  scopeContext
-}: RequiredCheckEvaluationInput) => RequiredCheckEvaluation;
-declare const EVIDENCE_DIR = ".factory-memory/evidence";
-declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
-//#endregion
-//#region src/review-proof-applicability.d.ts
-declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
-declare const reviewStatusSchema: z.ZodEnum<{
-  "not-required": "not-required";
-  blocked: "blocked";
-  current: "current";
-  stale: "stale";
-  missing: "missing";
-}>;
-type ReviewStatus = z.infer<typeof reviewStatusSchema>;
-interface CurrentReviewIdentity {
-  headSha: string;
-  patchId: string;
-}
-declare const reviewStatus: ({
-  blocked,
-  required,
-  reviewedHeadSha,
-  reviewedPatchId,
-  headSha,
-  patchId
-}: CurrentReviewIdentity & {
-  blocked?: boolean;
-  required: boolean;
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-}) => ReviewStatus;
-declare namespace proof_identity_d_exports {
-  export { CurrentReviewIdentity, REVIEW_STATUS_VALUES, ReviewProofClaim, ReviewStatus, explicitFailureIdentity, isExplicitReviewFailure, isUntypedReviewProof, reviewStatus, reviewStatusSchema, selectReviewProof };
-}
-type ReviewProofClaim = {
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-  untypedVerdict?: boolean;
-} | {
-  explicitFailure: true;
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-  untypedVerdict?: boolean;
-};
-declare const isExplicitReviewFailure: (proof: ReviewProofClaim) => proof is {
-  explicitFailure: true;
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-  untypedVerdict?: boolean;
-};
-declare const isUntypedReviewProof: (proof: ReviewProofClaim) => proof is {
-  untypedVerdict: true;
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-};
-declare const explicitFailureIdentity: (proof: ReviewProofClaim) => {
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-};
-declare const selectReviewProof: ({
-  reviewProof
-}: {
-  reviewProof: ReviewProofClaim;
-}) => {
-  reviewedHeadSha?: string;
-  reviewedPatchId?: string;
-  untypedVerdict?: boolean;
-};
-//#endregion
-//#region src/pr-readiness/review-epoch.d.ts
-interface ReviewCycleState {
-  autoBlockingFindings: number;
-  countsBySeverity: Record<ReviewFindingSeverity, number>;
-  highestBlockingSeverity?: ReviewFindingSeverity;
-  highestOpenSeverity?: ReviewFindingSeverity;
-  maxReviewCycles?: number;
-  nonBlockingFindings: number;
-  openFindings: number;
-  reviewCycle?: number;
-  staleRepeatFindings?: number;
-  windowExhausted: boolean;
-}
-declare const reviewCycleStateFor: (proof: Pick<PrReviewProof, "ladder" | "reviewCycle" | "maxReviewCycles" | "reviews">, policy?: ReviewLadderPolicy, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewCycleState;
-type ReviewAcceptance = "accepted-after-cap" | "accepted-clean" | "accepted-through-ladder" | "blocked";
-declare const resolveReviewAcceptance: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewAcceptance;
-type ReviewTerminalState = "accepted-with-findings" | "blocked" | "clean";
-declare const resolveReviewTerminalStateForEpoch: (proof: PrReviewProof, review: PrReviewResult, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState;
-declare const resolveReviewTerminalState: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewTerminalState;
-declare const resolveReviewTerminalStateAcrossReviews: (proof: PrReviewProof, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState | undefined;
-declare const resolveReviewTerminalStateAcrossReviewsForPolicy: (proof: PrReviewProof, policy: ReviewLadderPolicy) => ReviewTerminalState | undefined;
-declare const reviewProofFor: (proof: PrReviewProof | undefined, kind: PrReviewKind, policy: ReviewLadderPolicy | undefined, current?: {
-  patchId: string;
-}) => ReviewProofClaim;
-declare namespace review_proof_d_exports {
-  export { DEFAULT_PR_REVIEW_MAX_CYCLES, DEFAULT_PR_REVIEW_PROOF_PATH, PR_REVIEW_FINAL_READINESS_NOTICE, PR_REVIEW_FINDING_PROVENANCE_VERSION, PR_REVIEW_PROOF_DESCRIPTOR, PR_REVIEW_SCHEMA_VERSION, PrReviewFinding, PrReviewKind, PrReviewLadderState, PrReviewMode, PrReviewOutcome, PrReviewProof, PrReviewResult, PrReviewStageResolution, REVIEW_SEVERITIES, ReviewAcceptance, ReviewCycleState, ReviewFindingCategory, ReviewFindingSeverity, ReviewTerminalState, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, readPrReviewProof, resolveReviewAcceptance, resolveReviewTerminalState, resolveReviewTerminalStateAcrossReviews, resolveReviewTerminalStateAcrossReviewsForPolicy, resolveReviewTerminalStateForEpoch, reviewCycleStateFor, reviewProofFor, validatePrReviewProof, validatePrReviewResult };
-}
-declare const PR_REVIEW_SCHEMA_VERSION = 2;
-declare const PR_REVIEW_FINDING_PROVENANCE_VERSION = 1;
-declare const DEFAULT_PR_REVIEW_PROOF_PATH = ".factory-memory/pr-review.json";
-declare const DEFAULT_PR_REVIEW_MAX_CYCLES = 5;
-declare const PR_REVIEW_FINAL_READINESS_NOTICE = "pr:review is a final readiness proof gate. Run it after local verification and avoid repeated full runs unless the review proof records actionable findings. Default review window: 5 cycles.";
-declare const prReviewFindingSchema: z.ZodType<PrReviewFinding>;
-declare const prReviewResultSchema: z.ZodType<PrReviewResult>;
-declare const prReviewProofSchema: z.ZodType<PrReviewProof>;
-declare const validatePrReviewResult: (value: unknown) => PrReviewResult;
-declare const validatePrReviewProof: (value: unknown) => PrReviewProof;
-declare const readPrReviewProof: (filePath: string) => PrReviewProof;
-declare const PR_REVIEW_PROOF_DESCRIPTOR: ProofDescriptor<PrReviewProof>;
-declare namespace verification_proof_d_exports {
-  export { PrVerifyBaselineFullProof, PrVerifyCommandResult, PrVerifyExecutedCommand, PrVerifyNotRequiredCommand, PrVerifyProof, PrVerifySchemaVersion, ResolvedPrVerifyMode, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, VerificationHeadShas, VerificationProofState, VerifiedHeadShas, prVerifyFullHeadShasForDiff, prVerifyProofHeadShas, readPrVerifyProof, resolveVerifyProofApplicability, trustedImpactStamp, validatePrVerifyProof, verificationProofApplicabilityFor, verificationProofBlockingReason, verificationProofForReadiness, verificationProofStateFor, verifyProofIdentityMatches, verifyProofPassed };
-}
-interface VerifiedHeadShas {
-  docsOnlyVerifiedHeadShas: string[];
-  trivialVerifiedHeadShas: string[];
-  verifiedHeadShas: string[];
-}
-type VerificationHeadShas = {
-  explicitFailure: true;
-} | VerifiedHeadShas;
-declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [1, 2, 3, 4];
-type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
-interface PrVerifyCommandResult {
-  command: string;
-  description: string;
-  /**
-   * Epic #550 wave 3 (#430): the profile's declared impact target for this
-   * command, recorded from v4 on. It is the proof's own command→target
-   * mapping: a `notRequiredCommands` entry must name the target recorded HERE
-   * for the same command, so a withholding cannot point at whichever released
-   * target happens to be convenient. Absent for a command the profile does
-   * not scope, and for v1–v3 proofs, which predate the field.
-   */
-  impactTarget?: string;
-  name: string;
-  scope: "always" | "docs-only" | "trivial" | "full";
-}
-interface PrVerifyExecutedCommand {
-  command: string;
-  counts?: {
-    testFiles?: number;
-    tests?: number;
-  };
-  durationMs: number;
-  exitCode: number;
-  name: string;
-  scope: "always" | "docs-only" | "trivial" | "full";
-}
-/**
- * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
- * candidate cannot reach, so the battery did not run it.
- *
- * The completeness invariant lives in the pairing: `verificationCommands`
- * records every command the resolved mode selected, `executedCommands` records
- * what ran, and this list records the rest WITH the stamp's own basis. A
- * withheld stack is therefore never silently absent from the proof — it is
- * present, named, and explained.
- */
-interface PrVerifyNotRequiredCommand {
-  basis: string;
-  impactTarget: string;
-  name: string;
-}
-interface PrVerifyProof {
-  schemaVersion: PrVerifySchemaVersion;
-  authoringSession?: string;
-  base: string;
-  baselineFullProofs?: {
-    base: string;
-    changedFiles: string[];
-    headSha: string;
-    profilePath: string;
-    projectKey: string;
-    repository: string;
-  }[];
-  changedFiles: string[];
-  classification: DiffClassification;
-  classificationReasons: string[];
-  command: "patronage-factory pr:verify";
-  durationMs: number;
-  endedAt: string;
-  executedCommands?: PrVerifyExecutedCommand[];
-  headSha: string;
-  impactStamp?: ImpactStamp;
-  mode: ResolvedPrVerifyMode;
-  mergeBaseSha?: string;
-  notRequiredCommands?: PrVerifyNotRequiredCommand[];
-  outcome?: "aborted" | "passed";
-  patchId?: string;
-  profilePath: string;
-  projectKey: string;
-  repository: string;
-  startedAt: string;
-  verificationCommands: PrVerifyCommandResult[];
-}
-type PrVerifyBaselineFullProof = NonNullable<PrVerifyProof["baselineFullProofs"]>[number];
-declare function validatePrVerifyProof(value: unknown): PrVerifyProof;
-declare function readPrVerifyProof(filePath: string): PrVerifyProof;
-declare const verifyProofPassed: (proof: PrVerifyProof) => boolean;
-declare const prVerifyProofHeadShas: (proof: PrVerifyProof | undefined, creditedHeadSha?: string) => VerifiedHeadShas;
-declare const verifyProofIdentityMatches: ({
-  currentIdentity,
-  proof
-}: {
-  currentIdentity?: {
-    patchId: string;
-    mergeBaseSha?: string;
-  };
-  proof?: PrVerifyProof;
-}) => boolean;
-/**
- * Wave-2 consumption (#542): the recorded impact stamp, released for demand
- * resolution ONLY when it is identity-bound to the current candidate — the
- * proof passed, and its recorded headSha AND patchId both name exactly this
- * candidate (the same identities the proof already binds). Everything else —
- * no proof, an aborted run, a stale head, a moved patch id, a pre-stamp proof
- * — returns `undefined`, and the consumer keeps today's full-demand floor.
- *
- * Deliberately stricter than verify-once applicability (which tolerates a
- * head-only or patch-id-only match): a stamp narrows external demands, so it
- * is trusted only on an exact double binding, fail closed.
- */
-declare const trustedImpactStamp: ({
+  candidate: {
+    headSha: string;
+    patchId: string;
+  };
+  proof: PrVerifyProof | undefined;
+}) => ImpactStamp | undefined;
+/**
+ * #833: the recorded catch-up recognition, consumed ONLY when it is
+ * identity-bound to the current candidate under exactly the rules
+ * `trustedImpactStamp` applies — the proof passed, is v4+, and its recorded
+ * headSha AND patchId both name this candidate. The recognition withdraws
+ * review and preview demands, so it earns the same strict double binding and
+ * the same fail-closed answer (`undefined`) on every other state.
+ */
+declare const trustedCatchUpRecognition: ({
   candidate,
   proof
 }: {
@@ -2001,7 +1717,7 @@ declare const trustedImpactStamp: ({
     patchId: string;
   };
   proof: PrVerifyProof | undefined;
-}) => ImpactStamp | undefined;
+}) => CatchUpRecognition | undefined;
 declare const prVerifyFullHeadShasForDiff: ({
   docsOnlyDeltaAcceptedSince,
   files,
@@ -2024,260 +1740,782 @@ type VerificationProofState = {
   headShas: VerifiedHeadShas;
   proof: PrVerifyProof;
 } | {
-  kind: "typed-diff-mismatch";
-  mode: ResolvedPrVerifyMode;
+  kind: "typed-diff-mismatch";
+  mode: ResolvedPrVerifyMode;
+};
+declare const verificationProofStateFor: ({
+  proof,
+  proofMatchesCurrentDiff,
+  proofPath
+}: {
+  proof?: PrVerifyProof;
+  proofMatchesCurrentDiff?: boolean;
+  proofPath?: string;
+}) => VerificationProofState;
+declare const verificationProofApplicabilityFor: ({
+  docsOnlyDeltaAcceptedSince,
+  explicitProof,
+  files,
+  headSha,
+  currentIdentity,
+  proof,
+  proofPath,
+  proofReadError
+}: {
+  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
+  explicitProof: boolean;
+  files: string[];
+  headSha: string;
+  currentIdentity?: {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  proof?: PrVerifyProof;
+  proofPath?: string;
+  proofReadError?: unknown;
+}) => {
+  fullVerifiedHeadShas: never[];
+  verificationProof: VerificationProofState;
+} | {
+  fullVerifiedHeadShas: string[];
+  verificationProof: {
+    headShas: VerifiedHeadShas;
+    kind: "typed";
+    proof: PrVerifyProof;
+  };
+};
+declare const resolveVerifyProofApplicability: ({
+  proofPath,
+  explicitProof,
+  docsOnlyDeltaAcceptedSince,
+  files,
+  headSha,
+  currentVerifyIdentityForBase,
+  preread
+}: {
+  proofPath: string;
+  explicitProof: boolean;
+  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
+  files: string[];
+  headSha: string;
+  currentVerifyIdentityForBase?: (base: string) => {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  preread?: {
+    proof?: PrVerifyProof;
+    error?: unknown;
+  };
+}) => {
+  fullVerifiedHeadShas: never[];
+  verificationProof: VerificationProofState;
+} | {
+  fullVerifiedHeadShas: string[];
+  verificationProof: {
+    headShas: VerifiedHeadShas;
+    kind: "typed";
+    proof: PrVerifyProof;
+  };
+};
+declare const verificationProofForReadiness: (state: VerificationProofState) => VerificationHeadShas;
+declare const verificationProofBlockingReason: (state: VerificationProofState) => string | undefined;
+//#endregion
+//#region src/preview-lifecycle.d.ts
+type PreviewDisposition = "deploy" | "not-required";
+interface PreviewTargetPlan {
+  basis: string;
+  disposition: PreviewDisposition;
+  name: string;
+}
+interface PreviewLifecyclePlan {
+  /** The declared preview stacks to deploy, in declaration order. */
+  deploy: string[];
+  /** The withheld stacks, in declaration order. */
+  notRequired: PreviewTargetPlan[];
+  /** Whether a trusted, identity-bound stamp was available at all. */
+  stampTrusted: boolean;
+  /** Every declared preview target with its disposition, in declaration order. */
+  targets: PreviewTargetPlan[];
+}
+/** Validate a serialized plan without deriving or changing its dispositions. */
+declare const validatePreviewLifecyclePlan: (value: unknown) => PreviewLifecyclePlan;
+/**
+ * Structural subset of the profile: the impact declarations plus the external
+ * demand list. Structural rather than a `Pick` so this module does not import
+ * `profile.ts`.
+ */
+interface PreviewLifecycleProfile {
+  impact?: {
+    targets: {
+      name: string;
+    }[];
+  };
+  requiredChecks?: {
+    name: string;
+  }[];
+}
+/**
+ * The declared preview stacks: impact targets that are ALSO declared required
+ * checks — i.e. targets whose proof is produced externally, which is exactly
+ * what a preview producer is.
+ *
+ * Deriving the list from the two existing declarations rather than adding a
+ * third is what makes lifecycle and demand unable to disagree: the stacks this
+ * plan can withhold are precisely the demands wave 2 can release, so a stack
+ * can never be skipped while its proof stays demanded.
+ */
+declare const previewLifecycleTargets: (profile: PreviewLifecycleProfile) => string[];
+/**
+ * Plan the preview lifecycle for one candidate.
+ *
+ * Trust is resolved here through the SAME identity gate demand release uses
+ * (`trustedImpactStamp`): the proof must have passed and must bind both the
+ * candidate's headSha and its patchId. A stale, aborted, absent, or
+ * differently-bound proof yields no stamp, and every declared stack is planned
+ * for deploy. Total over its INPUTS — no proof, stamp, or profile can make it
+ * throw. A malformed CALL is the deliberate exception: omitting
+ * `vetoedTargets` is API misuse, not data doubt, and throws.
+ */
+declare const planPreviewLifecycle: ({
+  candidate,
+  profile,
+  proof,
+  vetoedTargets
+}: {
+  candidate: {
+    headSha: string;
+    patchId: string;
+  };
+  profile: PreviewLifecycleProfile;
+  proof: PrVerifyProof | undefined;
+  /**
+   * Stack names with a current, candidate-bound FAILING envelope. Scoping is
+   * withheld for these whatever the stamp says — the same veto demand release
+   * applies, and for the same reason: a withheld stack is a stack that can
+   * never re-emit the envelope its standing demand needs. Callers hold the
+   * checkout context, so they resolve the set with `boundFailingCheckNames`
+   * and pass it in; this module stays pure.
+   *
+   * REQUIRED, with no default, on purpose: a defaulted `[]` reads the same
+   * whether the caller inspected the envelopes or never looked, and this seam
+   * exists precisely for EXTERNAL preview producers — the callers most likely
+   * to skip the lookup. Pass the result of `boundFailingCheckNames`; pass `[]`
+   * only to mean "inspected the envelopes and found no bound failure".
+   *
+   * Deliberately visible to `api:check` as a breaking signature change
+   * (pre-1.0, no external callers yet).
+   */
+  vetoedTargets: readonly string[];
+}) => PreviewLifecyclePlan;
+//#endregion
+//#region src/pr-status-hud.d.ts
+type FactoryPrStatusCheckName = "patronage-factory/merge-freeze" | "patronage-factory/pr-ready" | "patronage-factory/pr-verify";
+interface CompletedFactoryCheckSnapshot {
+  readonly completedAt: string;
+  readonly conclusion: string;
+  readonly detailsUrl?: string;
+  readonly headSha: string;
+  readonly name: FactoryPrStatusCheckName;
+}
+interface FailedPreviewSnapshot {
+  readonly completedAt: string;
+  readonly conclusion: string;
+  readonly detailsUrl?: string;
+  readonly headSha: string;
+  readonly name: string;
+}
+interface FactoryPrStatusSources {
+  readonly baseSha: string;
+  readonly checks: Readonly<Partial<Record<FactoryPrStatusCheckName, CompletedFactoryCheckSnapshot>>>;
+  readonly previewFailures?: Readonly<Partial<Record<string, FailedPreviewSnapshot>>>;
+  readonly previewRegistrations: readonly PreviewProofRegistration[];
+}
+interface RenderFactoryPrStatusHudInput extends FactoryPrStatusSources {
+  readonly headSha: string;
+  readonly plan: PreviewLifecyclePlan;
+  readonly planHeadSha: string;
+  readonly pr: number;
+  /** ISO instant at which the presentation sources were observed. */
+  readonly renderedAt: string;
+}
+interface PresentFactoryPrStatusHudInput {
+  readonly headSha: string;
+  readonly owner: string;
+  readonly plan: PreviewLifecyclePlan;
+  readonly planHeadSha: string;
+  readonly pr: number;
+  readonly renderedAt?: string;
+  readonly repo: string;
+}
+interface PresentFactoryPrStatusHudDependencies {
+  /**
+   * Read only `previewProofInventory.list` registrations and completed,
+   * Factory-App-owned check snapshots. PR comment bodies are not an evidence
+   * source and are deliberately absent from this contract.
+   */
+  readonly readSources: (input: {
+    headSha: string;
+    owner: string;
+    pr: number;
+    previewTargets?: readonly string[];
+    repo: string;
+  }) => Promise<FactoryPrStatusSources>;
+  /** Recheck both PR endpoints immediately before mutating the sticky HUD. */
+  readonly assertCurrentIdentity: (input: {
+    baseSha: string;
+    headSha: string;
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => Promise<void>;
+  readonly upsert?: typeof upsertFactoryPrStatusComment;
+}
+interface ReadFactoryPrStatusSourcesInput {
+  readonly headSha: string;
+  /**
+   * Read token for `previewProofInventory.list`. The list walks the
+   * force-push timeline, which needs commit (contents) read; the Factory App
+   * token has no contents permission, so pass a workflow `GITHUB_TOKEN`
+   * (#825). Falls back to `token`.
+   */
+  readonly inventoryToken?: string;
+  readonly owner: string;
+  readonly pr: number;
+  /**
+   * Demanded preview stack names from the lifecycle plan. Used only to look up
+   * a completed unsuccessful check run when inventory has no registration.
+   */
+  readonly previewTargets?: readonly string[];
+  readonly repo: string;
+  /** Factory App installation token, normally minted by the presentation job. */
+  readonly token: string;
+}
+interface ReadFactoryPrStatusSourcesDependencies {
+  readonly fetch?: typeof fetch;
+  readonly listPreviewRegistrations?: (input: {
+    owner: string;
+    pr: number;
+    repo: string;
+    token: string;
+  }) => Promise<readonly PreviewProofRegistration[]>;
+  readonly timeoutMs?: number;
+}
+declare function renderFactoryPrStatusHud(input: RenderFactoryPrStatusHudInput): string;
+declare function presentFactoryPrStatusHud(input: PresentFactoryPrStatusHudInput, dependencies: PresentFactoryPrStatusHudDependencies): Promise<UpsertFactoryPrStatusCommentResult>;
+declare function assertFactoryPrStatusIdentity(input: ReadFactoryPrStatusSourcesInput & {
+  readonly baseSha: string;
+}, dependencies?: ReadFactoryPrStatusSourcesDependencies): Promise<void>;
+declare function readFactoryPrStatusSources(input: ReadFactoryPrStatusSourcesInput, dependencies?: ReadFactoryPrStatusSourcesDependencies): Promise<FactoryPrStatusSources>;
+interface PlanFactoryPrStatusHudInput {
+  readonly cwd: string;
+  readonly headSha: string;
+  readonly mergeBaseSha?: string;
+  readonly patchId?: string;
+  readonly profilePath?: string;
+}
+/**
+ * Consume `planPreviewLifecycle` for the current checkout. No second plan is
+ * invented: dispositions are Ready/Skipped from `deploy` vs `not-required`.
+ * Candidate identity is never copied from the proof. Absent independent
+ * identity or an unbound verify proof is the planner's conservative path.
+ */
+declare function planFactoryPrStatusHud(input: PlanFactoryPrStatusHudInput): PreviewLifecyclePlan;
+interface RefreshFactoryPrStatusHudInput {
+  readonly cwd: string;
+  readonly headSha: string;
+  readonly mergeBaseSha?: string;
+  readonly owner: string;
+  readonly patchId?: string;
+  readonly pr: number;
+  readonly profilePath?: string;
+  readonly repo: string;
+  readonly token?: string;
+}
+/** Plan from the checkout and present the App-owned HUD. */
+declare function refreshFactoryPrStatusHud(input: RefreshFactoryPrStatusHudInput): Promise<UpsertFactoryPrStatusCommentResult>;
+/**
+ * Presentation must not fail an admission gate. Used after pr:ready publishes
+ * its check so the table is not stuck at first-write.
+ */
+declare function refreshFactoryPrStatusHudSafely(input: RefreshFactoryPrStatusHudInput, onNotice?: (message: string) => void): Promise<void>;
+//#endregion
+//#region src/pr-ready.d.ts
+interface PrReadyArgs extends LoadProjectProfileInput {
+  authoringSessionIds?: string[];
+  base: string;
+  epic?: number;
+  json?: boolean;
+  output?: string;
+  report?: boolean;
+  pr: number;
+  reviewProof?: string;
+  throwWhenBlocked?: boolean;
+  verifyProof?: string;
+}
+interface GitHubPullRequest {
+  /**
+   * GitHub's live auto-merge enablement, or `null` when nothing is scheduled.
+   *
+   * Required, not optional (#515 review). `gh pr view --json autoMergeRequest`
+   * always returns the key — explicitly `null` when nothing is scheduled — and
+   * errors loudly on a field name it does not know, so there is no shape where
+   * the real CLI omits it. But `fetchPullRequest` is injectable, and an
+   * implementation that left the field out would silently disable the
+   * `boundary-wave` refusal that stops an epicless run from greening a
+   * candidate GitHub is already scheduled to merge. Requiring it makes the
+   * compiler enforce what `gh` already promises.
+   */
+  autoMergeRequest: {
+    enabledAt?: string;
+  } | null;
+  baseRefName: string;
+  baseRefOid: string;
+  body: string;
+  headRefName?: string;
+  headRefOid: string;
+  isDraft: boolean;
+  mergeStateStatus: string;
+  mergeable: string;
+  number: number;
+  reviewDecision: string | null;
+  statusCheckRollup?: StatusCheckRollup[];
+  title: string;
+  unresolvedReviewThreads: number;
+  url: string;
+}
+interface PrReadyProof {
+  schemaVersion: 3;
+  /**
+   * What GitHub actually did when this run armed native auto-merge (#477).
+   * Present exactly when a ready wave authorizes machine merge and arming ran;
+   * read back from the PR rather than inferred from the invocation, because `gh pr merge
+   * --auto` arms, merges, or does nothing with the same exit code and the same
+   * empty output. `not-armed` means the candidate is admitted but nothing will
+   * merge it, and `followUp` carries the re-dispatch.
+   */
+  arming?: {
+    detail?: string;
+    headSha: string;
+    outcome: "armed" | "merged" | "not-armed";
+  };
+  /**
+   * Why this run blocked, one entry per refusing demand (#391): `code` is the
+   * demand key from the resolver's vocabulary, `detail` the one-sentence
+   * refusal. Same refusals as `blockingReasons`, in the same order — the
+   * analyzable projection of a flat string list, so a wall of blocked proofs
+   * on one PR can be counted by cause. Absent when nothing blocked.
+   */
+  blockedReasons?: BlockedReason[];
+  blockingReasons: string[];
+  humanBlockingReasons: string[];
+  command: "patronage-factory pr:ready";
+  /**
+   * Machine-safe arg array for the obvious next action (#523): when `ready`
+   * but arming did not take effect, a `pr:ready` re-dispatch (idempotent on
+   * an unchanged head); otherwise the `gh pr ready` undraft repair or the
+   * `pr:verify` re-run that the blocking reasons name (re-verify the head,
+   * then re-run pr:ready). Same `argv` shape `factory:delegate --print`
+   * emits. Optional and purely additive.
+   */
+  followUp?: FollowUpAction;
+  /**
+   * `ledger.headSha` is the evaluated head SHA: the GitHub `pr.headRefOid`
+   * captured at evaluation time (not a local git read), recorded explicitly
+   * so merge-time identity checks are a pure comparison against the live
+   * pushed HEAD, not a re-derivation. See the ledger schema.
+   */
+  ledger: ManagedReadinessLedger;
+  /**
+   * Actionable facts that did not block (#477): a settling merge-freeze
+   * generation that permitted readiness and any authorized arming with a
+   * notice, an admitted-but-unscheduled false boundary wave, and how each
+   * waived demand reads to a human. Absent when there are none.
+   */
+  notices?: string[];
+  /** Committed profile blob evaluated by readiness. Required for merge. */
+  profileBlobSha?: string;
+  /** Checkout-relative committed profile path evaluated by readiness. */
+  profilePath?: string;
+  repairs: ReadinessRepair[];
+  /** Trusted checkout repository used for all GitHub reads and writes. */
+  repository?: string;
+  status: ReadinessStatus;
+  /**
+   * Demands that were in force, were NOT met, and were waived by the operator
+   * (#354, moved here from the merge-time proof by #477). Each entry carries
+   * the demand's refusals verbatim, so a waived demand can never read as a met
+   * one; readiness proceeds on the recorded operator act, not on evidence.
+   */
+  waivedDemands?: WaivedDemand[];
+}
+interface PrReadyDependencies {
+  /**
+   * Arms GitHub native auto-merge only for a passing boundary wave that
+   * authorizes machine merge (#477). Defaults to the real `gh pr merge --auto`
+   * call plus the read-back that says what actually happened.
+   */
+  armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
+  github?: {
+    fetchClosingPullRequests?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => {
+      number: number;
+    }[];
+    fetchIssueBody?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => string;
+    fetchPullRequest: (input: {
+      owner: string;
+      repo: string;
+      pr: number;
+    }) => GitHubPullRequest;
+  };
+  git?: PrReadyGitDependencies;
+  hq?: HqIngestDependencies;
+  /**
+   * The authoritative merge-freeze reader (#477). Defaults to the pinned-App
+   * GitHub check-run authority — readiness is a control, so an absent
+   * dependency must not mean an unread freeze.
+   */
+  mergeFreeze?: Pick<MergeFreezeAuthority, "readGeneration">;
+  /**
+   * Awaited publication of the branded check, which is a source-pinned
+   * required check rather than a mirror (#477). Returns true only when the
+   * App-owned run landed. Defaults to `ensureFactoryCheckRunPublished`.
+   *
+   * `pr:ready` has no other publication seam, and this one cannot express a
+   * non-terminal run (#526): `status` is omitted from the input, so every run
+   * readiness creates is completed with a conclusion. A `pr:ready` invocation
+   * therefore cannot leave a run holding the source-pinned required check
+   * open, which is a permanent block on the pull request (#524).
+   */
+  publishFinalCheckRun?: (input: Omit<PublishFactoryCheckInput, "status"> & {
+    conclusion: "failure" | "success";
+  }) => Promise<boolean> | boolean;
+  /**
+   * Re-present the App-owned HUD after this run's ready check is published
+   * so the table is not stuck at first-write. Defaults to a safe refresh
+   * that never fails the gate.
+   */
+  presentStatusHud?: (input: RefreshFactoryPrStatusHudInput) => Promise<void> | void;
+  /** Injectable delay for the UNKNOWN-mergeable brief poll (tests). */
+  sleep?: (ms: number) => Promise<void>;
+}
+interface PrReadyGitDependencies {
+  canResolveCommit: (cwd: string, sha: string) => boolean;
+  changedFiles: (cwd: string, base: string, headSha?: string) => string[];
+  checkoutRepository: (cwd: string) => CheckoutRepository;
+  currentHeadSha: (cwd: string) => string;
+  mergeBaseSha: (cwd: string, base: string) => string;
+  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  resolveCommitSha: (cwd: string, ref: string) => string | undefined;
+  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  stablePatchId: (cwd: string, base: string) => string;
+}
+declare function validatePrReadyProof(value: unknown): PrReadyProof;
+declare function readPrReadyProof(filePath: string): PrReadyProof;
+declare function runPrReady(args: PrReadyArgs, dependencies?: PrReadyDependencies): Promise<PrReadyProof>;
+//#endregion
+//#region src/required-check-policy.d.ts
+declare const EVIDENCE_CHECK_TYPES: readonly ["review", "verify"];
+type EvidenceCheckType = (typeof EVIDENCE_CHECK_TYPES)[number];
+declare const requiredCheckScopeSchema: z.ZodObject<{
+  classifications: z.ZodArray<z.ZodEnum<{
+    "docs/process-only": "docs/process-only";
+    trivial: "trivial";
+    "non-trivial": "non-trivial";
+  }>>;
+}, z.core.$strict>;
+type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
+interface RequiredCheckScopeContext {
+  catchUpRecognition?: CatchUpRecognition;
+  classification: DiffClassification | undefined;
+  impactStamp?: ImpactStamp;
+}
+interface ScopeDecision {
+  inScope: boolean;
+  reason: string;
+}
+declare const requiredCheckInScope: ({
+  context,
+  scope
+}: {
+  context: RequiredCheckScopeContext;
+  scope?: RequiredCheckScope;
+}) => ScopeDecision;
+interface RequiredCheck {
+  name: string;
+  checkType: EvidenceCheckType;
+  scope?: RequiredCheckScope;
+}
+//#endregion
+//#region src/factory-session.d.ts
+declare const resolveAuthoringSessionIds: ({
+  override,
+  recorded
+}: {
+  override?: string[];
+  recorded?: string;
+}) => string[];
+declare namespace external_evidence_d_exports {
+  export { EVIDENCE_CHECK_TYPES, EVIDENCE_DIR, EVIDENCE_ENVELOPE_SCHEMA_VERSION, EVIDENCE_REVIEW_RUNGS, EvidenceCandidateIdentity, EvidenceCheckType, EvidenceEnvelope, EvidenceEnvelopeParse, EvidenceReviewRung, IndependenceResult, LoadedEvidenceEnvelope, RequiredCheck, RequiredCheckEvaluation, RequiredCheckEvaluationInput, RequiredCheckOutcome, RequiredCheckScope, RequiredCheckScopeContext, ScopeDecision, boundFailingCheckNames, evaluateRequiredChecks, evidenceBindingFresh, evidenceEnvelopeSchema, evidenceReviewIndependence, loadEvidenceEnvelopes, parseEvidenceEnvelope, requiredCheckInScope, requiredCheckScopeSchema, resolveAuthoringSessionIds };
+}
+declare const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
+declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
+  check: z.ZodString;
+  checkType: z.ZodEnum<{
+    review: "review";
+    verify: "verify";
+  }>;
+  findingsPointer: z.ZodOptional<z.ZodString>;
+  headSha: z.ZodString;
+  mergeBaseSha: z.ZodString;
+  model: z.ZodOptional<z.ZodString>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  patchId: z.ZodString;
+  policyVersion: z.ZodOptional<z.ZodString>;
+  producer: z.ZodString;
+  requestId: z.ZodOptional<z.ZodString>;
+  rung: z.ZodOptional<z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  timestamp: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$loose>;
+declare const evidenceEnvelopeSchema: z.ZodObject<{
+  check: z.ZodString;
+  checkType: z.ZodEnum<{
+    review: "review";
+    verify: "verify";
+  }>;
+  findingsPointer: z.ZodOptional<z.ZodString>;
+  headSha: z.ZodString;
+  mergeBaseSha: z.ZodString;
+  model: z.ZodOptional<z.ZodString>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  patchId: z.ZodString;
+  policyVersion: z.ZodOptional<z.ZodString>;
+  producer: z.ZodString;
+  requestId: z.ZodOptional<z.ZodString>;
+  rung: z.ZodOptional<z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  timestamp: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$loose>;
+type EvidenceEnvelope = z.infer<typeof evidenceEnvelopeBaseSchema>;
+type EvidenceEnvelopeParse = {
+  ok: true;
+  envelope: EvidenceEnvelope;
+} | {
+  ok: false;
+  error: string;
 };
-declare const verificationProofStateFor: ({
-  proof,
-  proofMatchesCurrentDiff,
-  proofPath
-}: {
-  proof?: PrVerifyProof;
-  proofMatchesCurrentDiff?: boolean;
-  proofPath?: string;
-}) => VerificationProofState;
-declare const verificationProofApplicabilityFor: ({
-  docsOnlyDeltaAcceptedSince,
-  explicitProof,
-  files,
-  headSha,
-  currentIdentity,
-  proof,
-  proofPath,
-  proofReadError
-}: {
-  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
-  explicitProof: boolean;
-  files: string[];
+declare const parseEvidenceEnvelope: (raw: unknown) => EvidenceEnvelopeParse;
+interface EvidenceCandidateIdentity {
   headSha: string;
-  currentIdentity?: {
-    patchId: string;
-    mergeBaseSha?: string;
-  };
-  proof?: PrVerifyProof;
-  proofPath?: string;
-  proofReadError?: unknown;
-}) => {
-  fullVerifiedHeadShas: never[];
-  verificationProof: VerificationProofState;
-} | {
-  fullVerifiedHeadShas: string[];
-  verificationProof: {
-    headShas: VerifiedHeadShas;
-    kind: "typed";
-    proof: PrVerifyProof;
-  };
-};
-declare const resolveVerifyProofApplicability: ({
-  proofPath,
-  explicitProof,
-  docsOnlyDeltaAcceptedSince,
-  files,
-  headSha,
-  currentVerifyIdentityForBase,
-  preread
+  patchId: string;
+  mergeBaseSha: string;
+}
+declare const evidenceBindingFresh: ({
+  candidate,
+  envelope
 }: {
-  proofPath: string;
-  explicitProof: boolean;
-  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
-  files: string[];
-  headSha: string;
-  currentVerifyIdentityForBase?: (base: string) => {
-    patchId: string;
-    mergeBaseSha?: string;
-  };
-  preread?: {
-    proof?: PrVerifyProof;
-    error?: unknown;
-  };
-}) => {
-  fullVerifiedHeadShas: never[];
-  verificationProof: VerificationProofState;
+  candidate: EvidenceCandidateIdentity;
+  envelope: EvidenceEnvelope;
+}) => boolean;
+interface IndependenceResult {
+  independent: boolean;
+  reason?: "no-session" | "unknown-authoring-identity" | "same-session";
+}
+declare const evidenceReviewIndependence: ({
+  authoringSessionIds,
+  envelope
+}: {
+  authoringSessionIds: string[];
+  envelope: EvidenceEnvelope;
+}) => IndependenceResult;
+type LoadedEvidenceEnvelope = {
+  ok: true;
+  envelope: EvidenceEnvelope;
+  path: string;
 } | {
-  fullVerifiedHeadShas: string[];
-  verificationProof: {
-    headShas: VerifiedHeadShas;
-    kind: "typed";
-    proof: PrVerifyProof;
-  };
+  check?: string;
+  error: string;
+  ok: false;
+  path: string;
 };
-declare const verificationProofForReadiness: (state: VerificationProofState) => VerificationHeadShas;
-declare const verificationProofBlockingReason: (state: VerificationProofState) => string | undefined;
-//#endregion
-//#region src/retro-envelope.d.ts
 /**
- * Versioned retro envelope schema (epic #27 wave 2, issue #34).
- *
- * One envelope per lane, built at `factory:closeout` and delivered through the
- * typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
- * from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
- * merged). This module is the single source of truth for the v1 wire shape
- * and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}) — producer and consumer
- * alike. HQ imports these exports directly from the Worker-safe
- * `@patronage/software-factory/schemas` subpath
- * (`software-factory-hq/src/contracts/retro-schemas.ts`) instead of
- * maintaining a parallel hand-written copy, so there is exactly one wire
- * contract and no drift-detection machinery is needed (issue #350; formerly
- * a hand-written twin plus a 767-line parity test, #46).
- *
- * DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
- *
- * The two model families use different tokenizers, prices, and accounting
- * conventions, so any token total that spans Claude and GPT is a lie:
- *
- * 1. There is no combined/total token field anywhere in the envelope.
- * 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
- *    cannot smuggle in a third "all"/"combined" slot.
- * 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
- *    (claude is a single flat block keyed on freshInput/cacheReadInput/
- *    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
- *    COUNTS share no key name across families. The residual names shared
- *    between the claude block and a gpt ROLE entry are pinned to exactly
- *    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
- *    USD is the one cross-family summable unit (rule 4); `model` is an
- *    unsummable label; `output` is the same name at DIFFERENT depths (lane
- *    block vs per-role entry), frozen by a tripwire test in
- *    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
- *    is a schemaVersion-2 wire change, deliberately not spent in v1.
- * 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
- *    only, and only as a projection-time sum of per-family USD.
+ * Every check name with a current, candidate-bound FAILING envelope on disk.
  *
- * Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
- * is not prompt size (true input context = freshInput + cacheReadInput +
- * cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
- * already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
- * is the only value safe to feed a per-token pricer.
+ * The wave-3 scoping veto input. Callers pass the resolved set to
+ * `planVerificationBattery` / `planPreviewLifecycle`, which stay pure — the
+ * planners decide, they never read the filesystem.
  *
- * COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
- * `tokenFamilies` may legitimately be absent. The closeout build gate demands
- * a valid envelope, not available telemetry. A families-absent envelope keeps
- * its operator-visible data gaps and is a replayable advisory HQ event, so it
- * never substitutes unavailable usage with zero. The wire shape (field names,
- * types, structure) stays byte-parity with HQ v1.
- */
-declare const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
-declare const retroEnvelopeV1Schema: z.ZodObject<{
-  agentRunId: z.ZodString;
-  archiveRef: z.ZodOptional<z.ZodString>;
-  cycles: z.ZodObject<{
-    gateRunsToFirstGreen: z.ZodNumber;
-    reviewerFixRounds: z.ZodNumber;
-    thermoFixRounds: z.ZodNumber;
-  }, z.core.$strict>;
-  dataGaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
-  gates: z.ZodArray<z.ZodObject<{
-    cycle: z.ZodNumber;
-    duration: z.ZodNumber;
-    gate: z.ZodString;
-    outcome: z.ZodEnum<{
-      pass: "pass";
-      fail: "fail";
-      skip: "skip";
-    }>;
-    startedAt: z.ZodISODateTime;
-  }, z.core.$strict>>;
-  generatedAt: z.ZodISODateTime;
-  interventions: z.ZodObject<{
-    count: z.ZodNumber;
-  }, z.core.$strict>;
-  joinKeys: z.ZodObject<{
-    claudeSessionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    codexThreadIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
-  }, z.core.$strict>;
-  kind: z.ZodLiteral<"retro-envelope">;
-  outcome: z.ZodOptional<z.ZodObject<{
-    status: z.ZodEnum<{
-      success: "success";
-      fail: "fail";
-      blocked: "blocked";
-      "ship-with-followups": "ship-with-followups";
-    }>;
-    verdict: z.ZodOptional<z.ZodString>;
-  }, z.core.$strict>>;
-  phases: z.ZodArray<z.ZodObject<{
-    at: z.ZodISODateTime;
-    deltaSec: z.ZodOptional<z.ZodNumber>;
-    name: z.ZodString;
-  }, z.core.$strict>>;
-  refs: z.ZodObject<{
-    branch: z.ZodOptional<z.ZodString>;
-    epic: z.ZodOptional<z.ZodString>;
-    headSha: z.ZodOptional<z.ZodString>;
-    issue: z.ZodOptional<z.ZodString>;
-    prNumber: z.ZodOptional<z.ZodNumber>;
-  }, z.core.$strict>;
-  repo: z.ZodObject<{
-    name: z.ZodString;
-    owner: z.ZodString;
-  }, z.core.$strict>;
-  schemaVersion: z.ZodLiteral<1>;
-  tokenFamilies: z.ZodObject<{
-    claude: z.ZodOptional<z.ZodObject<{
-      cacheCreationInput: z.ZodNumber;
-      cacheReadInput: z.ZodNumber;
-      costUsd: z.ZodNullable<z.ZodNumber>;
-      family: z.ZodLiteral<"claude">;
-      freshInput: z.ZodNumber;
-      model: z.ZodString;
-      output: z.ZodNumber;
-      requests: z.ZodNumber;
-    }, z.core.$strict>>;
-    gpt: z.ZodOptional<z.ZodObject<{
-      family: z.ZodLiteral<"gpt">;
-      roles: z.ZodArray<z.ZodObject<{
-        cachedInput: z.ZodNumber;
-        costUsd: z.ZodNullable<z.ZodNumber>;
-        freshInputDerived: z.ZodNumber;
-        inputInclusiveOfCache: z.ZodNumber;
-        model: z.ZodString;
-        output: z.ZodNumber;
-        reasoningOutput: z.ZodNumber;
-        role: z.ZodString;
-        threadId: z.ZodOptional<z.ZodString>;
-      }, z.core.$strict>>;
-    }, z.core.$strict>>;
-  }, z.core.$strict>;
-  wallClock: z.ZodObject<{
-    endTs: z.ZodISODateTime;
-    startTs: z.ZodISODateTime;
-    totalSec: z.ZodNumber;
-  }, z.core.$strict>;
-}, z.core.$strict>;
-type RetroEnvelope = z.infer<typeof retroEnvelopeV1Schema>;
-/**
- * Versioned payload validators, keyed by schema major. Unknown majors never
- * reach these — {@link parseRetroEnvelope} returns them raw and marked
- * degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
+ * `checkType` is the caller's, not a guess: schema-v5 requiredChecks are
+ * verify-only (`resolveProfileRequiredChecks`), so a scoping caller passes
+ * `"verify"` and matches exactly the pair wave 2 evaluates.
  */
-declare const RETRO_ENVELOPE_VALIDATORS: Record<number, z.ZodType<RetroEnvelope, unknown>>;
-declare const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS: readonly number[];
-/** The `schemaVersion` a candidate declares, or undefined when unreadable. */
-declare const retroEnvelopeSchemaVersionOf: (candidate: unknown) => number | undefined;
-type ParsedRetroEnvelope = {
-  disposition: "trusted";
-  envelope: RetroEnvelope;
-  schemaVersion: number;
+declare const boundFailingCheckNames: ({
+  candidate,
+  checkType,
+  envelopes
+}: {
+  candidate: EvidenceCandidateIdentity;
+  checkType: EvidenceCheckType;
+  envelopes: LoadedEvidenceEnvelope[];
+}) => string[];
+interface RequiredCheckEvaluationInput {
+  authoringSessionIds: string[];
+  candidate: EvidenceCandidateIdentity;
+  envelopes: LoadedEvidenceEnvelope[];
+  requiredChecks: RequiredCheck[];
+  scopeContext: RequiredCheckScopeContext;
+}
+interface RequiredCheckOutcome {
+  name: string;
+  checkType: EvidenceCheckType;
+  status: "satisfied" | "unmet" | "out-of-scope";
+  inScope: boolean;
+  scopeReason: string;
+  scope?: RequiredCheckScope;
+  reason?: string;
+  matchedPath?: string;
+}
+interface RequiredCheckEvaluation {
+  outcomes: RequiredCheckOutcome[];
+  blockingReasons: string[];
+}
+declare const evaluateRequiredChecks: ({
+  authoringSessionIds,
+  candidate,
+  envelopes,
+  requiredChecks,
+  scopeContext
+}: RequiredCheckEvaluationInput) => RequiredCheckEvaluation;
+declare const EVIDENCE_DIR = ".factory-memory/evidence";
+declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
+//#endregion
+//#region src/review-proof-applicability.d.ts
+declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
+declare const reviewStatusSchema: z.ZodEnum<{
+  "not-required": "not-required";
+  stale: "stale";
+  blocked: "blocked";
+  current: "current";
+  missing: "missing";
+}>;
+type ReviewStatus = z.infer<typeof reviewStatusSchema>;
+interface CurrentReviewIdentity {
+  headSha: string;
+  patchId: string;
+}
+declare const reviewStatus: ({
+  blocked,
+  required,
+  reviewedHeadSha,
+  reviewedPatchId,
+  headSha,
+  patchId
+}: CurrentReviewIdentity & {
+  blocked?: boolean;
+  required: boolean;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+}) => ReviewStatus;
+declare namespace proof_identity_d_exports {
+  export { CurrentReviewIdentity, REVIEW_STATUS_VALUES, ReviewProofClaim, ReviewStatus, explicitFailureIdentity, isExplicitReviewFailure, isUntypedReviewProof, reviewStatus, reviewStatusSchema, selectReviewProof };
+}
+type ReviewProofClaim = {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
 } | {
-  disposition: "degraded";
-  raw: unknown;
-  schemaVersion: number | undefined;
+  explicitFailure: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
 };
-/**
- * Parses a candidate against the versioned validators. A recognized major is
- * validated typed-only (throws on an invalid known-version payload); an unknown
- * major is round-tripped RAW and marked degraded — the retained payload is the
- * exact input object, never a coerced projection. Mirrors the HQ ingest seam so
- * the two sides agree on the skew posture.
- */
-declare const parseRetroEnvelope: (candidate: unknown) => ParsedRetroEnvelope;
-/**
- * Whether harvest recorded at least one token family. This is an operator
- * summary predicate, not a delivery gate: a families-absent envelope remains
- * valid and replayable when its data gaps explain why telemetry is unavailable.
- */
-declare const isRetroEnvelopeWireComplete: (envelope: Pick<RetroEnvelope, "tokenFamilies">) => boolean;
-/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
-declare const retroEpicReference: (refs: RetroEnvelope["refs"]) => string | undefined;
+declare const isExplicitReviewFailure: (proof: ReviewProofClaim) => proof is {
+  explicitFailure: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+};
+declare const isUntypedReviewProof: (proof: ReviewProofClaim) => proof is {
+  untypedVerdict: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+};
+declare const explicitFailureIdentity: (proof: ReviewProofClaim) => {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+};
+declare const selectReviewProof: ({
+  reviewProof
+}: {
+  reviewProof: ReviewProofClaim;
+}) => {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+};
+//#endregion
+//#region src/pr-readiness/review-epoch.d.ts
+interface ReviewCycleState {
+  autoBlockingFindings: number;
+  countsBySeverity: Record<ReviewFindingSeverity, number>;
+  highestBlockingSeverity?: ReviewFindingSeverity;
+  highestOpenSeverity?: ReviewFindingSeverity;
+  maxReviewCycles?: number;
+  nonBlockingFindings: number;
+  openFindings: number;
+  reviewCycle?: number;
+  staleRepeatFindings?: number;
+  windowExhausted: boolean;
+}
+declare const reviewCycleStateFor: (proof: Pick<PrReviewProof, "ladder" | "reviewCycle" | "maxReviewCycles" | "reviews">, policy?: ReviewLadderPolicy, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewCycleState;
+type ReviewAcceptance = "accepted-after-cap" | "accepted-clean" | "accepted-through-ladder" | "blocked";
+declare const resolveReviewAcceptance: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewAcceptance;
+type ReviewTerminalState = "accepted-with-findings" | "blocked" | "clean";
+declare const resolveReviewTerminalStateForEpoch: (proof: PrReviewProof, review: PrReviewResult, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState;
+declare const resolveReviewTerminalState: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewTerminalState;
+declare const resolveReviewTerminalStateAcrossReviews: (proof: PrReviewProof, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState | undefined;
+declare const resolveReviewTerminalStateAcrossReviewsForPolicy: (proof: PrReviewProof, policy: ReviewLadderPolicy) => ReviewTerminalState | undefined;
+declare const reviewProofFor: (proof: PrReviewProof | undefined, kind: PrReviewKind, policy: ReviewLadderPolicy | undefined, current?: {
+  patchId: string;
+}) => ReviewProofClaim;
+declare namespace review_proof_d_exports {
+  export { DEFAULT_PR_REVIEW_MAX_CYCLES, DEFAULT_PR_REVIEW_PROOF_PATH, PR_REVIEW_FINAL_READINESS_NOTICE, PR_REVIEW_FINDING_PROVENANCE_VERSION, PR_REVIEW_PROOF_DESCRIPTOR, PR_REVIEW_SCHEMA_VERSION, PrReviewFinding, PrReviewKind, PrReviewLadderState, PrReviewMode, PrReviewOutcome, PrReviewProof, PrReviewResult, PrReviewStageResolution, REVIEW_SEVERITIES, ReviewAcceptance, ReviewCycleState, ReviewFindingCategory, ReviewFindingSeverity, ReviewTerminalState, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, readPrReviewProof, resolveReviewAcceptance, resolveReviewTerminalState, resolveReviewTerminalStateAcrossReviews, resolveReviewTerminalStateAcrossReviewsForPolicy, resolveReviewTerminalStateForEpoch, reviewCycleStateFor, reviewProofFor, validatePrReviewProof, validatePrReviewResult };
+}
+declare const PR_REVIEW_SCHEMA_VERSION = 2;
+declare const PR_REVIEW_FINDING_PROVENANCE_VERSION = 1;
+declare const DEFAULT_PR_REVIEW_PROOF_PATH = ".factory-memory/pr-review.json";
+declare const DEFAULT_PR_REVIEW_MAX_CYCLES = 5;
+declare const PR_REVIEW_FINAL_READINESS_NOTICE = "pr:review is a final readiness proof gate. Run it after local verification and avoid repeated full runs unless the review proof records actionable findings. Default review window: 5 cycles.";
+declare const prReviewFindingSchema: z.ZodType<PrReviewFinding>;
+declare const prReviewResultSchema: z.ZodType<PrReviewResult>;
+declare const prReviewProofSchema: z.ZodType<PrReviewProof>;
+declare const validatePrReviewResult: (value: unknown) => PrReviewResult;
+declare const validatePrReviewProof: (value: unknown) => PrReviewProof;
+declare const readPrReviewProof: (filePath: string) => PrReviewProof;
+declare const PR_REVIEW_PROOF_DESCRIPTOR: ProofDescriptor<PrReviewProof>;
 //#endregion
 //#region src/schemas.d.ts
 declare const boundaryCheckProofSchema: z.ZodObject<{
@@ -2328,24 +2566,18 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
     value: z.ZodString;
   }, z.core.$strip>>;
   status: z.ZodEnum<{
-    blocked: "blocked";
     ready: "ready";
+    blocked: "blocked";
   }>;
 }, z.core.$strip>;
 type BoundaryCheckProofRecord = z.infer<typeof boundaryCheckProofSchema>;
 //#endregion
 //#region src/boundary-check.d.ts
-interface BoundaryPullRequestRef {
-  headRefOid?: string;
-  mergeCommitOid?: string;
-  number: number;
-  state: "OPEN" | "CLOSED" | "MERGED";
-}
 interface BoundaryCheckGithub {
   fetchIssueBody: (repo: string, issue: number) => string;
   fetchIssueComments: (repo: string, issue: number) => GithubIssueComment[];
   fetchClosingPullRequests: (repo: string, issue: number) => BoundaryPullRequestRef[];
-  fetchPullRequest: (repo: string, pr: number) => BoundaryPullRequestRef;
+  fetchPullRequest?: (repo: string, pr: number) => BoundaryPullRequestRef;
 }
 interface BoundaryCheckArgs {
   cwd?: string;
@@ -2362,7 +2594,7 @@ interface BoundaryCheckDependencies {
 declare function runBoundaryCheck(args: BoundaryCheckArgs, dependencies?: BoundaryCheckDependencies): BoundaryCheckProofRecord;
 declare function validateBoundaryCheckProof(value: unknown): BoundaryCheckProofRecord;
 //#endregion
-//#region src/commands/doctor.d.ts
+//#region src/cli-output.d.ts
 interface CliOutput {
   stderr: Pick<NodeJS.WriteStream, "write">;
   stdout: Pick<NodeJS.WriteStream, "write">;
@@ -2410,32 +2642,6 @@ declare const runDemandWaive: (args: DemandWaiveArgs, dependencies?: DemandWaive
 //#region src/commands/demand-waive.d.ts
 type DemandWaiveAction = (args: DemandWaiveArgs) => DemandWaiver;
 //#endregion
-//#region src/hq-credentials.d.ts
-/**
- * Why a reference did not resolve. Each value names a different remedy, and
- * none of them can be inferred from a value-or-nothing result:
- *
- * - `resolver-missing` — no secret-manager binary on PATH.
- * - `resolver-blocked` — a binary exists but this session may not execute it
- *   (a sandbox denying exec). The command belongs outside the sandbox.
- * - `resolver-timeout` — the probe expired: a desktop agent waiting on an
- *   approval nobody can give here.
- * - `resolver-refused` — the binary ran and produced no value. Its store is
- *   unreachable from this session (a sandbox with no keychain access) or the
- *   reference is not readable. These two stay one status on purpose: telling
- *   them apart would mean reading resolver output.
- */
-type SecretResolutionFailure = "resolver-blocked" | "resolver-missing" | "resolver-refused" | "resolver-timeout";
-/** A structured resolution outcome. The value travels only when resolved. */
-type SecretResolution = {
-  status: "resolved";
-  value: string;
-} | {
-  status: SecretResolutionFailure;
-};
-/** Resolves a secret reference. Injected so tests stay offline. */
-type SecretReferenceResolver = (reference: string) => SecretResolution;
-//#endregion
 //#region src/hq-flush.d.ts
 /**
  * Spool locations this run did not drain because they sit under an earlier
@@ -2459,6 +2665,19 @@ type HqFlushResult = (HqFlushOrphans & {
   status: "flushed";
 });
 //#endregion
+//#region src/catch-up-recognition.d.ts
+type CatchUpRecognitionResult = {
+  recognition: CatchUpRecognition;
+  recognized: true;
+} | {
+  reasons: string[];
+  recognized: false;
+};
+type CatchUpRecognizer = (input: {
+  base: string;
+  cwd: string;
+}) => CatchUpRecognitionResult;
+//#endregion
 //#region src/pr-review.d.ts
 interface PrReviewArgs extends LoadProjectProfileInput {
   base: string;
@@ -2474,13 +2693,13 @@ interface PrReviewGitDependencies {
   changedFiles: (cwd: string, base: string) => string[];
   currentHeadSha: (cwd: string) => string;
   isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
+  recognizeCatchUp?: CatchUpRecognizer;
   stablePatchId: (cwd: string, base: string) => string;
   statusPorcelain: (cwd: string) => string;
 }
 interface PrReviewDependencies {
   git?: PrReviewGitDependencies;
   hq?: HqIngestDependencies;
-  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
 declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
 //#endregion
@@ -2493,7 +2712,7 @@ interface CleanInstallResolutionDependencies {
 }
 //#endregion
 //#region src/pr-verify.d.ts
-type PrVerifyMode = "auto" | "docs-only" | "trivial" | "full";
+type PrVerifyMode = "auto" | "docs-only" | "full";
 interface VerificationCommandOutcome {
   counts?: {
     testFiles?: number;
@@ -2514,6 +2733,7 @@ interface PrVerifyGitDependencies {
   currentHeadSha: (cwd: string) => string;
   emptyTreeHash: (cwd: string) => string;
   mergeBaseSha: (cwd: string, base: string) => string;
+  recognizeCatchUp?: CatchUpRecognizer;
   runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
   showFileAtRef?: (cwd: string, ref: string, absolutePath: string) => string | undefined;
   statusPorcelain: (cwd: string) => string;
@@ -2702,6 +2922,28 @@ type PrReadyAction = (args: PrReadyArgs) => Promise<unknown>;
 //#region src/commands/pr-review.d.ts
 type PrReviewAction = (args: PrReviewArgs) => Promise<unknown>;
 //#endregion
+//#region src/pr-status-hud-command.d.ts
+interface PrStatusHudArgs {
+  readonly cwd: string;
+  readonly headSha: string;
+  /**
+   * Read token for the preview-proof inventory list. The App token cannot
+   * read the force-push timeline (no contents permission), so the workflow
+   * `GITHUB_TOKEN` serves that read (#825).
+   */
+  readonly inventoryToken?: string;
+  readonly owner: string;
+  readonly planPath?: string;
+  readonly pr: number;
+  readonly repo: string;
+  readonly token: string;
+}
+type PrStatusHudAction = (args: PrStatusHudArgs) => Promise<{
+  action: string;
+  commentId: number;
+  url: string;
+}>;
+//#endregion
 //#region src/packages/trace/implementation/core.d.ts
 declare const FactoryTraceEnvelopeCoreSchema: z.ZodObject<{
   createdAt: z.ZodString;
@@ -2846,6 +3088,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   patchId: z.ZodString;
   reason: z.ZodEnum<{
     "no-applicable-mode": "no-applicable-mode";
+    "faithful-merge": "faithful-merge";
   }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>, readonly [z.ZodObject<{
@@ -2868,6 +3111,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   patchId: z.ZodString;
   reason: z.ZodEnum<{
     "no-applicable-mode": "no-applicable-mode";
+    "faithful-merge": "faithful-merge";
   }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>], {
@@ -2881,6 +3125,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     patchId: z.ZodString;
     reason: z.ZodEnum<{
       "no-applicable-mode": "no-applicable-mode";
+      "faithful-merge": "faithful-merge";
     }>;
     reviewCycle: z.ZodNumber;
   }, z.core.$strict>;
@@ -2898,7 +3143,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: string;
   outcome: "not-required";
   patchId: string;
-  reason: "no-applicable-mode";
+  reason: "no-applicable-mode" | "faithful-merge";
   reviewCycle: number;
   issue?: number | undefined;
   pr?: number | undefined;
@@ -3699,74 +3944,6 @@ declare const scanFactoryTraceDiagnostics: ({
   repoRoot,
   to
 }: ScanFactoryTraceDiagnosticsOptions) => FactoryTraceDiagnostic[];
-//#endregion
-//#region src/interior-telemetry/gate-timing.d.ts
-declare const GATE_TIMING_SCHEMA_VERSION = 1;
-type FactoryGateName = "boundary:check" | "factory:closeout" | "pr:ready" | "pr:review" | "pr:verify";
-type GateTimingOutcome = "fail" | "pass";
-interface GateTimingRecord {
-  agentRunId: string;
-  cycle: number;
-  durationMs: number;
-  gate: FactoryGateName;
-  outcome: GateTimingOutcome;
-  schemaVersion: typeof GATE_TIMING_SCHEMA_VERSION;
-  startedAt: string;
-  startOffsetMs: number;
-}
-//#endregion
-//#region src/retro-envelope-builder.d.ts
-/**
- * Folds a lane's gate-timing ledger (`.factory-memory/gate-timing/<id>.jsonl`,
- * wave-1 PR #33) into a versioned retro envelope at `factory:closeout`.
- *
- * STRUCTURAL INVARIANT (#677 repeat-class rule; PR #35 review cycles 1-2):
- * telemetry CONTENT can never fail the closeout build gate. Every value that
- * reaches the envelope passes through one sanitization seam that makes the
- * output valid BY CONSTRUCTION:
- *
- * - strings are clamped to their wire bounds (truncated, with a data gap when
- *   truncation lost information);
- * - numbers must be finite and within plausibility bounds BEFORE any derived
- *   arithmetic; an absurd value (1e16 ms duration, year-9999 timestamp) SKIPS
- *   its record with a data gap rather than clamping, because clamping would
- *   assert a measurement that never happened;
- * - arrays are bounded to their schema maxima (gates[] keeps the most recent);
- * - derived computations (wall clock, cycles) consume only sanitized inputs,
- *   so no ledger content can push them outside Date/Number safe ranges.
- *
- * Terminal backstop: the assembled candidate goes through a final schema
- * parse; if that still fails, a minimal-valid envelope (clamped identity,
- * empty gates, a data gap naming the failure) is built and returned instead.
- * `buildRetroEnvelope` therefore never throws for content — the closeout gate
- * can only fail on filesystem errors when persisting.
- */
-interface BuildRetroEnvelopeInput {
-  agentRunId: string;
-  /** Optional pointer (key/URL) to #8's durable proof archive — never payload. */
-  archiveRef?: string;
-  dataGaps?: string[];
-  generatedAt: Date;
-  interventions?: number;
-  /** Per-family session identities the lane already records. */
-  joinKeys?: {
-    claudeSessionIds?: string[];
-    codexThreadIds?: string[];
-  };
-  /** The lane's gate-timing ledger records, in append order. */
-  ledger: GateTimingRecord[];
-  outcome?: RetroEnvelope["outcome"];
-  phases?: RetroEnvelope["phases"];
-  refs: RetroEnvelope["refs"];
-  repo: RetroEnvelope["repo"];
-  /**
-   * Token families. They may be absent when native session data is unavailable
-   * (valid does not imply available telemetry). When present they satisfy the
-   * family invariants.
-   */
-  tokenFamilies?: RetroEnvelope["tokenFamilies"];
-}
-declare const buildRetroEnvelope: (input: BuildRetroEnvelopeInput) => RetroEnvelope;
 declare namespace comment_provenance_d_exports {
   export { SHA_MATCH_MIN_LENGTH, isBotLogin, sameHeadSha };
 }
@@ -3776,18 +3953,12 @@ declare const sameHeadSha: (left: string, right: string) => boolean;
 //#endregion
 //#region src/doctor-hq-checks.d.ts
 /**
- * Two `doctor` checks that make silent HQ delivery failure loud (#394,
- * epic #389 wave 2).
- *
- * Both consume #414's structured credential resolution rather than inventing
- * a second classification: a sandboxed session that cannot reach the
- * keychain is reported as "cannot resolve credentials here", never as
- * "credentials are wrong" or a silent pass. Both name `psf hq:flush` and
- * `psf pr:publish` as the commands that need a trusted local session.
+ * The `doctor` check that makes silent HQ delivery failure loud (#394,
+ * epic #389 wave 2): the local spool is empty, and no stranded evidence is
+ * waiting under the spool root.
  *
- * Advisory stays advisory: neither check can block anything but doctor's own
- * exit status (epic #389 design decision 4). Absent credentials make the
- * remote check a skip with a printed reason, never a silent pass.
+ * Advisory stays advisory: this check can block nothing but doctor's own exit
+ * status (epic #389 design decision 4).
  */
 type DoctorCheckStatus = "error" | "ok" | "warning";
 interface DoctorCheck {
@@ -3799,12 +3970,6 @@ interface HqSpoolCheckDependencies {
   countSpool?: typeof countHqSpoolWork;
   sweepOrphans?: typeof sweepHqSpoolOrphans;
 }
-interface HqRetroReadbackCheckDependencies {
-  fetch?: typeof fetch;
-  readFile?: typeof readFile;
-  resolve?: SecretReferenceResolver;
-  timeoutMs?: number;
-}
 //#endregion
 //#region src/doctor.d.ts
 interface DoctorReport {
@@ -3823,8 +3988,6 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   base?: string;
   env?: NodeJS.ProcessEnv;
   /** Test seam for the local HQ spool check (#394); production never sets this. */
-  hqRetroReadbackDependencies?: HqRetroReadbackCheckDependencies;
-  /** Test seam for the remote HQ retro-envelope read-back check (#394). */
   hqSpoolDependencies?: HqSpoolCheckDependencies;
   /**
    * Append the read-only admission checklist (#292): every requirement this
@@ -3913,98 +4076,6 @@ declare const renderPrBodySections: ({
   reviewProof?: PrReviewProof;
   verifyProof?: PrVerifyProof;
 }) => string;
-declare namespace boundary_manifest_d_exports {
-  export { BOUNDARY_CLOSEOUT_DEFAULT_RUNG, BOUNDARY_MANIFEST_SCHEMA_VERSION, BoundaryManifest, BoundaryManifestExtraction, BoundaryManifestParse, FACTORY_BOUNDARY_FENCE_LANG, boundaryManifestSchema, closeoutRungFor, extractBoundaryManifestBlock, manifestContentHash, parseBoundaryManifest, rungMeetsMinimum, specContentHash };
-}
-declare const FACTORY_BOUNDARY_FENCE_LANG = "factory-boundary";
-declare const BOUNDARY_MANIFEST_SCHEMA_VERSION = 1;
-declare const BOUNDARY_CLOSEOUT_DEFAULT_RUNG: EvidenceReviewRung;
-declare const rungMeetsMinimum: (rung: EvidenceReviewRung, minimum: EvidenceReviewRung) => boolean;
-declare const boundaryManifestBaseSchema: z.ZodObject<{
-  boundary: z.ZodString;
-  closeout: z.ZodOptional<z.ZodObject<{
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-  declaredBy: z.ZodString;
-  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  schemaVersion: z.ZodLiteral<1>;
-  topology: z.ZodEnum<{
-    flagged: "flagged";
-    "each-to-main": "each-to-main";
-    stacked: "stacked";
-  }>;
-  waves: z.ZodArray<z.ZodObject<{
-    autoMerge: z.ZodOptional<z.ZodBoolean>;
-    issues: z.ZodArray<z.ZodNumber>;
-    name: z.ZodString;
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
-declare const boundaryManifestSchema: z.ZodObject<{
-  boundary: z.ZodString;
-  closeout: z.ZodOptional<z.ZodObject<{
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-  declaredBy: z.ZodString;
-  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  schemaVersion: z.ZodLiteral<1>;
-  topology: z.ZodEnum<{
-    flagged: "flagged";
-    "each-to-main": "each-to-main";
-    stacked: "stacked";
-  }>;
-  waves: z.ZodArray<z.ZodObject<{
-    autoMerge: z.ZodOptional<z.ZodBoolean>;
-    issues: z.ZodArray<z.ZodNumber>;
-    name: z.ZodString;
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
-type BoundaryManifest = z.infer<typeof boundaryManifestBaseSchema>;
-type BoundaryManifestExtraction = {
-  ok: true;
-  blockText: string;
-} | {
-  ok: false;
-  error: string;
-};
-declare const extractBoundaryManifestBlock: (issueBody: string) => BoundaryManifestExtraction;
-declare const manifestContentHash: (blockText: string) => string;
-declare const specContentHash: (issueBody: string) => string;
-type BoundaryManifestParse = {
-  ok: true;
-  manifest: BoundaryManifest;
-  manifestHash: string;
-} | {
-  ok: false;
-  error: string;
-};
-declare const parseBoundaryManifest: (issueBody: string) => BoundaryManifestParse;
-declare const closeoutRungFor: (manifest: BoundaryManifest) => EvidenceReviewRung;
-//#endregion
-//#region src/demand-resolution.d.ts
-/** The boundary-manifest wave demand that applies to one pull request. */
-interface WaveReviewDemand {
-  autoMerge: boolean;
-  review: EvidenceReviewRung;
-  wave: string;
-}
 declare namespace readiness_evaluation_d_exports {
   export { CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON, DRAFT_BLOCKER_REASON, EvaluationInput, ManagedReadinessLedger, PENDING_CHECKS_BLOCKER_REASON_PREFIX, READINESS_REPAIR_CODES, ReadinessRepair, ReadinessStatus, SCHEMA_VERSION, SECURITY_UNTYPED_REVIEW_BLOCKER_REASON, evaluateReadiness, managedReadinessLedgerSchema, readinessExitCode, readinessRepairSchema, validateManagedReadinessLedger };
 }
@@ -4056,7 +4127,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
   ledger: {
     baseSha: string;
     blockingReasons: string[];
-    classification: "trivial" | "docs/process-only" | "non-trivial";
+    classification: "docs/process-only" | "trivial" | "non-trivial";
     github: {
       draft: boolean;
       mergeStateStatus: string;
@@ -4076,13 +4147,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4090,7 +4161,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     schemaVersion: 1;
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "passed" | "stale" | "missing";
+      prVerify: "stale" | "passed" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;
@@ -4105,7 +4176,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
       status: "satisfied" | "unmet" | "out-of-scope";
       reason?: string | undefined;
       scope?: {
-        classifications: ("trivial" | "docs/process-only" | "non-trivial")[];
+        classifications: ("docs/process-only" | "trivial" | "non-trivial")[];
       } | undefined;
     }[] | undefined;
     mergeBaseSha?: string | undefined;
@@ -4458,6 +4529,34 @@ declare const appendReviewLadderStageTraceEvent: ({
 }) => AppendFactoryTraceEventResult;
 declare const tryAppendReviewLadderStageTraceEvent: (input: Parameters<typeof appendReviewLadderStageTraceEvent>[0]) => ReviewLadderStageTraceWriteResult;
 //#endregion
+//#region src/verification-run-context.d.ts
+declare const FACTORY_BASE_REF_ENV = "FACTORY_BASE_REF";
+declare const FACTORY_CHANGED_FILES_ENV = "FACTORY_CHANGED_FILES";
+declare const FACTORY_CHANGED_FILES_FILE_ENV = "FACTORY_CHANGED_FILES_FILE";
+declare const EMPTY_TREE_OBJECT_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+declare const DEFAULT_ROOT_SHARED_GLOBS: string[];
+interface VerificationRunContextInput {
+  baseRef: string;
+  changedFiles: string[];
+  fullSuiteBaseRef?: string;
+  rootSharedGlobs?: string[];
+  inlineLimitBytes?: number;
+  tmpDir?: string;
+}
+interface VerificationEnv {
+  env: Record<string, string>;
+  cleanup: () => void;
+}
+interface VerificationRunContext {
+  readonly baseRef: string;
+  readonly changedFiles: string[];
+  readonly forcesFullSuite: boolean;
+  readonly fullSuiteReasons: string[];
+  buildEnv: () => VerificationEnv;
+  runSummaryLines: () => string[];
+}
+declare function createVerificationRunContext(input: VerificationRunContextInput): VerificationRunContext;
+//#endregion
 //#region src/verification-battery.d.ts
 type BatteryDisposition = "executed" | "not-required";
 /**
@@ -4535,92 +4634,6 @@ declare const planVerificationBattery: <Command extends BatteryCandidateCommand>
 /** Console lines naming every withheld command and why. Never silent. */
 declare const batteryScopeSummaryLines: (plan: VerificationBatteryPlan<BatteryCandidateCommand>) => string[];
 //#endregion
-//#region src/preview-lifecycle.d.ts
-type PreviewDisposition = "deploy" | "not-required";
-interface PreviewTargetPlan {
-  basis: string;
-  disposition: PreviewDisposition;
-  name: string;
-}
-interface PreviewLifecyclePlan {
-  /** The declared preview stacks to deploy, in declaration order. */
-  deploy: string[];
-  /** The withheld stacks, in declaration order. */
-  notRequired: PreviewTargetPlan[];
-  /** Whether a trusted, identity-bound stamp was available at all. */
-  stampTrusted: boolean;
-  /** Every declared preview target with its disposition, in declaration order. */
-  targets: PreviewTargetPlan[];
-}
-/**
- * Structural subset of the profile: the impact declarations plus the external
- * demand list. Structural rather than a `Pick` so this module does not import
- * `profile.ts`.
- */
-interface PreviewLifecycleProfile {
-  impact?: {
-    targets: {
-      name: string;
-    }[];
-  };
-  requiredChecks?: {
-    name: string;
-  }[];
-}
-/**
- * The declared preview stacks: impact targets that are ALSO declared required
- * checks — i.e. targets whose proof is produced externally, which is exactly
- * what a preview producer is.
- *
- * Deriving the list from the two existing declarations rather than adding a
- * third is what makes lifecycle and demand unable to disagree: the stacks this
- * plan can withhold are precisely the demands wave 2 can release, so a stack
- * can never be skipped while its proof stays demanded.
- */
-declare const previewLifecycleTargets: (profile: PreviewLifecycleProfile) => string[];
-/**
- * Plan the preview lifecycle for one candidate.
- *
- * Trust is resolved here through the SAME identity gate demand release uses
- * (`trustedImpactStamp`): the proof must have passed and must bind both the
- * candidate's headSha and its patchId. A stale, aborted, absent, or
- * differently-bound proof yields no stamp, and every declared stack is planned
- * for deploy. Total over its INPUTS — no proof, stamp, or profile can make it
- * throw. A malformed CALL is the deliberate exception: omitting
- * `vetoedTargets` is API misuse, not data doubt, and throws.
- */
-declare const planPreviewLifecycle: ({
-  candidate,
-  profile,
-  proof,
-  vetoedTargets
-}: {
-  candidate: {
-    headSha: string;
-    patchId: string;
-  };
-  profile: PreviewLifecycleProfile;
-  proof: PrVerifyProof | undefined;
-  /**
-   * Stack names with a current, candidate-bound FAILING envelope. Scoping is
-   * withheld for these whatever the stamp says — the same veto demand release
-   * applies, and for the same reason: a withheld stack is a stack that can
-   * never re-emit the envelope its standing demand needs. Callers hold the
-   * checkout context, so they resolve the set with `boundFailingCheckNames`
-   * and pass it in; this module stays pure.
-   *
-   * REQUIRED, with no default, on purpose: a defaulted `[]` reads the same
-   * whether the caller inspected the envelopes or never looked, and this seam
-   * exists precisely for EXTERNAL preview producers — the callers most likely
-   * to skip the lookup. Pass the result of `boundFailingCheckNames`; pass `[]`
-   * only to mean "inspected the envelopes and found no bound failure".
-   *
-   * Deliberately visible to `api:check` as a breaking signature change
-   * (pre-1.0, no external callers yet).
-   */
-  vetoedTargets: readonly string[];
-}) => PreviewLifecyclePlan;
-//#endregion
 //#region src/worker-checkout-guard.d.ts
 type CheckoutDirsProbe = (cwd: string) => {
   gitCommonDir: string;
@@ -4647,6 +4660,7 @@ interface CreateProgramOptions {
     prPublish?: PrPublishAction;
     prReady?: PrReadyAction;
     prReview?: PrReviewAction;
+    prStatusHud?: PrStatusHudAction;
   };
   factoryCliInvocation?: FactoryCliInvocation;
   output?: CliOutput;
@@ -4654,4 +4668,4 @@ interface CreateProgramOptions {
 declare function createProgram(options?: CreateProgramOptions): Command;
 declare function run(argv?: string[]): Promise<void>;
 //#endregion
-export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BatteryCommandDisposition, type BatteryDisposition, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type BuildRetroEnvelopeInput, type CloudflareAccessServiceToken, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FindingDisposition, type FindingLedgerEntry, type FollowUpAction, FollowUpActionSchema, type ImpactScopeDecision, type ImpactScopeSurface, type IssueReviewFocus, type LadderDispositionDeclaration, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeState, type ParsedRetroEnvelope, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PreviewDisposition, type PreviewLifecyclePlan, type PreviewTargetPlan, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, REVIEW_FOCUS_SECTION, type RetroEnvelope, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewLadderCycle, type ReviewLadderEvaluation, type ReviewLadderPolicy, type ReviewLadderStageEvent, type ReviewLadderTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type ScopedOutCommand, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationBatteryPlan, type VerificationReuse, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildRetroEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_d_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, isRetroEnvelopeWireComplete, loadProjectProfile, normalizeIssueComments, openLadderFindings, parseRetroEnvelope, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readPrReadyProof, readPrReviewProof, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };
+export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BatteryCommandDisposition, type BatteryDisposition, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type CloudflareAccessServiceToken, type CompletedFactoryCheckSnapshot, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryPrStatusCheckName, type FactoryPrStatusSources, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FindingDisposition, type FindingLedgerEntry, type FollowUpAction, FollowUpActionSchema, type ImpactScopeDecision, type ImpactScopeSurface, type IssueReviewFocus, type LadderDispositionDeclaration, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeState, type PlanFactoryPrStatusHudInput, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PresentFactoryPrStatusHudDependencies, type PresentFactoryPrStatusHudInput, type PreviewDisposition, type PreviewLifecyclePlan, type PreviewTargetPlan, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, REVIEW_FOCUS_SECTION, type ReadFactoryPrStatusSourcesDependencies, type ReadFactoryPrStatusSourcesInput, type RefreshFactoryPrStatusHudInput, type RenderFactoryPrStatusHudInput, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewLadderCycle, type ReviewLadderEvaluation, type ReviewLadderPolicy, type ReviewLadderStageEvent, type ReviewLadderTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type ScopedOutCommand, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationBatteryPlan, type VerificationReuse, type VerificationRunContext, type VerificationRunContextInput, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_d_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, openLadderFindings, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, readPrReviewProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };