@patronage/software-factory 1.0.0-alpha.23 → 1.0.0-alpha.24

package/dist/schemas.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 //#region src/packages/review-prompt-sections/schema.d.ts
 declare const reviewPromptSectionSchema: z.ZodObject<{
   provenance: z.ZodEnum<{
+    "coding-standards": "coding-standards";
     "prior-review-ledger": "prior-review-ledger";
     "issue-review-focus": "issue-review-focus";
   }>;
@@ -12,6 +13,7 @@ type ReviewPromptSection = z.infer<typeof reviewPromptSectionSchema>;
 type ReviewPromptSectionProvenance = ReviewPromptSection["provenance"];
 declare const reviewPromptSectionsSchema: z.ZodArray<z.ZodObject<{
   provenance: z.ZodEnum<{
+    "coding-standards": "coding-standards";
     "prior-review-ledger": "prior-review-ledger";
     "issue-review-focus": "issue-review-focus";
   }>;
@@ -225,21 +227,38 @@ declare const boundaryReviewProofBaseSchema: z.ZodObject<{
 }, z.core.$loose>;
 type BoundaryReviewProof = z.infer<typeof boundaryReviewProofBaseSchema>;
 //#endregion
-//#region src/follow-up.d.ts
-interface FollowUpAction {
-  /**
-   * Machine-safe argv-style array for the obvious next action, e.g.
-   * ["gh","pr","merge","513","--squash"]. Same shape and field name that
-   * `factory:delegate --print` emits, so an orchestrating agent can spawn the
-   * next command without reconstructing a shell string. argv[0] is the
-   * executable; the rest are literal, already-split arguments.
-   */
-  argv: string[];
+//#region src/policy-resolution.d.ts
+/** How a gate resolved the review policy it evaluated a candidate under. */
+declare const policyResolutionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  basePolicyDigest: z.ZodString;
+  baseRefName: z.ZodString;
+  candidatePolicyDigest: z.ZodString;
+  effectiveDigest: z.ZodString;
+  policyBaseSha: z.ZodString;
+  reviewPolicyChanged: z.ZodBoolean;
+  status: z.ZodLiteral<"authoritative">;
+}, z.core.$strict>, z.ZodObject<{
+  baseRefName: z.ZodString;
+  reason: z.ZodString;
+  status: z.ZodLiteral<"unresolved">;
+}, z.core.$strict>], "status">;
+type PolicyResolution = z.infer<typeof policyResolutionSchema>;
+//#endregion
+//#region src/catch-up-recognition-record.d.ts
+interface CatchUpRecognition {
+  /** The ref the candidate targets, as the recognizing command resolved it. */
+  baseRef: string;
+  /** The live target tip at recognition time; the head's first parent. */
+  baseTipSha: string;
+  /** The head's second parent: the admitted base-side content merged in. */
+  mergedParentSha: string;
   /**
-   * Human-readable rendering of {@link argv} for logs and operators. Additive
-   * to argv, never a substitute for it — argv is the source of truth.
+   * The tree `git merge-tree --write-tree` produced for the two parents. It
+   * equals the head's own tree; that equality is the faithfulness proof.
    */
-  command: string;
+  mergedTreeSha: string;
+  /** The ref that proves the second parent is admitted content. */
+  upstreamRef: string;
 }
 //#endregion
 //#region src/diff-classification.d.ts
@@ -274,6 +293,23 @@ declare const impactStampSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ImpactStamp = z.infer<typeof impactStampSchema>;
 //#endregion
+//#region src/follow-up.d.ts
+interface FollowUpAction {
+  /**
+   * Machine-safe argv-style array for the obvious next action, e.g.
+   * ["gh","pr","merge","513","--squash"]. Same shape and field name that
+   * `factory:delegate --print` emits, so an orchestrating agent can spawn the
+   * next command without reconstructing a shell string. argv[0] is the
+   * executable; the rest are literal, already-split arguments.
+   */
+  argv: string[];
+  /**
+   * Human-readable rendering of {@link argv} for logs and operators. Additive
+   * to argv, never a substitute for it — argv is the source of truth.
+   */
+  command: string;
+}
+//#endregion
 //#region src/pr-verify-mode.d.ts
 /**
  * The verification mode `pr:verify` resolved for a run.
@@ -388,12 +424,12 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       "interior-cap-reached": "interior-cap-reached";
     }>>;
     nextAction: z.ZodEnum<{
-      "run-interior-cycle": "run-interior-cycle";
-      "advance-to-gate": "advance-to-gate";
       "run-gate-cycle": "run-gate-cycle";
       "accept-nonblocking-findings": "accept-nonblocking-findings";
       "escalate-to-triage": "escalate-to-triage";
       "ready-for-human": "ready-for-human";
+      "advance-to-gate": "advance-to-gate";
+      "run-interior-cycle": "run-interior-cycle";
     }>;
     stage: z.ZodEnum<{
       gate: "gate";
@@ -461,23 +497,6 @@ type ReadinessRepair = z.infer<typeof readinessRepairSchema>;
 type ReadinessStatus = "ready" | "blocked";
 type ManagedReadinessLedger = z.infer<typeof managedReadinessLedgerSchema>;
 //#endregion
-//#region src/catch-up-recognition-record.d.ts
-interface CatchUpRecognition {
-  /** The ref the candidate targets, as the recognizing command resolved it. */
-  baseRef: string;
-  /** The live target tip at recognition time; the head's first parent. */
-  baseTipSha: string;
-  /** The head's second parent: the admitted base-side content merged in. */
-  mergedParentSha: string;
-  /**
-   * The tree `git merge-tree --write-tree` produced for the two parents. It
-   * equals the head's own tree; that equality is the faithfulness proof.
-   */
-  mergedTreeSha: string;
-  /** The ref that proves the second parent is admitted content. */
-  upstreamRef: string;
-}
-//#endregion
 //#region src/pr-verify-proof-contract.d.ts
 declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [1, 2, 3, 4];
 type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
@@ -713,6 +732,13 @@ interface PrReadyProof {
    * waived demand reads to a human. Absent when there are none.
    */
   notices?: string[];
+  /**
+   * The policy identity readiness resolved review demand under (#922): the
+   * base ref, its live tip, and the digests of the base, candidate, and merged
+   * review policies. Optional on the wire and additive — this is a new record
+   * on an unchanged contract, so no schema version moves.
+   */
+  policyResolution?: PolicyResolution;
   /** Committed profile blob evaluated by readiness. Required for merge. */
   profileBlobSha?: string;
   /** Checkout-relative committed profile path evaluated by readiness. */
@@ -1086,20 +1112,18 @@ declare const prReadyProofSchema: z.ZodObject<{
       forcedTransition: z.ZodOptional<z.ZodEnum<{
         "gate-cap-exhausted": "gate-cap-exhausted";
         "interior-cap-reached": "interior-cap-reached";
-        "interior-takeover": "interior-takeover";
       }>>;
       nextAction: z.ZodEnum<{
-        "run-interior-cycle": "run-interior-cycle";
-        "advance-to-gate": "advance-to-gate";
         "run-gate-cycle": "run-gate-cycle";
         "accept-nonblocking-findings": "accept-nonblocking-findings";
         "escalate-to-triage": "escalate-to-triage";
         "ready-for-human": "ready-for-human";
+        "advance-to-gate": "advance-to-gate";
+        "run-interior-cycle": "run-interior-cycle";
       }>;
       stage: z.ZodEnum<{
         gate: "gate";
         interior: "interior";
-        "interior-takeover": "interior-takeover";
         "interior-complete": "interior-complete";
       }>;
     }, z.core.$strip>>;
@@ -1166,6 +1190,19 @@ declare const prReadyProofSchema: z.ZodObject<{
     }, z.core.$strict>], "prVerify">;
   }, z.core.$strip>;
   notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  policyResolution: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    basePolicyDigest: z.ZodString;
+    baseRefName: z.ZodString;
+    candidatePolicyDigest: z.ZodString;
+    effectiveDigest: z.ZodString;
+    policyBaseSha: z.ZodString;
+    reviewPolicyChanged: z.ZodBoolean;
+    status: z.ZodLiteral<"authoritative">;
+  }, z.core.$strict>, z.ZodObject<{
+    baseRefName: z.ZodString;
+    reason: z.ZodString;
+    status: z.ZodLiteral<"unresolved">;
+  }, z.core.$strict>], "status">>;
   profileBlobSha: z.ZodOptional<z.ZodString>;
   profilePath: z.ZodOptional<z.ZodString>;
   repairs: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/schemas.js

@@ -2,12 +2,12 @@ import { z } from "zod";
 import "yaml";
 import "picomatch";
 //#region src/review-rungs.ts
-const EVIDENCE_REVIEW_RUNGS$1 = [
+const EVIDENCE_REVIEW_RUNGS = [
 	"independent-model",
 	"oracle",
 	"human"
 ];
-Object.fromEntries(EVIDENCE_REVIEW_RUNGS$1.map((rung, index) => [rung, index]));
+Object.fromEntries(EVIDENCE_REVIEW_RUNGS.map((rung, index) => [rung, index]));
 //#endregion
 //#region src/demand-keys.ts
 /** The demands that exist at most once per candidate. */
@@ -116,7 +116,7 @@ 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-rung") return EVIDENCE_REVIEW_RUNGS.includes(decoded);
 	if (family === "review-mode") return REVIEW_MODE_DEMAND_VALUES.includes(decoded);
 	return true;
 };
@@ -234,8 +234,71 @@ const waivedDemandSchema = z.object({
 	unmetReasons: z.array(z.string().min(1)).min(1)
 });
 //#endregion
+//#region src/diff-classification.ts
+const DIFF_CLASSIFICATIONS = [
+	"docs/process-only",
+	"trivial",
+	"non-trivial"
+];
+//#endregion
+//#region src/policy-resolution.ts
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const digestSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+/**
+* The authority resolved: the live tip of the PR's own base ref served a
+* parseable profile, and demand was resolved from the union of that policy and
+* the candidate's.
+*
+* Every identity field is REQUIRED. A cross-stage reader compares these digests
+* to decide whether two stages judged the same candidate under the same policy;
+* an `authoritative` record with a digest missing would read to that reader as
+* "nothing disagrees", which is a silent downgrade of exactly the demand this
+* record exists to protect. `reason` is forbidden here — a resolved authority
+* has nothing to explain.
+*/
+const authoritativePolicyResolutionSchema = z.object({
+	/** sha256 of the canonical base `review` subtree. */
+	basePolicyDigest: digestSchema,
+	/** The PR's own base ref, whose live tip is the authority. */
+	baseRefName: z.string().min(1),
+	/** sha256 of the canonical candidate `review` subtree. */
+	candidatePolicyDigest: digestSchema,
+	/** sha256 of the merged (base ∪ candidate) protected-path set. */
+	effectiveDigest: digestSchema,
+	/** The base-ref tip the base policy was read at. */
+	policyBaseSha: z.string().regex(COMMIT_SHA_PATTERN),
+	/**
+	* Whether the candidate's `review` subtree differs from the base's. The
+	* digests prove which policies were read; this says whether they agreed,
+	* which is the fact that explains a demand the candidate's own profile
+	* would not have produced.
+	*/
+	reviewPolicyChanged: z.boolean(),
+	status: z.literal("authoritative")
+}).strict();
+/**
+* The authority could not be read, and `reason` says why — required, because an
+* unresolved record with no reason is an unactionable refusal. `pr:ready`
+* refuses before it writes a proof, so a Slice A ready proof never carries one;
+* this member is the recorded form of that refusal for the stages that carry it
+* forward.
+*/
+const unresolvedPolicyResolutionSchema = z.object({
+	/** The base ref whose policy could not be read. */
+	baseRefName: z.string().min(1),
+	/** Why the authority is unresolved. */
+	reason: z.string().min(1),
+	status: z.literal("unresolved")
+}).strict();
+/** How a gate resolved the review policy it evaluated a candidate under. */
+const policyResolutionSchema = z.discriminatedUnion("status", [authoritativePolicyResolutionSchema, unresolvedPolicyResolutionSchema]);
+//#endregion
 //#region src/packages/review-prompt-sections/schema.ts
-const REVIEW_PROMPT_SECTION_PROVENANCES = ["prior-review-ledger", "issue-review-focus"];
+const REVIEW_PROMPT_SECTION_PROVENANCES = [
+	"coding-standards",
+	"prior-review-ledger",
+	"issue-review-focus"
+];
 const nonBlankString$1 = z.string().refine((value) => value.trim().length > 0, { message: "must not be blank" });
 const reviewPromptSectionSchema = z.object({
 	provenance: z.enum(REVIEW_PROMPT_SECTION_PROVENANCES),
@@ -617,6 +680,20 @@ z.array(z.object({
 }).strict());
 //#endregion
 //#region src/review-ladder.ts
+const LADDER_NEXT_ACTION_KINDS = [
+	"run-interior-cycle",
+	"advance-to-gate",
+	"run-gate-cycle",
+	"accept-nonblocking-findings",
+	"escalate-to-triage",
+	"ready-for-human"
+];
+const LADDER_STAGES = [
+	"interior",
+	"interior-complete",
+	"gate"
+];
+const LADDER_FORCED_TRANSITION_KINDS = ["gate-cap-exhausted", "interior-cap-reached"];
 const ladderCycleRefsFor = (cycles) => {
 	let interior = 0;
 	let gate = 0;
@@ -685,7 +762,7 @@ const prReviewResultSchema = z.object({
 	]),
 	producer: nonBlankString.optional(),
 	promptSections: reviewPromptSectionsSchema.optional(),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS$1).optional(),
+	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
 	sessionId: nonBlankString.optional(),
 	startedAt: parseableDateString,
 	summary: z.string().refine((value) => value.trim().length > 0 && value !== "<one sentence>", { message: "summary must not be blank or a placeholder" }),
@@ -751,6 +828,17 @@ const prReviewProofSchema = z.object({
 	});
 });
 //#endregion
+//#region src/required-check-policy.ts
+const EVIDENCE_CHECK_TYPES = ["review", "verify"];
+const requiredCheckScopeSchema = z.object({ classifications: z.array(z.enum(DIFF_CLASSIFICATIONS)).min(1) }).strict();
+const reviewStatusSchema = z.enum([
+	"not-required",
+	"current",
+	"stale",
+	"missing",
+	"blocked"
+]);
+//#endregion
 //#region src/review-state.ts
 const reviewStateIssue = (message, field) => [{
 	code: "custom",
@@ -1228,24 +1316,12 @@ const closeoutArtifactSchema = z.object({
 }).strict();
 //#endregion
 //#region src/schemas.ts
-const EVIDENCE_CHECK_TYPES = ["review", "verify"];
-const EVIDENCE_REVIEW_RUNGS = [
-	"independent-model",
-	"oracle",
-	"human"
-];
-const DIFF_CLASSIFICATIONS = [
-	"docs/process-only",
-	"trivial",
-	"non-trivial"
-];
-const REVIEW_STATUS_VALUES = [
-	"not-required",
-	"current",
-	"stale",
-	"missing",
-	"blocked"
-];
+const evidenceCheckTypeSchema = z.enum(EVIDENCE_CHECK_TYPES);
+const evidenceReviewRungSchema = z.enum(EVIDENCE_REVIEW_RUNGS);
+const diffClassificationSchema = z.enum(DIFF_CLASSIFICATIONS);
+const ladderStageSchema = z.enum(LADDER_STAGES);
+const ladderNextActionSchema = z.enum(LADDER_NEXT_ACTION_KINDS);
+const ladderForcedTransitionSchema = z.enum(LADDER_FORCED_TRANSITION_KINDS);
 const followUpActionSchema = z.object({
 	argv: z.array(z.string()),
 	command: z.string()
@@ -1254,7 +1330,7 @@ const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
 const evidenceShaSchema = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
 const evidenceEnvelopeSchema = z.object({
 	check: z.string().min(1),
-	checkType: z.enum(EVIDENCE_CHECK_TYPES),
+	checkType: evidenceCheckTypeSchema,
 	findingsPointer: z.string().min(1).optional(),
 	headSha: evidenceShaSchema,
 	mergeBaseSha: evidenceShaSchema,
@@ -1264,7 +1340,7 @@ const evidenceEnvelopeSchema = z.object({
 	policyVersion: z.string().min(1).optional(),
 	producer: z.string().min(1),
 	requestId: z.string().min(1).optional(),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
+	rung: evidenceReviewRungSchema.optional(),
 	schemaVersion: z.literal(1),
 	sessionId: z.string().trim().min(1).optional(),
 	timestamp: z.iso.datetime().optional()
@@ -1327,7 +1403,7 @@ const boundaryReviewProofSchema = z.object({
 	}).passthrough(),
 	outcome: z.enum(["pass", "fail"]),
 	producer: z.string().min(1),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS),
+	rung: evidenceReviewRungSchema,
 	schemaVersion: z.literal(1),
 	sessionId: z.string().min(1).optional(),
 	specHash: z.object({
@@ -1348,7 +1424,7 @@ const boundaryCheckProofSchema = z.object({
 		state: z.enum(["merged", "open"]),
 		wave: z.string().min(1)
 	})),
-	demandedRung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
+	demandedRung: evidenceReviewRungSchema.optional(),
 	epicIssue: z.number().int().positive(),
 	manifestHash: z.object({
 		algo: z.literal("sha256"),
@@ -1360,7 +1436,7 @@ const boundaryCheckProofSchema = z.object({
 		commentId: z.union([z.string(), z.number()]).optional(),
 		commentUrl: z.string().optional(),
 		producer: z.string().min(1),
-		rung: z.enum(EVIDENCE_REVIEW_RUNGS),
+		rung: evidenceReviewRungSchema,
 		sessionId: z.string().min(1).optional(),
 		specHash: z.object({
 			algo: z.literal("sha256"),
@@ -1375,7 +1451,6 @@ const boundaryCheckProofSchema = z.object({
 	}).optional(),
 	status: z.enum(["ready", "blocked"])
 });
-const requiredCheckScopeSchema = z.object({ classifications: z.array(z.enum(DIFF_CLASSIFICATIONS)).min(1) }).strict();
 const readinessRepairSchema = z.object({
 	action: z.string().min(1),
 	code: z.enum([
@@ -1389,7 +1464,7 @@ const reviewStateSchema = z.object({
 	required: z.boolean(),
 	reviewedHeadSha: z.string().optional(),
 	reviewedPatchId: z.string().optional(),
-	status: z.enum(REVIEW_STATUS_VALUES)
+	status: reviewStatusSchema
 }).strict().superRefine((state, context) => {
 	for (const issue of reviewStateIssues(state)) context.addIssue(issue);
 });
@@ -1410,9 +1485,9 @@ const historicalHandledHumanCommentSchema = z.object({
 const managedReadinessLedgerSchema = z.object({
 	baseSha: z.string().regex(/^[0-9a-f]{40}$/u),
 	blockingReasons: z.array(z.string()),
-	classification: z.enum(DIFF_CLASSIFICATIONS),
+	classification: diffClassificationSchema,
 	externalChecks: z.array(z.object({
-		checkType: z.enum(EVIDENCE_CHECK_TYPES),
+		checkType: evidenceCheckTypeSchema,
 		name: z.string().min(1),
 		reason: z.string().optional(),
 		scope: requiredCheckScopeSchema.optional(),
@@ -1485,25 +1560,9 @@ const managedReadinessLedgerSchema = z.object({
 			gate: z.number().int().nonnegative(),
 			interior: z.number().int().nonnegative()
 		}),
-		forcedTransition: z.enum([
-			"gate-cap-exhausted",
-			"interior-cap-reached",
-			"interior-takeover"
-		]).optional(),
-		nextAction: z.enum([
-			"run-interior-cycle",
-			"advance-to-gate",
-			"run-gate-cycle",
-			"accept-nonblocking-findings",
-			"escalate-to-triage",
-			"ready-for-human"
-		]),
-		stage: z.enum([
-			"interior",
-			"interior-takeover",
-			"interior-complete",
-			"gate"
-		])
+		forcedTransition: ladderForcedTransitionSchema.optional(),
+		nextAction: ladderNextActionSchema,
+		stage: ladderStageSchema
 	}).optional(),
 	reviewRuns: z.array(prReviewResultSchema).optional(),
 	reviewTerminalState: z.enum([
@@ -1580,6 +1639,7 @@ const prReadyProofSchema = z.object({
 	humanBlockingReasons: z.array(z.string()).default([]),
 	ledger: managedReadinessLedgerSchema,
 	notices: z.array(z.string().min(1)).optional(),
+	policyResolution: policyResolutionSchema.optional(),
 	profileBlobSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	profilePath: z.string().min(1).optional(),
 	repairs: z.array(readinessRepairSchema).default([]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.23",
+  "version": "1.0.0-alpha.24",
   "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.23"
+    "@patronage/factory-ci": "1.0.0-alpha.24"
   },
   "devDependencies": {
     "@types/node": "24.13.3",