@patronage/software-factory 1.0.0-alpha.8 → 1.0.0-alpha.9

package/CONTEXT.md

@@ -6,12 +6,22 @@ The shared Patronage software factory: typed lifecycle state, proof gates, and o
 
 ## Language
 
+### Admission
+
+**Candidate**: The exact patch under admission — the `headSha` / `patchId` / `mergeBaseSha` identity every piece of evidence binds to. A GitHub draft pull request is not a Candidate; GitHub's draft boolean is the machine lifecycle authority, and ready-for-review is the Candidate state. Experiment and interactive describe human intent only and create no machine states.
+
+**Promotion**: The one transition from a draft pull request into a Candidate. `pr:publish` is the promotion verb. Its composed handoff finishes proof while draft, promotes, then evaluates Candidate demands at the unchanged head. Draft open and synchronize events run no substantive hosted Verify battery; `ready_for_review` starts the complete applicable Candidate pass.
+
 ### Proof reuse
 
 **Proof gate**: A command that emits a typed proof — the self-timed set is `pr:verify`, `pr:review`, `pr:ready`, `boundary:check`, and `factory:closeout`; one execution is a **gate run**. Typed proof files are the source of readiness truth; prose never substitutes.
 
 **Proof-reuse gate**: The decision that consumes trusted verification proof and determines whether hosted CI may skip work already performed. Refusing reuse runs the hosted suite; it does not fail the candidate. Defined by ADR 0022. _Avoid_: proof gate (that produces readiness proof rather than reusing it).
 
+### Impact
+
+**Impact**: The candidate-bound classification of which declared product targets a changed path or lockfile graph can reach. Path impact is opt-in: a target is affected if and only if a valid changed path matches one of its declared globs. A valid path matched by no target is **unsubscribed** and demands no target-scoped work, while remaining explicit in the stamp basis and human summary. Shared paths affect every target that subscribes to them. Invalid paths and unreadable or malformed required inputs still fail closed. Impact may withdraw target-scoped work; it never certifies a merge target, whose push-triggered verification stays full. Defined by ADR 0027. _Avoid_: affectedness; ownership (the declaration is a subscription, not an implicit filesystem owner).
+
 ### Planning intake
 
 **Spec**: The single through-line planning artifact — a technical, non-technical, or blended description of the work to be built, produced by `to-spec`. The term supersedes "PRD"; older artifacts titled "PRD:" (e.g. #232) are specs by another name. _Avoid_: PRD (retired), requirements doc.

package/README.md

@@ -37,7 +37,7 @@ A stacked release train has one terminal release-owning slice. Interior slices d
 A stable cut has two phases. Phase 1 is the verified package candidate: steps 1 through 4 below, ending in the attended npm publish, tag, and GitHub release. Phase 2 is post-publication stable-doc convergence: steps 5 and 6, a normal admitted docs PR followed by the read-only convergence assertion from a clean `main`. Stable docs must never claim an unpublished version, so they cannot land in the phase-1 change. Prerelease behavior is unchanged: prerelease notes may land before publish while stable docs keep naming the prior stable version.
 
 1. Bump `package.json` to valid SemVer. The assertion derives its expected stable or prerelease channel from the version; it accepts no channel flag.
-2. Publish to npm per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended, hand-cut, `pnpm publish` only). **Always pass `--tag` explicitly, on every publish, prerelease or stable** — `pnpm --filter @patronage/software-factory publish --tag next` for a prerelease, `--tag latest` for a stable cut. A filtered publish takes pnpm's recursive path, which passes its own `--tag` (defaulting to `latest`) to npm and therefore ignores the `publishConfig.tag: next` pin both factory packages carry; that is how 1.0.0-alpha.6 briefly took `latest` (#658). The pins stay as belt and braces, but they are not the control. Omitting the flag is not a safe failure: on the filtered command it moves `latest`, which the convergence assertion can only report after the fact.
+2. Build and review one pnpm tarball, then publish that exact tarball per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended and hand-cut). Publishing the workspace directory is not allowed because it rebuilds during `prepack` after the artifact review. **Always pass `--tag` explicitly, on every publish, prerelease or stable**: `pnpm publish "$SOFTWARE_FACTORY_TARBALL" --tag next --access public` for a prerelease, `--tag latest` for a stable cut. A filtered directory publish takes pnpm's recursive path, which passes its own `--tag` (defaulting to `latest`) to npm and therefore ignores the `publishConfig.tag: next` pin both factory packages carry; that is how 1.0.0-alpha.6 briefly took `latest` (#658). The pins stay as belt and braces, but they are not the control. Omitting the flag is not a safe failure: it moves `latest`, which the convergence assertion can only report after the fact. The attended token path does not promise an npm provenance attestation; the source SHA and reviewed tarball SRI are its operational provenance.
 3. Cut the `software-factory-vX.Y.Z` tag and push it.
 4. Cut the GitHub release for that tag, with notes covering features, deletions, breaking changes, and closed issues. Mark it as a prerelease exactly when its SemVer version has a prerelease component. When the release changes the profile `schemaVersion`, state it in the notes — the profile schema version is a separate axis from the package version.
 5. Converge the stable docs after publication. Update affected `software-factory-docs/` pages through a normal admitted docs PR. Stable docs must state the current stable version. Prerelease docs may record the candidate and its migration notes, but must not represent it as the current stable release.
@@ -60,6 +60,8 @@ pnpm exec patronage-factory --help   # or: psf --help
 
 The repository profile declares its admission policy. Operator-local settings and HQ credentials are documented separately, so they do not become committed project configuration.
 
+Generated production workflows may call `psf production:impact --before <sha> --after <sha> --github-output <path>`. The command recomputes the profile's opt-in impact subscriptions from those exact real commits and emits stable demanded/withdrawn target outputs, the changed-file decision basis, and unsubscribed paths. It only withdraws work: missing, zero, malformed, unreachable, non-ancestral, or otherwise unclassifiable identities leave every known target demanded. The factory owns this decision seam; each consumer owns its deploy jobs, commands, credentials, topology, and post-deploy convergence/no-op proof. Merge-target Verify remains full and does not consult this command.
+
 For factory workflow, install the four canonical skills from the repository:
 
 ```bash

package/dist/index.d.ts

@@ -743,8 +743,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    active: "active";
     stale: "stale";
+    active: "active";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1243,8 +1243,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        stale: "stale";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1255,8 +1255,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        stale: "stale";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1267,8 +1267,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      stale: "stale";
       passed: "passed";
+      stale: "stale";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1517,7 +1517,7 @@ declare const impactStampSchema: z.ZodObject<{
     conservative: "conservative";
   }>;
   reasons: z.ZodArray<z.ZodString>;
-  stampVersion: z.ZodLiteral<2>;
+  stampVersion: z.ZodLiteral<3>;
   targets: z.ZodArray<z.ZodObject<{
     basis: z.ZodString;
     impact: z.ZodEnum<{
@@ -1526,6 +1526,7 @@ declare const impactStampSchema: z.ZodObject<{
     }>;
     name: z.ZodString;
   }, z.core.$strip>>;
+  unsubscribedPaths: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 type ImpactStamp = z.infer<typeof impactStampSchema>;
 /**
@@ -1770,8 +1771,8 @@ declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale"
 declare const reviewStatusSchema: z.ZodEnum<{
   blocked: "blocked";
   "not-required": "not-required";
-  stale: "stale";
   current: "current";
+  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2177,9 +2178,9 @@ declare const retroEnvelopeV1Schema: z.ZodObject<{
   kind: z.ZodLiteral<"retro-envelope">;
   outcome: z.ZodOptional<z.ZodObject<{
     status: z.ZodEnum<{
-      blocked: "blocked";
       success: "success";
       fail: "fail";
+      blocked: "blocked";
       "ship-with-followups": "ship-with-followups";
     }>;
     verdict: z.ZodOptional<z.ZodString>;
@@ -3323,8 +3324,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3402,8 +3403,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3472,8 +3473,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      review: "review";
       code: "code";
+      review: "review";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3545,7 +3546,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "review" | "code";
+  purpose: "code" | "review";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -4066,13 +4067,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "blocked" | "not-required" | "stale" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "blocked" | "not-required" | "stale" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4080,7 +4081,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     schemaVersion: 1;
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "stale" | "passed" | "missing";
+      prVerify: "passed" | "stale" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;

package/dist/index.js

@@ -15,9 +15,9 @@ import { Worker } from "node:worker_threads";
 import picomatch from "picomatch";
 import { parse } from "yaml";
 import { promisify } from "node:util";
-import { FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, readVitestProfileDocument } from "@patronage/factory-ci";
+import { FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
 //#region package.json
-var version = "1.0.0-alpha.8";
+var version = "1.0.0-alpha.9";
 //#endregion
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS$1 = [
@@ -981,7 +981,7 @@ const requiredCheckSchema = z.object({
 const impactTargetSchema = z.object({
 	importers: z.array(z.string().min(1)).min(1),
 	name: z.string().min(1),
-	paths: z.array(repoRelativeGlobSchema).min(1).optional()
+	paths: z.array(repoRelativeGlobSchema).min(1).optional().describe("Opt-in repo-relative path subscriptions. A target is affected only when a valid changed path matches one of its globs; valid unmatched paths affect no target and are recorded as unsubscribed. Shared files must be listed by every subscribing target.")
 }).strict();
 const impactConfigSchema = z.object({ targets: z.array(impactTargetSchema).min(1).superRefine((targets, context) => {
 	const names = targets.map((target) => target.name);
@@ -3553,15 +3553,18 @@ const impactStampTargetSchema = z.object({
 const impactStampSchema = z.object({
 	basis: z.enum(["target-scoped", "conservative"]),
 	reasons: z.array(z.string()),
-	stampVersion: z.literal(2),
+	stampVersion: z.literal(3),
 	targets: z.array(impactStampTargetSchema).superRefine((targets, context) => {
 		const names = targets.map((target) => target.name);
 		if (new Set(names).size !== names.length) context.addIssue({
 			code: "custom",
 			message: "impact stamp targets must have distinct names."
 		});
-	})
+	}),
+	unsubscribedPaths: z.array(z.string())
 });
+/** Human-readable lines for every impact decision, including quiet releases. */
+const impactStampSummaryLines = (stamp) => [`Impact stamp: ${stamp.basis}; ${stamp.targets.filter(({ impact }) => impact === "affected").length}/${stamp.targets.length} target(s) affected.`, stamp.unsubscribedPaths.length === 0 ? "Unsubscribed changed paths: none." : `Unsubscribed changed paths (demand no target): ${stamp.unsubscribedPaths.join(", ")}`];
 /**
 * A configuration contradiction between the profile's impact declarations and
 * the repository's actual lockfile — e.g. a declared importer root that
@@ -3611,8 +3614,8 @@ const impactStampScopeDecision = ({ stamp, surface, targetName }) => {
 		reason: `no trusted identity-bound impact stamp covers this candidate; ${floor}`,
 		scoped: false
 	};
-	if (stamp.stampVersion !== 2) return {
-		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 2; ${floor}`,
+	if (stamp.stampVersion !== 3) return {
+		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 3; ${floor}`,
 		scoped: false
 	};
 	if (stamp.basis !== "target-scoped") return {
@@ -3654,15 +3657,16 @@ const impactStampDemandRelease = ({ checkName, stamp }) => {
 * every doubt path lands on, and the stamp a producer must fall back to if
 * stamp computation itself fails for any reason.
 */
-const conservativeImpactStamp = (targets, reasons) => ({
+const conservativeImpactStamp = (targets, reasons, unsubscribedPaths = []) => ({
 	basis: "conservative",
 	reasons,
-	stampVersion: 2,
+	stampVersion: 3,
 	targets: targets.map((target) => ({
 		basis: CONSERVATIVE_TARGET_BASIS,
 		impact: "affected",
 		name: target.name
-	}))
+	})),
+	unsubscribedPaths
 });
 const conservativeStamp = conservativeImpactStamp;
 const DEPENDENCY_FIELDS = [
@@ -3793,9 +3797,10 @@ const targetImpactForLockfileDelta = (target, delta) => {
 /**
 * Compute the impact stamp for one candidate: every declared target recorded
 * as affected/not-affected with its exact basis. `not-affected` is only ever
-* returned only when every changed input is owned by a declared source glob or
-* is an analyzable pnpm-lock.yaml (v9) delta. Source and lockfile reachability
-* are unioned per target. Any invalid, unmatched, unreadable, unsupported, or
+* returned only when every changed input is a valid source path or an
+* analyzable pnpm-lock.yaml (v9) delta. Source and lockfile reachability are
+* unioned per target. A valid source path matched by no target is recorded in
+* `unsubscribedPaths` and affects none. Invalid, unreadable, unsupported, or
 * otherwise doubtful input widens the whole stamp to full impact.
 *
 * Total by contract: this function never throws. Any unexpected failure in
@@ -3872,10 +3877,6 @@ const analyzeSourcePaths = (sourceFiles, targets, profilePath) => {
 			kind: "conservative",
 			reason: `changed source path "${file}" is the impact profile being evaluated; fail closed to full impact`
 		};
-		if (!targets.some((target) => matchesAnyGlob(target.paths ?? [], file))) return {
-			kind: "conservative",
-			reason: `changed source path "${file}" has no declared impact target owner; fail closed to full impact`
-		};
 	}
 	return {
 		kind: "ok",
@@ -3890,7 +3891,8 @@ const analyzeSourcePaths = (sourceFiles, targets, profilePath) => {
 				impact: "affected",
 				name: target.name
 			};
-		})
+		}),
+		unsubscribedPaths: sourceFiles.filter((file) => !targets.some((target) => matchesAnyGlob(target.paths ?? [], file)))
 	};
 };
 const unionTargetImpact = (source, lockfile) => {
@@ -3906,8 +3908,9 @@ const computeImpactStampOrThrow = ({ changedFiles, profilePath = "software-facto
 	if (targets.length === 0) return {
 		basis: "conservative",
 		reasons: ["no impact targets declared in the profile; every surface keeps full demand"],
-		stampVersion: 2,
-		targets: []
+		stampVersion: 3,
+		targets: [],
+		unsubscribedPaths: changedFiles.filter((file) => file !== "pnpm-lock.yaml" && isRepoRelativePath(file))
 	};
 	assertDeclaredPathGlobs(targets);
 	const sides = readLockfileSides(readLockfile);
@@ -3916,18 +3919,19 @@ const computeImpactStampOrThrow = ({ changedFiles, profilePath = "software-facto
 	const sourceFiles = changedFiles.filter((file) => file !== LOCKFILE_PATH);
 	const source = analyzeSourcePaths(sourceFiles, targets, profilePath);
 	if (source.kind === "conservative") return conservativeStamp(targets, [source.reason]);
-	if (sides.kind === "threw") throw sides.error;
-	if (sides.kind === "unreadable") return conservativeStamp(targets, [`pnpm-lock.yaml is unreadable at the ${sides.side} side; fail closed to full impact`]);
-	if (sides.kind === "unparseable") return conservativeStamp(targets, [`pnpm-lock.yaml is unparseable or structurally malformed at the ${sides.side} side; fail closed to full impact`]);
-	if (sides.kind === "unsupported-version") return conservativeStamp(targets, [`pnpm-lock.yaml is not lockfileVersion ${SUPPORTED_LOCKFILE_VERSION}; only pnpm v9 lockfiles are modelled; fail closed to full impact`]);
+	if (sides.kind === "threw") return conservativeStamp(targets, [`impact stamp computation failed (${sides.error instanceof Error ? sides.error.message : String(sides.error)}); fail closed to full impact`], source.unsubscribedPaths);
+	if (sides.kind === "unreadable") return conservativeStamp(targets, [`pnpm-lock.yaml is unreadable at the ${sides.side} side; fail closed to full impact`], source.unsubscribedPaths);
+	if (sides.kind === "unparseable") return conservativeStamp(targets, [`pnpm-lock.yaml is unparseable or structurally malformed at the ${sides.side} side; fail closed to full impact`], source.unsubscribedPaths);
+	if (sides.kind === "unsupported-version") return conservativeStamp(targets, [`pnpm-lock.yaml is not lockfileVersion ${SUPPORTED_LOCKFILE_VERSION}; only pnpm v9 lockfiles are modelled; fail closed to full impact`], source.unsubscribedPaths);
 	if (!changedFiles.includes("pnpm-lock.yaml")) return {
 		basis: "target-scoped",
-		reasons: ["all changed source paths have declared target ownership; impact scoped by repo-relative path globs"],
-		stampVersion: 2,
-		targets: source.targets
+		reasons: [source.unsubscribedPaths.length === 0 ? "all changed source paths match at least one declared target subscription; impact scoped by repo-relative path globs" : `${source.unsubscribedPaths.length} changed source path(s) match no declared target subscription and affect no target`],
+		stampVersion: 3,
+		targets: source.targets,
+		unsubscribedPaths: source.unsubscribedPaths
 	};
 	const [baseLock, headLock] = sides.parsed;
-	if (stableStringify$1(nonGraphSections(baseLock)) !== stableStringify$1(nonGraphSections(headLock))) return conservativeStamp(targets, ["pnpm-lock.yaml delta touches sections outside importers/packages/snapshots (e.g. settings, overrides, patchedDependencies); fail closed to full impact"]);
+	if (stableStringify$1(nonGraphSections(baseLock)) !== stableStringify$1(nonGraphSections(headLock))) return conservativeStamp(targets, ["pnpm-lock.yaml delta touches sections outside importers/packages/snapshots (e.g. settings, overrides, patchedDependencies); fail closed to full impact"], source.unsubscribedPaths);
 	const delta = {
 		changedImporters: changedSectionKeys(baseLock.importers, headLock.importers),
 		changedPackages: changedSectionKeys(baseLock.packages, headLock.packages),
@@ -3938,9 +3942,10 @@ const computeImpactStampOrThrow = ({ changedFiles, profilePath = "software-facto
 	const mixed = sourceFiles.length > 0;
 	return {
 		basis: "target-scoped",
-		reasons: mixed ? ["all changed source paths have declared target ownership and pnpm-lock.yaml is analyzable; impact is the union of path ownership and importer/snapshot graph analysis"] : ["pnpm-lock.yaml is the only changed file; impact scoped by importer/snapshot graph analysis"],
-		stampVersion: 2,
-		targets: mixed ? source.targets.map((sourceTarget, index) => unionTargetImpact(sourceTarget, lockfileTargets[index])) : lockfileTargets
+		reasons: mixed ? [source.unsubscribedPaths.length === 0 ? "all changed source paths match at least one declared target subscription and pnpm-lock.yaml is analyzable; impact is the union of path subscriptions and importer/snapshot graph analysis" : `${source.unsubscribedPaths.length} changed source path(s) match no declared target subscription; subscribed path impact is unioned with importer/snapshot graph analysis`] : ["pnpm-lock.yaml is the only changed file; impact scoped by importer/snapshot graph analysis"],
+		stampVersion: 3,
+		targets: mixed ? source.targets.map((sourceTarget, index) => unionTargetImpact(sourceTarget, lockfileTargets[index])) : lockfileTargets,
+		unsubscribedPaths: source.unsubscribedPaths
 	};
 };
 //#endregion
@@ -5543,17 +5548,21 @@ const asClassification = (value) => DIFF_CLASSIFICATIONS$1.includes(value) ? val
 const prVerifyCheckPayloadFor = (proof) => {
 	const value = proof;
 	if (!value || typeof value.headSha !== "string" || value.headSha.length === 0 || !isResolvedPrVerifyMode(value.mode)) return;
+	const carriesReleases = value.notRequiredCommands !== void 0;
 	return {
 		classification: asClassification(value.classification),
 		executedCommands: (value.executedCommands ?? []).map(({ name }) => name).filter((name) => typeof name === "string"),
 		headSha: value.headSha,
+		...carriesReleases && value.impactStamp !== void 0 ? { impactStamp: value.impactStamp } : {},
 		kind: PR_VERIFY_CHECK_PAYLOAD_KIND,
 		mode: value.mode,
+		...carriesReleases ? { notRequiredCommands: value.notRequiredCommands } : {},
 		outcome: outcomeFor(value),
 		proofSchemaVersion: typeof value.schemaVersion === "number" ? value.schemaVersion : 0,
 		schemaVersion: PR_VERIFY_CHECK_PAYLOAD_SCHEMA_VERSION,
 		...typeof value.patchId === "string" ? { patchId: value.patchId } : {},
-		...typeof value.repository === "string" ? { repository: value.repository } : {}
+		...typeof value.repository === "string" ? { repository: value.repository } : {},
+		...carriesReleases && value.verificationCommands !== void 0 ? { verificationCommands: value.verificationCommands } : {}
 	};
 };
 const renderPrVerifyCheckPayloadText = (payload) => `\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
@@ -7442,9 +7451,15 @@ const installationToken = (repository, config, request, now, timeoutMs = GITHUB_
 function verifyOutput(proof) {
 	const value = proof;
 	const commands = value.executedCommands?.length ?? 0;
+	const unsubscribedBasis = value.impactStamp?.unsubscribedPaths;
+	let unsubscribedSummary;
+	if (Array.isArray(unsubscribedBasis)) {
+		const unsubscribed = unsubscribedBasis.filter((path) => typeof path === "string");
+		unsubscribedSummary = unsubscribed.length === 0 ? "Unsubscribed changed paths: none." : `Unsubscribed changed paths (demand no target): ${unsubscribed.join(", ")}.`;
+	} else unsubscribedSummary = "Unsubscribed changed paths: unavailable (legacy or malformed stamp).";
 	const payload = prVerifyCheckPayloadFor(proof);
 	return {
-		summary: `Schema v${value.schemaVersion}; mode **${value.mode ?? "unknown"}**; classification **${value.classification ?? "unknown"}**; outcome **${value.outcome ?? "unknown"}**; ${commands} command(s) executed.`,
+		summary: `Schema v${value.schemaVersion}; mode **${value.mode ?? "unknown"}**; classification **${value.classification ?? "unknown"}**; outcome **${value.outcome ?? "unknown"}**; ${commands} command(s) executed. ${unsubscribedSummary}`,
 		...payload ? { text: renderPrVerifyCheckPayloadText(payload) } : {},
 		title: `pr:verify ${value.outcome ?? "unknown"}`
 	};
@@ -7458,8 +7473,10 @@ function reviewOutput(proof) {
 	for (const { disposition } of value.ladder ? ladderLedgerFor(value.ladder) : []) dispositionCounts[disposition] = (dispositionCounts[disposition] ?? 0) + 1;
 	if (!value.ladder && findings > 0) dispositionCounts.open = findings;
 	const dispositions = Object.entries(dispositionCounts).map(([name, count]) => `${name} ${count}`).join(", ");
+	const unavailable = "unavailable (legacy proof)";
+	const provenance = reviews.length === 0 ? "not required" : reviews.map(({ kind, model, producer, rung }) => `${kind ?? "unknown mode"}: rung ${rung ?? unavailable}; producer ${producer ?? unavailable}; model ${model ?? unavailable}`).join(" | ");
 	return {
-		summary: `Schema v${value.schemaVersion}; modes **${modes}**; ${findings} finding(s) recorded; dispositions: ${dispositions || "none"}.`,
+		summary: `Schema v${value.schemaVersion}; modes **${modes}**; ${findings} finding(s) recorded; dispositions: ${dispositions || "none"}. Review provenance: ${provenance}.`,
 		title: findings === 0 ? "pr:review clean" : "pr:review proof recorded"
 	};
 }
@@ -11632,6 +11649,7 @@ function runPrVerify(args, dependencies = {}) {
 		if (error instanceof ImpactStampConfigError) throw error;
 		impactStamp = conservativeImpactStamp(profile.impact?.targets ?? [], [`impact stamp computation failed (${error instanceof Error ? error.message : String(error)}); fail closed to full impact`]);
 	}
+	for (const line of impactStampSummaryLines(impactStamp)) console.log(line);
 	const vetoedTargets = boundFailingCheckNames({
 		candidate: {
 			headSha,
@@ -13593,6 +13611,13 @@ const prVerifyFollowUp = (authoringSession) => followUpFromArgv([
 	"pr:verify",
 	...authoringSession ? ["--authoring-session", authoringSession] : []
 ]);
+/** The route-owned Promotion from a GitHub draft into a Candidate. */
+const prUndraftFollowUp = (pr) => followUpFromArgv([
+	"gh",
+	"pr",
+	"ready",
+	String(pr)
+]);
 /** Canonical zod schema for the optional follow-up field on JSON outputs. */
 const FollowUpActionSchema = z.object({
 	argv: z.array(z.string()),
@@ -14708,15 +14733,18 @@ const collectBlockers = ({ correctnessRequired, correctnessStatus, correctnessUn
 			command: `gh pr checks ${input.pr} --watch`
 		} } : {}
 	});
-	if (input.draft) blockers.push({
-		demand: DEMAND_KEYS.draft,
-		reason: DRAFT_BLOCKER_REASON,
-		repair: {
-			action: "Mark the PR ready for review; draft is route-owned once proof gates pass.",
-			code: "undraft-pr",
-			command: `gh pr ready ${input.pr}`
-		}
-	});
+	if (input.draft) {
+		const promotion = prUndraftFollowUp(input.pr);
+		blockers.push({
+			demand: DEMAND_KEYS.draft,
+			reason: DRAFT_BLOCKER_REASON,
+			repair: {
+				action: "Mark the PR ready for review; draft is route-owned once proof gates pass.",
+				code: "undraft-pr",
+				command: promotion.command
+			}
+		});
+	}
 	return blockers;
 };
 const orderRepairs = (repairs) => repairs.toSorted((a, b) => READINESS_REPAIR_CODES.indexOf(a.code) - READINESS_REPAIR_CODES.indexOf(b.code));
@@ -15380,12 +15408,7 @@ async function runPrReady(args, dependencies = {}) {
 		]);
 		let followUp;
 		if (evaluation.status === "ready") followUp = arming?.outcome === "not-armed" ? readyRedispatch() : void 0;
-		else if (undraftRepair && evaluation.humanBlockingReasons.length === 0) followUp = followUpFromArgv([
-			"gh",
-			"pr",
-			"ready",
-			String(args.pr)
-		]);
+		else if (undraftRepair && evaluation.humanBlockingReasons.length === 0) followUp = prUndraftFollowUp(args.pr);
 		else if (!pendingExternalChecksOnly) followUp = prVerifyFollowUp(authoringSession);
 		const notices = [
 			...evaluation.notices,
@@ -16184,6 +16207,50 @@ const reevaluateReadiness = (args, dependencies) => (dependencies.runPrReady ??
 	...args,
 	throwWhenBlocked: false
 }, dependencies);
+const requirePromotionHead = ({ actualHeadSha, expectedHeadSha, phase }) => {
+	if (!sameHeadSha(actualHeadSha, expectedHeadSha)) throw new PrPublishTransactionAbortedError(`${phase}: live PR head ${actualHeadSha} differs from the proved publish head ${expectedHeadSha}. Re-run pr:publish against the current head.`);
+};
+/**
+* Promote a proved draft before the first Candidate demand evaluation (#649).
+* The route-owned action is shared with pr:ready; this helper only orders it.
+*/
+const promoteDraftBeforeDemandEvaluation = async ({ cwd, expectedHeadSha, factoryCliInvocation, fetchPr, pr, prSnapshot, runFollowUp }) => {
+	if (!prSnapshot.isDraft) return { status: "not-requested" };
+	const before = fetchPr();
+	requirePromotionHead({
+		actualHeadSha: before.headRefOid,
+		expectedHeadSha,
+		phase: "Promotion refused before transition"
+	});
+	if (!before.isDraft) return { status: "not-requested" };
+	const promotion = prUndraftFollowUp(pr);
+	try {
+		await (runFollowUp ?? defaultFollowUpRunner(factoryCliInvocation))(promotion, cwd);
+	} catch (error) {
+		throw new PrPublishTransactionAbortedError(`Promotion failed (${promotion.command}): ${errorMessage(error)}`);
+	}
+	const after = fetchPr();
+	requirePromotionHead({
+		actualHeadSha: after.headRefOid,
+		expectedHeadSha,
+		phase: "Promotion invalidated during transition"
+	});
+	if (after.isDraft) throw new PrPublishTransactionAbortedError(`Promotion did not make PR #${pr} ready for review at proved head ${expectedHeadSha}. Re-run pr:publish after GitHub settles.`);
+	return {
+		action: promotion,
+		reason: "Promotion precedes Candidate demand evaluation on the unchanged head",
+		status: "succeeded"
+	};
+};
+const requirePromotedProofHead = ({ expectedHeadSha, promotion, proof }) => {
+	if (promotion.status !== "succeeded") return;
+	requirePromotionHead({
+		actualHeadSha: proof.ledger.headSha,
+		expectedHeadSha,
+		phase: "Promotion invalidated before Candidate demand evaluation completed"
+	});
+};
+const candidateFollowUpAfterPromotion = (promotion, proof) => promotion.status === "not-requested" ? proof.followUp : void 0;
 /**
 * A proof with no follow-up that is not `ready` means `pr:ready` found the
 * candidate blocked solely on a pending hosted check for the family excluded
@@ -16318,6 +16385,11 @@ async function runPrPublish(args, dependencies = {}) {
 		reviewProofPath
 	});
 	const pr = fetchPr();
+	requirePromotionHead({
+		actualHeadSha: pr.headRefOid,
+		expectedHeadSha: verifyProof.headSha,
+		phase: "Publish refused before managed body update"
+	});
 	const parts = renderPrBodySectionParts({
 		reviewProof,
 		verifyProof: verifyProof && verifyProofPassed(verifyProof) ? verifyProof : void 0
@@ -16342,13 +16414,28 @@ async function runPrPublish(args, dependencies = {}) {
 		json: false,
 		report: false
 	};
+	const promotion = await promoteDraftBeforeDemandEvaluation({
+		cwd,
+		expectedHeadSha: verifyProof.headSha,
+		factoryCliInvocation,
+		fetchPr,
+		pr: prNumber,
+		prSnapshot: pr,
+		runFollowUp: dependencies.runFollowUp
+	});
 	const initialProof = await reevaluateReadiness(readyEvalArgs, publishDependencies);
+	requirePromotedProofHead({
+		expectedHeadSha: verifyProof.headSha,
+		promotion,
+		proof: initialProof
+	});
 	const initialHandoff = summarizeHumanHandoff(initialProof);
-	let followUp = { status: "not-requested" };
+	let followUp = promotion;
 	let currentProof = initialProof;
-	if (initialProof.followUp) {
+	const candidateFollowUp = candidateFollowUpAfterPromotion(promotion, initialProof);
+	if (candidateFollowUp) {
 		followUp = await settleFollowUp({
-			action: initialProof.followUp,
+			action: candidateFollowUp,
 			cwd,
 			factoryCliInvocation,
 			onFailure: (failed, error) => {
@@ -16363,13 +16450,13 @@ async function runPrPublish(args, dependencies = {}) {
 			},
 			plan: planPublishFollowUp({
 				binding: verifyProofBinding,
-				followUp: initialProof.followUp,
+				followUp: candidateFollowUp,
 				proofHeadSha: verifyProof.headSha,
 				verifiedHeadSha: verified.verifiedHeadSha
 			}),
 			runFollowUp: dependencies.runFollowUp
 		});
-		if (followUp.status === "succeeded" && isSelfInvalidatingFollowUp(initialProof.followUp)) currentProof = await reevaluateReadiness(readyEvalArgs, publishDependencies);
+		if (followUp.status === "succeeded" && isSelfInvalidatingFollowUp(candidateFollowUp)) currentProof = await reevaluateReadiness(readyEvalArgs, publishDependencies);
 	}
 	const proof = await awaitCurrentReadyVerdict({
 		args: readyEvalArgs,
@@ -16420,7 +16507,7 @@ async function deliverSpooledEvidence({ awaitPending, cwd, flush, profilePath })
 //#endregion
 //#region src/commands/pr-publish.ts
 function createPrPublishCommand(_output, action = runPrPublish) {
-	return markCwdOptionDefault(new Command("pr:publish").description("Compose supplied proof into a ready-for-human handoff; never launches review").option("--pr <number>", "pull request number", positiveInteger("--pr")).option("--base <ref>", "explicit base branch or ref override").option("--authoring-session <id>", "known authoring session identity for verification retries").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--epic <number>", "epic issue containing the factory-boundary manifest; the composed readiness evaluation then applies the wave-demanded review rung (#351)", positiveInteger("--epic")).option("--findings <path>", "clean-session findings to validate when no current review proof is available").option("--json", "print the publish result as JSON").option("--output <path>", "write readiness proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--review-proof <path>", "pr:review proof JSON path").option("--verify-proof <path>", "pr:verify proof JSON path").action(async (options) => {
+	return markCwdOptionDefault(new Command("pr:publish").description("Promote a proved draft, then evaluate Candidate demands; never launches review").option("--pr <number>", "pull request number", positiveInteger("--pr")).option("--base <ref>", "explicit base branch or ref override").option("--authoring-session <id>", "known authoring session identity for verification retries").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--epic <number>", "epic issue containing the factory-boundary manifest; the composed readiness evaluation then applies the wave-demanded review rung (#351)", positiveInteger("--epic")).option("--findings <path>", "clean-session findings to validate when no current review proof is available").option("--json", "print the publish result as JSON").option("--output <path>", "write readiness proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--review-proof <path>", "pr:review proof JSON path").option("--verify-proof <path>", "pr:verify proof JSON path").action(async (options) => {
 		await action({
 			authoringSessionIds: options.authoringSession ? [options.authoringSession] : void 0,
 			base: options.base ?? "",
@@ -16546,6 +16633,146 @@ function modeFor(options) {
 	if (options.full) return "full";
 	return "auto";
 }
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/iu;
+const ZERO_SHA_PATTERN = /^0{40}$/u;
+const demandedTargets = (profile, reason) => (profile?.impact?.targets ?? []).map(({ name }) => ({
+	basis: reason,
+	name,
+	state: "demanded"
+}));
+const refusal = ({ after, before, profile, reason }) => ({
+	...after ? { afterSha: after } : {},
+	basis: {
+		changedFiles: [],
+		classification: "refused",
+		reasons: [reason]
+	},
+	...before ? { beforeSha: before } : {},
+	decision: "refused",
+	schemaVersion: 1,
+	targets: demandedTargets(profile, reason),
+	unsubscribedPaths: []
+});
+const assertCommitIdentity = (value, name) => {
+	if (value === void 0 || !COMMIT_SHA_PATTERN.test(value) || ZERO_SHA_PATTERN.test(value)) throw new Error(`${name} must be a non-zero 40-character commit SHA`);
+	return value.toLowerCase();
+};
+const assertReachableCommit = (cwd, sha, name) => {
+	try {
+		runCapture("git", [
+			"cat-file",
+			"-e",
+			`${sha}^{commit}`
+		], cwd);
+	} catch {
+		throw new Error(`${name} commit ${sha} is not reachable in this checkout`);
+	}
+};
+const writeGithubOutputs = (outputPath, decision) => {
+	appendFileSync(outputPath, `${[
+		`decision=${decision.decision}`,
+		`basis=${JSON.stringify(decision.basis)}`,
+		`unsubscribed_paths=${JSON.stringify(decision.unsubscribedPaths)}`,
+		...decision.targets.map((target) => `${productionImpactTargetOutput(target.name)}=${target.state}`)
+	].join("\n")}\n`, "utf-8");
+};
+/**
+* Recompute impact from one merge push's exact before/after commits. The
+* result may withdraw consumer work only; every doubt path returns a refused
+* decision whose known targets remain demanded.
+*/
+const runProductionImpact = (args) => {
+	const cwd = path.resolve(args.cwd ?? process.cwd());
+	let profile;
+	let profilePath;
+	let decision;
+	try {
+		const { path: loadedPath, profile: loadedProfile } = loadProjectProfile({
+			cwd,
+			profilePath: args.profilePath
+		});
+		profile = loadedProfile;
+		profilePath = loadedPath;
+		const before = assertCommitIdentity(args.before, "before");
+		const after = assertCommitIdentity(args.after, "after");
+		assertReachableCommit(cwd, before, "before");
+		assertReachableCommit(cwd, after, "after");
+		const checkedOutHead = runCapture("git", ["rev-parse", "HEAD"], cwd).stdout.trim().toLowerCase();
+		if (checkedOutHead !== after) throw new Error(`after commit ${after} is not the checked-out HEAD ${checkedOutHead}; refusing to mix commit identities with declarations from another tree`);
+		try {
+			runCapture("git", [
+				"merge-base",
+				"--is-ancestor",
+				before,
+				after
+			], cwd);
+		} catch {
+			throw new Error(`before commit ${before} is not an ancestor of after commit ${after}`);
+		}
+		const changedFiles = [...new Set(filesFromNameStatus(runCapture("git", [
+			"diff",
+			"--find-renames",
+			"--name-status",
+			before,
+			after
+		], cwd).stdout))].toSorted();
+		const stamp = computeImpactStamp({
+			changedFiles,
+			profile,
+			profilePath: path.relative(cwd, profilePath),
+			readLockfile: (side) => showFileAtRef(cwd, side === "base" ? before : after, path.join(cwd, LOCKFILE_PATH))
+		});
+		const usable = stamp.basis === "target-scoped";
+		decision = {
+			afterSha: after,
+			basis: {
+				changedFiles,
+				classification: stamp.basis,
+				reasons: stamp.reasons
+			},
+			beforeSha: before,
+			decision: usable ? "usable" : "refused",
+			schemaVersion: 1,
+			targets: stamp.targets.map((target) => ({
+				basis: target.basis,
+				name: target.name,
+				state: usable && target.impact === "not-affected" ? "withdrawn" : "demanded"
+			})),
+			unsubscribedPaths: stamp.unsubscribedPaths
+		};
+	} catch (error) {
+		decision = refusal({
+			after: args.after,
+			before: args.before,
+			profile,
+			reason: `production impact classification refused: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+	if (args.githubOutput) writeGithubOutputs(path.resolve(cwd, args.githubOutput), decision);
+	if (args.githubSummary) appendFileSync(path.resolve(cwd, args.githubSummary), `### Production impact\n\n${productionImpactSummaryLines(decision).join("\n")}\n`, "utf-8");
+	return decision;
+};
+const productionImpactSummaryLines = (decision) => decision.basis.classification === "refused" ? [
+	"Production impact: refused; all consumer work remains demanded.",
+	...decision.basis.reasons,
+	"Unsubscribed changed paths: unavailable because classification was refused."
+] : [`Production impact: ${decision.basis.classification}; ${decision.targets.filter(({ state }) => state === "demanded").length}/${decision.targets.length} target(s) demanded.`, decision.unsubscribedPaths.length === 0 ? "Unsubscribed changed paths: none." : `Unsubscribed changed paths (demand no target): ${decision.unsubscribedPaths.join(", ")}`];
+//#endregion
+//#region src/commands/production-impact.ts
+function createProductionImpactCommand(output) {
+	return markCwdOptionDefault(new Command("production:impact").description("Classify production targets from an exact merge-push before/after diff").option("--before <sha>", "merge-push before commit SHA").option("--after <sha>", "merge-push after commit SHA").option("--cwd <path>", "repository working directory", collectCwdOption).option("--profile <path>", "path to the project profile JSON file").option("--github-output <path>", "append stable decision outputs to a GitHub Actions output file").option("--github-summary <path>", "append a human-readable decision to a GitHub Actions summary file").option("--json", "print the complete decision as JSON").action((options) => {
+		const decision = runProductionImpact({
+			after: options.after,
+			before: options.before,
+			cwd: resolveCwdOption(options.cwd),
+			githubOutput: options.githubOutput,
+			githubSummary: options.githubSummary,
+			profilePath: options.profile
+		});
+		if (options.json) output.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
+		else output.stdout.write(`${productionImpactSummaryLines(decision).join("\n")}\n`);
+	}));
+}
 //#endregion
 //#region src/worktree-scratch-files.ts
 var worktree_scratch_files_exports = /* @__PURE__ */ __exportAll({
@@ -16837,6 +17064,7 @@ function createProgram(options = {}) {
 	program.addCommand(createHqFlushCommand(output));
 	program.addCommand(createBoundaryCheckCommand(output, options.actions?.boundaryCheck));
 	program.addCommand(createPrVerifyCommand(output));
+	program.addCommand(createProductionImpactCommand(output));
 	program.addCommand(createCloseoutCommand(output));
 	program.addCommand(createEpicPublishStructureCommand(output));
 	program.addCommand(createPrReviewCommand(output, options.actions?.prReview));

package/dist/schemas.d.ts

@@ -497,7 +497,7 @@ declare const impactStampSchema: z.ZodObject<{
     conservative: "conservative";
   }>;
   reasons: z.ZodArray<z.ZodString>;
-  stampVersion: z.ZodLiteral<2>;
+  stampVersion: z.ZodLiteral<3>;
   targets: z.ZodArray<z.ZodObject<{
     basis: z.ZodString;
     impact: z.ZodEnum<{
@@ -506,6 +506,7 @@ declare const impactStampSchema: z.ZodObject<{
     }>;
     name: z.ZodString;
   }, z.core.$strip>>;
+  unsubscribedPaths: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 type ImpactStamp = z.infer<typeof impactStampSchema>;
 //#endregion
@@ -1366,7 +1367,7 @@ declare const prVerifyProofSchema: z.ZodObject<{
       conservative: "conservative";
     }>;
     reasons: z.ZodArray<z.ZodString>;
-    stampVersion: z.ZodLiteral<2>;
+    stampVersion: z.ZodLiteral<3>;
     targets: z.ZodArray<z.ZodObject<{
       basis: z.ZodString;
       impact: z.ZodEnum<{
@@ -1375,6 +1376,7 @@ declare const prVerifyProofSchema: z.ZodObject<{
       }>;
       name: z.ZodString;
     }, z.core.$strip>>;
+    unsubscribedPaths: z.ZodArray<z.ZodString>;
   }, z.core.$strip>>;
   mergeBaseSha: z.ZodOptional<z.ZodString>;
   mode: z.ZodEnum<{

package/dist/schemas.js

@@ -242,14 +242,15 @@ const impactStampTargetSchema = z.object({
 const impactStampSchema = z.object({
 	basis: z.enum(["target-scoped", "conservative"]),
 	reasons: z.array(z.string()),
-	stampVersion: z.literal(2),
+	stampVersion: z.literal(3),
 	targets: z.array(impactStampTargetSchema).superRefine((targets, context) => {
 		const names = targets.map((target) => target.name);
 		if (new Set(names).size !== names.length) context.addIssue({
 			code: "custom",
 			message: "impact stamp targets must have distinct names."
 		});
-	})
+	}),
+	unsubscribedPaths: z.array(z.string())
 });
 /**
 * The surfaces that consume the stamp. One classification, consumed
@@ -287,8 +288,8 @@ const impactStampScopeDecision = ({ stamp, surface, targetName }) => {
 		reason: `no trusted identity-bound impact stamp covers this candidate; ${floor}`,
 		scoped: false
 	};
-	if (stamp.stampVersion !== 2) return {
-		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 2; ${floor}`,
+	if (stamp.stampVersion !== 3) return {
+		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 3; ${floor}`,
 		scoped: false
 	};
 	if (stamp.basis !== "target-scoped") return {

package/package.json

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