@patronage/software-factory 0.20.0 → 0.25.0

package/dist/schemas.js

@@ -1,4 +1,235 @@
 import { z } from "zod";
+//#region src/review-rungs.ts
+const EVIDENCE_REVIEW_RUNGS$1 = [
+	"independent-model",
+	"oracle",
+	"human"
+];
+Object.fromEntries(EVIDENCE_REVIEW_RUNGS$1.map((rung, index) => [rung, index]));
+//#endregion
+//#region src/demand-keys.ts
+/** The demands that exist at most once per candidate. */
+const DEMAND_KEYS = {
+	/** The PR is still a draft. */
+	draft: "draft",
+	/** The candidate is not the intended final human review point. */
+	finalReviewPoint: "final-review-point",
+	/** GitHub's own check rollup for the candidate head. */
+	githubChecks: "github-checks",
+	/** Local HEAD and the GitHub PR head must be the same commit. */
+	headIdentity: "head-identity",
+	/** An unhandled post-readiness human comment or review submission. */
+	humanBlocker: "human-blocker",
+	/** The repository-wide merge freeze. */
+	mergeFreeze: "merge-freeze",
+	/** GitHub's mergeability / merge-state rollup. */
+	mergeState: "merge-state",
+	/** The PR body's required rendered sections. */
+	prBodySections: "pr-body-sections",
+	/** A current, head-bound, passing typed `pr:verify` proof. */
+	prVerify: "pr-verify",
+	/** The profile-resolved review ladder policy. */
+	reviewLadder: "review-ladder",
+	/** Unresolved GitHub review threads. */
+	reviewThreads: "review-threads",
+	/** An explicit trivial waiver that the diff does not support. */
+	trivialWaiver: "trivial-waiver"
+};
+/** The families whose instances are named by a resolved value. */
+const QUALIFIED_DEMAND_FAMILIES = [
+	"required-check",
+	"review-mode",
+	"review-rung"
+];
+const QUALIFIER_PATTERN = /^[A-Za-z0-9._%/-]{1,64}$/u;
+const percentEncode = (character) => {
+	const code = character.codePointAt(0) ?? 0;
+	if (code >= 55296 && code <= 57343) return `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+	return [...new TextEncoder().encode(character)].map((byte) => `%${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("");
+};
+/**
+* Express a resolved value as a qualifier. Percent-encoding, not scrubbing:
+* the mapping is injective, so two differently named required checks can never
+* collapse into one key — which would let one operator waiver silently cover a
+* demand nobody waived, and make HQ count two causes as one.
+*
+* Deterministic in both directions of use: the key a `pr:ready` proof records
+* is the key a `pr:merge-check` waiver matches.
+*/
+const demandQualifier = (value) => value.replaceAll(/[^A-Za-z0-9._/-]/gu, percentEncode);
+const FIXED_DEMAND_KEYS = Object.values(DEMAND_KEYS);
+/** The review modes a profile can resolve, and therefore demand. */
+const REVIEW_MODE_DEMAND_VALUES = ["correctness", "security"];
+const escapePattern = /%(?:u[0-9A-F]{4}|[0-9A-F]{2})/gu;
+/**
+* Reverse `demandQualifier`. A qualifier is canonical exactly when encoding
+* its decoded form reproduces it — which rejects both malformed escapes and
+* noncanonical aliases like `%41` for `A`. Returns undefined when the
+* qualifier cannot have been minted here.
+*/
+const decodeQualifier = (qualifier) => {
+	const bytes = [];
+	let decoded = "";
+	let index = 0;
+	const flush = () => {
+		if (bytes.length === 0) return true;
+		try {
+			decoded += new TextDecoder("utf-8", {
+				fatal: true,
+				ignoreBOM: true
+			}).decode(Uint8Array.from(bytes));
+		} catch {
+			return false;
+		}
+		bytes.length = 0;
+		return true;
+	};
+	while (index < qualifier.length) {
+		const character = qualifier[index];
+		if (character !== "%") {
+			if (!flush()) return;
+			decoded += character;
+			index += 1;
+			continue;
+		}
+		escapePattern.lastIndex = index;
+		const escape = escapePattern.exec(qualifier);
+		if (!escape || escape.index !== index) return;
+		if (escape[0][1] === "u") {
+			if (!flush()) return;
+			decoded += String.fromCodePoint(Number.parseInt(escape[0].slice(2), 16));
+		} else bytes.push(Number.parseInt(escape[0].slice(1), 16));
+		index += escape[0].length;
+	}
+	return flush() ? decoded : void 0;
+};
+const qualifierIsMintable = (family, qualifier) => {
+	if (!QUALIFIER_PATTERN.test(qualifier)) return false;
+	const decoded = decodeQualifier(qualifier);
+	if (decoded === void 0 || demandQualifier(decoded) !== qualifier) return false;
+	if (family === "review-rung") return EVIDENCE_REVIEW_RUNGS$1.includes(decoded);
+	if (family === "review-mode") return REVIEW_MODE_DEMAND_VALUES.includes(decoded);
+	return true;
+};
+/**
+* A demand key from the closed vocabulary: a known unqualified family, or a
+* known qualified family with a qualifier this module could actually have
+* minted. Closed on purpose — an invented family, an unresolvable rung, or a
+* noncanonical encoding would be indistinguishable from a typo to anyone
+* counting causes, which is the whole point of recording codes.
+*/
+const demandKeySchema = z.string().refine((value) => {
+	if (FIXED_DEMAND_KEYS.includes(value)) return true;
+	const separator = value.indexOf(":");
+	if (separator === -1) return false;
+	const family = value.slice(0, separator);
+	return QUALIFIED_DEMAND_FAMILIES.includes(family) && qualifierIsMintable(family, value.slice(separator + 1));
+}, { message: `a demand key is one of ${FIXED_DEMAND_KEYS.join(", ")} or a resolvable ${QUALIFIED_DEMAND_FAMILIES.join(" / ")} key` });
+/**
+* The key shape an operator may *name* in a waiver: syntactic, not closed.
+*
+* Deliberately distinct from `demandKeySchema` above, which is what a proof's
+* reason codes must come from. A waiver store is durable operator evidence
+* written before today's vocabulary existed, so tightening its validation
+* would make an existing record parse as no waiver and let the next write drop
+* it. A waiver naming a key nobody resolves is already inert — `pr:merge-check`
+* reports it as an unapplied waiver — so nothing is admitted by accepting it.
+*/
+const waiverDemandKeySchema = z.string().regex(/^[a-z][a-z0-9-]*(?::[A-Za-z0-9._%/-]+)?$/u, "A demand key is a lowercase family, optionally qualified by its resolved value (e.g. review-rung:human).");
+//#endregion
+//#region src/blocked-reasons.ts
+/**
+* The wire bound on one `detail`. A blocked proof carries one short sentence
+* per demand, never a transcript: HQ's ingest cap is 256 KB and this field
+* must stay far under it even when a candidate blocks on every gate at once.
+*/
+const BLOCKED_REASON_DETAIL_MAX = 280;
+/**
+* The wire bound on how many demands one proof may name. Well past any real
+* candidate (there are a dozen fixed demands plus the profile's checks and the
+* live human blockers) and, with the detail bound, keeps the whole field two
+* orders of magnitude under the ingest cap. Bounded here rather than trimmed
+* downstream: HQ rejects an over-long list loudly instead of storing a quietly
+* truncated one.
+*/
+const BLOCKED_REASONS_MAX = 100;
+/** One refusal sentence: single line, trimmed, bounded. */
+const blockedReasonDetailSchema = z.string().min(1).max(280).refine((value) => value.trim().length > 0, { message: "must not be blank" }).refine((value) => !/[\r\n]/u.test(value), { message: "must be one line, not a multi-line payload" });
+const blockedReasonSchema = z.object({
+	code: demandKeySchema,
+	detail: blockedReasonDetailSchema
+});
+const blockedReasonsSchema = z.array(blockedReasonSchema).max(100);
+/** Fit one refusal sentence to the wire bound without losing its head. */
+const blockedReasonDetail = (reason) => {
+	const line = reason.replaceAll(/\s+/gu, " ").trim();
+	return line.length <= 280 ? line : `${line.slice(0, 279)}…`;
+};
+const blockedReasonIssue = (message) => [{
+	code: "custom",
+	message,
+	path: ["blockedReasons"]
+}];
+/**
+* The invariant every reader enforces, shared by the emitting schema and the
+* wire schema so it is one rule rather than two that can drift. It is the
+* producer's state machine, written down:
+*
+* - `ready` refused nothing, so it carries neither projection, and it is the
+*   final review point;
+* - `slice-ready/not-final` was held back by exactly one demand — being a
+*   slice — and names it;
+* - `blocked` refused something other than being a slice, and says so;
+* - whichever it is, `blockedReasons` names every refusal listed in
+*   `blockingReasons`, in the same order, as the bounded form of that sentence.
+*
+* Naming the slice demand and the ledger's `finalReviewPoint` are the same
+* fact, so a proof that says one and not the other is refused.
+*/
+const blockedReasonIssues = (proof) => {
+	const named = proof.blockedReasons ?? [];
+	const reasons = proof.blockingReasons ?? [];
+	const slice = DEMAND_KEYS.finalReviewPoint;
+	const namesSlice = named.some((reason) => reason.code === slice);
+	if (proof.status === "ready") {
+		if (named.length > 0 || reasons.length > 0) return blockedReasonIssue("a ready pr:ready proof must carry no blocking reasons");
+	} else if (proof.status === "slice-ready/not-final") {
+		if (named.length !== 1 || !namesSlice) return blockedReasonIssue(`a slice-ready/not-final pr:ready proof is held back by exactly one demand, ${slice}`);
+	} else if (reasons.length === 0) return blockedReasonIssue("a blocked pr:ready proof must record what blocked it");
+	else if (named.length > 0 && !named.some((r) => r.code !== slice)) return blockedReasonIssue(`a blocked pr:ready proof must name a demand other than ${slice}`);
+	if (proof.finalReviewPoint !== void 0 && namesSlice === proof.finalReviewPoint) return blockedReasonIssue(`naming ${slice} and the ledger's finalReviewPoint are the same fact; this proof says both`);
+	if (named.length !== reasons.length) return blockedReasonIssue(`blockedReasons must name every blocking reason: ${reasons.length} reason(s), ${named.length} named`);
+	const drifted = named.findIndex((reason, index) => reason.detail !== blockedReasonDetail(reasons[index]));
+	return drifted === -1 ? [] : blockedReasonIssue(`blockedReasons[${drifted}] does not carry blocking reason ${drifted}; the two projections must tell one story`);
+};
+//#endregion
+//#region src/demand-waiver.ts
+const DEMAND_WAIVER_SCHEMA_VERSION = 1;
+const shaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
+const demandWaiverSchema = z.object({
+	candidate: z.object({
+		headSha: shaSchema,
+		pr: z.number().int().positive()
+	}),
+	demand: waiverDemandKeySchema,
+	operator: z.string().trim().min(1),
+	rationale: z.string().trim().min(1),
+	recordedAt: z.iso.datetime(),
+	session: z.string().trim().min(1)
+});
+z.object({
+	command: z.literal("patronage-factory demand:waive"),
+	schemaVersion: z.literal(DEMAND_WAIVER_SCHEMA_VERSION),
+	waivers: z.array(demandWaiverSchema)
+});
+const waivedDemandSchema = z.object({
+	demand: waiverDemandKeySchema,
+	operator: z.string().trim().min(1),
+	rationale: z.string().trim().min(1),
+	recordedAt: z.iso.datetime(),
+	session: z.string().trim().min(1),
+	unmetReasons: z.array(z.string().min(1)).min(1)
+});
 const MAX_CLOSEOUT_ROWS = 1e3;
 const IdentifierSchema = z.string().min(1).max(500);
 const NarrativeSchema = z.string().min(1).max(1e4);
@@ -103,6 +334,239 @@ const closeoutArtifactSchema = z.object({
 	schemaVersion: z.literal(3)
 }).strict();
 //#endregion
+//#region src/retro-envelope.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.
+*/
+const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
+/**
+* v1 wire bounds — the single source the schemas below are built from and the
+* builder's sanitization seam clamps to (`retro-envelope-builder.ts` imports
+* these; it keeps no bound constants of its own). HQ imports this module
+* directly (issue #350), so there is one set of bounds, not a second copy to
+* keep in sync.
+*/
+const RETRO_ENVELOPE_WIRE_BOUNDS = {
+	/** archiveRef pointer (key/URL) max characters. */
+	archiveRefMaxChars: 2048,
+	/** refs.branch max characters (git ref length ceiling). */
+	branchMaxChars: 255,
+	/** gates[] wire cap — the builder keeps the most recent records. */
+	gatesMax: 500,
+	/** gpt roles[] cap (delegated roles per lane). */
+	gptRolesMax: 20,
+	/** Cap for list fields: joinKeys id arrays, phases, dataGaps. */
+	listMax: 100,
+	/** Bounded name fields: agentRunId, gate, phase name, refs, join-key ids. */
+	nameMaxChars: 200,
+	/** Short identifier fields: repo name/owner, model, role. */
+	shortMaxChars: 100,
+	/** Free-text fields: dataGaps entries, outcome.verdict. */
+	textMaxChars: 500
+};
+const nonNegInt = z.number().int().nonnegative();
+const isoTimestamp = z.iso.datetime();
+const boundedName = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.nameMaxChars);
+const boundedShortName = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.shortMaxChars);
+const boundedText = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.textMaxChars);
+const RetroRepoSchema = z.object({
+	name: boundedShortName,
+	owner: boundedShortName
+}).strict();
+const RetroRefsSchema = z.object({
+	branch: z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.branchMaxChars).optional(),
+	epic: boundedName.optional(),
+	headSha: z.string().regex(/^[0-9a-f]{7,40}$/u).optional(),
+	issue: boundedName.optional(),
+	prNumber: z.number().int().positive().optional()
+}).strict();
+/**
+* Per-lane join keys: how the envelope re-joins raw per-session sources.
+* `agentRunId` lives at the envelope root; these carry the per-family session
+* identities (Claude `session.id`, codex `threadId`).
+*/
+const RetroJoinKeysSchema = z.object({
+	claudeSessionIds: z.array(boundedName).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([]),
+	codexThreadIds: z.array(boundedName).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([])
+}).strict();
+const RetroWallClockSchema = z.object({
+	endTs: isoTimestamp,
+	startTs: isoTimestamp,
+	totalSec: z.number().nonnegative()
+}).strict();
+const RetroPhaseMarkSchema = z.object({
+	at: isoTimestamp,
+	deltaSec: z.number().nonnegative().optional(),
+	name: boundedName
+}).strict();
+/** Gate-timing ledger entry: `{gate, startedAt, duration, outcome, cycle}`. */
+const RetroGateLedgerEntrySchema = z.object({
+	cycle: nonNegInt,
+	duration: z.number().nonnegative(),
+	gate: boundedName,
+	outcome: z.enum([
+		"pass",
+		"fail",
+		"skip"
+	]),
+	startedAt: isoTimestamp
+}).strict();
+/**
+* Claude family: Anthropic-style EXCLUSIVE input tiers. True input context is
+* freshInput + cacheReadInput + cacheCreationInput; values are
+* requestId-deduped (S2: naive row sums overcount input ~1.94x).
+*/
+const claudeTokenBlockSchema = z.object({
+	cacheCreationInput: nonNegInt,
+	cacheReadInput: nonNegInt,
+	costUsd: z.number().nonnegative().nullable(),
+	family: z.literal("claude"),
+	freshInput: nonNegInt,
+	model: boundedShortName,
+	output: nonNegInt,
+	requests: nonNegInt
+}).strict();
+/**
+* GPT/codex family, per delegated role. codex reports `input_tokens`
+* INCLUSIVE of cached tokens; `freshInputDerived` = inclusive − cached is the
+* only value safe for a per-token pricer (S3: skipping this overprices ~3.9x).
+*/
+const gptRoleUsageSchema = z.object({
+	cachedInput: nonNegInt,
+	costUsd: z.number().nonnegative().nullable(),
+	freshInputDerived: nonNegInt,
+	inputInclusiveOfCache: nonNegInt,
+	model: boundedShortName,
+	output: nonNegInt,
+	reasoningOutput: nonNegInt,
+	role: boundedShortName,
+	threadId: boundedName.optional()
+}).strict().refine((usage) => usage.freshInputDerived === usage.inputInclusiveOfCache - usage.cachedInput, { message: "freshInputDerived must equal inputInclusiveOfCache - cachedInput (S3 accounting rule)" });
+const gptTokenBlockSchema = z.object({
+	family: z.literal("gpt"),
+	roles: z.array(gptRoleUsageSchema).min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.gptRolesMax)
+}).strict();
+/**
+* Strict: only `claude` and `gpt`, both optional, no third slot.
+*
+* A lane may have no usable native session data. The build gate accepts that
+* state and the advisory sink journals the valid envelope with its recorded
+* gaps, without inventing usage.
+*/
+const retroTokenFamiliesSchema = z.object({
+	claude: claudeTokenBlockSchema.optional(),
+	gpt: gptTokenBlockSchema.optional()
+}).strict();
+const RetroCycleCountersSchema = z.object({
+	gateRunsToFirstGreen: nonNegInt,
+	reviewerFixRounds: nonNegInt,
+	thermoFixRounds: nonNegInt
+}).strict();
+const RetroOutcomeSchema = z.object({
+	mergeCheck: z.enum([
+		"pass",
+		"fail",
+		"not-run"
+	]).optional(),
+	status: z.enum([
+		"success",
+		"blocked",
+		"fail",
+		"ship-with-followups"
+	]),
+	verdict: boundedText.optional()
+}).strict();
+const retroEnvelopeV1Schema = z.object({
+	agentRunId: boundedName,
+	/** Pointer (key/URL) to #8's durable proof archive — never the payload. */
+	archiveRef: z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.archiveRefMaxChars).optional(),
+	cycles: RetroCycleCountersSchema,
+	dataGaps: z.array(boundedText).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([]),
+	gates: z.array(RetroGateLedgerEntrySchema).max(RETRO_ENVELOPE_WIRE_BOUNDS.gatesMax),
+	generatedAt: isoTimestamp,
+	interventions: z.object({ count: nonNegInt }).strict(),
+	joinKeys: RetroJoinKeysSchema,
+	kind: z.literal("retro-envelope"),
+	outcome: RetroOutcomeSchema.optional(),
+	phases: z.array(RetroPhaseMarkSchema).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax),
+	refs: RetroRefsSchema,
+	repo: RetroRepoSchema,
+	schemaVersion: z.literal(1),
+	tokenFamilies: retroTokenFamiliesSchema,
+	wallClock: RetroWallClockSchema
+}).strict().refine((envelope) => envelope.refs.epic !== void 0 || envelope.refs.issue !== void 0 || envelope.refs.prNumber !== void 0, { message: "refs must anchor to an epic, issue, or PR" });
+/**
+* Version 1 envelopes written before #170 carried an inert `harness` label.
+* Accept that exact historical field and normalize it away. The current strict
+* schema above neither emits nor exposes it, and all other unknown fields still
+* fail validation.
+*/
+const retroEnvelopeV1ReaderSchema = z.preprocess((candidate) => {
+	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate) || !("harness" in candidate)) return candidate;
+	const record = candidate;
+	if (!boundedShortName.safeParse(record.harness).success) return candidate;
+	const { harness: _historicalHarness, ...current } = record;
+	return current;
+}, 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).
+*/
+const RETRO_ENVELOPE_VALIDATORS = { [1]: retroEnvelopeV1ReaderSchema };
+const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS = Object.keys(RETRO_ENVELOPE_VALIDATORS).map(Number);
+/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
+const retroEpicReference = (refs) => {
+	return (refs.epic ?? refs.issue ?? (refs.prNumber === void 0 ? void 0 : `pr#${refs.prNumber}`))?.replace(/^#/u, "");
+};
+//#endregion
 //#region src/schemas.ts
 const EVIDENCE_CHECK_TYPES = ["review", "verify"];
 const EVIDENCE_REVIEW_RUNGS = [
@@ -411,7 +875,7 @@ const prReviewProofSchema = z.object({
 	patchId: z.string().regex(/^[0-9a-f]{40,64}$/u),
 	reviewCycle: z.number().int().positive().optional(),
 	reviewRequirement: z.object({
-		reason: z.literal("docs-only-profile-bypass"),
+		reason: z.enum(["no-applicable-mode"]),
 		status: z.literal("not-required")
 	}).strict().optional(),
 	reviews: z.array(prReviewResultSchema),
@@ -561,6 +1025,7 @@ const prMergeCheckProofSchema = z.object({
 	pr: z.number().int().positive(),
 	schemaVersion: z.literal(1),
 	status: z.enum(["pass", "fail"]),
+	waivedDemands: z.array(waivedDemandSchema).optional(),
 	worktreeHeldBranch: z.object({
 		branch: z.string().min(1),
 		worktreePath: z.string().min(1)
@@ -749,8 +1214,16 @@ const managedReadinessLedgerSchema = z.object({
 		verifiedHeadSha: z.string().optional()
 	})
 });
-const PR_READY_SCHEMA_VERSION = 1;
+const PR_READY_SCHEMA_VERSION = 2;
+/**
+* The pr:ready proof versions a reader still accepts. `pr:ready` emits v2 only
+* (#391) — one current contract — but v1 events were spooled before the bump
+* and HQ must ingest them without degrading, so the wire schema parses both.
+*/
+const SUPPORTED_PR_READY_SCHEMA_VERSIONS = [1, 2];
+const prReadySchemaVersionSchema = z.number().refine((value) => SUPPORTED_PR_READY_SCHEMA_VERSIONS.includes(value), { message: `schemaVersion must be one of: ${SUPPORTED_PR_READY_SCHEMA_VERSIONS.join(", ")}` });
 const prReadyProofSchema = z.object({
+	blockedReasons: blockedReasonsSchema.optional(),
 	blockingReasons: z.array(z.string()),
 	command: z.literal("patronage-factory pr:ready"),
 	followUp: followUpActionSchema.optional(),
@@ -760,12 +1233,25 @@ const prReadyProofSchema = z.object({
 	profilePath: z.string().min(1).optional(),
 	repairs: z.array(readinessRepairSchema).default([]),
 	repository: z.string().regex(/^[^/\s]+\/[^/\s]+$/u).optional(),
-	schemaVersion: z.literal(1),
+	schemaVersion: prReadySchemaVersionSchema,
 	status: z.enum([
 		"ready",
 		"blocked",
 		"slice-ready/not-final"
 	])
+}).superRefine((proof, context) => {
+	if (proof.schemaVersion < 2) {
+		if (proof.blockedReasons !== void 0) context.addIssue({
+			code: "custom",
+			message: "blockedReasons is a schemaVersion 2 field; a v1 pr:ready proof must not carry it.",
+			path: ["blockedReasons"]
+		});
+		return;
+	}
+	for (const issue of blockedReasonIssues({
+		...proof,
+		finalReviewPoint: proof.ledger.finalReviewPoint
+	})) context.addIssue(issue);
 });
 //#endregion
-export { BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, EVIDENCE_ENVELOPE_SCHEMA_VERSION, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema };
+export { BLOCKED_REASONS_MAX, BLOCKED_REASON_DETAIL_MAX, BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, EVIDENCE_ENVELOPE_SCHEMA_VERSION, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, SUPPORTED_PR_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "0.20.0",
+  "version": "0.25.0",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {