@patronage/software-factory 0.20.0 → 0.23.0

package/dist/index.d.ts

@@ -4,7 +4,6 @@ import { z } from "zod";
 
 //#region src/github-issue-comments.d.ts
 interface GithubIssueCommentApi {
-  author_association?: string;
   body: string;
   created_at: string;
   html_url: string;
@@ -18,7 +17,6 @@ interface GithubIssueComment {
   author: {
     login?: string;
   };
-  authorAssociation?: string;
   body: string;
   createdAt: string;
   id: string;
@@ -169,6 +167,103 @@ interface HqIngestDependencies {
   transportTimeoutMs?: number;
 }
 //#endregion
+//#region src/demand-waiver.d.ts
+declare const DEFAULT_DEMAND_WAIVER_PATH = ".factory-memory/demand-waivers.json";
+/** One recorded operator act: this demand, on this candidate, waived. */
+interface DemandWaiver {
+  candidate: {
+    headSha: string;
+    pr: number;
+  };
+  demand: string;
+  /** The authenticated GitHub account that recorded the waiver. */
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  /** The operator session the waiver was recorded in. */
+  session: string;
+}
+interface DemandWaiverStore {
+  command: "patronage-factory demand:waive";
+  schemaVersion: 1;
+  waivers: DemandWaiver[];
+}
+declare const validateDemandWaiverStore: (value: unknown) => DemandWaiverStore;
+/**
+ * A demand that was in force, was NOT met, and was waived by the operator.
+ *
+ * `unmetReasons` is required and non-empty: every reason the demand refused is
+ * carried through verbatim. There is no field on this record that could say
+ * "satisfied", and no code path constructs one without a refusal to carry.
+ */
+interface WaivedDemand {
+  demand: string;
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  session: string;
+  /** The demand's refusals at evaluation time, preserved verbatim. */
+  unmetReasons: string[];
+}
+declare const waivedDemandSchema: z.ZodType<WaivedDemand>;
+/** The waivers that bind one candidate: same PR, same head. */
+declare const selectWaiversForCandidate: ({
+  headSha,
+  pr,
+  waivers
+}: {
+  headSha: string | undefined;
+  pr: number;
+  waivers: readonly DemandWaiver[];
+}) => DemandWaiver[];
+interface DemandOutcome {
+  blockingReasons: string[];
+  waived?: WaivedDemand;
+}
+/**
+ * Fold one resolved demand's refusals through the operator's waivers.
+ *
+ * A satisfied demand (no refusals) stays satisfied and the waiver stays inert
+ * — a waiver can only ever move a demand from *unmet-and-blocking* to
+ * *unmet-and-waived*, never to met.
+ */
+declare const applyDemandWaiver: ({
+  demand,
+  reasons,
+  waivers
+}: {
+  demand: string;
+  reasons: readonly string[];
+  waivers: readonly DemandWaiver[];
+}) => DemandOutcome;
+/** How a waived demand reads to a human. Never the word "satisfied". */
+declare const waivedDemandNotice: (waived: WaivedDemand) => string;
+interface DemandWaiverAuthorization {
+  operator: string;
+  session: string;
+}
+type AuthorizeDemandWaiverResult = {
+  authorization: DemandWaiverAuthorization;
+  refusals?: undefined;
+} | {
+  authorization?: undefined;
+  refusals: string[];
+};
+/**
+ * Operator identity, `declaredBy`-style: a named human account, recorded on
+ * the waiver and enforced here — plus session distinctness from the candidate
+ * the waiver applies to. Every refusal is named; nothing falls open.
+ */
+declare const authorizeDemandWaiver: ({
+  authenticatedLogin,
+  authoringSession,
+  session
+}: {
+  authenticatedLogin: string | undefined;
+  authoringSession: string | undefined;
+  session: string | undefined;
+}) => AuthorizeDemandWaiverResult;
+//#endregion
 //#region src/checkout-repository.d.ts
 interface CheckoutRepository {
   name: string;
@@ -218,35 +313,227 @@ interface GithubPullRequestReview {
   url: string;
 }
 //#endregion
-//#region src/pr-readiness/handled-human-comments.d.ts
-declare const HANDLED_COMMENTS_PAYLOAD_KIND: "handled-human-comments";
+//#region src/merge-freeze.d.ts
+declare const MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
+declare const MERGE_FREEZE_APP_SLUG = "patronage-factory";
+declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  active: z.ZodLiteral<true>;
+  generationId: z.ZodNumber;
+  headSha: z.ZodString;
+  outcome: z.ZodEnum<{
+    stale: "stale";
+    active: "active";
+  }>;
+  reason: z.ZodString;
+  recordedAt: z.ZodISODateTime;
+  schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+  active: z.ZodLiteral<false>;
+  clearRationale: z.ZodOptional<z.ZodString>;
+  generationId: z.ZodNumber;
+  headSha: z.ZodString;
+  outcome: z.ZodLiteral<"inactive">;
+  reason: z.ZodString;
+  recordedAt: z.ZodISODateTime;
+  schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>], "active">;
+type MergeFreezeState = z.infer<typeof mergeFreezeStateSchema>;
 /**
- * Authenticated producer of the durable handled set. Recorded on the readiness
- * ledger; unverifiable producers are ignored on read (fail closed).
+ * The write side of this contract lives in the generated main-push verify
+ * workflow (#356, ADR 0016 as amended): it is the ONLY producer of
+ * `patronage-factory/merge-freeze` generations. Its emitted `output.text`
+ * payload must parse under this exact reader schema, which is what the
+ * workflow's own tests assert through this export.
  */
-type HandledCommentsProducerMode = "app" | "commit-status";
-interface HandledCommentsProducer {
-  /** App id (stringified) or GitHub login, depending on mode. */
-  identity: string;
-  mode: HandledCommentsProducerMode;
+declare function validateMergeFreezeState(value: unknown): MergeFreezeState;
+interface MergeFreezeStoreInput {
+  cwd: string;
+  headSha: string;
+  repository: CheckoutRepository;
 }
-interface HandledCommentsCheckPayload {
-  clearedAt?: string;
-  handledCommentUrls: string[];
-  kind: typeof HANDLED_COMMENTS_PAYLOAD_KIND;
-  pr: number;
-  schemaVersion: 1;
-  sessionId?: string;
+interface MergeFreezeStore {
+  read: (input: MergeFreezeStoreInput) => unknown;
 }
-//#endregion
-//#region src/diff-classification.d.ts
-declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
-type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
+declare namespace worktree_held_branch_d_exports {
+  export { MergeOperationalNotices, WorktreeHeldBranch, WorktreeHeldBranchCheck, WorktreeListEntry, checkWorktreeHeldBranch, findWorktreeHeldBranch, formatHeldBranchCloseoutSummary, listWorktreesPorcelain, parseGitWorktreeList, resolveMergeOperationalNotices, worktreeHeldBranchNotice };
+}
+/**
+ * Detects when a PR head branch is checked out in a local git worktree.
+ *
+ * `gh pr merge --delete-branch` fails when the local branch is held by a
+ * worktree (git refuses to delete a checked-out branch), which previously
+ * broke the auto-merge lane mid-merge (patronage/internal#284). The merge
+ * preflight surfaces this as an actionable notice — not a hard fail — so the
+ * operator merges without `--delete-branch` (or prunes the worktree first)
+ * and defers local branch cleanup to closeout.
+ */
+interface WorktreeHeldBranch {
+  branch: string;
+  worktreePath: string;
+}
+interface WorktreeListEntry {
+  branch?: string;
+  path: string;
+}
+/**
+ * Parses `git worktree list --porcelain` output. Entries are separated by
+ * blank lines; each starts with `worktree <path>` and carries an optional
+ * `branch refs/heads/<name>` attribute (detached worktrees have none).
+ */
+declare function parseGitWorktreeList(porcelain: string): WorktreeListEntry[];
+/**
+ * Returns the worktree holding `branch`, or undefined when no local worktree
+ * has it checked out (or the porcelain listing was unavailable).
+ */
+declare function findWorktreeHeldBranch({
+  branch,
+  worktreeListPorcelain
+}: {
+  branch: string;
+  worktreeListPorcelain: string | undefined;
+}): undefined | WorktreeHeldBranch;
+declare function worktreeHeldBranchNotice(held: WorktreeHeldBranch): string;
+interface MergeOperationalNotices {
+  notices: string[];
+  worktreeHeldBranch?: WorktreeHeldBranch;
+  worktreeHeldBranches?: WorktreeHeldBranch[];
+}
+/**
+ * Single entry point for non-blocking merge preflight notices, mirroring
+ * `resolveMergeGuardIdentity`/`mergeGuardBlockingReasons` in
+ * merge-identity.ts: adding a notice kind never requires coordinated edits
+ * in the command runner, and persisted notice strings cannot drift from the
+ * structured detection result.
+ */
+declare function resolveMergeOperationalNotices({
+  headRefName,
+  worktreeListPorcelain
+}: {
+  headRefName: string | undefined;
+  worktreeListPorcelain: string | undefined;
+}): MergeOperationalNotices;
+/**
+ * Shared `git worktree list --porcelain` reader for merge preflight and
+ * closeout. Returns undefined when the directory is missing, not a git
+ * repository, or git is unavailable — detection is best-effort and callers
+ * report "skipped" rather than fabricating a result.
+ */
+declare function listWorktreesPorcelain(cwd: string): string | undefined;
+interface WorktreeHeldBranchCheck {
+  held?: WorktreeHeldBranch;
+  /** "skipped" means no branch was recorded or worktrees were unlistable. */
+  status: "clean" | "held" | "skipped";
+}
+/**
+ * Closeout-side counterpart to the merge-preflight notice: the merge step
+ * defers local branch cleanup to closeout, so closeout planning checks
+ * whether the worker branch is still held by a worktree (#284).
+ */
+declare function checkWorktreeHeldBranch({
+  branch,
+  worktreeListPorcelain
+}: {
+  branch: string | undefined;
+  worktreeListPorcelain: string | undefined;
+}): WorktreeHeldBranchCheck;
+/** One-line closeout summary, owned beside the detection logic. */
+declare function formatHeldBranchCloseoutSummary(check: WorktreeHeldBranchCheck): string;
+declare namespace merge_identity_d_exports {
+  export { LiveHeadInput, MergeGuardIdentity, MergeIdentityResult, PostProofCommit, ReadyProofForMergeIdentity, evaluateMergeIdentity, mergeGuardBlockingReasons, mergeGuardIdentitySchema, resolveMergeGuardIdentity };
+}
+interface PostProofCommit {
+  sha: string;
+  subject: string;
+}
+/**
+ * The slice of the pr:ready proof the merge guard actually consumes, so this
+ * module does not depend on the parent proof envelope. `PrReadyProof` is
+ * structurally assignable to this type.
+ */
+interface ReadyProofForMergeIdentity {
+  blockingReasons: string[];
+  ledger: {
+    /**
+     * The evaluated head SHA recorded by pr:ready: `pr.headRefOid` captured
+     * at evaluation time. The merge guard compares it to the live pushed
+     * HEAD with exact equality.
+     */
+    headSha: string;
+    pr: number;
+  };
+  status: string;
+}
+type MergeIdentityResult = {
+  kind: "match";
+  headSha: string;
+} | {
+  kind: "diverged";
+  liveHeadSha: string;
+  postProofCommits?: PostProofCommit[];
+  proofHeadSha: string;
+};
+type MergeGuardIdentity = MergeIdentityResult | {
+  kind: "live-head-invalid";
+  pr: number;
+  received: string;
+} | {
+  kind: "ready-proof-missing";
+  errorDetail?: string;
+  readyProofPath: string;
+} | {
+  kind: "ready-proof-pr-mismatch";
+  proofPr: number;
+  requestedPr: number;
+} | {
+  kind: "ready-proof-not-ready";
+  blockingReasons: string[];
+  status: string;
+};
+declare const evaluateMergeIdentity: ({
+  liveHeadSha,
+  postProofCommits,
+  proofHeadSha
+}: {
+  liveHeadSha: string;
+  postProofCommits?: PostProofCommit[];
+  proofHeadSha: string;
+}) => MergeIdentityResult;
+/**
+ * The live PR head as fetched from GitHub: either a validated 40-hex SHA or
+ * the raw (stringified) response that failed validation.
+ */
+type LiveHeadInput = {
+  headSha: string;
+} | {
+  invalidResponse: string;
+};
+/**
+ * Single entry point that owns construction of every MergeGuardIdentity
+ * kind, so adding or changing a kind never requires coordinated edits in the
+ * command runner.
+ */
+declare const resolveMergeGuardIdentity: ({
+  commitsBetween,
+  liveHead,
+  pr,
+  readyProof,
+  readyProofError,
+  readyProofPath
+}: {
+  commitsBetween?: (fromSha: string, toSha: string) => PostProofCommit[] | undefined;
+  liveHead: LiveHeadInput;
+  pr: number;
+  readyProof: ReadyProofForMergeIdentity | undefined;
+  readyProofError?: unknown;
+  readyProofPath: string;
+}) => MergeGuardIdentity;
+declare const mergeGuardIdentitySchema: z.ZodType<MergeGuardIdentity>;
+declare const mergeGuardBlockingReasons: (identity: MergeGuardIdentity) => string[];
 //#endregion
 //#region src/profile.d.ts
 declare const DEFAULT_FACTORY_REPOSITORY = "unknown/unknown";
-/** The one profile shape this build accepts (ADR 0023, #318). */
-declare const PROFILE_SCHEMA_VERSION = 3;
+/** The one profile shape this build accepts (ADR 0023, #318, #351). */
+declare const PROFILE_SCHEMA_VERSION = 4;
 declare const factoryProjectProfileSchema: z.ZodObject<{
   $schema: z.ZodOptional<z.ZodString>;
   env: z.ZodOptional<z.ZodObject<{
@@ -295,7 +582,6 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
       paths: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>;
     defaultMaxCycles: z.ZodNumber;
-    docsOnlyBypass: z.ZodOptional<z.ZodBoolean>;
     ladder: z.ZodOptional<z.ZodObject<{
       gate: z.ZodOptional<z.ZodObject<{
         cap: z.ZodNumber;
@@ -307,7 +593,7 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     }>>;
     standingChecklist: z.ZodOptional<z.ZodArray<z.ZodString>>;
   }, z.core.$strict>;
-  schemaVersion: z.ZodLiteral<3>;
+  schemaVersion: z.ZodLiteral<4>;
   verification: z.ZodObject<{
     commands: z.ZodArray<z.ZodObject<{
       command: z.ZodString;
@@ -324,11 +610,6 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
 }, z.core.$strict>;
 type FactoryProjectProfile = z.infer<typeof factoryProjectProfileSchema>;
 declare const resolveFactoryRepository: (profile?: Pick<FactoryProjectProfile, "repository"> | undefined) => string;
-/**
- * Whether a pure docs/process diff may skip independent review. Opt-in: absent
- * config means review is required (#318, ADR 0023).
- */
-declare const resolveDocsOnlyReviewBypass: (profile: Pick<FactoryProjectProfile, "review">) => boolean;
 interface LoadProjectProfileInput {
   cwd?: string;
   profilePath?: string;
@@ -339,26 +620,158 @@ interface LoadProjectProfileResult {
 }
 declare function loadProjectProfile(input?: LoadProjectProfileInput): LoadProjectProfileResult;
 //#endregion
-//#region src/pr-verify-mode.d.ts
-/**
- * The verification mode `pr:verify` resolved for a run.
- *
- * Canonically declared here rather than inside `pr-readiness/` so that modules
- * on either side of that boundary — the readiness proof shape and the durable
- * check-run payload — can name the same union without importing each other.
- */
-type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
+//#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/pr-verify-status.d.ts
-type CommitStatusState = "failure" | "pending" | "success";
-interface PostCommitStatusInput {
-  context?: string;
-  cwd: string;
-  description: string;
-  owner: string;
-  repo: string;
-  sha: string;
-  state: CommitStatusState;
+//#region src/pr-merge-check.d.ts
+interface PrMergeCheckArgs extends LoadProjectProfileInput {
+  epic?: number;
+  json?: boolean;
+  output?: string;
+  pr: number;
+  readyProof?: string;
+}
+interface PrMergeCheckProof {
+  schemaVersion: 1;
+  blockingReasons: string[];
+  boundary?: {
+    autoMerge: boolean;
+    epic: number;
+    review: EvidenceReviewRung;
+    wave: string;
+  };
+  command: "patronage-factory pr:merge-check";
+  /**
+   * Machine-safe arg array for the obvious next action (#523): on `pass`, the
+   * remote-only GitHub merge API invocation for this PR; on `fail`, the re-run that clears the
+   * block (`pr:ready`, or `pr:verify` then `pr:ready` after a head
+   * divergence). Same `argv` shape `factory:delegate --print` emits. Optional
+   * and purely additive — existing consumers ignore it.
+   */
+  followUp?: FollowUpAction;
+  identity: MergeGuardIdentity;
+  /**
+   * The pushed PR head SHA fetched from GitHub at check time. Absent only
+   * when GitHub returned no usable 40-hex head (identity kind
+   * "live-head-invalid"), which is itself a fail-closed blocking state.
+   */
+  liveHeadSha?: string;
+  /**
+   * Actionable operational notices that do not block the merge, e.g. a PR
+   * head branch held by a local worktree, which makes
+   * `gh pr merge --delete-branch` fail (patronage/internal#284).
+   */
+  notices?: string[];
+  pr: number;
+  status: "pass" | "fail";
+  /**
+   * Demands that were in force, were NOT met, and were waived by the operator
+   * (#354). Each entry carries the demand's refusals verbatim, so a waived
+   * demand can never read as a met one; the merge proceeds on the recorded
+   * operator act, not on evidence.
+   */
+  waivedDemands?: WaivedDemand[];
+  /** Present when the PR head branch is checked out in a local worktree. */
+  worktreeHeldBranch?: WorktreeHeldBranch;
+  /** All merge-relevant branches held by local worktrees (head and default). */
+  worktreeHeldBranches?: WorktreeHeldBranch[];
+}
+interface PrMergeCheckGitDependencies {
+  checkoutRepository: (cwd: string) => CheckoutRepository;
+  commitsBetween: (cwd: string, fromSha: string, toSha: string) => PostProofCommit[] | undefined;
+  worktreeListPorcelain: (cwd: string) => string | undefined;
+  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+}
+interface PrMergeCheckDependencies {
+  git?: Partial<PrMergeCheckGitDependencies>;
+  github?: {
+    fetchClosingPullRequests?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => {
+      number: number;
+    }[];
+    fetchIssueBody?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => string;
+    fetchPullRequestHead: (input: {
+      cwd: string;
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => {
+      headRefName?: string;
+      headRefOid: string;
+      baseRefName?: string;
+      baseRefOid?: string;
+      mergedAt?: string | null;
+      remoteHeadRefExists?: boolean;
+      labels?: {
+        name: string;
+      }[];
+    };
+    fetchPullRequestReviews?: (input: {
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => GithubPullRequestReview[];
+  };
+  mergeFreeze?: MergeFreezeStore;
+}
+declare function validatePrMergeCheckProof(value: unknown): PrMergeCheckProof;
+declare function readPrMergeCheckProof(filePath: string): PrMergeCheckProof;
+declare function runPrMergeCheck(args: PrMergeCheckArgs, dependencies?: PrMergeCheckDependencies): PrMergeCheckProof;
+//#endregion
+//#region src/pr-readiness/handled-human-comments.d.ts
+declare const HANDLED_COMMENTS_PAYLOAD_KIND: "handled-human-comments";
+/**
+ * Authenticated producer of the durable handled set. Recorded on the readiness
+ * ledger; unverifiable producers are ignored on read (fail closed).
+ */
+type HandledCommentsProducerMode = "app" | "commit-status";
+interface HandledCommentsProducer {
+  /** App id (stringified) or GitHub login, depending on mode. */
+  identity: string;
+  mode: HandledCommentsProducerMode;
+}
+interface HandledCommentsCheckPayload {
+  clearedAt?: string;
+  handledCommentUrls: string[];
+  kind: typeof HANDLED_COMMENTS_PAYLOAD_KIND;
+  pr: number;
+  schemaVersion: 1;
+  sessionId?: string;
+}
+//#endregion
+//#region src/diff-classification.d.ts
+declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
+type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
+//#endregion
+//#region src/pr-verify-mode.d.ts
+/**
+ * The verification mode `pr:verify` resolved for a run.
+ *
+ * Canonically declared here rather than inside `pr-readiness/` so that modules
+ * on either side of that boundary — the readiness proof shape and the durable
+ * check-run payload — can name the same union without importing each other.
+ */
+type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
+//#endregion
+//#region src/pr-verify-status.d.ts
+type CommitStatusState = "failure" | "pending" | "success";
+interface PostCommitStatusInput {
+  context?: string;
+  cwd: string;
+  description: string;
+  owner: string;
+  repo: string;
+  sha: string;
+  state: CommitStatusState;
   /**
    * Drop this mirror's own failure diagnostic because the caller has already
    * reported the same cause. Set only on the pre-push path, where the status
@@ -389,6 +802,10 @@ declare const factoryUserConfigSchema: z.ZodObject<{
     privateKeyPath: z.ZodString;
   }, z.core.$strip>>;
   hqAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  hqIngestCredentials: z.ZodOptional<z.ZodObject<{
+    clientIdRef: z.ZodString;
+    clientSecretRef: z.ZodString;
+  }, z.core.$strip>>;
   schemaVersion: z.ZodLiteral<2>;
 }, z.core.$strip>;
 type FactoryUserConfig = z.infer<typeof factoryUserConfigSchema>;
@@ -473,304 +890,6 @@ interface PublishHandledCommentsCheckInput {
   sha: string;
 }
 //#endregion
-//#region src/merge-freeze.d.ts
-interface MergeFreezeGeneration {
-  headSha: string;
-  id: number;
-  startedAt: string;
-}
-interface MergeFreezeStoreInput {
-  cwd: string;
-  headSha: string;
-  repository: CheckoutRepository;
-}
-interface MergeFreezeStore {
-  complete: (input: MergeFreezeStoreInput & {
-    clearRationale?: string;
-    generation: MergeFreezeGeneration;
-    outcome: "active" | "inactive" | "stale";
-    reason: string;
-  }) => Promise<void>;
-  read: (input: MergeFreezeStoreInput) => unknown;
-  start: (input: MergeFreezeStoreInput) => Promise<MergeFreezeGeneration>;
-}
-declare namespace worktree_held_branch_d_exports {
-  export { MergeOperationalNotices, WorktreeHeldBranch, WorktreeHeldBranchCheck, WorktreeListEntry, checkWorktreeHeldBranch, findWorktreeHeldBranch, formatHeldBranchCloseoutSummary, listWorktreesPorcelain, parseGitWorktreeList, resolveMergeOperationalNotices, worktreeHeldBranchNotice };
-}
-/**
- * Detects when a PR head branch is checked out in a local git worktree.
- *
- * `gh pr merge --delete-branch` fails when the local branch is held by a
- * worktree (git refuses to delete a checked-out branch), which previously
- * broke the auto-merge lane mid-merge (patronage/internal#284). The merge
- * preflight surfaces this as an actionable notice — not a hard fail — so the
- * operator merges without `--delete-branch` (or prunes the worktree first)
- * and defers local branch cleanup to closeout.
- */
-interface WorktreeHeldBranch {
-  branch: string;
-  worktreePath: string;
-}
-interface WorktreeListEntry {
-  branch?: string;
-  path: string;
-}
-/**
- * Parses `git worktree list --porcelain` output. Entries are separated by
- * blank lines; each starts with `worktree <path>` and carries an optional
- * `branch refs/heads/<name>` attribute (detached worktrees have none).
- */
-declare function parseGitWorktreeList(porcelain: string): WorktreeListEntry[];
-/**
- * Returns the worktree holding `branch`, or undefined when no local worktree
- * has it checked out (or the porcelain listing was unavailable).
- */
-declare function findWorktreeHeldBranch({
-  branch,
-  worktreeListPorcelain
-}: {
-  branch: string;
-  worktreeListPorcelain: string | undefined;
-}): undefined | WorktreeHeldBranch;
-declare function worktreeHeldBranchNotice(held: WorktreeHeldBranch): string;
-interface MergeOperationalNotices {
-  notices: string[];
-  worktreeHeldBranch?: WorktreeHeldBranch;
-  worktreeHeldBranches?: WorktreeHeldBranch[];
-}
-/**
- * Single entry point for non-blocking merge preflight notices, mirroring
- * `resolveMergeGuardIdentity`/`mergeGuardBlockingReasons` in
- * merge-identity.ts: adding a notice kind never requires coordinated edits
- * in the command runner, and persisted notice strings cannot drift from the
- * structured detection result.
- */
-declare function resolveMergeOperationalNotices({
-  headRefName,
-  worktreeListPorcelain
-}: {
-  headRefName: string | undefined;
-  worktreeListPorcelain: string | undefined;
-}): MergeOperationalNotices;
-/**
- * Shared `git worktree list --porcelain` reader for merge preflight and
- * closeout. Returns undefined when the directory is missing, not a git
- * repository, or git is unavailable — detection is best-effort and callers
- * report "skipped" rather than fabricating a result.
- */
-declare function listWorktreesPorcelain(cwd: string): string | undefined;
-interface WorktreeHeldBranchCheck {
-  held?: WorktreeHeldBranch;
-  /** "skipped" means no branch was recorded or worktrees were unlistable. */
-  status: "clean" | "held" | "skipped";
-}
-/**
- * Closeout-side counterpart to the merge-preflight notice: the merge step
- * defers local branch cleanup to closeout, so closeout planning checks
- * whether the worker branch is still held by a worktree (#284).
- */
-declare function checkWorktreeHeldBranch({
-  branch,
-  worktreeListPorcelain
-}: {
-  branch: string | undefined;
-  worktreeListPorcelain: string | undefined;
-}): WorktreeHeldBranchCheck;
-/** One-line closeout summary, owned beside the detection logic. */
-declare function formatHeldBranchCloseoutSummary(check: WorktreeHeldBranchCheck): string;
-declare namespace merge_identity_d_exports {
-  export { LiveHeadInput, MergeGuardIdentity, MergeIdentityResult, PostProofCommit, ReadyProofForMergeIdentity, evaluateMergeIdentity, mergeGuardBlockingReasons, mergeGuardIdentitySchema, resolveMergeGuardIdentity };
-}
-interface PostProofCommit {
-  sha: string;
-  subject: string;
-}
-/**
- * The slice of the pr:ready proof the merge guard actually consumes, so this
- * module does not depend on the parent proof envelope. `PrReadyProof` is
- * structurally assignable to this type.
- */
-interface ReadyProofForMergeIdentity {
-  blockingReasons: string[];
-  ledger: {
-    /**
-     * The evaluated head SHA recorded by pr:ready: `pr.headRefOid` captured
-     * at evaluation time. The merge guard compares it to the live pushed
-     * HEAD with exact equality.
-     */
-    headSha: string;
-    pr: number;
-  };
-  status: string;
-}
-type MergeIdentityResult = {
-  kind: "match";
-  headSha: string;
-} | {
-  kind: "diverged";
-  liveHeadSha: string;
-  postProofCommits?: PostProofCommit[];
-  proofHeadSha: string;
-};
-type MergeGuardIdentity = MergeIdentityResult | {
-  kind: "live-head-invalid";
-  pr: number;
-  received: string;
-} | {
-  kind: "ready-proof-missing";
-  errorDetail?: string;
-  readyProofPath: string;
-} | {
-  kind: "ready-proof-pr-mismatch";
-  proofPr: number;
-  requestedPr: number;
-} | {
-  kind: "ready-proof-not-ready";
-  blockingReasons: string[];
-  status: string;
-};
-declare const evaluateMergeIdentity: ({
-  liveHeadSha,
-  postProofCommits,
-  proofHeadSha
-}: {
-  liveHeadSha: string;
-  postProofCommits?: PostProofCommit[];
-  proofHeadSha: string;
-}) => MergeIdentityResult;
-/**
- * The live PR head as fetched from GitHub: either a validated 40-hex SHA or
- * the raw (stringified) response that failed validation.
- */
-type LiveHeadInput = {
-  headSha: string;
-} | {
-  invalidResponse: string;
-};
-/**
- * Single entry point that owns construction of every MergeGuardIdentity
- * kind, so adding or changing a kind never requires coordinated edits in the
- * command runner.
- */
-declare const resolveMergeGuardIdentity: ({
-  commitsBetween,
-  liveHead,
-  pr,
-  readyProof,
-  readyProofError,
-  readyProofPath
-}: {
-  commitsBetween?: (fromSha: string, toSha: string) => PostProofCommit[] | undefined;
-  liveHead: LiveHeadInput;
-  pr: number;
-  readyProof: ReadyProofForMergeIdentity | undefined;
-  readyProofError?: unknown;
-  readyProofPath: string;
-}) => MergeGuardIdentity;
-declare const mergeGuardIdentitySchema: z.ZodType<MergeGuardIdentity>;
-declare const mergeGuardBlockingReasons: (identity: MergeGuardIdentity) => string[];
-//#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/pr-merge-check.d.ts
-interface PrMergeCheckArgs extends LoadProjectProfileInput {
-  epic?: number;
-  json?: boolean;
-  output?: string;
-  pr: number;
-  readyProof?: string;
-}
-interface PrMergeCheckProof {
-  schemaVersion: 1;
-  blockingReasons: string[];
-  boundary?: {
-    autoMerge: boolean;
-    epic: number;
-    review: EvidenceReviewRung;
-    wave: string;
-  };
-  command: "patronage-factory pr:merge-check";
-  /**
-   * Machine-safe arg array for the obvious next action (#523): on `pass`, the
-   * remote-only GitHub merge API invocation for this PR; on `fail`, the re-run that clears the
-   * block (`pr:ready`, or `pr:verify` then `pr:ready` after a head
-   * divergence). Same `argv` shape `factory:delegate --print` emits. Optional
-   * and purely additive — existing consumers ignore it.
-   */
-  followUp?: FollowUpAction;
-  identity: MergeGuardIdentity;
-  /**
-   * The pushed PR head SHA fetched from GitHub at check time. Absent only
-   * when GitHub returned no usable 40-hex head (identity kind
-   * "live-head-invalid"), which is itself a fail-closed blocking state.
-   */
-  liveHeadSha?: string;
-  /**
-   * Actionable operational notices that do not block the merge, e.g. a PR
-   * head branch held by a local worktree, which makes
-   * `gh pr merge --delete-branch` fail (patronage/internal#284).
-   */
-  notices?: string[];
-  pr: number;
-  status: "pass" | "fail";
-  /** Present when the PR head branch is checked out in a local worktree. */
-  worktreeHeldBranch?: WorktreeHeldBranch;
-  /** All merge-relevant branches held by local worktrees (head and default). */
-  worktreeHeldBranches?: WorktreeHeldBranch[];
-}
-interface PrMergeCheckGitDependencies {
-  changedFilesBetween: (cwd: string, baseSha: string, headSha: string) => string[] | undefined;
-  checkoutRepository: (cwd: string) => CheckoutRepository;
-  commitsBetween: (cwd: string, fromSha: string, toSha: string) => PostProofCommit[] | undefined;
-  worktreeListPorcelain: (cwd: string) => string | undefined;
-  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-}
-interface PrMergeCheckDependencies {
-  git?: Partial<PrMergeCheckGitDependencies>;
-  github?: {
-    fetchClosingPullRequests?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => {
-      number: number;
-    }[];
-    fetchIssueBody?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => string;
-    fetchPullRequestHead: (input: {
-      cwd: string;
-      owner: string;
-      pr: number;
-      repo: string;
-    }) => {
-      headRefName?: string;
-      headRefOid: string;
-      baseRefName?: string;
-      baseRefOid?: string;
-      mergedAt?: string | null;
-      remoteHeadRefExists?: boolean;
-      labels?: {
-        name: string;
-      }[];
-    };
-    fetchPullRequestReviews?: (input: {
-      owner: string;
-      pr: number;
-      repo: string;
-    }) => GithubPullRequestReview[];
-  };
-  mergeFreeze?: MergeFreezeStore;
-}
-declare function validatePrMergeCheckProof(value: unknown): PrMergeCheckProof;
-declare function readPrMergeCheckProof(filePath: string): PrMergeCheckProof;
-declare function runPrMergeCheck(args: PrMergeCheckArgs, dependencies?: PrMergeCheckDependencies): PrMergeCheckProof;
-//#endregion
 //#region src/pr-proof-io.d.ts
 interface ProofDescriptor<T> {
   label: string;
@@ -1064,7 +1183,7 @@ interface PrReviewProof {
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
   reviewRequirement?: {
-    reason: "docs-only-profile-bypass";
+    reason: "no-applicable-mode";
     status: "not-required";
   };
   reviews: PrReviewResult[];
@@ -1349,6 +1468,7 @@ interface PrReadyArgs extends LoadProjectProfileInput {
   authoringSessionIds?: string[];
   base: string;
   bodyForEvaluation?: string;
+  epic?: number;
   handledCommentUrls?: string[];
   json?: boolean;
   output?: string;
@@ -1427,6 +1547,18 @@ interface PrReadyProof {
 type PublishHandledCommentsResult = HandledCommentsProducer | Promise<HandledCommentsProducer | undefined> | undefined;
 interface PrReadyDependencies {
   github?: {
+    fetchClosingPullRequests?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => {
+      number: number;
+    }[];
+    fetchIssueBody?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => string;
     fetchHandledComments?: (input: {
       owner: string;
       pr: number;
@@ -1484,7 +1616,7 @@ declare const requiredCheckScopeSchema: z.ZodObject<{
 type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
 interface RequiredCheckScopeContext {
   labels: string[] | undefined;
-  classification: DiffClassification;
+  classification: DiffClassification | undefined;
 }
 interface ScopeDecision {
   inScope: boolean;
@@ -1913,15 +2045,195 @@ declare const resolveVerifyProofApplicability: ({
   fullVerifiedHeadShas: never[];
   verificationProof: VerificationProofState;
 } | {
-  fullVerifiedHeadShas: string[];
-  verificationProof: {
-    headShas: VerifiedHeadShas;
-    kind: "typed";
-    proof: PrVerifyProof;
-  };
+  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/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.
+ *
+ * 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.
+ *
+ * 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<{
+    mergeCheck: z.ZodOptional<z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      "not-run": "not-run";
+    }>>;
+    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).
+ */
+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;
+} | {
+  disposition: "degraded";
+  raw: unknown;
+  schemaVersion: number | undefined;
 };
-declare const verificationProofForReadiness: (state: VerificationProofState) => VerificationHeadShas;
-declare const verificationProofBlockingReason: (state: VerificationProofState) => string | undefined;
+/**
+ * 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;
 //#endregion
 //#region src/schemas.d.ts
 declare const boundaryCheckProofSchema: z.ZodObject<{
@@ -2015,6 +2327,74 @@ interface CliOutput {
 //#region src/commands/boundary-check.d.ts
 type BoundaryCheckAction = (args: BoundaryCheckArgs) => BoundaryCheckProofRecord;
 //#endregion
+//#region src/demand-waive.d.ts
+/** Every waiver recorded in this checkout; an absent or unreadable store is
+ * no waivers, so a damaged file can only ever block, never permit. */
+declare const readDemandWaivers: (cwd: string, filePath?: string) => DemandWaiver[];
+interface DemandWaiveArgs {
+  cwd?: string;
+  demand: string;
+  json?: boolean;
+  output?: string;
+  pr: number;
+  rationale: string;
+}
+interface DemandWaiveDependencies {
+  checkoutRepository?: (cwd: string) => CheckoutRepository;
+  env?: NodeJS.ProcessEnv;
+  fetchAuthenticatedLogin?: (cwd: string) => string | undefined;
+  fetchPullRequestHeadSha?: (input: {
+    cwd: string;
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => string | undefined;
+  now?: () => Date;
+}
+declare class DemandWaiveRefusalError extends Error {
+  readonly refusals: string[];
+  constructor(refusals: string[]);
+}
+/**
+ * Record one waiver. One step: the operator names the demand, the candidate,
+ * and why. No confirmation, no second approval, no cooldown — the trust model
+ * puts the bar at operator identity, not at ceremony aimed at the operator
+ * (ADR 0025).
+ */
+declare const runDemandWaive: (args: DemandWaiveArgs, dependencies?: DemandWaiveDependencies) => DemandWaiver;
+//#endregion
+//#region src/commands/demand-waive.d.ts
+type DemandWaiveAction = (args: DemandWaiveArgs) => DemandWaiver;
+//#endregion
+//#region src/commands/pr-merge-check.d.ts
+type PrMergeCheckAction = (args: PrMergeCheckArgs) => PrMergeCheckProof;
+//#endregion
+//#region src/pr-review.d.ts
+interface PrReviewArgs extends LoadProjectProfileInput {
+  base: string;
+  cycle: number;
+  dispositions?: string;
+  findings?: string;
+  issue?: number;
+  maxCycles?: number;
+  mode: PrReviewMode;
+  output?: string;
+  verifyProof?: string;
+}
+interface PrReviewGitDependencies {
+  changedFiles: (cwd: string, base: string) => string[];
+  currentHeadSha: (cwd: string) => string;
+  isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
+  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
 //#region src/workspace-install-resolution.d.ts
 interface CleanInstallResolutionDependencies {
   existsSync?: typeof existsSync;
@@ -2043,62 +2423,21 @@ interface PrVerifyArgs extends LoadProjectProfileInput {
 interface PrVerifyGitDependencies {
   changedFiles: (cwd: string, base: string) => string[];
   currentHeadSha: (cwd: string) => string;
-  emptyTreeHash: (cwd: string) => string;
-  mergeBaseSha: (cwd: string, base: string) => string;
-  runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
-  statusPorcelain: (cwd: string) => string;
-  stablePatchId: (cwd: string, base: string) => string;
-}
-interface PrVerifyDependencies {
-  cleanInstall?: CleanInstallResolutionDependencies | false;
-  env?: NodeJS.ProcessEnv;
-  git?: PrVerifyGitDependencies;
-  hq?: HqIngestDependencies;
-  postCommitStatus?: PostCommitStatus;
-  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
-}
-declare function runPrVerify(args: PrVerifyArgs, dependencies?: PrVerifyDependencies): PrVerifyProof;
-//#endregion
-//#region src/canary-verify.d.ts
-interface CanaryVerifyArgs extends LoadProjectProfileInput {
-  /** Lift an active merge freeze without running verification. */
-  clear?: boolean;
-  output?: string;
-  /** Required with --clear; recorded on the canary proof. */
-  rationale?: string;
-}
-//#endregion
-//#region src/commands/canary-verify.d.ts
-type CanaryVerifyAction = (args: CanaryVerifyArgs) => Promise<unknown> | unknown;
-//#endregion
-//#region src/commands/pr-merge-check.d.ts
-type PrMergeCheckAction = (args: PrMergeCheckArgs) => PrMergeCheckProof;
-//#endregion
-//#region src/pr-review.d.ts
-interface PrReviewArgs extends LoadProjectProfileInput {
-  base: string;
-  cycle: number;
-  dispositions?: string;
-  findings?: string;
-  issue?: number;
-  maxCycles?: number;
-  mode: PrReviewMode;
-  output?: string;
-  verifyProof?: string;
-}
-interface PrReviewGitDependencies {
-  changedFiles: (cwd: string, base: string) => string[];
-  currentHeadSha: (cwd: string) => string;
-  isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
-  stablePatchId: (cwd: string, base: string) => string;
+  emptyTreeHash: (cwd: string) => string;
+  mergeBaseSha: (cwd: string, base: string) => string;
+  runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
   statusPorcelain: (cwd: string) => string;
+  stablePatchId: (cwd: string, base: string) => string;
 }
-interface PrReviewDependencies {
-  git?: PrReviewGitDependencies;
+interface PrVerifyDependencies {
+  cleanInstall?: CleanInstallResolutionDependencies | false;
+  env?: NodeJS.ProcessEnv;
+  git?: PrVerifyGitDependencies;
   hq?: HqIngestDependencies;
+  postCommitStatus?: PostCommitStatus;
   publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
-declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
+declare function runPrVerify(args: PrVerifyArgs, dependencies?: PrVerifyDependencies): PrVerifyProof;
 //#endregion
 //#region src/pr-publish.d.ts
 type PrPublishArgs = Omit<PrReadyArgs, "pr" | "throwWhenBlocked"> & {
@@ -2176,6 +2515,11 @@ interface PrPublishDependencies extends PrReadyDependencies {
   runPrReady?: typeof runPrReady;
   runPrReview?: (args: PrReviewArgs) => Promise<PrReviewProof>;
   runPrVerify?: (args: PrVerifyArgs) => Promise<PrVerifyProof>;
+  /**
+   * Injectable delay for the bounded hosted-run await (#348; tests only —
+   * production always waits the real interval).
+   */
+  sleep?: (ms: number) => Promise<void>;
 }
 /**
  * What became of the durable `pr:verify` binding for this publish. Reported in
@@ -2392,7 +2736,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: z.ZodString;
   outcome: z.ZodLiteral<"not-required">;
   patchId: z.ZodString;
-  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reason: z.ZodEnum<{
+    "no-applicable-mode": "no-applicable-mode";
+  }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>, readonly [z.ZodObject<{
   createdAt: z.ZodString;
@@ -2412,7 +2758,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: z.ZodString;
   outcome: z.ZodLiteral<"not-required">;
   patchId: z.ZodString;
-  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reason: z.ZodEnum<{
+    "no-applicable-mode": "no-applicable-mode";
+  }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>], {
   readonly 1: z.ZodObject<{
@@ -2423,7 +2771,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     observedAt: z.ZodString;
     outcome: z.ZodLiteral<"not-required">;
     patchId: z.ZodString;
-    reason: z.ZodLiteral<"docs-only-profile-bypass">;
+    reason: z.ZodEnum<{
+      "no-applicable-mode": "no-applicable-mode";
+    }>;
     reviewCycle: z.ZodNumber;
   }, z.core.$strict>;
 }, {
@@ -2440,7 +2790,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: string;
   outcome: "not-required";
   patchId: string;
-  reason: "docs-only-profile-bypass";
+  reason: "no-applicable-mode";
   reviewCycle: number;
   issue?: number | undefined;
   pr?: number | undefined;
@@ -2875,8 +3225,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -2954,8 +3304,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3024,8 +3374,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      review: "review";
       code: "code";
+      review: "review";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3097,7 +3447,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "review" | "code";
+  purpose: "code" | "review";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -3165,263 +3515,82 @@ interface FactoryTraceFilters {
   pr?: number | readonly number[];
   repo?: string | readonly string[];
   threadId?: string | readonly string[];
-  workerId?: string | readonly string[];
-}
-interface FactoryTraceDiagnostic {
-  code: "malformed-json" | "invalid-event" | "unknown-event-type" | "unknown-event-version";
-  event?: {
-    eventId: string;
-    eventType: string;
-    issue?: number;
-    pr?: number;
-    repo: string;
-    threadId?: string;
-    workerId?: string;
-  };
-  file: string;
-  line: number;
-  message: string;
-}
-interface ScanFactoryTraceOptions {
-  diagnosticsOnly?: boolean;
-  filters?: FactoryTraceFilters;
-  from: string;
-  malformed?: "diagnostic" | "throw";
-  repoRoot: string;
-  to: string;
-}
-interface ScanFactoryTraceResult {
-  diagnostics: FactoryTraceDiagnostic[];
-  events: ReadableFactoryTraceEvent[];
-}
-interface ScanFactoryTraceDiagnosticsOptions {
-  filters?: FactoryTraceFilters;
-  from: string;
-  repoRoot: string;
-  to: string;
-}
-declare const validateFactoryTraceEvent: (event: unknown) => FactoryTraceEvent;
-declare const toFactoryTraceEnvelope: (event: FactoryTraceEvent) => {
-  createdAt: string;
-  envelope: 1;
-  eventId: string;
-  payload: unknown;
-  repo: string;
-  type: string;
-  typeVersion: number;
-  issue?: number | undefined;
-  pr?: number | undefined;
-  thread?: string | undefined;
-  worker?: string | undefined;
-};
-interface AppendFactoryTraceEventResult {
-  event: FactoryTraceEvent;
-  filePath: string;
-  mirrorDiagnostics: TraceMirrorDiagnostic[];
-}
-declare const scanFactoryTraceEvents: ({
-  diagnosticsOnly,
-  filters,
-  from,
-  malformed,
-  repoRoot,
-  to
-}: ScanFactoryTraceOptions) => ScanFactoryTraceResult;
-/**
- * Diagnostics-only trace read (#707). Scans the shard window purely to surface
- * malformed / unknown-record diagnostics, without materializing (and then
- * discarding) every well-formed event. Malformed shards are always collected as
- * diagnostics, never thrown. Use when a consumer wants shard-corruption signal
- * but no event payloads — e.g. epic closeout after the orchestrator-metrics
- * removal.
- */
-declare const scanFactoryTraceDiagnostics: ({
-  filters,
-  from,
-  repoRoot,
-  to
-}: ScanFactoryTraceDiagnosticsOptions) => FactoryTraceDiagnostic[];
-//#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) and kept structurally parity-compatible with HQ's v1 wire validator
- * (`software-factory-hq/src/contracts/retro-schemas.ts`, PR #32): a complete
- * envelope emitted by this package validates verbatim against HQ's payload
- * validator. This module is the producer-side single source of truth for the
- * v1 wire shape and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}); the
- * exhaustive per-field/bound parity test in
- * `software-factory-hq/src/retro-envelope-parity.test.ts` (#46) walks this
- * schema against HQ's actual validator so ANY drift — field, type, bound,
- * enum, strictness — fails CI, not just drift a fixture happens to exercise.
- *
- * 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.
- *
- * 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.
- *
- * 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<{
-    mergeCheck: z.ZodOptional<z.ZodEnum<{
-      pass: "pass";
-      fail: "fail";
-      "not-run": "not-run";
-    }>>;
-    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).
- */
-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;
-} | {
-  disposition: "degraded";
-  raw: unknown;
-  schemaVersion: number | undefined;
+  workerId?: string | readonly string[];
+}
+interface FactoryTraceDiagnostic {
+  code: "malformed-json" | "invalid-event" | "unknown-event-type" | "unknown-event-version";
+  event?: {
+    eventId: string;
+    eventType: string;
+    issue?: number;
+    pr?: number;
+    repo: string;
+    threadId?: string;
+    workerId?: string;
+  };
+  file: string;
+  line: number;
+  message: string;
+}
+interface ScanFactoryTraceOptions {
+  diagnosticsOnly?: boolean;
+  filters?: FactoryTraceFilters;
+  from: string;
+  malformed?: "diagnostic" | "throw";
+  repoRoot: string;
+  to: string;
+}
+interface ScanFactoryTraceResult {
+  diagnostics: FactoryTraceDiagnostic[];
+  events: ReadableFactoryTraceEvent[];
+}
+interface ScanFactoryTraceDiagnosticsOptions {
+  filters?: FactoryTraceFilters;
+  from: string;
+  repoRoot: string;
+  to: string;
+}
+declare const validateFactoryTraceEvent: (event: unknown) => FactoryTraceEvent;
+declare const toFactoryTraceEnvelope: (event: FactoryTraceEvent) => {
+  createdAt: string;
+  envelope: 1;
+  eventId: string;
+  payload: unknown;
+  repo: string;
+  type: string;
+  typeVersion: number;
+  issue?: number | undefined;
+  pr?: number | undefined;
+  thread?: string | undefined;
+  worker?: string | undefined;
 };
+interface AppendFactoryTraceEventResult {
+  event: FactoryTraceEvent;
+  filePath: string;
+  mirrorDiagnostics: TraceMirrorDiagnostic[];
+}
+declare const scanFactoryTraceEvents: ({
+  diagnosticsOnly,
+  filters,
+  from,
+  malformed,
+  repoRoot,
+  to
+}: ScanFactoryTraceOptions) => ScanFactoryTraceResult;
 /**
- * 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.
+ * Diagnostics-only trace read (#707). Scans the shard window purely to surface
+ * malformed / unknown-record diagnostics, without materializing (and then
+ * discarding) every well-formed event. Malformed shards are always collected as
+ * diagnostics, never thrown. Use when a consumer wants shard-corruption signal
+ * but no event payloads — e.g. epic closeout after the orchestrator-metrics
+ * removal.
  */
-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 scanFactoryTraceDiagnostics: ({
+  filters,
+  from,
+  repoRoot,
+  to
+}: ScanFactoryTraceDiagnosticsOptions) => FactoryTraceDiagnostic[];
 //#endregion
 //#region src/interior-telemetry/gate-timing.d.ts
 declare const GATE_TIMING_SCHEMA_VERSION = 1;
@@ -3716,17 +3885,100 @@ 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/pr-readiness/review-requiredness.d.ts
-interface DocsOnlyReviewBypassState {
-  applies: boolean;
+//#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 const resolveDocsOnlyReviewBypassState: (input: {
-  classification: DiffClassification;
-  docsOnlyReviewBypass?: boolean;
-}) => DocsOnlyReviewBypassState;
 declare namespace readiness_evaluation_d_exports {
-  export { CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON, DRAFT_BLOCKER_REASON, DocsOnlyReviewBypassState, EvaluationInput, ManagedReadinessLedger, PENDING_CHECKS_BLOCKER_REASON_PREFIX, PreviewDeployProof, PreviewSeedStatus, READINESS_REPAIR_CODES, RENDER_PR_BODY_SECTIONS_BLOCKER_REASON, ReadinessRepair, ReadinessStatus, SCHEMA_VERSION, SECURITY_UNTYPED_REVIEW_BLOCKER_REASON, evaluateReadiness, managedReadinessLedgerSchema, readinessExitCode, readinessRepairSchema, resolveDocsOnlyReviewBypassState, validateManagedReadinessLedger };
+  export { CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON, DRAFT_BLOCKER_REASON, EvaluationInput, ManagedReadinessLedger, PENDING_CHECKS_BLOCKER_REASON_PREFIX, PreviewDeployProof, PreviewSeedStatus, READINESS_REPAIR_CODES, RENDER_PR_BODY_SECTIONS_BLOCKER_REASON, ReadinessRepair, ReadinessStatus, SCHEMA_VERSION, SECURITY_UNTYPED_REVIEW_BLOCKER_REASON, evaluateReadiness, managedReadinessLedgerSchema, readinessExitCode, readinessRepairSchema, validateManagedReadinessLedger };
 }
 declare const CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON = "Correctness review proof is not a head-bound typed findings verdict; re-run pr:review with a valid findings file.";
 declare const SECURITY_UNTYPED_REVIEW_BLOCKER_REASON = "Security review proof is not a head-bound typed findings verdict; re-run pr:review with a valid findings file.";
@@ -3757,7 +4009,6 @@ interface EvaluationInput {
   verificationProof?: VerificationProofState;
   docsOnlyVerifyBaselineHeadShas?: string[];
   docsOnlySinceReviewProof?: boolean;
-  docsOnlyReviewBypass?: boolean;
   externalRequiredChecks?: RequiredCheck[];
   evidenceEnvelopes?: LoadedEvidenceEnvelope[];
   mergeBaseSha?: string;
@@ -3772,6 +4023,7 @@ interface EvaluationInput {
   };
   handledCommentSessionId?: string;
   handledCommentClearedAt?: string;
+  waveReviewDemand?: Pick<WaveReviewDemand, "review" | "wave">;
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
   blockingReasons: string[];
@@ -4134,90 +4386,6 @@ declare const isProductionHqUrl: (url: string) => boolean;
  * surfaced with actionable guidance; any non-2xx throws.
  */
 declare const publishEpicStructure: (args: PublishEpicStructureArgs) => Promise<PublishEpicStructureResult>;
-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/review-focus.d.ts
 declare const REVIEW_FOCUS_SECTION = "Review focus";
@@ -4323,7 +4491,7 @@ declare function assertWorkerCheckoutAllowed({
 interface CreateProgramOptions {
   actions?: {
     boundaryCheck?: BoundaryCheckAction;
-    canaryVerify?: CanaryVerifyAction;
+    demandWaive?: DemandWaiveAction;
     prMergeCheck?: PrMergeCheckAction;
     prPublish?: PrPublishAction;
     prReady?: PrReadyAction;
@@ -4335,4 +4503,4 @@ interface CreateProgramOptions {
 declare function createProgram(options?: CreateProgramOptions): Command;
 declare function run(argv?: string[]): Promise<void>;
 //#endregion
-export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type BuildRetroEnvelopeInput, type CloudflareAccessServiceToken, CreateProgramOptions, DEFAULT_FACTORY_REPOSITORY, type DagDocument, 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 IssueReviewFocus, type LadderDispositionDeclaration, type ParsedRetroEnvelope, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, 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 TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationReuse, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, assembleReviewPrompt, assertWorkerCheckoutAllowed, 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, inferFixedInThreadDispositions, isProductionHqUrl, isRetroEnvelopeWireComplete, loadProjectProfile, normalizeIssueComments, openLadderFindings, parseRetroEnvelope, planPublishFollowUp, worktree_held_branch_d_exports as prMergePreflight, pr_body_metadata_d_exports as prReadinessBodyMetadata, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, merge_identity_d_exports as prReadinessMergeIdentity, post_readiness_comments_d_exports as prReadinessPostComments, 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, publishEpicStructure, readPrMergeCheckProof, readPrReadyProof, readPrReviewProof, resolveDocsOnlyReviewBypass, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runEvidenceEmit, runPrMergeCheck, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateFactoryTraceEvent, validatePrMergeCheckProof, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, worktree_scratch_files_d_exports as worktreeScratchFiles };
+export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, 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 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 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 TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationReuse, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertWorkerCheckoutAllowed, authorizeDemandWaiver, 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, inferFixedInThreadDispositions, isProductionHqUrl, isRetroEnvelopeWireComplete, loadProjectProfile, normalizeIssueComments, openLadderFindings, parseRetroEnvelope, planPublishFollowUp, worktree_held_branch_d_exports as prMergePreflight, pr_body_metadata_d_exports as prReadinessBodyMetadata, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, merge_identity_d_exports as prReadinessMergeIdentity, post_readiness_comments_d_exports as prReadinessPostComments, 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, publishEpicStructure, readDemandWaivers, readPrMergeCheckProof, readPrReadyProof, readPrReviewProof, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrMergeCheck, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrMergeCheckProof, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };