@patronage/software-factory 0.20.0 → 0.23.0

package/dist/schemas.d.ts

@@ -1,5 +1,24 @@
 import { z } from "zod";
 
+//#region src/demand-waiver.d.ts
+/**
+ * A demand that was in force, was NOT met, and was waived by the operator.
+ *
+ * `unmetReasons` is required and non-empty: every reason the demand refused is
+ * carried through verbatim. There is no field on this record that could say
+ * "satisfied", and no code path constructs one without a refusal to carry.
+ */
+interface WaivedDemand {
+  demand: string;
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  session: string;
+  /** The demand's refusals at evaluation time, preserved verbatim. */
+  unmetReasons: string[];
+}
+declare const waivedDemandSchema: z.ZodType<WaivedDemand>;
+//#endregion
 //#region src/boundary-review-proof.d.ts
 declare const boundaryReviewProofBaseSchema: z.ZodObject<{
   boundary: z.ZodString;
@@ -64,20 +83,6 @@ interface FollowUpAction {
   command: string;
 }
 //#endregion
-//#region src/diff-classification.d.ts
-declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
-type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
-//#endregion
-//#region src/pr-verify-mode.d.ts
-/**
- * The verification mode `pr:verify` resolved for a run.
- *
- * Canonically declared here rather than inside `pr-readiness/` so that modules
- * on either side of that boundary — the readiness proof shape and the durable
- * check-run payload — can name the same union without importing each other.
- */
-type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
-//#endregion
 //#region src/merge-preflight/worktree-held-branch.d.ts
 /**
  * Detects when a PR head branch is checked out in a local git worktree.
@@ -164,12 +169,33 @@ interface PrMergeCheckProof {
   notices?: string[];
   pr: number;
   status: "pass" | "fail";
+  /**
+   * Demands that were in force, were NOT met, and were waived by the operator
+   * (#354). Each entry carries the demand's refusals verbatim, so a waived
+   * demand can never read as a met one; the merge proceeds on the recorded
+   * operator act, not on evidence.
+   */
+  waivedDemands?: WaivedDemand[];
   /** Present when the PR head branch is checked out in a local worktree. */
   worktreeHeldBranch?: WorktreeHeldBranch;
   /** All merge-relevant branches held by local worktrees (head and default). */
   worktreeHeldBranches?: WorktreeHeldBranch[];
 }
 //#endregion
+//#region src/diff-classification.d.ts
+declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
+type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
+//#endregion
+//#region src/pr-verify-mode.d.ts
+/**
+ * The verification mode `pr:verify` resolved for a run.
+ *
+ * Canonically declared here rather than inside `pr-readiness/` so that modules
+ * on either side of that boundary — the readiness proof shape and the durable
+ * check-run payload — can name the same union without importing each other.
+ */
+type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
+//#endregion
 //#region src/packages/review-prompt-sections/schema.d.ts
 declare const reviewPromptSectionSchema: z.ZodObject<{
   provenance: z.ZodEnum<{
@@ -286,7 +312,7 @@ interface PrReviewProof {
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
   reviewRequirement?: {
-    reason: "docs-only-profile-bypass";
+    reason: "no-applicable-mode";
     status: "not-required";
   };
   reviews: PrReviewResult[];
@@ -720,9 +746,9 @@ declare const closeoutArtifactSchema: z.ZodObject<{
     unit: z.ZodEnum<{
       boolean: "boolean";
       text: "text";
+      count: "count";
       tokens: "tokens";
       usd: "usd";
-      count: "count";
       ratio: "ratio";
     }>;
     value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>;
@@ -732,6 +758,187 @@ declare const closeoutArtifactSchema: z.ZodObject<{
 }, z.core.$strict>;
 type CloseoutArtifact = z.infer<typeof closeoutArtifactSchema>;
 //#endregion
+//#region src/retro-envelope.d.ts
+/**
+ * Versioned retro envelope schema (epic #27 wave 2, issue #34).
+ *
+ * One envelope per lane, built at `factory:closeout` and delivered through the
+ * typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
+ * from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
+ * merged). This module is the single source of truth for the v1 wire shape
+ * and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}) — producer and consumer
+ * alike. HQ imports these exports directly from the Worker-safe
+ * `@patronage/software-factory/schemas` subpath
+ * (`software-factory-hq/src/contracts/retro-schemas.ts`) instead of
+ * maintaining a parallel hand-written copy, so there is exactly one wire
+ * contract and no drift-detection machinery is needed (issue #350; formerly
+ * a hand-written twin plus a 767-line parity test, #46).
+ *
+ * DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
+ *
+ * The two model families use different tokenizers, prices, and accounting
+ * conventions, so any token total that spans Claude and GPT is a lie:
+ *
+ * 1. There is no combined/total token field anywhere in the envelope.
+ * 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
+ *    cannot smuggle in a third "all"/"combined" slot.
+ * 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
+ *    (claude is a single flat block keyed on freshInput/cacheReadInput/
+ *    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
+ *    COUNTS share no key name across families. The residual names shared
+ *    between the claude block and a gpt ROLE entry are pinned to exactly
+ *    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
+ *    USD is the one cross-family summable unit (rule 4); `model` is an
+ *    unsummable label; `output` is the same name at DIFFERENT depths (lane
+ *    block vs per-role entry), frozen by a tripwire test in
+ *    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
+ *    is a schemaVersion-2 wire change, deliberately not spent in v1.
+ * 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
+ *    only, and only as a projection-time sum of per-family USD.
+ *
+ * Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
+ * is not prompt size (true input context = freshInput + cacheReadInput +
+ * cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
+ * already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
+ * is the only value safe to feed a per-token pricer.
+ *
+ * COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
+ * `tokenFamilies` may legitimately be absent. The closeout build gate demands
+ * a valid envelope, not available telemetry. A families-absent envelope keeps
+ * its operator-visible data gaps and is a replayable advisory HQ event, so it
+ * never substitutes unavailable usage with zero. The wire shape (field names,
+ * types, structure) stays byte-parity with HQ v1.
+ */
+declare const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
+/**
+ * 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.
+ */
+declare const RETRO_ENVELOPE_WIRE_BOUNDS: {
+  /** archiveRef pointer (key/URL) max characters. */readonly archiveRefMaxChars: 2048; /** refs.branch max characters (git ref length ceiling). */
+  readonly branchMaxChars: 255; /** gates[] wire cap — the builder keeps the most recent records. */
+  readonly gatesMax: 500; /** gpt roles[] cap (delegated roles per lane). */
+  readonly gptRolesMax: 20; /** Cap for list fields: joinKeys id arrays, phases, dataGaps. */
+  readonly listMax: 100; /** Bounded name fields: agentRunId, gate, phase name, refs, join-key ids. */
+  readonly nameMaxChars: 200; /** Short identifier fields: repo name/owner, model, role. */
+  readonly shortMaxChars: 100; /** Free-text fields: dataGaps entries, outcome.verdict. */
+  readonly textMaxChars: 500;
+};
+declare const retroEnvelopeV1Schema: z.ZodObject<{
+  agentRunId: z.ZodString;
+  archiveRef: z.ZodOptional<z.ZodString>;
+  cycles: z.ZodObject<{
+    gateRunsToFirstGreen: z.ZodNumber;
+    reviewerFixRounds: z.ZodNumber;
+    thermoFixRounds: z.ZodNumber;
+  }, z.core.$strict>;
+  dataGaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  gates: z.ZodArray<z.ZodObject<{
+    cycle: z.ZodNumber;
+    duration: z.ZodNumber;
+    gate: z.ZodString;
+    outcome: z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      skip: "skip";
+    }>;
+    startedAt: z.ZodISODateTime;
+  }, z.core.$strict>>;
+  generatedAt: z.ZodISODateTime;
+  interventions: z.ZodObject<{
+    count: z.ZodNumber;
+  }, z.core.$strict>;
+  joinKeys: z.ZodObject<{
+    claudeSessionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codexThreadIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>;
+  kind: z.ZodLiteral<"retro-envelope">;
+  outcome: z.ZodOptional<z.ZodObject<{
+    mergeCheck: z.ZodOptional<z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      "not-run": "not-run";
+    }>>;
+    status: z.ZodEnum<{
+      fail: "fail";
+      success: "success";
+      blocked: "blocked";
+      "ship-with-followups": "ship-with-followups";
+    }>;
+    verdict: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  phases: z.ZodArray<z.ZodObject<{
+    at: z.ZodISODateTime;
+    deltaSec: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+  }, z.core.$strict>>;
+  refs: z.ZodObject<{
+    branch: z.ZodOptional<z.ZodString>;
+    epic: z.ZodOptional<z.ZodString>;
+    headSha: z.ZodOptional<z.ZodString>;
+    issue: z.ZodOptional<z.ZodString>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>;
+  repo: z.ZodObject<{
+    name: z.ZodString;
+    owner: z.ZodString;
+  }, z.core.$strict>;
+  schemaVersion: z.ZodLiteral<1>;
+  tokenFamilies: z.ZodObject<{
+    claude: z.ZodOptional<z.ZodObject<{
+      cacheCreationInput: z.ZodNumber;
+      cacheReadInput: z.ZodNumber;
+      costUsd: z.ZodNullable<z.ZodNumber>;
+      family: z.ZodLiteral<"claude">;
+      freshInput: z.ZodNumber;
+      model: z.ZodString;
+      output: z.ZodNumber;
+      requests: z.ZodNumber;
+    }, z.core.$strict>>;
+    gpt: z.ZodOptional<z.ZodObject<{
+      family: z.ZodLiteral<"gpt">;
+      roles: z.ZodArray<z.ZodObject<{
+        cachedInput: z.ZodNumber;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        freshInputDerived: z.ZodNumber;
+        inputInclusiveOfCache: z.ZodNumber;
+        model: z.ZodString;
+        output: z.ZodNumber;
+        reasoningOutput: z.ZodNumber;
+        role: z.ZodString;
+        threadId: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  wallClock: z.ZodObject<{
+    endTs: z.ZodISODateTime;
+    startTs: z.ZodISODateTime;
+    totalSec: z.ZodNumber;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type RetroEnvelope = z.infer<typeof retroEnvelopeV1Schema>;
+/**
+ * Versioned payload validators, keyed by schema major. Unknown majors never
+ * reach these — {@link parseRetroEnvelope} returns them raw and marked
+ * degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
+ */
+declare const RETRO_ENVELOPE_VALIDATORS: Record<number, z.ZodType<RetroEnvelope, unknown>>;
+declare const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS: readonly number[];
+type ParsedRetroEnvelope = {
+  disposition: "trusted";
+  envelope: RetroEnvelope;
+  schemaVersion: number;
+} | {
+  disposition: "degraded";
+  raw: unknown;
+  schemaVersion: number | undefined;
+};
+/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
+declare const retroEpicReference: (refs: RetroEnvelope["refs"]) => string | undefined;
+//#endregion
 //#region src/schemas.d.ts
 declare const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
 declare const evidenceEnvelopeSchema: z.ZodObject<{
@@ -865,7 +1072,9 @@ declare const prReviewProofSchema: z.ZodObject<{
   patchId: z.ZodString;
   reviewCycle: z.ZodOptional<z.ZodNumber>;
   reviewRequirement: z.ZodOptional<z.ZodObject<{
-    reason: z.ZodLiteral<"docs-only-profile-bypass">;
+    reason: z.ZodEnum<{
+      "no-applicable-mode": "no-applicable-mode";
+    }>;
     status: z.ZodLiteral<"not-required">;
   }, z.core.$strict>>;
   reviews: z.ZodArray<z.ZodObject<{
@@ -1097,6 +1306,7 @@ declare const prMergeCheckProofSchema: z.ZodObject<{
     pass: "pass";
     fail: "fail";
   }>;
+  waivedDemands: z.ZodOptional<z.ZodArray<z.ZodType<WaivedDemand, unknown, z.core.$ZodTypeInternals<WaivedDemand, unknown>>>>;
   worktreeHeldBranch: z.ZodOptional<z.ZodObject<{
     branch: z.ZodString;
     worktreePath: z.ZodString;
@@ -1427,4 +1637,4 @@ declare const prReadyProofSchema: z.ZodObject<{
   }>;
 }, z.core.$strip>;
 //#endregion
-export { BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, BoundaryCheckProofRecord, type BoundaryReviewProof, type CloseoutArtifact, EVIDENCE_ENVELOPE_SCHEMA_VERSION, type EvidenceEnvelope, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, type PrMergeCheckProof, type PrReadyProof, type PrReviewProof, type PrVerifyProof, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema };
+export { BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, BoundaryCheckProofRecord, type BoundaryReviewProof, type CloseoutArtifact, EVIDENCE_ENVELOPE_SCHEMA_VERSION, type EvidenceEnvelope, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, type ParsedRetroEnvelope, type PrMergeCheckProof, type PrReadyProof, type PrReviewProof, type PrVerifyProof, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, type RetroEnvelope, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type WaivedDemand, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };

package/dist/schemas.js

@@ -1,4 +1,39 @@
 import { z } from "zod";
+//#region src/demand-waiver.ts
+const DEMAND_WAIVER_SCHEMA_VERSION = 1;
+const shaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
+/**
+* A resolved demand's key: a family, optionally qualified by the resolved
+* value that makes it this demand *instance* (`review-rung:human`,
+* `required-check:core`, `merge-freeze`). The consumer that resolved the
+* demand owns the key; this module only matches on it, which is why no
+* control name is enumerated here.
+*/
+const demandKeySchema = 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).");
+const demandWaiverSchema = z.object({
+	candidate: z.object({
+		headSha: shaSchema,
+		pr: z.number().int().positive()
+	}),
+	demand: demandKeySchema,
+	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: demandKeySchema,
+	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 +138,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 +679,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 +829,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)
@@ -768,4 +1037,4 @@ const prReadyProofSchema = z.object({
 	])
 });
 //#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 { 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_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, 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.23.0",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {