@patronage/software-factory 1.0.0-alpha.41 → 1.0.0-alpha.43

package/dist/index.d.ts

@@ -228,7 +228,7 @@ interface GithubIssueComment {
 }
 declare const normalizeIssueComments: (value: GithubIssueCommentApi[] | GithubIssueCommentApi[][]) => GithubIssueComment[];
 declare namespace boundary_review_proof_d_exports {
-  export { BOUNDARY_REVIEW_PROOF_KIND, BoundaryReviewProof, BoundaryReviewProofComment, boundaryReviewProofAuthorsSeen, boundaryReviewProofSchema, selectBoundaryReviewProof, undispositionedBlockingFindings };
+  export { BOUNDARY_REVIEW_PROOF_KIND, BoundaryReviewProof, BoundaryReviewProofComment, BoundaryReviewProofParseFailure, boundaryReviewProofAuthorsSeen, boundaryReviewProofParseFailures, boundaryReviewProofSchema, selectBoundaryReviewProof, undispositionedBlockingFindings };
 }
 declare const BOUNDARY_REVIEW_PROOF_KIND = "boundary-review-proof";
 declare const boundaryReviewProofBaseSchema: z.ZodObject<{
@@ -325,8 +325,14 @@ interface BoundaryReviewProofComment {
   commentId?: string | number;
   commentUrl?: string;
 }
+interface BoundaryReviewProofParseFailure {
+  commentAuthor: string;
+  commentUrl?: string;
+  parseError: string;
+}
 declare const selectBoundaryReviewProof: (comments: GithubIssueComment[], boundary: string, declaredBy: string) => BoundaryReviewProofComment | undefined;
 declare const boundaryReviewProofAuthorsSeen: (comments: GithubIssueComment[], boundary: string) => string[];
+declare const boundaryReviewProofParseFailures: (comments: GithubIssueComment[], boundary: string) => BoundaryReviewProofParseFailure[];
 declare const undispositionedBlockingFindings: (proof: BoundaryReviewProof) => string[];
 //#endregion
 //#region src/boundary-membership-graph.d.ts
@@ -2500,6 +2506,12 @@ interface CompletedFactoryCheckSnapshot {
   readonly detailsUrl?: string;
   readonly headSha: string;
   readonly name: FactoryPrStatusCheckName;
+  /**
+   * Merge freeze only (#1501): the cancellation-only generations, newest
+   * first, that the freeze selection read past to reach this snapshot's
+   * generation (#1158). Absent when the newest generation stands.
+   */
+  readonly readPastRunIds?: readonly number[];
 }
 interface FailedPreviewSnapshot {
   readonly completedAt: string;

package/dist/index.js

@@ -22,7 +22,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { pathToFileURL } from "node:url";
 //#region package.json
 var name = "@patronage/software-factory";
-var version = "1.0.0-alpha.41";
+var version = "1.0.0-alpha.43";
 //#endregion
 //#region src/git-globals-parse.ts
 const VALUE_TAKING_GIT_OPTIONS = new Set([
@@ -2507,6 +2507,7 @@ const coveredSetDivergences = (computed, proof) => {
 var boundary_review_proof_exports = /* @__PURE__ */ __exportAll({
 	BOUNDARY_REVIEW_PROOF_KIND: () => BOUNDARY_REVIEW_PROOF_KIND$1,
 	boundaryReviewProofAuthorsSeen: () => boundaryReviewProofAuthorsSeen,
+	boundaryReviewProofParseFailures: () => boundaryReviewProofParseFailures,
 	boundaryReviewProofSchema: () => boundaryReviewProofSchema$1,
 	selectBoundaryReviewProof: () => selectBoundaryReviewProof,
 	undispositionedBlockingFindings: () => undispositionedBlockingFindings
@@ -2561,8 +2562,11 @@ const boundaryReviewProofSchema$1 = z.object({
 	}).passthrough().optional()
 }).passthrough();
 const FENCED_JSON_PATTERN = /```json[ \t]*\r?\n(?<inner>[\s\S]*?)```/gu;
-const collectValidBoundaryReviewProofs = (comments, boundary) => {
-	const entries = [];
+const scanBoundaryReviewProofs = (comments, boundary) => {
+	const scan = {
+		failed: [],
+		valid: []
+	};
 	for (const comment of comments) {
 		const commentAuthor = comment.author.login;
 		if (!commentAuthor) continue;
@@ -2576,8 +2580,17 @@ const collectValidBoundaryReviewProofs = (comments, boundary) => {
 			}
 			if (typeof raw !== "object" || raw === null || raw.kind !== "boundary-review-proof") continue;
 			const parsed = boundaryReviewProofSchema$1.safeParse(raw);
-			if (!parsed.success || parsed.data.boundary !== boundary) continue;
-			entries.push({
+			if (!parsed.success) {
+				const rawBoundary = raw.boundary;
+				if (typeof rawBoundary !== "string" || rawBoundary === boundary) scan.failed.push({
+					commentAuthor,
+					...comment.url === void 0 ? {} : { commentUrl: comment.url },
+					parseError: formatZodIssues(parsed.error)
+				});
+				continue;
+			}
+			if (parsed.data.boundary !== boundary) continue;
+			scan.valid.push({
 				commentAuthor,
 				...comment.id === void 0 ? {} : { commentId: comment.id },
 				...comment.url === void 0 ? {} : { commentUrl: comment.url },
@@ -2585,12 +2598,12 @@ const collectValidBoundaryReviewProofs = (comments, boundary) => {
 			});
 		}
 	}
-	return entries;
+	return scan;
 };
 const selectBoundaryReviewProof = (comments, boundary, declaredBy) => {
 	let selected;
 	const declaredByLower = declaredBy.toLowerCase();
-	for (const entry of collectValidBoundaryReviewProofs(comments, boundary)) {
+	for (const entry of scanBoundaryReviewProofs(comments, boundary).valid) {
 		if (entry.commentAuthor.toLowerCase() !== declaredByLower) continue;
 		selected = {
 			...entry.commentId === void 0 ? {} : { commentId: entry.commentId },
@@ -2602,9 +2615,10 @@ const selectBoundaryReviewProof = (comments, boundary, declaredBy) => {
 };
 const boundaryReviewProofAuthorsSeen = (comments, boundary) => {
 	const authors = /* @__PURE__ */ new Set();
-	for (const entry of collectValidBoundaryReviewProofs(comments, boundary)) authors.add(entry.commentAuthor);
+	for (const entry of scanBoundaryReviewProofs(comments, boundary).valid) authors.add(entry.commentAuthor);
 	return [...authors];
 };
+const boundaryReviewProofParseFailures = (comments, boundary) => scanBoundaryReviewProofs(comments, boundary).failed;
 const undispositionedBlockingFindings = (proof) => proof.findings.filter((finding) => (finding.category !== "maintainability" || finding.blockingAfterCap === true) && finding.disposition === void 0).map((finding) => `boundary finding "${finding.title}" (category ${finding.category ?? "unknown"}) has no disposition; fix it or record waived / follow-up-filed`);
 //#endregion
 //#region src/boundary-topology.ts
@@ -3030,6 +3044,42 @@ const waivedDemandSchema = z.object({
 	session: z.string().trim().min(1).optional(),
 	unmetReasons: z.array(z.string().min(1)).min(1)
 });
+/**
+* The demands an operator waiver can reach (#354; moved out of `pr:ready` by
+* #1492 so `demand:waive` refuses by the same contract every reader folds by,
+* and can never record an authorization nothing applies).
+*
+* `pr:ready` folds the merge freeze, the profile's external required checks
+* and the boundary wave's review rung — the demands the resolver puts *in
+* force* for one candidate — plus the review-round limit (#1280), which exists
+* only to be waived and which `pr:review --assemble` folds too.
+* `boundary:check --final` folds the closeout pin `child-issue-open` (#901);
+* readiness never raises that demand, so naming it here widens nothing at
+* `pr:ready`.
+*
+* Everything else stays unwaivable. Structural refusals — candidate identity,
+* proof binding, an unreadable demand authority, wave membership — were never
+* waivable at merge time and are not waivable now; in `pr:ready` most of them
+* refuse by throwing before any blocker list exists. The evidence gates
+* readiness has always owned (verify, review modes, draft, human blockers) and
+* GitHub's own check and merge-state rollups are satisfied or not; a waiver is
+* not a second way to pass them.
+*/
+const WAIVABLE_DEMAND_KEYS = [
+	DEMAND_KEYS.mergeFreeze,
+	DEMAND_KEYS.reviewRoundLimit,
+	DEMAND_KEYS.childIssueOpen
+];
+/** Every instance of these qualified families is waivable at `pr:ready`. */
+const WAIVABLE_QUALIFIED_DEMAND_FAMILIES = ["required-check", "review-rung"];
+const isWaivableDemand = (demand) => WAIVABLE_DEMAND_KEYS.includes(demand) || WAIVABLE_QUALIFIED_DEMAND_FAMILIES.some((family) => demand.startsWith(`${family}:`));
+/**
+* Why `demand:waive` refuses a well-formed key outside that contract. It names
+* the key and the waivable set, built from the same lists the predicate reads,
+* and says nothing about the demand itself: whether it is in force or met is
+* the reader's to decide, and a refused waiver changes neither.
+*/
+const ineligibleWaiverRefusal = (demand) => `demand:waive refuses demand key "${demand}": no factory command applies a waiver of it, so a recorded waiver would authorize nothing. A waiver can name ${WAIVABLE_DEMAND_KEYS.join(", ")}, or a ${WAIVABLE_QUALIFIED_DEMAND_FAMILIES.map((family) => `${family}:<value>`).join(" or ")} key.`;
 /** The waivers that bind one candidate: same PR, same head. */
 const selectWaiversForCandidate = ({ headSha, pr, waivers }) => headSha === void 0 ? [] : waivers.filter((waiver) => waiver.candidate.pr === pr && waiver.candidate.headSha === headSha);
 /**
@@ -8835,7 +8885,7 @@ const readTransportedVerifyProof = (value, text) => {
 */
 const parsePrVerifyCheckPayload = (text) => {
 	if (!text?.trim()) return;
-	const candidate = (text.match(/```(?:json)?\s*(?<body>[\s\S]*?)```/u)?.groups?.body ?? text).trim();
+	const candidate = (text.match(/```(?:json)?\s*(?<body>[\s\S]*?)\n```/u)?.groups?.body ?? text).trim();
 	try {
 		const parsed = JSON.parse(candidate);
 		if (parsed.schemaVersion !== PR_VERIFY_CHECK_PAYLOAD_SCHEMA_VERSION || parsed.kind !== "pr-verify-proof-binding" || typeof parsed.headSha !== "string" || parsed.headSha.length === 0 || !isResolvedPrVerifyMode(parsed.mode) || !isOutcome(parsed.outcome)) return;
@@ -9632,63 +9682,199 @@ const completeCheckRunPages = (pages) => {
 	const runs = pages.flatMap((page) => page.check_runs);
 	return pages.every((page) => page.total_count === runs.length) ? runs : void 0;
 };
+/** The only instant shape either pr-verify reader takes from a typed proof. */
+const CANONICAL_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/u;
+/** An instant in epoch milliseconds, rounded down to its whole second. */
+const wholeSecondMs = (ms) => Math.floor(ms / 1e3) * 1e3;
+/**
+* When the verification a transported typed proof records started: its
+* `endedAt` minus its `durationMs`, rounded down to the whole second. Nothing
+* when `endedAt` is not canonical UTC or `durationMs` is not a finite
+* non-negative number; the run is then ordered like one without a typed proof.
+*/
+const proofStartMs = (proof) => {
+	if (proof === void 0 || !CANONICAL_UTC.test(proof.endedAt)) return;
+	const { durationMs } = proof;
+	if (!(Number.isFinite(durationMs) && durationMs >= 0)) return;
+	const startMs = Date.parse(proof.endedAt) - durationMs;
+	return Number.isFinite(startMs) ? wholeSecondMs(startMs) : void 0;
+};
+/**
+* Whether a run is a pass: completed with conclusion `success`, and its bound
+* payload has outcome `passed`. The hosted gate's jq calls this `passing`.
+*/
+const isPassingRun = (run, payload) => payload !== void 0 && run.status === "completed" && run.conclusion === "success" && payload.outcome === "passed";
+/**
+* When a passing run's verification started, by its transported typed proof
+* (`proofStartMs`). Nothing for any other run, which is ordered at its
+* `started_at` whatever proof it carries (#1506).
+*/
+const passingProofStartMs = (run, payload) => isPassingRun(run, payload) ? proofStartMs(payload.verificationProof) : void 0;
 /** The same bound payload with the same status and conclusion. */
 const sameVerdict = (one, other) => one.payload !== void 0 && (one.run.status ?? "") === (other.run.status ?? "") && (one.run.conclusion ?? "") === (other.run.conclusion ?? "") && isDeepStrictEqual(one.payload, other.payload);
 /**
-* The newest generation of the `pr:verify` proof at one head (#1409), or
-* nothing when no single generation can be trusted. It is the rule #1408 gave
-* the proof resume (`proof-resume.ts`, since reverted by #1411), applied to
-* this reader:
-*
-* - A run whose bound payload transports a typed proof is ordered at the
-*   `endedAt` that proof records, never by when it reached GitHub. Runs that
-*   carry the same such payload with the same status and conclusion are one
-*   generation posted more than once (`pr:verify` posts, `pr:publish`
-*   re-posts), so an older pass re-posted after a newer failure does not
-*   outrank it, and the normal post plus re-post is not a tie.
-* - Any other run is its own generation at its `started_at`: no bound payload,
-*   or a proof over the text cap that travels without its typed proof. The
-*   factory records a proof before it posts it, so that is the latest its
-*   proof could have been recorded, and it still vetoes every pass recorded
-*   before it was posted.
-* - Such a run carries no generation identity, so it is never grouped. Two
-*   separate executions with the same command names and verdict post the same
-*   compact payload, and so does a re-post. When the newest generation is one
-*   of these and repeats another run's verdict (`sameVerdict`), it could be a
-*   re-post of an older verdict or a new one, and nothing is trusted. Proofs
-*   that size are rare, so refusing costs one fresh verification.
-* - Two different generations at the newest instant refuse, by the shared
-*   sequencing owner's rule.
-*
-* Factory-ci's hosted proof-reuse gate applies the same rule in jq.
+* Every generation among the served runs, ordered and grouped by the rule
+* `newestVerifyProofGeneration` states, and every run's post with the
+* generation it belongs to.
 */
-const newestVerifyProofGeneration = (runs, bound) => {
+const verifyProofGenerations = (runs, bound) => {
 	const generations = [];
+	const posts = [];
 	for (const run of runs) {
 		const parsed = parsePrVerifyCheckPayload(run.output?.text) ?? parsePrVerifyCheckPayload(run.output?.summary);
 		const payload = run.head_sha === bound.sha && parsed?.headSha === bound.sha && parsed.repository === bound.repository ? parsed : void 0;
-		const recordedMs = generationOrderMs(payload?.verificationProof?.endedAt);
-		if (payload === void 0 || !Number.isFinite(recordedMs)) {
-			generations.push({
-				orderMs: generationOrderMs(run.started_at),
+		const postedMs = wholeSecondMs(generationOrderMs(run.started_at));
+		const startMs = passingProofStartMs(run, payload);
+		if (payload === void 0 || startMs === void 0) {
+			const generation = {
+				orderMs: postedMs,
 				...payload === void 0 ? {} : { payload },
 				recorded: false,
 				run
+			};
+			generations.push(generation);
+			posts.push({
+				generation,
+				postedMs
 			});
 			continue;
 		}
 		const generation = {
-			orderMs: recordedMs,
+			orderMs: Math.min(startMs, postedMs),
 			payload,
 			recorded: true,
 			run
 		};
-		if (!generations.some((earlier) => earlier.recorded && sameVerdict(earlier, generation))) generations.push(generation);
+		const earlier = generations.find((candidate) => candidate.recorded && sameVerdict(candidate, generation));
+		if (earlier === void 0) generations.push(generation);
+		else earlier.orderMs = Math.min(earlier.orderMs, generation.orderMs);
+		posts.push({
+			generation: earlier ?? generation,
+			postedMs
+		});
 	}
+	return {
+		generations,
+		posts
+	};
+};
+/**
+* The newest generation of the `pr:verify` proof at one head, or nothing when
+* no single generation can be trusted. A passing generation is ordered by when
+* its verification started, never later than when its run reached GitHub and
+* never by when its verification ended (#1409, #1490). Every other run is
+* ordered by when it reached GitHub (#1506):
+*
+* - A passing run is completed with conclusion `success`, and its bound
+*   payload has outcome `passed`. When that payload transports a typed proof
+*   whose start is computable (`proofStartMs`: its `endedAt` minus its
+*   `durationMs`), the run is ordered at that start, or at its own
+*   `started_at` when that is earlier. Runs that carry the same such payload
+*   with the same status and conclusion are one generation posted more than
+*   once (`pr:verify` posts, `pr:publish` re-posts), ordered at the earliest of
+*   its members' instants, whatever order GitHub serves them in. A re-post
+*   does not move the proof's start, so an older pass re-posted after a newer
+*   failure does not outrank it, and the normal post plus re-post is not a
+*   tie.
+* - Any other run is its own generation at its `started_at`: one still
+*   running, a failure or cancellation whether or not it carries a proof, one
+*   with no bound payload (including one whose transported proof fails the
+*   proof schema, which drops the whole payload), or a pass with no usable
+*   typed proof (over the text cap, or with no computable start). A run is
+*   created no earlier than its verification began, so `started_at` is an
+*   upper bound on that start. Ranking there can only make such a run newer
+*   than it is, so it vetoes more, never less.
+* - Neither `endedAt` nor a passing run's `started_at` is its start. Every
+*   writer posts its `pr-verify` run only once verification has finished
+*   (`pr:verify` on success or failure, `pr:publish` on re-post), so both say
+*   when it ended, and an older pass ordered there would hide a run that
+*   started after the pass began: still running, or failed (#1490). A pass's
+*   `started_at` only caps its proof's start. A failure's `started_at` is when
+*   it was posted, not when it started, and that is deliberate: a veto's
+*   instant only has to be no earlier than its start.
+* - Only a pass is ordered by its proof because the hosted gate cannot run the
+*   proof schema this reader runs (#1506). Ordered by its proof's claimed
+*   start there, a failure carrying a malformed proof ranked under an older
+*   pass, and the gate reused the pass where this reader refused. For an
+*   honest proof, `started_at` is no earlier than `endedAt`, which is no
+*   earlier than the start, so the cap changes nothing for a valid pass, and
+*   it also caps a schema-valid proof from a skewed clock.
+* - A pass is reused only when its verification started strictly after every
+*   other run at this head was posted (#1506). Its start is its instant
+*   (`orderMs`): its proof's start, capped as above, or its `started_at` when
+*   it is ordered there. Every other run's post is its `started_at`, rounded
+*   down to the whole second. Only the pass's own generation is left out: its
+*   re-post group, or, for a pass with no typed proof, that run alone. At most
+*   one generation can satisfy this, and that one is the newest, so this
+*   reader selects the newest generation and, when it is a pass
+*   (`isPassingRun`), trusts nothing unless every other run was posted before
+*   its instant (`postedSinceItStarted`). When the newest generation is not a
+*   pass, the caller refuses reuse anyway, so it is returned as before.
+* - The check exists because a run may be ordered earlier than its post by
+*   its proof. This reader validates proofs, so for it the check only refuses
+*   a valid pass that started before another pass was posted. The hosted gate
+*   cannot validate them: without the check, a successful run whose malformed
+*   proof claimed an early start ranked under an older pass there, whether
+*   that pass was ordered by its proof or at its `started_at`, and the gate
+*   reused the older pass where this reader, which drops that payload and
+*   ranks the run at its `started_at`, refused. Both readers apply the check
+*   so they agree. With it, whether a pass may be reused never consults
+*   another run's proof fields, only when each other run was posted, which
+*   GitHub records. In the hosted gate those fields can only cause a refusal;
+*   they never hide a veto. The pass's own clock is capped at its post, so it
+*   can only count against that pass.
+* - Two changes on valid input follow, and both only add refusals, each
+*   costing one fresh verification in a rare case. A failure carrying a proof
+*   is ordered when it was posted instead of when it started, so an older
+*   failure that finished after a newer pass began now refuses reuse. Two pass
+*   generations whose verifications overlapped now refuse, as does an older
+*   pass re-posted after a newer pass started. Passes that ran one after the
+*   other, and a pass with its own re-posts, are reused as before.
+* - The hosted gate's trust boundary is a class. The gate does not
+*   reimplement this reader's payload parser. On payloads the factory's
+*   writer emits, both readers select the same pass or both refuse: the
+*   differential suite, `pr-verify-reuse-differential.test.ts`, asserts it
+*   over 9,653 generated run sets. On App-signed text the writer never emits,
+*   the two can differ in either direction. The known instances where the
+*   hosted gate reuses and this reader refuses are: (a) a reused run whose
+*   typed proof fails `validatePrVerifyProof`; (b) a newest pass that repeats
+*   another run's verdict only once this reader normalizes that run's
+*   payload, say by dropping a key; (c) a payload in `output.summary` beside
+*   a text payload this reader cannot read, which it reads from the summary
+*   and the hosted gate from the text; (d) text the gate's strip-and-`fromjson`
+*   reads and this reader's fence match or `JSON.parse` refuses, such as a
+*   closing fence with no opening one, a doubled opening fence, a fence line
+*   inside the JSON, a payload split across two fenced blocks, or a number
+*   literal such as `NaN` where the gate's jq accepts it (jq 1.8 does).
+*   Mirroring any of it would turn the gate's jq into a parser. Only the
+*   factory App can post the run, and that identity bounds the whole class
+*   (#1511).
+* - A run not ordered by a typed proof carries no generation identity, so it
+*   is never grouped. Two separate executions with the same command names and
+*   verdict post the same compact payload, and so does a re-post. When the
+*   newest generation is one of these and repeats another run's verdict
+*   (`sameVerdict`), it could be a re-post of an older verdict or a new one,
+*   and nothing is trusted. Proofs that size are rare, so refusing costs one
+*   fresh verification.
+* - Two different generations at the newest instant refuse, by the shared
+*   sequencing owner's rule.
+*
+* Every instant is rounded down to its whole second (`wholeSecondMs`), as the
+* hosted gate's jq must: it compares epoch seconds. Rounding down is monotonic,
+* so it can merge two instants into a tie, which refuses, but never invert
+* them. It also fails closed: a proof's start never moves later, so it never
+* outranks an unbound run in the same second.
+*
+* Factory-ci's hosted proof-reuse gate applies the same rule in jq.
+*/
+const newestVerifyProofGeneration = (runs, bound) => {
+	const { generations, posts } = verifyProofGenerations(runs, bound);
 	const selected = selectNewestGeneration(generations);
 	if (selected.kind !== "newest") return;
 	const newest = selected.generation;
-	return !newest.recorded && newest.payload !== void 0 && generations.some((generation) => generation !== newest && sameVerdict(generation, newest)) ? void 0 : newest;
+	const repeatsAnotherRun = !newest.recorded && newest.payload !== void 0 && generations.some((generation) => generation !== newest && sameVerdict(generation, newest));
+	const postedSinceItStarted = isPassingRun(newest.run, newest.payload) && posts.some((post) => post.generation !== newest && post.postedMs >= newest.orderMs);
+	return repeatsAnotherRun || postedSinceItStarted ? void 0 : newest;
 };
 /**
 * Read the machine-readable `pr:verify` binding for one commit (#247).
@@ -11003,8 +11189,21 @@ var DemandWaiveRefusalError = class extends Error {
 		this.refusals = refusals;
 	}
 };
-/** Refusals about the request itself: a malformed key, a missing rationale. */
-const requestRefusals = ({ demand, parsedDemand, rationale }) => [...parsedDemand.success ? [] : [`demand:waive refuses demand key "${demand}": a demand key is a lowercase family, optionally qualified by its resolved value (e.g. review-rung:human).`], ...rationale.length === 0 ? ["demand:waive requires a non-empty --rationale."] : []];
+/**
+* Refusals about the named key: malformed, or well-formed but outside the one
+* eligibility contract the readers fold by (#1492). An ineligible key refuses
+* here, before anything is written, so the store never holds an apparent
+* operator authorization that no command applies.
+*/
+const demandKeyRefusals = ({ demand, parsedDemand }) => {
+	if (!parsedDemand.success) return [`demand:waive refuses demand key "${demand}": a demand key is a lowercase family, optionally qualified by its resolved value (e.g. review-rung:human).`];
+	return isWaivableDemand(parsedDemand.data) ? [] : [ineligibleWaiverRefusal(parsedDemand.data)];
+};
+/** Refusals about the request itself: the key, a missing rationale. */
+const requestRefusals = ({ demand, parsedDemand, rationale }) => [...demandKeyRefusals({
+	demand,
+	parsedDemand
+}), ...rationale.length === 0 ? ["demand:waive requires a non-empty --rationale."] : []];
 /**
 * Refusals about the candidate the waiver would bind to. A waiver names one
 * pushed head. For ordinary demands that head must be the one verification
@@ -12320,10 +12519,14 @@ const defaultResolveRepo = (cwd) => runCapture("gh", [
 	"--jq",
 	".nameWithOwner"
 ], cwd).stdout.trim();
-const evaluateProofAgainstDemands = ({ authorsSeen, computed, declaredBy, demandedRung, manifestHash, selected }) => {
+const parseFailureReason = ({ commentAuthor, commentUrl, parseError }) => `found a boundary-review-proof block from ${commentAuthor}${commentUrl === void 0 ? "" : ` (${commentUrl})`} that failed to parse: ${parseError}; edit that comment so the block matches the boundary-review proof schema — an unparseable proof satisfies nothing`;
+const evaluateProofAgainstDemands = ({ boundary, comments, computed, declaredBy, demandedRung, manifestHash, selected }) => {
 	if (!selected) {
-		if (authorsSeen.length === 0) return { blockingReasons: [`no boundary-review proof found on the epic issue; run the boundary review at the ${demandedRung} rung and post its fenced JSON proof comment — absence fails closed`] };
-		return { blockingReasons: [`boundary-review proof block(s) found on the epic issue, but none authored by declaredBy "${declaredBy}" (authors seen: ${authorsSeen.join(", ")}); run the boundary review at the ${demandedRung} rung from that account, or correct declaredBy if it names the wrong one`] };
+		const authorsSeen = boundaryReviewProofAuthorsSeen(comments, boundary);
+		const blockingReasons = boundaryReviewProofParseFailures(comments, boundary).map(parseFailureReason);
+		if (authorsSeen.length > 0) blockingReasons.push(`boundary-review proof block(s) found on the epic issue, but none authored by declaredBy "${declaredBy}" (authors seen: ${authorsSeen.join(", ")}); run the boundary review at the ${demandedRung} rung from that account, or correct declaredBy if it names the wrong one`);
+		if (blockingReasons.length === 0) blockingReasons.push(`no boundary-review proof found on the epic issue; run the boundary review at the ${demandedRung} rung and post its fenced JSON proof comment — absence fails closed`);
+		return { blockingReasons };
 	}
 	const { proof } = selected;
 	const blockingReasons = [];
@@ -12350,7 +12553,8 @@ function runBoundaryCheck(args, dependencies = {}) {
 		const comments = github.fetchIssueComments(repo, args.epic);
 		const selected = selectBoundaryReviewProof(comments, parsed.manifest.boundary, parsed.manifest.declaredBy);
 		const { blockingReasons } = evaluateProofAgainstDemands({
-			authorsSeen: selected ? [] : boundaryReviewProofAuthorsSeen(comments, parsed.manifest.boundary),
+			boundary: parsed.manifest.boundary,
+			comments,
 			computed,
 			declaredBy: parsed.manifest.declaredBy,
 			demandedRung,
@@ -17920,50 +18124,161 @@ const commitParentsSchema = z.object({
 	parents: z.array(z.object({ sha: shaSchema$2 })),
 	sha: shaSchema$2
 });
-function selectListedMergeFreezeGeneration(listed, expectedHeadSha) {
-	const runs = z.object({ check_runs: z.array(z.unknown()) }).parse(listed).check_runs.map((run) => {
-		const listedRun = mergeFreezeCheckRunListItemSchema.parse(run);
-		if (!checkRunProducedByFactoryApp({
-			app: listedRun.app,
-			expectedAppId: FACTORY_PROOF_GATE_APP_ID
-		})) throw new Error(`${MERGE_FREEZE_CHECK_NAME} check run ${listedRun.id} was not written by the pinned Factory App ${FACTORY_PROOF_GATE_APP_ID}.`);
-		return listedRun;
-	});
-	if (runs.length === 0) return { kind: "missing" };
+/**
+* The verdict a completed generation carries. A malformed payload throws, and
+* a payload that disagrees with its own check run is unreadable.
+*/
+function settleCompletedGeneration(run) {
+	const completed = completedMergeFreezeCheckRunSchema.parse(run);
+	const state = mergeFreezeStateSchema.parse(JSON.parse(completed.output.text));
+	if (state.generationId !== completed.id || state.headSha !== completed.head_sha || state.outcome === "active" && completed.conclusion !== "failure" || state.outcome === "stale" && completed.conclusion !== "neutral" || !state.active && completed.conclusion !== "success") return {
+		kind: "unreadable",
+		reason: `Newest ${MERGE_FREEZE_CHECK_NAME} check run has inconsistent state.`
+	};
+	return {
+		kind: "settled",
+		state
+	};
+}
+/**
+* Whether a generation's recorded verification was cancelled and nothing in it
+* failed (#1158): at least one `cancelled` job and no `failure`. It reads only
+* the recorded job facts and never infers why a run was cancelled. A legacy
+* schema-1 record without `verification` is never cancellation-only, because
+* the reader cannot tell why it froze.
+*/
+function isCancellationOnly(state) {
+	const results = Object.values(state.verification?.jobs ?? {});
+	return results.includes("cancelled") && !results.includes("failure");
+}
+/**
+* The verdict behind a newest generation whose verification was only
+* cancelled (#1158).
+*
+* The freeze reads the newest completed generation at the exact tip whose
+* verification was not cancellation-only. A cancellation-only generation means
+* verification did not finish, so it says nothing about the code. A duplicate
+* push or a concurrency group can cancel a later Verify run at a tip an earlier
+* run already judged, and that later run must not override the earlier verdict.
+*
+* So the reader steps back, newest first by the same `started_at` rule, over
+* cancellation-only generations to the first older one that decides. A failed
+* or mixed failed-and-cancelled generation decides, and so does a legacy
+* record without job facts. If no older generation decides, `newest` stands,
+* which keeps the freeze active and fail-closed. That covers three cases:
+* every completed generation at the tip is cancellation-only; the next older
+* generation is still running, since an older green never outranks a newer
+* running one; and the next older generation is for another tip, is malformed,
+* or shares its `started_at` with another.
+*
+* `steppedPast` carries the cancellation-only runs walked so far, newest first,
+* starting with the newest run itself. The selection reports them only when an
+* older verdict decides; when `newest` stands, it read past nothing.
+*/
+function verdictBehindCancellation(newest, olderRuns, expectedHeadSha, steppedPast) {
+	const standing = {
+		...newest,
+		readPast: []
+	};
+	const selected = selectNewestGeneration(olderRuns.map((run) => ({
+		orderMs: generationOrderMs(run.started_at),
+		run
+	})));
+	if (selected.kind !== "newest") return standing;
+	const { run } = selected.generation;
+	if (run.head_sha !== expectedHeadSha || run.status !== "completed") return standing;
+	let older;
+	try {
+		older = settleCompletedGeneration(run);
+	} catch {
+		return standing;
+	}
+	if (older.kind !== "settled") return standing;
+	if (!isCancellationOnly(older.state)) return {
+		generation: older,
+		readPast: steppedPast,
+		run
+	};
+	return verdictBehindCancellation(newest, olderRuns.filter((candidate) => candidate !== run), expectedHeadSha, [...steppedPast, run]);
+}
+/**
+* The generation the freeze selects among the runs listed at one tip: the one
+* rule behind `readGeneration`, `read`, and the PR status HUD's freeze row
+* (#1501). It is pure. Its caller has already decided which runs to trust; the
+* reader refuses the whole read on a run the pinned App did not write.
+*
+* GitHub documents check-run IDs only as unique, not ordered. The factory
+* deliberately relies on GitHub-stamped `started_at`, and equal newest instants
+* stay ambiguous and fail closed. `filter=all` in the API reader is required
+* because `latest` can hide a live generation (#522, #524).
+*
+* A malformed newest payload throws, as `settleCompletedGeneration` does.
+*/
+function selectMergeFreezeRun(runs, expectedHeadSha) {
+	if (runs.length === 0) return {
+		generation: { kind: "missing" },
+		readPast: []
+	};
 	const selected = selectNewestGeneration(runs.map((run) => ({
 		orderMs: generationOrderMs(run.started_at),
 		run
 	})));
 	if (selected.kind === "ambiguous") return {
-		kind: "unreadable",
-		reason: `Newest ${MERGE_FREEZE_CHECK_NAME} generation is ambiguous: ${selected.tied.length} check runs share ${new Date(selected.orderMs).toISOString()}.`
+		generation: {
+			kind: "unreadable",
+			reason: `Newest ${MERGE_FREEZE_CHECK_NAME} generation is ambiguous: ${selected.tied.length} check runs share ${new Date(selected.orderMs).toISOString()}.`
+		},
+		readPast: []
+	};
+	if (selected.kind === "none") return {
+		generation: { kind: "missing" },
+		readPast: []
 	};
-	if (selected.kind === "none") return { kind: "missing" };
 	const newest = selected.generation.run;
 	if (newest.head_sha !== expectedHeadSha) return {
-		kind: "unreadable",
-		reason: `Newest ${MERGE_FREEZE_CHECK_NAME} check run targets ${newest.head_sha}, expected ${expectedHeadSha}.`
+		generation: {
+			kind: "unreadable",
+			reason: `Newest ${MERGE_FREEZE_CHECK_NAME} check run targets ${newest.head_sha}, expected ${expectedHeadSha}.`
+		},
+		readPast: []
 	};
 	if (newest.status !== "completed") return {
-		kind: "settling",
-		phase: "running-generation",
-		reason: `Authoritative merge freeze generation ${newest.id} is in progress.`,
-		witness: {
-			headSha: newest.head_sha,
-			runId: newest.id
-		}
+		generation: {
+			kind: "settling",
+			phase: "running-generation",
+			reason: `Authoritative merge freeze generation ${newest.id} is in progress.`,
+			witness: {
+				headSha: newest.head_sha,
+				runId: newest.id
+			}
+		},
+		readPast: []
 	};
-	const completed = completedMergeFreezeCheckRunSchema.parse(newest);
-	const state = mergeFreezeStateSchema.parse(JSON.parse(completed.output.text));
-	if (state.generationId !== completed.id || state.headSha !== completed.head_sha || state.outcome === "active" && completed.conclusion !== "failure" || state.outcome === "stale" && completed.conclusion !== "neutral" || !state.active && completed.conclusion !== "success") return {
-		kind: "unreadable",
-		reason: `Newest ${MERGE_FREEZE_CHECK_NAME} check run has inconsistent state.`
+	const verdict = settleCompletedGeneration(newest);
+	if (verdict.kind !== "settled") return {
+		generation: verdict,
+		readPast: []
 	};
+	if (isCancellationOnly(verdict.state)) return verdictBehindCancellation({
+		generation: verdict,
+		run: newest
+	}, runs.filter((run) => run !== newest), expectedHeadSha, [newest]);
 	return {
-		kind: "settled",
-		state
+		generation: verdict,
+		readPast: [],
+		run: newest
 	};
 }
+function selectListedMergeFreezeGeneration(listed, expectedHeadSha) {
+	return selectMergeFreezeRun(z.object({ check_runs: z.array(z.unknown()) }).parse(listed).check_runs.map((run) => {
+		const listedRun = mergeFreezeCheckRunListItemSchema.parse(run);
+		if (!checkRunProducedByFactoryApp({
+			app: listedRun.app,
+			expectedAppId: FACTORY_PROOF_GATE_APP_ID
+		})) throw new Error(`${MERGE_FREEZE_CHECK_NAME} check run ${listedRun.id} was not written by the pinned Factory App ${FACTORY_PROOF_GATE_APP_ID}.`);
+		return listedRun;
+	}), expectedHeadSha).generation;
+}
 function unconfiguredMergeFreeze(input, detail) {
 	return {
 		kind: "unreadable",
@@ -18835,26 +19150,9 @@ const reviewRoundLimitBlockers = (input) => {
 	}];
 };
 /**
-* The demands an operator waiver can reach (#354, moved here from
-* `pr:merge-check` by #477). Exactly the set the merge-time site could waive:
-* the merge freeze, the profile's external required checks, and the boundary
-* wave's review rung — the demands the resolver puts *in force* for one
-* candidate — plus the review-round limit (#1280), which exists only to be
-* waived.
-*
-* Everything else stays unwaivable, and relocating the consumption site does
-* not widen the operator's override. Structural refusals — candidate identity,
-* proof binding, an unreadable demand authority, wave membership — were never
-* waivable at merge time and are not waivable here; in `pr:ready` most of them
-* refuse by throwing before any blocker list exists. The evidence gates
-* readiness has always owned (verify, review modes, draft, human blockers) are
-* satisfied or not; a waiver is not a second way to pass them.
-*/
-const WAIVABLE_QUALIFIED_DEMAND_FAMILIES = ["required-check", "review-rung"];
-const isWaivableDemand = (demand) => demand === DEMAND_KEYS.mergeFreeze || demand === DEMAND_KEYS.reviewRoundLimit || WAIVABLE_QUALIFIED_DEMAND_FAMILIES.some((family) => demand.startsWith(`${family}:`));
-/**
 * Fold the operator's waivers through the blockers, one call per demand so
-* `demand-waiver.ts` stays the single authority on what a waiver means. A
+* `demand-waiver.ts` stays the single authority on what a waiver means and
+* which demands it can reach — the contract `demand:waive` refuses by. A
 * waived demand keeps every refusal it made, verbatim, on the `WaivedDemand`
 * record — it is never rewritten as satisfied.
 */
@@ -19293,6 +19591,8 @@ const renderTable = (rows) => [
 	"| --- | --- | --- | --- |",
 	...rows.map((row) => `| ${markdownCell(row.target)} | ${statusLabel(row.status)} | ${row.link} | ${row.timestamp} |`)
 ].join("\n");
+/** Name the cancellation-only runs a merge-freeze row read past (#1501). */
+const withReadPastNote = (target, runIds) => runIds && runIds.length > 0 ? `${target} (read past cancellation-only ${runIds.length === 1 ? "run" : "runs"} ${runIds.join(", ")})` : target;
 const checkRow = (target, snapshot, renderedAt) => {
 	if (!snapshot) return {
 		detail: "No completed Factory App snapshot is available at this head.",
@@ -19305,7 +19605,7 @@ const checkRow = (target, snapshot, renderedAt) => {
 		detail: `Completed snapshot: ${snapshot.conclusion}.`,
 		link: safeMarkdownLink("Details", snapshot.detailsUrl),
 		status: snapshot.conclusion === "success" ? "Ready" : "Failed",
-		target,
+		target: withReadPastNote(target, snapshot.readPastRunIds),
 		timestamp: utcTimestamp(snapshot.completedAt)
 	};
 };
@@ -19417,7 +19717,9 @@ const checkRunSchema = z.object({
 	conclusion: z.string().nullable().optional(),
 	details_url: z.string().nullable().optional(),
 	head_sha: z.string().regex(/^[0-9a-f]{40}$/u),
+	id: z.number().int().positive(),
 	name: z.string(),
+	output: z.object({ text: z.string().nullable().optional() }).nullable().optional(),
 	started_at: z.iso.datetime().nullable(),
 	status: z.enum([
 		"completed",
@@ -19488,16 +19790,13 @@ const listFactoryCheckRuns = async (input, name, sha, dependencies) => {
 	}
 	throw new Error(`${name} pagination limit was exhausted before GitHub returned a final page.`);
 };
-const completedSnapshot = (name, sha, runs) => {
+/** The Factory App's generations of one check at one SHA, each orderable. */
+const factoryGenerations = (name, sha, runs) => {
 	const candidates = runs.filter((run) => String(run.app?.id ?? "") === FACTORY_PROOF_GATE_APP_ID && run.head_sha === sha && run.name === name);
 	if (candidates.some((run) => !Number.isFinite(generationOrderMs(run.started_at)))) throw new Error(`${name} presentation snapshot has a generation with no usable started_at.`);
-	const selected = selectNewestGeneration(candidates.map((run) => ({
-		orderMs: generationOrderMs(run.started_at),
-		run
-	})));
-	if (selected.kind === "ambiguous") throw new Error(`Newest ${name} presentation snapshot is ambiguous: ${selected.tied.length} check runs share the newest timestamp.`);
-	if (selected.kind === "none") return;
-	const { run } = selected.generation;
+	return candidates;
+};
+const runSnapshot = (name, run) => {
 	if (run.status !== "completed" || !run.completed_at || !run.conclusion) return;
 	return {
 		completedAt: run.completed_at,
@@ -19507,6 +19806,45 @@ const completedSnapshot = (name, sha, runs) => {
 		name
 	};
 };
+const newestSnapshot = (name, generations) => {
+	const selected = selectNewestGeneration(generations.map((run) => ({
+		orderMs: generationOrderMs(run.started_at),
+		run
+	})));
+	if (selected.kind === "ambiguous") throw new Error(`Newest ${name} presentation snapshot is ambiguous: ${selected.tied.length} check runs share the newest timestamp.`);
+	if (selected.kind === "none") return;
+	return runSnapshot(name, selected.generation.run);
+};
+const completedSnapshot = (name, sha, runs) => newestSnapshot(name, factoryGenerations(name, sha, runs));
+const MERGE_FREEZE_CHECK = "patronage-factory/merge-freeze";
+/**
+* The merge-freeze row shows the generation readiness reads (#1501), chosen by
+* the freeze's own selection rather than a second copy of it. That selection
+* reads past a cancellation-only generation to an older verdict at the same
+* tip (#1158). The newest completed run alone would show that cancellation as
+* a freeze readiness does not apply, so the row names the runs it read past.
+*
+* Otherwise the row is the newest completed snapshot, as for every other check:
+* running, missing and ambiguous generations present as before, and so does a
+* newest generation the selection cannot settle. Every case where the freeze
+* stays fail-closed keeps the newest generation, so the row stays red. The HUD
+* is advisory and never gates.
+*/
+const mergeFreezeSnapshot = (sha, runs) => {
+	const generations = factoryGenerations(MERGE_FREEZE_CHECK, sha, runs);
+	const newest = newestSnapshot(MERGE_FREEZE_CHECK, generations);
+	if (!newest) return newest;
+	try {
+		const { readPast, run } = selectMergeFreezeRun(generations, sha);
+		const selected = run && readPast.length > 0 ? runSnapshot(MERGE_FREEZE_CHECK, run) : void 0;
+		return selected ? {
+			...selected,
+			readPastRunIds: readPast.map((past) => past.id)
+		} : newest;
+	} catch {
+		return newest;
+	}
+};
 const FAILED_PREVIEW_CONCLUSIONS = new Set([
 	"action_required",
 	"cancelled",
@@ -19555,7 +19893,8 @@ async function readFactoryPrStatusSources(input, dependencies = {}) {
 	];
 	const listedChecks = await Promise.all(checkTargets.map(([name, sha]) => listFactoryCheckRuns(input, name, sha, dependencies)));
 	const checks = Object.fromEntries(checkTargets.flatMap(([name, sha], index) => {
-		const snapshot = completedSnapshot(name, sha, listedChecks[index] ?? []);
+		const runs = listedChecks[index] ?? [];
+		const snapshot = name === MERGE_FREEZE_CHECK ? mergeFreezeSnapshot(sha, runs) : completedSnapshot(name, sha, runs);
 		return snapshot ? [[name, snapshot]] : [];
 	}));
 	const previewTargets = input.previewTargets ?? [];
@@ -21418,11 +21757,20 @@ const assertEpicPullRequestOpen = ({ args, base }) => {
 * prompt for another patch, with no ladder cycle for that patch, is a review
 * that nobody recorded, and no ladder control can see it. Assembling again at
 * the same patch only rewrites that prompt.
+*
+* The prompt also counts as recorded when the checkout's own review proof
+* holds a cycle at exactly the patch and head the prompt names, whatever the
+* lineage (#1415). A squash merge of the previous pull request takes that head
+* off the next branch, so the ladder this candidate continues is empty, yet
+* the review of that prompt is on record. Only this question reads
+* `checkoutLadder`; the next review still continues `priorLadder`.
 */
-const assertPriorPromptRecorded = ({ existing, patchId, priorLadder }) => {
+const assertPriorPromptRecorded = ({ checkoutLadder, existing, patchId, priorLadder }) => {
 	if (existing.status !== "ok" || existing.artifact.patchId === patchId) return;
 	const prompted = existing.artifact;
-	if ((priorLadder?.cycles ?? []).some((cycle) => cycle.identity?.patchId === prompted.patchId)) return;
+	const recordedOnContinuedLadder = (priorLadder?.cycles ?? []).some((cycle) => cycle.identity?.patchId === prompted.patchId);
+	const recordedAtPromptedHead = (checkoutLadder?.cycles ?? []).some((cycle) => cycle.identity?.patchId === prompted.patchId && cycle.identity.headSha === prompted.headSha);
+	if (recordedOnContinuedLadder || recordedAtPromptedHead) return;
 	throw new Error(`pr:review --assemble refuses: ${DEFAULT_ASSEMBLED_REVIEW_PROMPT_PATH} holds a prompt for patch ${prompted.patchId} at ${prompted.headSha}, and the review ladder has no cycle for that patch. The candidate is now patch ${patchId}. Record the review of that patch first: patronage-factory pr:review --historical --findings <findings file for patch ${prompted.patchId}>. If no reviewer read that prompt, delete ${DEFAULT_ASSEMBLED_REVIEW_PROMPT_PATH} and assemble again.`);
 };
 /**
@@ -21469,14 +21817,16 @@ const assertAssembleMayPrepareReview = ({ args, base, cwd, git, headSha, output,
 		args,
 		base
 	});
+	const prior = readOptionalProofFor(PR_REVIEW_PROOF_DESCRIPTOR, cwd, output);
 	const priorLadder = priorLadderStateFor({
 		base: base.ref,
 		headSha,
 		isAncestor: (ancestor, descendant) => git.isAncestor(cwd, ancestor, descendant),
-		prior: readOptionalProofFor(PR_REVIEW_PROOF_DESCRIPTOR, cwd, output)
+		prior
 	});
 	const existing = readAssembledReviewPrompt(path.resolve(cwd, DEFAULT_ASSEMBLED_REVIEW_PROMPT_PATH));
 	assertPriorPromptRecorded({
+		checkoutLadder: prior?.ladder,
 		existing,
 		patchId,
 		priorLadder

package/dist/schemas.js

@@ -252,6 +252,7 @@ const waivedDemandSchema = z.object({
 	session: z.string().trim().min(1).optional(),
 	unmetReasons: z.array(z.string().min(1)).min(1)
 });
+DEMAND_KEYS.mergeFreeze, DEMAND_KEYS.reviewRoundLimit, DEMAND_KEYS.childIssueOpen;
 //#endregion
 //#region src/diff-classification.ts
 const DIFF_CLASSIFICATIONS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.41",
+  "version": "1.0.0-alpha.43",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "picomatch": "^4.0.5",
     "yaml": "^2.9.0",
     "zod": "4.4.3",
-    "@patronage/factory-ci": "1.0.0-alpha.41"
+    "@patronage/factory-ci": "1.0.0-alpha.43"
   },
   "devDependencies": {
     "@types/node": "24.13.3",