@patronage/software-factory 0.30.0 → 1.0.0-alpha.1

package/dist/index.d.ts

@@ -61,8 +61,8 @@ declare const boundaryReviewProofBaseSchema: z.ZodObject<{
   }>;
   producer: z.ZodString;
   rung: z.ZodEnum<{
-    oracle: "oracle";
     "independent-model": "independent-model";
+    oracle: "oracle";
     human: "human";
   }>;
   schemaVersion: z.ZodLiteral<1>;
@@ -105,8 +105,8 @@ declare const boundaryReviewProofSchema: z.ZodObject<{
   }>;
   producer: z.ZodString;
   rung: z.ZodEnum<{
-    oracle: "oracle";
     "independent-model": "independent-model";
+    oracle: "oracle";
     human: "human";
   }>;
   schemaVersion: z.ZodLiteral<1>;
@@ -533,6 +533,13 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     endpoint: z.ZodIntersection<z.ZodString, z.ZodString>;
   }, z.core.$strict>>;
+  impact: z.ZodOptional<z.ZodObject<{
+    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>>;
@@ -547,8 +554,8 @@ 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";
+        trivial: "trivial";
         "non-trivial": "non-trivial";
       }>>;
     }, z.core.$strict>>;
@@ -563,6 +570,7 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     commands: z.ZodArray<z.ZodObject<{
       command: z.ZodString;
       description: z.ZodString;
+      impactTarget: z.ZodOptional<z.ZodString>;
       name: z.ZodString;
       requiredCheck: z.ZodOptional<z.ZodString>;
       scope: z.ZodDefault<z.ZodEnum<{
@@ -763,8 +771,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "active">;
 type MergeFreezeState = z.infer<typeof mergeFreezeStateSchema>;
 /**
- * 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
+ * The write side of this contract lives in the generated merge-target push
+ * Verify workflow (#356, ADR 0016 as amended; #429): 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.
@@ -784,7 +792,7 @@ interface MergeFreezeStore {
  * `read` above collapses three different situations into one refusal, because
  * merge time treated all of them as "do not merge". Readiness distinguishes
  * them: a settled generation is the writer's verdict, a **settling** one is the
- * window between a merge landing and its main-push verify completing (a
+ * window between a merge landing and its merge-target Verify completing (a
  * running generation, or a missing generation proven by the immediately prior
  * settled tip plus a current source-pinned verify run), and an **unreadable**
  * one is ambiguous, malformed, foreign-App, or unavailable state. Same
@@ -1126,8 +1134,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<{
@@ -1140,8 +1148,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>>;
@@ -1191,15 +1199,15 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       unknown: "unknown";
       critical: "critical";
       high: "high";
-      low: "low";
       medium: "medium";
+      low: "low";
     }>>;
     highestOpenSeverity: z.ZodOptional<z.ZodEnum<{
       unknown: "unknown";
       critical: "critical";
       high: "high";
-      low: "low";
       medium: "medium";
+      low: "low";
     }>>;
     maxReviewCycles: z.ZodOptional<z.ZodNumber>;
     nonBlockingFindings: z.ZodNumber;
@@ -1227,8 +1235,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     }>;
     stage: z.ZodEnum<{
       gate: "gate";
-      interior: "interior";
       "interior-complete": "interior-complete";
+      interior: "interior";
     }>;
   }, z.core.$strip>>;
   reviewRuns: z.ZodOptional<z.ZodArray<z.ZodType<PrReviewResult, unknown, z.core.$ZodTypeInternals<PrReviewResult, unknown>>>>;
@@ -1506,19 +1514,90 @@ 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.
+ */
+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/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";
+    trivial: "trivial";
     "non-trivial": "non-trivial";
   }>>;
 }, z.core.$strict>;
 type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
 interface RequiredCheckScopeContext {
   classification: DiffClassification | undefined;
+  impactStamp?: ImpactStamp;
 }
 interface ScopeDecision {
   inScope: boolean;
@@ -1546,7 +1625,7 @@ declare const resolveAuthoringSessionIds: ({
   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, evaluateRequiredChecks, evidenceBindingFresh, evidenceEnvelopeSchema, evidenceReviewIndependence, loadEvidenceEnvelopes, parseEvidenceEnvelope, requiredCheckInScope, requiredCheckScopeSchema, resolveAuthoringSessionIds };
+  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<{
@@ -1568,8 +1647,8 @@ declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
   producer: z.ZodString;
   requestId: z.ZodOptional<z.ZodString>;
   rung: z.ZodOptional<z.ZodEnum<{
-    oracle: "oracle";
     "independent-model": "independent-model";
+    oracle: "oracle";
     human: "human";
   }>>;
   schemaVersion: z.ZodLiteral<1>;
@@ -1595,8 +1674,8 @@ declare const evidenceEnvelopeSchema: z.ZodObject<{
   producer: z.ZodString;
   requestId: z.ZodOptional<z.ZodString>;
   rung: z.ZodOptional<z.ZodEnum<{
-    oracle: "oracle";
     "independent-model": "independent-model";
+    oracle: "oracle";
     human: "human";
   }>>;
   schemaVersion: z.ZodLiteral<1>;
@@ -1645,6 +1724,26 @@ type LoadedEvidenceEnvelope = {
   ok: false;
   path: string;
 };
+/**
+ * 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.
+ *
+ * `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 boundFailingCheckNames: ({
+  candidate,
+  checkType,
+  envelopes
+}: {
+  candidate: EvidenceCandidateIdentity;
+  checkType: EvidenceCheckType;
+  envelopes: LoadedEvidenceEnvelope[];
+}) => string[];
 interface RequiredCheckEvaluationInput {
   authoringSessionIds: string[];
   candidate: EvidenceCandidateIdentity;
@@ -1781,7 +1880,7 @@ 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, PrVerifyProof, PrVerifySchemaVersion, ResolvedPrVerifyMode, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, VerificationHeadShas, VerificationProofState, VerifiedHeadShas, prVerifyFullHeadShasForDiff, prVerifyProofHeadShas, readPrVerifyProof, resolveVerifyProofApplicability, validatePrVerifyProof, verificationProofApplicabilityFor, verificationProofBlockingReason, verificationProofForReadiness, verificationProofStateFor, verifyProofIdentityMatches, verifyProofPassed };
+  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[];
@@ -1796,6 +1895,15 @@ 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";
 }
@@ -1810,6 +1918,21 @@ interface PrVerifyExecutedCommand {
   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;
@@ -1830,8 +1953,10 @@ interface PrVerifyProof {
   endedAt: string;
   executedCommands?: PrVerifyExecutedCommand[];
   headSha: string;
+  impactStamp?: ImpactStamp;
   mode: ResolvedPrVerifyMode;
   mergeBaseSha?: string;
+  notRequiredCommands?: PrVerifyNotRequiredCommand[];
   outcome?: "aborted" | "passed";
   patchId?: string;
   profilePath: string;
@@ -1855,6 +1980,28 @@ declare const verifyProofIdentityMatches: ({
   };
   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,
+  proof
+}: {
+  candidate: {
+    headSha: string;
+    patchId: string;
+  };
+  proof: PrVerifyProof | undefined;
+}) => ImpactStamp | undefined;
 declare const prVerifyFullHeadShasForDiff: ({
   docsOnlyDeltaAcceptedSince,
   files,
@@ -2040,9 +2187,9 @@ declare const retroEnvelopeV1Schema: z.ZodObject<{
   kind: z.ZodLiteral<"retro-envelope">;
   outcome: z.ZodOptional<z.ZodObject<{
     status: z.ZodEnum<{
+      blocked: "blocked";
       success: "success";
       fail: "fail";
-      blocked: "blocked";
       "ship-with-followups": "ship-with-followups";
     }>;
     verdict: z.ZodOptional<z.ZodString>;
@@ -2148,8 +2295,8 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
     wave: z.ZodString;
   }, z.core.$strip>>;
   demandedRung: z.ZodOptional<z.ZodEnum<{
-    oracle: "oracle";
     "independent-model": "independent-model";
+    oracle: "oracle";
     human: "human";
   }>>;
   epicIssue: z.ZodNumber;
@@ -2164,8 +2311,8 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
     commentUrl: z.ZodOptional<z.ZodString>;
     producer: z.ZodString;
     rung: z.ZodEnum<{
-      oracle: "oracle";
       "independent-model": "independent-model";
+      oracle: "oracle";
       human: "human";
     }>;
     sessionId: z.ZodOptional<z.ZodString>;
@@ -2368,6 +2515,7 @@ interface PrVerifyGitDependencies {
   emptyTreeHash: (cwd: string) => string;
   mergeBaseSha: (cwd: string, base: string) => string;
   runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
+  showFileAtRef?: (cwd: string, ref: string, absolutePath: string) => string | undefined;
   statusPorcelain: (cwd: string) => string;
   stablePatchId: (cwd: string, base: string) => string;
 }
@@ -3191,8 +3339,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
       high: "high";
-      low: "low";
       medium: "medium";
+      low: "low";
       xhigh: "xhigh";
     }>;
     engine: z.ZodString;
@@ -3204,18 +3352,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     }>;
     model: z.ZodString;
     tier: z.ZodEnum<{
+      oracle: "oracle";
       review: "review";
       delegate: "delegate";
-      oracle: "oracle";
       workhorse: "workhorse";
       scout: "scout";
     }>;
   }, z.core.$strict>;
   startedAt: z.ZodString;
   tier: z.ZodEnum<{
+    oracle: "oracle";
     review: "review";
     delegate: "delegate";
-    oracle: "oracle";
     workhorse: "workhorse";
     scout: "scout";
   }>;
@@ -3270,8 +3418,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
       high: "high";
-      low: "low";
       medium: "medium";
+      low: "low";
       xhigh: "xhigh";
     }>;
     engine: z.ZodString;
@@ -3283,18 +3431,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     }>;
     model: z.ZodString;
     tier: z.ZodEnum<{
+      oracle: "oracle";
       review: "review";
       delegate: "delegate";
-      oracle: "oracle";
       workhorse: "workhorse";
       scout: "scout";
     }>;
   }, z.core.$strict>;
   startedAt: z.ZodString;
   tier: z.ZodEnum<{
+    oracle: "oracle";
     review: "review";
     delegate: "delegate";
-    oracle: "oracle";
     workhorse: "workhorse";
     scout: "scout";
   }>;
@@ -3340,8 +3488,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
         high: "high";
-        low: "low";
         medium: "medium";
+        low: "low";
         xhigh: "xhigh";
       }>;
       engine: z.ZodString;
@@ -3353,18 +3501,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
       }>;
       model: z.ZodString;
       tier: z.ZodEnum<{
+        oracle: "oracle";
         review: "review";
         delegate: "delegate";
-        oracle: "oracle";
         workhorse: "workhorse";
         scout: "scout";
       }>;
     }, z.core.$strict>;
     startedAt: z.ZodString;
     tier: z.ZodEnum<{
+      oracle: "oracle";
       review: "review";
       delegate: "delegate";
-      oracle: "oracle";
       workhorse: "workhorse";
       scout: "scout";
     }>;
@@ -3409,15 +3557,15 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: string;
   purpose: "review" | "code";
   slotResolution: {
-    effort: "high" | "low" | "medium" | "xhigh";
+    effort: "high" | "medium" | "low" | "xhigh";
     engine: string;
     layerSource: "committedDefault" | "operatorSession" | "userConfig";
     model: string;
-    tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
+    tier: "oracle" | "review" | "delegate" | "workhorse" | "scout";
     fallbackTier?: "delegate" | undefined;
   };
   startedAt: string;
-  tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
+  tier: "oracle" | "review" | "delegate" | "workhorse" | "scout";
   tokenUsage: {
     source: "cursor-csv" | "codex-json" | "cursor-json" | "claude-json";
     status: "available";
@@ -3776,8 +3924,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
   boundary: z.ZodString;
   closeout: z.ZodOptional<z.ZodObject<{
     review: z.ZodEnum<{
-      oracle: "oracle";
       "independent-model": "independent-model";
+      oracle: "oracle";
       human: "human";
     }>;
   }, z.core.$loose>>;
@@ -3785,8 +3933,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
   prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   schemaVersion: z.ZodLiteral<1>;
   topology: z.ZodEnum<{
-    flagged: "flagged";
     "each-to-main": "each-to-main";
+    flagged: "flagged";
     stacked: "stacked";
   }>;
   waves: z.ZodArray<z.ZodObject<{
@@ -3794,8 +3942,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
     issues: z.ZodArray<z.ZodNumber>;
     name: z.ZodString;
     review: z.ZodEnum<{
-      oracle: "oracle";
       "independent-model": "independent-model";
+      oracle: "oracle";
       human: "human";
     }>;
   }, z.core.$loose>>;
@@ -3804,8 +3952,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
   boundary: z.ZodString;
   closeout: z.ZodOptional<z.ZodObject<{
     review: z.ZodEnum<{
-      oracle: "oracle";
       "independent-model": "independent-model";
+      oracle: "oracle";
       human: "human";
     }>;
   }, z.core.$loose>>;
@@ -3813,8 +3961,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
   prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   schemaVersion: z.ZodLiteral<1>;
   topology: z.ZodEnum<{
-    flagged: "flagged";
     "each-to-main": "each-to-main";
+    flagged: "flagged";
     stacked: "stacked";
   }>;
   waves: z.ZodArray<z.ZodObject<{
@@ -3822,8 +3970,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
     issues: z.ZodArray<z.ZodNumber>;
     name: z.ZodString;
     review: z.ZodEnum<{
-      oracle: "oracle";
       "independent-model": "independent-model";
+      oracle: "oracle";
       human: "human";
     }>;
   }, z.core.$loose>>;
@@ -3908,7 +4056,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;
@@ -3957,7 +4105,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;
@@ -3973,8 +4121,8 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
       nonBlockingFindings: number;
       openFindings: number;
       windowExhausted: boolean;
-      highestBlockingSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
-      highestOpenSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      highestBlockingSeverity?: "unknown" | "critical" | "high" | "medium" | "low" | undefined;
+      highestOpenSeverity?: "unknown" | "critical" | "high" | "medium" | "low" | undefined;
       maxReviewCycles?: number | undefined;
       reviewCycle?: number | undefined;
       staleRepeatFindings?: number | undefined;
@@ -3985,7 +4133,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
         interior: number;
       };
       nextAction: "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human" | "advance-to-gate" | "run-interior-cycle";
-      stage: "gate" | "interior" | "interior-complete";
+      stage: "gate" | "interior-complete" | "interior";
       forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
     } | undefined;
     reviewRuns?: PrReviewResult[] | undefined;
@@ -4310,6 +4458,169 @@ declare const appendReviewLadderStageTraceEvent: ({
 }) => AppendFactoryTraceEventResult;
 declare const tryAppendReviewLadderStageTraceEvent: (input: Parameters<typeof appendReviewLadderStageTraceEvent>[0]) => ReviewLadderStageTraceWriteResult;
 //#endregion
+//#region src/verification-battery.d.ts
+type BatteryDisposition = "executed" | "not-required";
+/**
+ * The structural subset of a profile verification command this planner reads.
+ * Kept structural — not a `Pick` of the profile type — so this leaf module
+ * never imports `profile.ts` (which already depends on the impact modules).
+ */
+interface BatteryCandidateCommand {
+  impactTarget?: string;
+  name: string;
+}
+interface BatteryCommandDisposition {
+  /** Why this command runs or is withheld — the stamp's own words when scoped. */
+  basis: string;
+  disposition: BatteryDisposition;
+  /** The declared impact target, when the command declares one. */
+  impactTarget?: string;
+  name: string;
+}
+/**
+ * A withheld command. `impactTarget` is REQUIRED here, not optional: only a
+ * command that declared a target can be released, so the proof record can
+ * always name the target whose classification released it.
+ */
+interface ScopedOutCommand {
+  basis: string;
+  impactTarget: string;
+  name: string;
+}
+interface VerificationBatteryPlan<Command> {
+  /** Every input command with its disposition, in input order. */
+  dispositions: BatteryCommandDisposition[];
+  /** The commands to run, in input order. */
+  execute: Command[];
+  /** The withheld commands, in input order. Recorded on the proof. */
+  notRequired: ScopedOutCommand[];
+}
+/**
+ * Plan one verification battery against the candidate's impact stamp.
+ *
+ * Pure and total: it makes a decision, it never reads a proof, a profile file,
+ * or the filesystem, and no INPUT can make it throw — every doubt path is a
+ * decision, not an exception. A malformed CALL is the one exception to that,
+ * and deliberately so: omitting `vetoedTargets` is API misuse rather than data
+ * doubt, and it throws (see {@link assertVetoedTargets}).
+ *
+ * `stamp` must already be trusted by
+ * the caller — inside `pr:verify` that is the stamp just computed for this
+ * candidate's own identity triple; anywhere else it is `trustedImpactStamp`'s
+ * output or `undefined`.
+ */
+declare const planVerificationBattery: <Command extends BatteryCandidateCommand>({
+  commands,
+  stamp,
+  vetoedTargets
+}: {
+  commands: readonly Command[];
+  stamp: ImpactStamp | undefined;
+  /**
+   * Target names with a current, candidate-bound FAILING envelope. Scoping is
+   * withheld for these whatever the stamp says.
+   *
+   * REQUIRED, with no default, on purpose: the veto is the rule that keeps a
+   * scoped-away command from leaving a demand nothing on this head could meet,
+   * and a defaulted `[]` cannot tell "I inspected the envelopes and found no
+   * bound failure" apart from "I never looked". Pass the result of
+   * `boundFailingCheckNames`; pass `[]` only to mean the former.
+   *
+   * This tightening is deliberately visible to `api:check` as a breaking
+   * signature change (pre-1.0, no external callers yet): an external producer
+   * must be made to state the veto set rather than silently skip it.
+   */
+  vetoedTargets: readonly string[];
+}) => VerificationBatteryPlan<Command>;
+/** 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;
@@ -4343,4 +4654,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_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, 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, 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 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 };