@patronage/software-factory 1.0.0-alpha.0 → 1.0.0-alpha.10

package/dist/index.js

@@ -1,23 +1,23 @@
 #!/usr/bin/env node
 import { t as __exportAll } from "./chunk-pbuEa-1d.js";
-import { appendFileSync, constants, cpSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { Command, InvalidArgumentError } from "commander";
 import path from "node:path";
-import crypto, { createHash, createSign, randomUUID } from "node:crypto";
+import crypto, { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { execFileSync, spawnSync } from "node:child_process";
 import { link, lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
-import os, { homedir } from "node:os";
-import { createInterface } from "node:readline";
+import os, { homedir, tmpdir } from "node:os";
 import { setImmediate } from "node:timers";
 import { setImmediate as setImmediate$1, setTimeout as setTimeout$1 } from "node:timers/promises";
 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, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
 //#region package.json
-var version = "1.0.0-alpha.0";
+var version = "1.0.0-alpha.10";
 //#endregion
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS$1 = [
@@ -44,6 +44,21 @@ const FACTORY_BOUNDARY_FENCE_LANG = "factory-boundary";
 const BOUNDARY_CLOSEOUT_DEFAULT_RUNG = "oracle";
 const rungMeetsMinimum = (rung, minimum) => RUNG_ORDER[rung] >= RUNG_ORDER[minimum];
 const rungSchema = z.enum(EVIDENCE_REVIEW_RUNGS$1);
+const BOUNDARY_TOPOLOGIES = [
+	"each-to-main",
+	"flagged",
+	"stacked",
+	"each-to-epic"
+];
+const isValidEpicIntegrationBranch = (branch) => {
+	if (!branch.startsWith("epic/") || branch.length === 5) return false;
+	if (branch.includes("//") || branch.includes("..") || branch.includes("@{") || branch.endsWith("/")) return false;
+	for (const character of branch) {
+		const codePoint = character.codePointAt(0);
+		if (codePoint === void 0 || codePoint <= 32 || codePoint === 127 || "~^:?*[\\".includes(character)) return false;
+	}
+	return branch.split("/").every((component) => component.length > 0 && !component.startsWith(".") && !component.endsWith(".") && !component.endsWith(".lock"));
+};
 const GITHUB_LOGIN_PATTERN = /^[A-Za-z\d](?:[A-Za-z\d]|-(?=[A-Za-z\d])){0,38}(?:\[[bB][oO][tT]\])?$/u;
 const waveSchema = z.object({
 	autoMerge: z.boolean().optional(),
@@ -55,15 +70,17 @@ const boundaryManifestSchema = z.object({
 	boundary: z.string().min(1),
 	closeout: z.object({ review: rungSchema }).passthrough().optional(),
 	declaredBy: z.string().regex(GITHUB_LOGIN_PATTERN, { message: "must be a GitHub login (letters, digits, single hyphens, max 39 chars), optionally suffixed with \"[bot]\" for a GitHub App identity — not an email address or display name" }),
+	integrationBranch: z.string().refine(isValidEpicIntegrationBranch, { message: "must name a valid non-empty Git branch under \"epic/**\" (git check-ref-format --branch rules)" }).optional(),
 	prs: z.record(z.string().regex(/^[0-9]+$/u), z.string().min(1)).optional(),
 	schemaVersion: z.literal(1),
-	topology: z.enum([
-		"each-to-main",
-		"flagged",
-		"stacked"
-	]),
+	topology: z.enum(BOUNDARY_TOPOLOGIES),
 	waves: z.array(waveSchema).min(1)
 }).passthrough().superRefine((manifest, context) => {
+	if (manifest.topology === "each-to-epic" && manifest.integrationBranch === void 0) context.addIssue({
+		code: "custom",
+		message: "topology \"each-to-epic\" requires the shared epic/** branch name",
+		path: ["integrationBranch"]
+	});
 	const names = manifest.waves.map((wave) => wave.name);
 	const seen = /* @__PURE__ */ new Set();
 	for (const name of names) {
@@ -233,6 +250,69 @@ const boundaryReviewProofAuthorsSeen = (comments, boundary) => {
 };
 const undispositionedBlockingFindings = (proof) => proof.findings.filter((finding) => (finding.category !== "maintainability" || finding.blockingAfterCap === true) && finding.disposition === void 0).map((finding) => `boundary finding "${finding.title}" (category ${finding.category ?? "unknown"}) has no disposition; fix it or record waived / follow-up-filed`);
 //#endregion
+//#region src/boundary-topology.ts
+const eachToEpicBranch = (manifest) => manifest.topology === "each-to-epic" ? manifest.integrationBranch : void 0;
+/**
+* Validate only the current member during admission. This deliberately does
+* not inspect sibling membership or require the terminal PR: an epic branch
+* is assembled one admitted interior candidate at a time.
+*/
+const pullRequestTopologyReasons = ({ manifest, pullRequest }) => {
+	const integrationBranch = eachToEpicBranch(manifest);
+	if (!integrationBranch) return [];
+	const { baseRefName, headRefName, number } = pullRequest;
+	if (!headRefName) return [`PR #${number} has no live head branch name; each-to-epic admission fails closed until GitHub reports the member's headRefName.`];
+	if (baseRefName === integrationBranch && headRefName !== integrationBranch) return [];
+	if (baseRefName === "main" && headRefName === integrationBranch) return [];
+	return [`PR #${number} contradicts each-to-epic topology: live head/base ${headRefName ?? "(unknown)"} -> ${baseRefName ?? "(unknown)"}; expected an interior member targeting ${integrationBranch}, or the terminal ${integrationBranch} -> main PR.`];
+};
+/**
+* Validate the complete declared member set at boundary closeout. Callers
+* supply only issue-linked and explicit-override PRs; branch names classify
+* those authoritative members' roles but never discover membership.
+*/
+const boundaryTopologyReasons = ({ manifest, pullRequests }) => {
+	const integrationBranch = eachToEpicBranch(manifest);
+	if (!integrationBranch) return [];
+	const reasons = [];
+	const byNumber = /* @__PURE__ */ new Map();
+	for (const pullRequest of pullRequests) {
+		const previous = byNumber.get(pullRequest.number);
+		if (previous && (previous.baseRefName !== pullRequest.baseRefName || previous.headRefName !== pullRequest.headRefName)) {
+			reasons.push(`PR #${pullRequest.number} has contradictory live branch data across its declared memberships.`);
+			continue;
+		}
+		byNumber.set(pullRequest.number, pullRequest);
+	}
+	const terminalPullRequests = [];
+	for (const pullRequest of byNumber.values()) {
+		if (!pullRequest.headRefName) {
+			reasons.push(`PR #${pullRequest.number} has no live head branch name; each-to-epic closeout fails closed until GitHub reports headRefName.`);
+			continue;
+		}
+		if (pullRequest.state === "CLOSED") {
+			reasons.push(`PR #${pullRequest.number} is closed without merge and cannot satisfy the each-to-epic branch graph.`);
+			continue;
+		}
+		if (pullRequest.baseRefName === integrationBranch) {
+			if (pullRequest.state === "OPEN") reasons.push(`PR #${pullRequest.number} is an open interior member targeting ${integrationBranch}; each-to-epic closeout requires every interior member to be merged before the integration branch is complete.`);
+			if (pullRequest.headRefName === integrationBranch) reasons.push(`PR #${pullRequest.number} cannot use ${integrationBranch} as both head and base.`);
+			continue;
+		}
+		if (pullRequest.baseRefName === "main") {
+			if (pullRequest.headRefName !== integrationBranch) {
+				reasons.push(`PR #${pullRequest.number} targets main from ${pullRequest.headRefName ?? "(unknown)"}; the each-to-epic terminal must originate from declared integrationBranch ${integrationBranch}.`);
+				continue;
+			}
+			terminalPullRequests.push(pullRequest.number);
+			continue;
+		}
+		reasons.push(`PR #${pullRequest.number} targets ${pullRequest.baseRefName ?? "(unknown)"}; every each-to-epic interior member must target declared integrationBranch ${integrationBranch}.`);
+	}
+	if (terminalPullRequests.length !== 1) reasons.push(`each-to-epic requires exactly one terminal member PR from ${integrationBranch} to main; found ${terminalPullRequests.length}.`);
+	return reasons;
+};
+//#endregion
 //#region src/comment-provenance.ts
 var comment_provenance_exports = /* @__PURE__ */ __exportAll({
 	SHA_MATCH_MIN_LENGTH: () => 7,
@@ -894,8 +974,15 @@ function isValidGlob(pattern) {
 		return false;
 	}
 }
+function isRepoRelativePath(value) {
+	const segments = value.split("/");
+	return value.length > 0 && !value.startsWith("/") && !/^[A-Za-z]:\//u.test(value) && !value.includes("\\") && !segments.some((segment) => segment === "" || segment === "." || segment === "..");
+}
+function isValidRepoRelativeGlob(pattern) {
+	return isRepoRelativePath(pattern) && !(pattern.startsWith("!") && !pattern.startsWith("!(")) && isValidGlob(pattern);
+}
 function matchesAnyGlob(patterns, file) {
-	return patterns.length > 0 && picomatch.isMatch(file, patterns);
+	return patterns.length > 0 && picomatch.isMatch(file, [...patterns]);
 }
 //#endregion
 //#region src/diff-classification.ts
@@ -939,8 +1026,9 @@ const LEGACY_PROFILE_SCHEMA_VERSIONS = [
 	3,
 	4
 ];
-const PROFILE_JSON_SCHEMA_DESCRIPTION = "Editor validation covers the profile input shape and straightforward cross-field constraints. Zod remains the load-time enforcement authority: verification command names must be distinct and requiredChecks entries must have distinct names; these invariants are enforced at load time, not by this schema.";
+const PROFILE_JSON_SCHEMA_DESCRIPTION = "Editor validation covers the profile input shape and straightforward cross-field constraints. Zod remains the load-time enforcement authority: verification command names must be distinct and requiredChecks entries must have distinct names; these invariants are enforced at load time, not by this schema. Impact target path patterns encode repo-relative safety in JSON Schema, while complete picomatch syntax validity remains a runtime-only refinement.";
 const globSchema = z.string().min(1).refine(isValidGlob, "must be a valid glob");
+const repoRelativeGlobSchema = z.string().min(1).regex(/^(?!(?:\/[\s\S]*|[A-Za-z]:\/[\s\S]*|!(?!\()[\s\S]*|[\s\S]*\\[\s\S]*|[\s\S]*\/\/[\s\S]*|[\s\S]*\/$|\.{1,2}(?:\/|$)[\s\S]*|[\s\S]*\/\.{1,2}(?:\/|$)[\s\S]*)).+$/u, "must be a repo-relative positive glob").refine(isValidRepoRelativeGlob, "must be a valid repo-relative glob");
 const commandSchema = z.object({
 	command: z.string().min(1),
 	description: z.string().min(1),
@@ -972,7 +1060,8 @@ const requiredCheckSchema = z.object({
 }).strict();
 const impactTargetSchema = z.object({
 	importers: z.array(z.string().min(1)).min(1),
-	name: z.string().min(1)
+	name: z.string().min(1),
+	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);
@@ -1073,7 +1162,7 @@ const factoryProjectProfileSchema = z.object({
 		mappedChecks.add(command.requiredCheck);
 	}
 }).meta({ description: PROFILE_JSON_SCHEMA_DESCRIPTION });
-const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const stringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 const quoteList = (values) => JSON.stringify(values);
 const namesExistingFile = (root, entry) => {
@@ -1122,13 +1211,13 @@ const migratedPolicyLines = (policy, root) => {
 */
 function v2MigrationLines(input, root) {
 	const lines = [];
-	const proof = isRecord$1(input.proof) ? input.proof : void 0;
-	if (proof && isRecord$1(proof.classificationPolicy)) lines.push(...migratedPolicyLines(proof.classificationPolicy, root));
-	const commands = isRecord$1(input.verification) ? input.verification.commands : void 0;
+	const proof = isRecord$2(input.proof) ? input.proof : void 0;
+	if (proof && isRecord$2(proof.classificationPolicy)) lines.push(...migratedPolicyLines(proof.classificationPolicy, root));
+	const commands = isRecord$2(input.verification) ? input.verification.commands : void 0;
 	if (Array.isArray(commands)) {
-		for (const [index, command] of commands.entries()) if (isRecord$1(command) && command.scope === "always") lines.push(`verification.commands[${index}].scope "always" -> "docs-only"`);
+		for (const [index, command] of commands.entries()) if (isRecord$2(command) && command.scope === "always") lines.push(`verification.commands[${index}].scope "always" -> "docs-only"`);
 	}
-	if (isRecord$1(input.hq) && typeof input.hq.endpoint === "string") try {
+	if (isRecord$2(input.hq) && typeof input.hq.endpoint === "string") try {
 		const url = new URL(input.hq.endpoint);
 		if (url.href !== `${url.origin}/` && url.href !== url.origin) lines.push(`hq.endpoint ${JSON.stringify(input.hq.endpoint)} -> ${JSON.stringify(url.origin)}`);
 	} catch {}
@@ -1140,25 +1229,25 @@ function hasCorrectnessOnlyReview(review) {
 }
 const v4MigrationLines = (input) => {
 	const lines = [];
-	if (isRecord$1(input.project) && "key" in input.project) lines.push("project.key -> removed; current proof writers derive projectKey from repository.name");
-	if (isRecord$1(input.repository) && "defaultBranch" in input.repository) lines.push("repository.defaultBranch -> removed; commands resolve the live base from Git/GitHub or an explicit --base");
-	if (isRecord$1(input.env) && "required" in input.env) lines.push("env.required -> removed; the command that needs an environment value owns its fail-closed diagnostic");
-	if (isRecord$1(input.review)) {
+	if (isRecord$2(input.project) && "key" in input.project) lines.push("project.key -> removed; current proof writers derive projectKey from repository.name");
+	if (isRecord$2(input.repository) && "defaultBranch" in input.repository) lines.push("repository.defaultBranch -> removed; commands resolve the live base from Git/GitHub or an explicit --base");
+	if (isRecord$2(input.env) && "required" in input.env) lines.push("env.required -> removed; the command that needs an environment value owns its fail-closed diagnostic");
+	if (isRecord$2(input.review)) {
 		const isCorrectnessOnlyReview = hasCorrectnessOnlyReview(input.review);
 		if ("defaultMaxCycles" in input.review) lines.push("review.defaultMaxCycles -> removed; the factory review cap is 5");
 		if ("modes" in input.review) lines.push("review.modes -> removed; correctness is always required");
 		if (isCorrectnessOnlyReview) lines.push("review -> removed; a correctness-only review has no v5 configuration, so delete the object");
 		if (Array.isArray(input.review.conditional)) {
-			for (const [index, conditional] of input.review.conditional.entries()) if (isRecord$1(conditional) && "modes" in conditional) lines.push(`review.conditional[${index}].modes -> removed; each retained conditional path list demands security review`);
+			for (const [index, conditional] of input.review.conditional.entries()) if (isRecord$2(conditional) && "modes" in conditional) lines.push(`review.conditional[${index}].modes -> removed; each retained conditional path list demands security review`);
 		}
 	}
 	if (Array.isArray(input.requiredChecks)) {
-		for (const [index, check] of input.requiredChecks.entries()) if (isRecord$1(check) && "checkType" in check) lines.push(`requiredChecks[${index}].checkType -> removed; external required checks are verify-type`);
+		for (const [index, check] of input.requiredChecks.entries()) if (isRecord$2(check) && "checkType" in check) lines.push(`requiredChecks[${index}].checkType -> removed; external required checks are verify-type`);
 	}
 	return lines;
 };
 function legacyProfileMigration(input, root) {
-	if (!(isRecord$1(input) && typeof input.schemaVersion === "number" && LEGACY_PROFILE_SCHEMA_VERSIONS.includes(input.schemaVersion))) return;
+	if (!(isRecord$2(input) && typeof input.schemaVersion === "number" && LEGACY_PROFILE_SCHEMA_VERSIONS.includes(input.schemaVersion))) return;
 	const foundVersion = input.schemaVersion;
 	const lines = [`schemaVersion ${foundVersion} -> 5`];
 	if (foundVersion === 2) lines.push(...v2MigrationLines(input, root));
@@ -1338,7 +1427,6 @@ function formatUserConfigError(configPath, error) {
 }
 const DEFAULT_HQ_TRANSPORT_TIMEOUT_MS = 2500;
 const HQ_RETRY_SPOOL_DIRNAME = "hq-retry-spool";
-const HQ_RETRY_JOURNAL_BASENAME = "hq-retry-journal.jsonl";
 /**
 * Appended to a spooled event that can never be delivered (#445).
 *
@@ -1379,9 +1467,6 @@ const SPOOL_REPOSITORY_MARKER = ".repository-identity";
 * and the extra level is slack for a key scheme that nests one deeper.
 */
 const HQ_SPOOL_SWEEP_MAX_DEPTH = 4;
-`${HQ_RETRY_JOURNAL_BASENAME}`;
-`${HQ_RETRY_SPOOL_DIRNAME}`;
-const LEGACY_FACTORY_MEMORY_DIRNAME = ".factory-memory";
 const HQ_SPOOL_STATE_SEGMENTS = ["patronage-factory", "hq-spool"];
 const MAX_HQ_CONFIG_BYTES = 1024 * 1024;
 const MAX_HQ_INGEST_PAYLOAD_BYTES = 256 * 1024;
@@ -1493,12 +1578,6 @@ const repositorySpoolLayout = (repository, env = process.env) => ({
 		HQ_RETRY_SPOOL_DIRNAME
 	]
 });
-/** Read-only drain source for spools written before the relocation. */
-const legacySpoolLayout = (cwd) => ({
-	create: false,
-	root: cwd,
-	segments: [LEGACY_FACTORY_MEMORY_DIRNAME, HQ_RETRY_SPOOL_DIRNAME]
-});
 /**
 * An operator-named directory (`hq:flush --dir`). Accepts either the spool
 * itself or the directory holding it, so a `.factory-memory` path and a
@@ -1570,30 +1649,10 @@ const secureSpoolLayout = async (layout, deadline) => {
 	const memoryIdentity = identities.at(-2);
 	if (spool === void 0 || memory === void 0 || spoolIdentity === void 0 || memoryIdentity === void 0 || !await directoryIdentityMatches(memory, memoryIdentity, deadline) || !await directoryIdentityMatches(spool, spoolIdentity, deadline)) return;
 	return {
-		memory,
-		memoryIdentity,
 		spool,
 		spoolIdentity
 	};
 };
-/**
-* The legacy JSONL journal lives one level above the spool. Securing it on its
-* own lets a pre-spool `.factory-memory` (journal but no spool directory)
-* drain without the read path creating anything inside the worktree.
-*/
-const secureJournalDirectory = async (layout, deadline) => {
-	const segments = layout.segments.slice(0, -1);
-	if (segments.length === 0) return;
-	const chain = await secureChain(layout, segments, deadline);
-	if (chain === void 0) return;
-	const directory = chain.directories.at(-1);
-	const identity = chain.identities.at(-1);
-	if (directory === void 0 || identity === void 0 || !await directoryIdentityMatches(directory, identity, deadline)) return;
-	return {
-		directory,
-		identity
-	};
-};
 const readDirectoryIdentity = async (directory, deadline) => {
 	const opened = await openWithin(directory, constants.O_RDONLY + constants.O_DIRECTORY + constants.O_NOFOLLOW, remainingMs(deadline));
 	if (opened.status !== "fulfilled") return;
@@ -2323,225 +2382,6 @@ const replayCloseoutSpool = async (layout, endpoint, clientId, clientSecret, req
 		if (!await mutateBoundDirectory(spool, spoolIdentity, performance.now() + flushBudgetMs, () => outcome.ok ? unlink(claimPath) : rename(claimPath, eventPath))) return;
 	}
 };
-const writeLegacyCursor = async (directory, directoryIdentity, cursorPath, offset, deadline) => {
-	if (path.dirname(cursorPath) !== directory || !await directoryIdentityMatches(directory, directoryIdentity, deadline)) return false;
-	const temporary = `${cursorPath}.${randomUUID()}.tmp`;
-	const opened = await openWithin(temporary, constants.O_CREAT + constants.O_EXCL + constants.O_WRONLY + constants.O_NOFOLLOW, remainingMs(deadline), 384);
-	if (opened.status !== "fulfilled") return false;
-	const wrote = await settleWithin((async () => {
-		await opened.value.writeFile(String(offset), "utf-8");
-		await opened.value.sync();
-	})(), remainingMs(deadline));
-	const closed = await settleWithin(opened.value.close(), remainingMs(deadline));
-	if (wrote.status !== "fulfilled" || closed.status !== "fulfilled") {
-		await mutateBoundDirectory(directory, directoryIdentity, deadline, async () => unlink(temporary));
-		return false;
-	}
-	if (!await mutateBoundDirectory(directory, directoryIdentity, deadline, async () => rename(temporary, cursorPath))) {
-		await mutateBoundDirectory(directory, directoryIdentity, deadline, async () => unlink(temporary));
-		return false;
-	}
-	return await syncBoundDirectory(directory, directoryIdentity, deadline);
-};
-const readLegacyCursor = async (cursorPath, deadline) => {
-	const file = await readBoundedTextFileNoFollow(cursorPath, deadline, 128);
-	if (file === void 0) return 0;
-	const offset = Number(file.contents);
-	return Number.isSafeInteger(offset) && offset >= 0 ? offset : 0;
-};
-const claimLegacySource = async (sourcePath, target, directory, directoryIdentity, deadline) => {
-	if (path.dirname(sourcePath) !== directory || !await directoryIdentityMatches(directory, directoryIdentity, deadline)) return;
-	const metadata = await settleWithin(lstat(sourcePath), remainingMs(deadline));
-	if (metadata.status !== "fulfilled" || !metadata.value.isFile() || metadata.value.isSymbolicLink()) return;
-	const claimPath = `${target}.legacy-claim-${randomUUID()}`;
-	if (!await mutateBoundDirectory(directory, directoryIdentity, deadline, async () => rename(sourcePath, claimPath))) return;
-	return claimPath;
-};
-const releaseLegacyClaim = async (claimPath, target, directory, directoryIdentity, deadline) => {
-	if (path.dirname(claimPath) !== directory) return false;
-	const readyPath = `${target}.legacy-ready-${randomUUID()}`;
-	return mutateBoundDirectory(directory, directoryIdentity, deadline, async () => rename(claimPath, readyPath));
-};
-async function replayRetryJournal(layout, writeLayout, endpoint, clientId, clientSecret, request, dependencies, transportBudgetMs, setupDeadline, replayDeadline, options = {}) {
-	const maxEntries = options.maxEntries ?? MAX_HQ_REPLAY_ENTRIES;
-	const { report } = options;
-	const secured = await settleWithin(secureJournalDirectory(layout, setupDeadline), remainingMs(setupDeadline));
-	if (secured.status !== "fulfilled" || secured.value === void 0) return;
-	const { directory, identity: directoryIdentity } = secured.value;
-	const target = path.join(directory, HQ_RETRY_JOURNAL_BASENAME);
-	const baseName = path.basename(target);
-	const listing = await settleWithin(readdir(directory), remainingMs(setupDeadline));
-	if (listing.status !== "fulfilled") return;
-	let delivered = 0;
-	let corruptDropped = 0;
-	const sources = listing.value.filter((name) => name === baseName || name.startsWith(`${baseName}.legacy-ready-`) || name.startsWith(`${baseName}.draining-`) || name.startsWith(`${baseName}.legacy-claim-`)).filter((name) => !name.includes(".cursor")).toSorted();
-	for (const name of sources) {
-		if (delivered >= maxEntries || remainingMs(replayDeadline) <= 0) break;
-		const sourcePath = path.join(directory, name);
-		if (name.startsWith(`${baseName}.draining-`) || name.startsWith(`${baseName}.legacy-claim-`)) {
-			const metadata = await settleWithin(lstat(sourcePath), remainingMs(setupDeadline));
-			if (metadata.status !== "fulfilled" || !metadata.value.isFile() || metadata.value.isSymbolicLink() || Date.now() - Math.max(metadata.value.mtimeMs, metadata.value.ctimeMs) < STALE_SPOOL_ARTIFACT_MS) continue;
-		}
-		const claimPath = await claimLegacySource(sourcePath, target, directory, directoryIdentity, setupDeadline);
-		if (claimPath === void 0) continue;
-		const opened = await openWithin(claimPath, constants.O_RDONLY + constants.O_NOFOLLOW, remainingMs(setupDeadline));
-		if (opened.status !== "fulfilled") {
-			await releaseLegacyClaim(claimPath, target, directory, directoryIdentity, setupDeadline);
-			continue;
-		}
-		const sourceMetadata = await settleWithin(opened.value.stat(), remainingMs(setupDeadline));
-		if (sourceMetadata.status !== "fulfilled" || !sourceMetadata.value.isFile()) {
-			await settleWithin(opened.value.close(), remainingMs(setupDeadline));
-			await releaseLegacyClaim(claimPath, target, directory, directoryIdentity, setupDeadline);
-			continue;
-		}
-		const cursorPath = `${target}.legacy-cursor-${String(sourceMetadata.value.dev)}-${String(sourceMetadata.value.ino)}`;
-		let offset = await readLegacyCursor(cursorPath, setupDeadline);
-		if (offset >= sourceMetadata.value.size) {
-			await settleWithin(opened.value.close(), remainingMs(setupDeadline));
-			const current = await settleWithin(lstat(claimPath), remainingMs(setupDeadline));
-			if (current.status === "fulfilled" && current.value.isFile() && !current.value.isSymbolicLink() && current.value.dev === sourceMetadata.value.dev && current.value.ino === sourceMetadata.value.ino && current.value.size === sourceMetadata.value.size) {
-				await mutateBoundDirectory(directory, directoryIdentity, setupDeadline, async () => unlink(claimPath));
-				await mutateBoundDirectory(directory, directoryIdentity, setupDeadline, async () => unlink(cursorPath));
-			}
-			continue;
-		}
-		const abort = new AbortController();
-		const streamBudget = Math.min(remainingMs(setupDeadline), remainingMs(replayDeadline));
-		const abortTimer = setTimeout(() => abort.abort(), Math.max(0, streamBudget));
-		abortTimer.unref();
-		const stream = createReadStream(claimPath, {
-			autoClose: false,
-			encoding: "utf-8",
-			fd: opened.value.fd,
-			signal: abort.signal,
-			start: offset
-		});
-		const lines = createInterface({
-			crlfDelay: Infinity,
-			input: stream
-		});
-		let reachedEof = true;
-		try {
-			for await (const line of lines) {
-				if (delivered >= maxEntries || remainingMs(replayDeadline) <= 0 || remainingMs(setupDeadline) <= 0) {
-					reachedEof = false;
-					break;
-				}
-				const nextOffset = Math.min(sourceMetadata.value.size, offset + Buffer.byteLength(line, "utf-8") + 1);
-				if (line.trim().length === 0) {
-					offset = nextOffset;
-					if (!await writeLegacyCursor(directory, directoryIdentity, cursorPath, offset, setupDeadline)) {
-						reachedEof = false;
-						break;
-					}
-					continue;
-				}
-				let parsed;
-				try {
-					parsed = JSON.parse(line);
-				} catch {
-					corruptDropped += 1;
-					offset = nextOffset;
-					if (!await writeLegacyCursor(directory, directoryIdentity, cursorPath, offset, setupDeadline)) {
-						reachedEof = false;
-						break;
-					}
-					continue;
-				}
-				if (!isReplayableEntry(parsed)) {
-					offset = nextOffset;
-					if (!await writeLegacyCursor(directory, directoryIdentity, cursorPath, offset, setupDeadline)) {
-						reachedEof = false;
-						break;
-					}
-					continue;
-				}
-				const entryEndpoint = validatedEndpoint(parsed.endpoint);
-				let handled = false;
-				const row = {
-					eventId: parsed.event.eventId,
-					kind: parsed.event.kind
-				};
-				let rowOutcome = {
-					detail: `recorded endpoint ${entryEndpoint?.origin ?? "(unusable)"} is not this repository's authorized HQ origin ${endpoint.origin}`,
-					...row,
-					spool: directory,
-					status: "migrated"
-				};
-				if (entryEndpoint?.origin === endpoint.origin) {
-					rowOutcome = {
-						...rowOutcome,
-						detail: "event could not be serialized for delivery"
-					};
-					let body;
-					try {
-						body = JSON.stringify(parsed.event);
-					} catch {
-						body = void 0;
-					}
-					if (body !== void 0) {
-						const outcome = await attemptTransport(request, endpoint, clientId, clientSecret, body, Math.min(transportBudgetMs, remainingMs(replayDeadline)), report !== void 0);
-						handled = outcome.ok;
-						if (handled) delivered += 1;
-						rowOutcome = outcome.ok ? {
-							...row,
-							spool: directory,
-							status: outcome.duplicate === true ? "duplicate" : "delivered"
-						} : {
-							...row,
-							detail: outcome.detail === void 0 ? outcome.reason : `${outcome.reason}: ${outcome.detail}`,
-							spool: directory,
-							status: drainFailureStatus(outcome.reason)
-						};
-					}
-				}
-				if (!handled) {
-					const retained = await appendCloseoutSpool(writeLayout, parsed, performance.now() + journalFlushBudgetFor(dependencies));
-					if (retained === void 0) options.onMigrate?.();
-					if (retained !== void 0) {
-						report?.({
-							...rowOutcome,
-							detail: `${rowOutcome.detail ?? rowOutcome.status}; migration into the current spool ${retained}`,
-							status: "unreachable"
-						});
-						reachedEof = false;
-						break;
-					}
-				}
-				report?.(rowOutcome);
-				offset = nextOffset;
-				if (!await writeLegacyCursor(directory, directoryIdentity, cursorPath, offset, setupDeadline)) {
-					reachedEof = false;
-					break;
-				}
-			}
-		} catch {
-			reachedEof = false;
-		} finally {
-			clearTimeout(abortTimer);
-			abort.abort();
-			lines.close();
-			stream.destroy();
-			await settleWithin(opened.value.close(), remainingMs(setupDeadline));
-		}
-		if (reachedEof && offset >= sourceMetadata.value.size) {
-			const current = await settleWithin(lstat(claimPath), remainingMs(setupDeadline));
-			if (current.status === "fulfilled" && current.value.isFile() && !current.value.isSymbolicLink() && current.value.dev === sourceMetadata.value.dev && current.value.ino === sourceMetadata.value.ino && current.value.size === sourceMetadata.value.size && await directoryIdentityMatches(directory, directoryIdentity, setupDeadline)) {
-				await mutateBoundDirectory(directory, directoryIdentity, setupDeadline, async () => unlink(claimPath));
-				await mutateBoundDirectory(directory, directoryIdentity, setupDeadline, async () => unlink(cursorPath));
-			}
-		} else await releaseLegacyClaim(claimPath, target, directory, directoryIdentity, setupDeadline);
-	}
-	await reportReplayOutcome(dependencies, delivered, corruptDropped);
-}
-async function reportReplayOutcome(dependencies, delivered, corruptDropped) {
-	if (delivered <= 0 && corruptDropped <= 0) return;
-	const parts = [];
-	if (delivered > 0) parts.push(`${delivered} queued event(s) delivered from the retry journal`);
-	if (corruptDropped > 0) parts.push(`${corruptDropped} unparseable journal line(s) dropped (partial write recovered, #120)`);
-	await reportDiagnostic(dependencies, performance.now() + journalFlushBudgetFor(dependencies), parts.join("; "), delivered > 0 ? "HQ ingest confirmed" : "HQ ingest recovered");
-}
 async function deliverHqIngest(input, dependencies, setupDeadline, timeoutMs, transportBudgetMs) {
 	let config;
 	try {
@@ -2585,7 +2425,6 @@ async function deliverHqIngest(input, dependencies, setupDeadline, timeoutMs, tr
 		owner: input.profile.repository.owner,
 		repo: input.profile.repository.name
 	}, env);
-	const readLayouts = [writeLayout, legacySpoolLayout(input.cwd)];
 	const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
 	const makeEventId = dependencies.randomUUID ?? randomUUID;
 	let event;
@@ -2656,10 +2495,7 @@ async function deliverHqIngest(input, dependencies, setupDeadline, timeoutMs, tr
 			throw new Error(reason);
 		}
 		const replayDeadline = performance.now() + timeoutMs;
-		for (const readLayout of readLayouts) {
-			await replayCloseoutSpool(readLayout, endpoint, clientId, clientSecret, request, transportBudgetMs, replayDeadline, replayDeadline, journalFlushBudgetFor(dependencies), persistedEventPath);
-			await replayRetryJournal(readLayout, writeLayout, endpoint, clientId, clientSecret, request, dependencies, transportBudgetMs, replayDeadline, replayDeadline);
-		}
+		await replayCloseoutSpool(writeLayout, endpoint, clientId, clientSecret, request, transportBudgetMs, replayDeadline, replayDeadline, journalFlushBudgetFor(dependencies), persistedEventPath);
 		const outcome = await attemptTransport(request, endpoint, clientId, clientSecret, body, transportBudgetMs);
 		if (!outcome.ok) {
 			({reason, unconfirmed} = outcome);
@@ -2738,20 +2574,7 @@ async function awaitPendingHqIngest() {
 const DEFAULT_HQ_FLUSH_BUDGET_MS = 600 * 1e3;
 /** ENOENT is the only filesystem answer that means "this location is absent". */
 const isMissingEntryError = (error) => typeof error === "object" && error !== null && error.code === "ENOENT";
-const journalRowCount = (contents) => contents.split("\n").filter((line) => line.trim() !== "").length;
-const journalLineTimestamps = (contents) => {
-	const timestamps = [];
-	for (const line of contents.split("\n")) {
-		const trimmed = line.trim();
-		if (trimmed === "") continue;
-		try {
-			const parsed = JSON.parse(trimmed);
-			if (typeof parsed.failedAt === "string") timestamps.push(parsed.failedAt);
-		} catch {}
-	}
-	return timestamps;
-};
-const countRemainingSpoolWork = async (spools, drainLayouts, deadline) => {
+const countRemainingSpoolWork = async (spools, deadline) => {
 	let remaining = 0;
 	let unlistableScans = 0;
 	let oldestMs;
@@ -2780,27 +2603,6 @@ const countRemainingSpoolWork = async (spools, drainLayouts, deadline) => {
 			if (probed.status === "fulfilled") noteTimestamp(probed.value.mtime.toISOString());
 		}
 	}
-	for (const layout of drainLayouts) {
-		const journalDir = path.dirname(layoutPath(layout));
-		const journalListing = await settleWithin(readdir(journalDir), remainingMs(deadline));
-		if (journalListing.status !== "fulfilled") {
-			await countUnlistable(journalDir);
-			continue;
-		}
-		const journalNames = journalListing.value.filter((name) => name === "hq-retry-journal.jsonl" || name.startsWith(`hq-retry-journal.jsonl.legacy-ready-`) || name.startsWith(`hq-retry-journal.jsonl.legacy-claim-`) || name.startsWith(`hq-retry-journal.jsonl.draining-`));
-		for (const name of journalNames) {
-			const journalFilePath = path.join(journalDir, name);
-			const read = await settleWithin(readFile(journalFilePath, "utf-8"), remainingMs(deadline));
-			if (read.status === "fulfilled") {
-				remaining += journalRowCount(read.value);
-				for (const timestamp of journalLineTimestamps(read.value)) noteTimestamp(timestamp);
-				continue;
-			}
-			remaining += 1;
-			const probed = await settleWithin(lstat(journalFilePath), remainingMs(deadline));
-			if (probed.status === "fulfilled") noteTimestamp(probed.value.mtime.toISOString());
-		}
-	}
 	return {
 		...oldestMs === void 0 ? {} : { oldestQueuedAt: new Date(oldestMs).toISOString() },
 		remaining,
@@ -2821,10 +2623,10 @@ const DEFAULT_HQ_SPOOL_INSPECT_BUDGET_MS = 5e3;
 */
 async function countHqSpoolWork(input, dependencies = {}) {
 	const env = dependencies.env ?? process.env;
-	const layouts = input.explicitDirectories && input.explicitDirectories.length > 0 ? input.explicitDirectories.map(explicitSpoolLayout) : [repositorySpoolLayout(input.repository, env), legacySpoolLayout(input.cwd)];
+	const layouts = input.explicitDirectories && input.explicitDirectories.length > 0 ? input.explicitDirectories.map(explicitSpoolLayout) : [repositorySpoolLayout(input.repository, env)];
 	const deadline = performance.now() + (dependencies.budgetMs ?? DEFAULT_HQ_SPOOL_INSPECT_BUDGET_MS);
 	const paths = layouts.map((layout) => layoutPath(layout));
-	const { oldestQueuedAt, remaining, unlistableScans } = await countRemainingSpoolWork(paths, layouts, deadline);
+	const { oldestQueuedAt, remaining, unlistableScans } = await countRemainingSpoolWork(paths, deadline);
 	const existing = await Promise.all(paths.map(async (spool) => {
 		return (await settleWithin(lstat(spool), remainingMs(deadline))).status === "fulfilled" ? spool : void 0;
 	}));
@@ -2992,7 +2794,7 @@ async function sweepHqSpoolOrphans(input, dependencies = {}) {
 			});
 			continue;
 		}
-		const counted = await countRemainingSpoolWork([spool], [explicitSpoolLayout(spool)], deadline);
+		const counted = await countRemainingSpoolWork([spool], deadline);
 		if (counted.remaining === 0 && counted.unlistableScans === 0) continue;
 		orphans.push({
 			directory: spool,
@@ -3012,7 +2814,7 @@ async function sweepHqSpoolOrphans(input, dependencies = {}) {
 			});
 			continue;
 		}
-		const counted = await countRemainingSpoolWork([spool], [explicitSpoolLayout(spool)], deadline);
+		const counted = await countRemainingSpoolWork([spool], deadline);
 		if (counted.remaining === 0 && counted.unlistableScans === 0) continue;
 		orphans.push({
 			directory: spool,
@@ -3032,8 +2834,8 @@ async function sweepHqSpoolOrphans(input, dependencies = {}) {
 * This is the deliberate counterpart to the sink's advisory emit path: the
 * caller has already resolved credentials explicitly, so there is no cap, no
 * daemon, and no background retry — one pass, bounded, over the repo-keyed
-* location plus the legacy cwd location (or the operator's `--dir`). Delivery
-* itself is the sink's own replay, so there is exactly one POST path.
+* location (or the operator's `--dir`). Delivery itself is the sink's own
+* replay, so there is exactly one POST path.
 */
 async function flushHqSpool(input, dependencies = {}) {
 	const endpoint = validatedIngestEndpoint(input.endpoint);
@@ -3041,10 +2843,12 @@ async function flushHqSpool(input, dependencies = {}) {
 	const env = dependencies.env ?? process.env;
 	const request = dependencies.fetch ?? fetch;
 	const transportBudgetMs = dependencies.transportTimeoutMs ?? DEFAULT_HQ_TRANSPORT_TIMEOUT_MS;
-	const flushBudgetMs = dependencies.journalFlushBudgetMs ?? HQ_JOURNAL_FLUSH_BUDGET_MS;
+	const flushBudgetMs = journalFlushBudgetFor({
+		env,
+		journalFlushBudgetMs: dependencies.journalFlushBudgetMs
+	});
 	const deadline = performance.now() + (dependencies.budgetMs ?? DEFAULT_HQ_FLUSH_BUDGET_MS);
-	const writeLayout = repositorySpoolLayout(input.repository, env);
-	const layouts = input.explicitDirectories && input.explicitDirectories.length > 0 ? input.explicitDirectories.map(explicitSpoolLayout) : [writeLayout, legacySpoolLayout(input.cwd)];
+	const layouts = input.explicitDirectories && input.explicitDirectories.length > 0 ? input.explicitDirectories.map(explicitSpoolLayout) : [repositorySpoolLayout(input.repository, env)];
 	const outcomeById = /* @__PURE__ */ new Map();
 	let rejectedFiles = 0;
 	let unreachableFiles = 0;
@@ -3053,31 +2857,13 @@ async function flushHqSpool(input, dependencies = {}) {
 		outcomeById.set(outcome.eventId, outcome);
 		dependencies.report?.(outcome);
 	};
-	const journalReport = (outcome) => {
-		if (outcome.status === "unreachable" && outcome.detail?.includes("migration into the current spool")) unreachableFiles += 1;
-		record(outcome);
-	};
 	const spoolReport = (outcome) => {
 		if (outcome.status === "rejected") rejectedFiles += 1;
 		if (outcome.status === "unreachable") unreachableFiles += 1;
 		record(outcome);
 	};
 	const spools = [];
-	let migratedIntoWriteLayout = false;
-	const journalDrainOptions = {
-		maxEntries: Number.POSITIVE_INFINITY,
-		onMigrate: () => {
-			migratedIntoWriteLayout = true;
-		},
-		report: journalReport
-	};
-	for (const layout of layouts) await replayRetryJournal(layout, writeLayout, endpoint, input.clientId, input.clientSecret, request, {
-		env,
-		fetch: request,
-		journalFlushBudgetMs: flushBudgetMs
-	}, transportBudgetMs, deadline, deadline, journalDrainOptions);
-	const drainLayouts = migratedIntoWriteLayout && !layouts.some((layout) => layoutPath(layout) === layoutPath(writeLayout)) ? [...layouts, writeLayout] : layouts;
-	for (const layout of drainLayouts) {
+	for (const layout of layouts) {
 		await replayCloseoutSpool(layout, endpoint, input.clientId, input.clientSecret, request, transportBudgetMs, deadline, deadline, flushBudgetMs, void 0, {
 			maxEntries: Number.POSITIVE_INFINITY,
 			report: spoolReport
@@ -3087,7 +2873,7 @@ async function flushHqSpool(input, dependencies = {}) {
 			if ((await settleWithin(lstat(layoutPath(layout)), remainingMs(deadline))).status === "fulfilled") unsecurableSpools += 1;
 		} else spools.push(secured.spool);
 	}
-	const { remaining, unlistableScans } = await countRemainingSpoolWork(spools, drainLayouts, deadline);
+	const { remaining, unlistableScans } = await countRemainingSpoolWork(spools, deadline);
 	const outcomes = [...outcomeById.values()];
 	const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
 	const rejected = count("rejected");
@@ -3845,17 +3631,20 @@ const impactStampTargetSchema = z.object({
 * input widened every target to full impact.
 */
 const impactStampSchema = z.object({
-	basis: z.enum(["lockfile-scoped", "conservative"]),
+	basis: z.enum(["target-scoped", "conservative"]),
 	reasons: z.array(z.string()),
-	stampVersion: z.literal(1),
+	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
@@ -3886,7 +3675,7 @@ const IMPACT_SCOPE_SURFACES = {
 * external proof demand (#542 wave 2), a verification-battery command, or a
 * preview (Alchemy) lifecycle stack (#430 wave 3).
 *
-* The only release path is a `lockfile-scoped` stamp of exactly this build's
+* The only release path is a `target-scoped` stamp of exactly this build's
 * stamp version whose target entry for exactly this name is provably
 * `not-affected`. Every other input — no trusted stamp, an unknown stamp
 * version, a conservative stamp, a name the stamp does not classify, or an
@@ -3905,11 +3694,11 @@ const impactStampScopeDecision = ({ stamp, surface, targetName }) => {
 		reason: `no trusted identity-bound impact stamp covers this candidate; ${floor}`,
 		scoped: false
 	};
-	if (stamp.stampVersion !== 1) return {
-		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 1; ${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 !== "lockfile-scoped") return {
+	if (stamp.basis !== "target-scoped") return {
 		reason: `impact stamp is conservative (full impact assumed); ${floor}`,
 		scoped: false
 	};
@@ -3948,15 +3737,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: 1,
+	stampVersion: 3,
 	targets: targets.map((target) => ({
 		basis: CONSERVATIVE_TARGET_BASIS,
 		impact: "affected",
 		name: target.name
-	}))
+	})),
+	unsubscribedPaths
 });
 const conservativeStamp = conservativeImpactStamp;
 const DEPENDENCY_FIELDS = [
@@ -3984,17 +3774,17 @@ const pnpmLockfileSchema = z.looseObject({
 	packages: z.record(z.string(), z.unknown()).optional(),
 	snapshots: z.record(z.string(), snapshotSectionSchema).optional()
 });
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const canonical = (value) => {
 	if (Array.isArray(value)) return value.map(canonical);
-	if (isRecord(value)) return Object.fromEntries(Object.keys(value).toSorted().map((key) => [key, canonical(value[key])]));
+	if (isRecord$1(value)) return Object.fromEntries(Object.keys(value).toSorted().map((key) => [key, canonical(value[key])]));
 	return value;
 };
 const stableStringify$1 = (value) => JSON.stringify(canonical(value));
 const parseLockfile = (content) => {
 	try {
 		const parsed = parse(content);
-		if (!isRecord(parsed)) return;
+		if (!isRecord$1(parsed)) return;
 		const validated = pnpmLockfileSchema.safeParse(parsed);
 		return validated.success ? validated.data : void 0;
 	} catch {
@@ -4087,11 +3877,11 @@ 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 for a provably-scoped pnpm-lock.yaml (v9) delta; every other input
-* — non-lockfile changed files, an empty diff, a missing, unparseable, or
-* structurally malformed lockfile side, an unsupported lockfile version, or a
-* delta outside the importers/packages/snapshots graph sections — widens to
-* full impact.
+* 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
 * reading, parsing, or traversal is itself a doubt path and returns the
@@ -4154,35 +3944,88 @@ const readLockfileSides = (readLockfile) => {
 const assertDeclaredImporterRoots = (targets, sides) => {
 	for (const target of targets) for (const root of target.importers) if (!sides.some((lockfile) => Object.keys(lockfile.importers).some((importerPath) => importerMatchesTarget(importerPath, [root])))) throw new ImpactStampConfigError(`impact target "${target.name}" declares importer root "${root}", but no importer under that root exists in pnpm-lock.yaml on either side of the delta; fix the profile's impact.targets declaration`);
 };
-const computeImpactStampOrThrow = ({ changedFiles, readLockfile }, targets) => {
+const assertDeclaredPathGlobs = (targets) => {
+	for (const target of targets) for (const pattern of target.paths ?? []) if (!isValidRepoRelativeGlob(pattern)) throw new ImpactStampConfigError(`impact target "${target.name}" declares invalid repo-relative path glob "${pattern}"; fix the profile's impact.targets declaration`);
+};
+const analyzeSourcePaths = (sourceFiles, targets, profilePath) => {
+	for (const file of sourceFiles) {
+		if (!isRepoRelativePath(file)) return {
+			kind: "conservative",
+			reason: `changed source path "${file}" is not a valid repo-relative path; fail closed to full impact`
+		};
+		if (file === profilePath) return {
+			kind: "conservative",
+			reason: `changed source path "${file}" is the impact profile being evaluated; fail closed to full impact`
+		};
+	}
+	return {
+		kind: "ok",
+		targets: targets.map((target) => {
+			const matched = sourceFiles.find((file) => matchesAnyGlob(target.paths ?? [], file));
+			return matched === void 0 ? {
+				basis: "no changed source path matches this target's declared paths",
+				impact: "not-affected",
+				name: target.name
+			} : {
+				basis: `changed source path "${matched}" matches this target's declared paths`,
+				impact: "affected",
+				name: target.name
+			};
+		}),
+		unsubscribedPaths: sourceFiles.filter((file) => !targets.some((target) => matchesAnyGlob(target.paths ?? [], file)))
+	};
+};
+const unionTargetImpact = (source, lockfile) => {
+	if (source.impact === "affected") return source;
+	if (lockfile.impact === "affected") return lockfile;
+	return {
+		basis: `${source.basis}; ${lockfile.basis}`,
+		impact: "not-affected",
+		name: source.name
+	};
+};
+const computeImpactStampOrThrow = ({ changedFiles, profilePath = "software-factory.profile.json", readLockfile }, targets) => {
 	if (targets.length === 0) return {
 		basis: "conservative",
 		reasons: ["no impact targets declared in the profile; every surface keeps full demand"],
-		stampVersion: 1,
-		targets: []
+		stampVersion: 3,
+		targets: [],
+		unsubscribedPaths: changedFiles.filter((file) => file !== "pnpm-lock.yaml" && isRepoRelativePath(file))
 	};
+	assertDeclaredPathGlobs(targets);
 	const sides = readLockfileSides(readLockfile);
 	if (sides.kind === "ok") assertDeclaredImporterRoots(targets, sides.parsed);
 	if (changedFiles.length === 0) return conservativeStamp(targets, ["no changed files detected; full impact assumed"]);
-	const unmodelledFiles = changedFiles.filter((file) => file !== LOCKFILE_PATH);
-	if (unmodelledFiles.length > 0) return conservativeStamp(targets, [`changed files outside the lockfile classifier's model (${unmodelledFiles.toSorted().join(", ")}); full impact assumed`]);
-	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`]);
+	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") 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: [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),
 		changedSnapshots: changedSectionKeys(baseLock.snapshots, headLock.snapshots),
 		sides: [baseLock, headLock]
 	};
+	const lockfileTargets = targets.map((target) => targetImpactForLockfileDelta(target, delta));
+	const mixed = sourceFiles.length > 0;
 	return {
-		basis: "lockfile-scoped",
-		reasons: ["pnpm-lock.yaml is the only changed file; impact scoped by importer/snapshot graph analysis"],
-		stampVersion: 1,
-		targets: targets.map((target) => targetImpactForLockfileDelta(target, delta))
+		basis: "target-scoped",
+		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
@@ -4361,7 +4204,7 @@ const assertBatteryCompleteness = (proof, context) => {
 * so authorization is bound to the same identities the proof binds. The
 * predicate is the shared {@link impactStampScopeDecision}, not a second
 * reading of the stamp: an entry is authorized exactly when the stamp would
-* have released that target's command in the first place (lockfile-scoped
+* have released that target's command in the first place (target-scoped
 * basis, this build's stamp version, exactly one row for the target,
 * `not-affected`). A conservative stamp, an unknown version, a
 * self-contradictory stamp, an unclassified name, or an `affected` verdict all
@@ -5480,7 +5323,7 @@ const CLOSING_PRS_QUERY = `query($owner: String!, $repo: String!, $issue: Int!)
   repository(owner: $owner, name: $repo) {
     issue(number: $issue) {
       closedByPullRequestsReferences(first: 50, includeClosedPrs: true) {
-        nodes { number state headRefOid mergeCommit { oid } }
+        nodes { number state baseRefName headRefName headRefOid mergeCommit { oid } }
       }
     }
   }
@@ -5508,7 +5351,9 @@ const defaultBoundaryCheckGithub = () => ({
 			"-F",
 			`issue=${issue}`
 		]).data?.repository?.issue?.closedByPullRequestsReferences?.nodes ?? []).map((node) => ({
+			...node.baseRefName ? { baseRefName: node.baseRefName } : {},
 			...node.headRefOid ? { headRefOid: node.headRefOid } : {},
+			...node.headRefName ? { headRefName: node.headRefName } : {},
 			...node.mergeCommit?.oid ? { mergeCommitOid: node.mergeCommit.oid } : {},
 			number: node.number,
 			state: node.state
@@ -5532,10 +5377,12 @@ const defaultBoundaryCheckGithub = () => ({
 			"--repo",
 			repo,
 			"--json",
-			"number,state,headRefOid,mergeCommit"
+			"number,state,baseRefName,headRefName,headRefOid,mergeCommit"
 		]);
 		return {
+			...raw.baseRefName ? { baseRefName: raw.baseRefName } : {},
 			...raw.headRefOid ? { headRefOid: raw.headRefOid } : {},
+			...raw.headRefName ? { headRefName: raw.headRefName } : {},
 			...raw.mergeCommit?.oid ? { mergeCommitOid: raw.mergeCommit.oid } : {},
 			number: raw.number,
 			state: raw.state
@@ -5574,10 +5421,12 @@ const coveredEntryFromRef = (ref, wave, issue, notices) => {
 const computeCoveredSet = (manifest, repo, github) => {
 	const notices = [];
 	const byPr = /* @__PURE__ */ new Map();
+	const pullRequests = /* @__PURE__ */ new Map();
 	for (const wave of manifest.waves) for (const issue of wave.issues) {
 		const refs = github.fetchClosingPullRequests(repo, issue);
 		if (refs.length === 0) notices.push(`issue #${issue} (wave ${wave.name}) has no linked closing PR yet`);
 		for (const ref of refs) {
+			if (!pullRequests.has(ref.number)) pullRequests.set(ref.number, ref);
 			const entry = coveredEntryFromRef(ref, wave.name, issue, notices);
 			if (entry && !byPr.has(entry.pr)) byPr.set(entry.pr, entry);
 		}
@@ -5585,12 +5434,15 @@ const computeCoveredSet = (manifest, repo, github) => {
 	for (const [prKey, waveName] of Object.entries(manifest.prs ?? {})) {
 		const prNumber = Number(prKey);
 		if (byPr.has(prNumber)) continue;
-		const entry = coveredEntryFromRef(github.fetchPullRequest(repo, prNumber), waveName, void 0, notices);
+		const ref = github.fetchPullRequest(repo, prNumber);
+		pullRequests.set(prNumber, ref);
+		const entry = coveredEntryFromRef(ref, waveName, void 0, notices);
 		if (entry) byPr.set(entry.pr, entry);
 	}
 	return {
 		entries: [...byPr.values()].toSorted((a, b) => a.pr - b.pr),
-		notices
+		notices,
+		pullRequests: [...pullRequests.values()].toSorted((a, b) => a.number - b.number)
 	};
 };
 const coveredSetDivergences = (computed, proof) => {
@@ -5657,6 +5509,10 @@ function runBoundaryCheck(args, dependencies = {}) {
 			manifestHash: parsed.manifestHash,
 			selected
 		});
+		blockingReasons.unshift(...boundaryTopologyReasons({
+			manifest: parsed.manifest,
+			pullRequests: computed.pullRequests
+		}));
 		record = {
 			blockingReasons,
 			boundary: parsed.manifest.boundary,
@@ -5785,17 +5641,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\`\`\``;
@@ -7609,31 +7469,6 @@ const defaultSleep = async (ms) => {
 	const { setTimeout: delay } = await import("node:timers/promises");
 	await delay(ms);
 };
-const base64url = (value) => Buffer.from(value).toString("base64url");
-function appJwt(config, now) {
-	const issuedAt = Math.floor(now / 1e3) - 60;
-	const unsigned = `${base64url(JSON.stringify({
-		alg: "RS256",
-		typ: "JWT"
-	}))}.${base64url(JSON.stringify({
-		exp: issuedAt + 600,
-		iat: issuedAt,
-		iss: config.appId
-	}))}`;
-	const signer = createSign("RSA-SHA256");
-	signer.update(unsigned);
-	signer.end();
-	return `${unsigned}.${signer.sign(readFileSync(config.privateKeyPath), "base64url")}`;
-}
-/** Carries the HTTP status so a caller can tell a retryable failure apart. */
-var GitHubApiError = class extends Error {
-	status;
-	constructor(status, statusText) {
-		super(`GitHub API ${status} ${statusText}`);
-		this.name = "GitHubApiError";
-		this.status = status;
-	}
-};
 /**
 * Worth another attempt: 422 is what GitHub answers for a head SHA it has not
 * seen yet (the whole reason the retry exists), 5xx and rate limiting are
@@ -7688,30 +7523,36 @@ async function githubJson(request, url, init, timeoutMs = GITHUB_PUBLISH_TIMEOUT
 	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
 	return await response.json();
 }
-async function installationToken(repository, config, request, now, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) {
-	const jwt = appJwt(config, now);
-	let { installationId } = config;
-	if (installationId === void 0) {
-		const installation = await githubJson(request, `https://api.github.com/repos/${repository.owner}/${repository.repo}/installation`, {
-			headers: { Authorization: `Bearer ${jwt}` },
-			method: "GET"
-		}, timeoutMs);
-		if (typeof installation.id !== "number") throw new TypeError("GitHub App installation response omitted id");
-		installationId = installation.id;
-	}
-	const token = await githubJson(request, `https://api.github.com/app/installations/${installationId}/access_tokens`, {
-		headers: { Authorization: `Bearer ${jwt}` },
-		method: "POST"
-	}, timeoutMs);
-	if (typeof token.token !== "string") throw new TypeError("GitHub App token response omitted token");
-	return token.token;
-}
+/**
+* Mint an installation token for the Patronage Factory App.
+*
+* The mechanism — app JWT, installation lookup, token exchange — lives in
+* `@patronage/factory-ci` (#617), because paitronage's proof-comment publisher
+* had grown a second copy of it. What stays here is what is this repository's:
+* where the credentials come from (`user-config`), and the publish timeout the
+* rest of these calls are bound by. Nothing is cached, as before.
+*/
+const installationToken = (repository, config, request, now, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) => mintInstallationToken({
+	credentials: config,
+	owner: repository.owner,
+	repo: repository.repo
+}, {
+	fetch: request,
+	now: () => now,
+	timeoutMs
+});
 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"}`
 	};
@@ -7725,8 +7566,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"
 	};
 }
@@ -8820,8 +8663,24 @@ function positiveInteger(name) {
 	};
 }
 function resolveCwdOption(cwd) {
-	if (typeof cwd !== "string" || cwd.trim() === "") throw new Error("--cwd requires a non-empty path; relative values resolve against the current working directory");
-	return path.resolve(cwd);
+	const value = typeof cwd === "string" ? cwd : ".";
+	if (value.trim() === "") throw new Error("--cwd requires a non-empty path; relative values resolve against the current working directory");
+	return path.resolve(value);
+}
+function collectCwdOption(rawValue, previous) {
+	if (previous === void 0) return rawValue;
+	const previousResolved = resolveCwdOption(previous);
+	const currentResolved = resolveCwdOption(rawValue);
+	if (previousResolved !== currentResolved) throw new Error(`--cwd was passed multiple times with conflicting values: "${previous}" (resolves to ${previousResolved}) and "${rawValue}" (resolves to ${currentResolved})`);
+	return rawValue;
+}
+function markCwdOptionDefault(command) {
+	const option = command.options.find((candidate) => candidate.attributeName() === "cwd");
+	if (option) {
+		option.defaultValue = ".";
+		option.defaultValueDescription = ".";
+	}
+	return command;
 }
 function resolveCheckoutPath(cwd, target) {
 	return path.resolve(cwd, target);
@@ -8844,7 +8703,7 @@ const renderReport = (record) => {
 	return `${lines.join("\n")}\n`;
 };
 function createBoundaryCheckCommand(output, action) {
-	return new Command("boundary:check").description("Boundary readiness gate (T8): require a membership-fresh boundary-review proof at the declared closeout rung. Blocks closeout/enablement, never merge.").requiredOption("--epic <number>", "epic issue number carrying the factory-boundary manifest", positiveInteger("--epic")).option("--repo <owner/name>", "GitHub repository (default: resolved from --cwd)").option("--cwd <path>", "repository working directory", ".").option("--output <path>", "write an additional proof copy to this path").option("--json", "print the full proof record as JSON").action(withGateTiming({
+	return markCwdOptionDefault(new Command("boundary:check").description("Boundary readiness gate (T8): require a membership-fresh boundary-review proof at the declared closeout rung. Blocks closeout/enablement, never merge.").requiredOption("--epic <number>", "epic issue number carrying the factory-boundary manifest", positiveInteger("--epic")).option("--repo <owner/name>", "GitHub repository (default: resolved from --cwd)").option("--cwd <path>", "repository working directory", collectCwdOption).option("--output <path>", "write an additional proof copy to this path").option("--profile <path>", "path to the project profile JSON file").option("--json", "print the full proof record as JSON").action(withGateTiming({
 		gate: "boundary:check",
 		resolveLedgerRoot: (options) => resolveCwdOption(options.cwd),
 		stderr: output.stderr
@@ -8860,7 +8719,10 @@ function createBoundaryCheckCommand(output, action) {
 		if (!action) {
 			const [owner, name] = record.repo.split("/");
 			if (owner && name) {
-				const hqLaneBaseUrl = hqLaneRefBaseUrlFromProfile(tryLoadProjectProfile({ cwd: args.cwd })?.profile);
+				const hqLaneBaseUrl = hqLaneRefBaseUrlFromProfile(tryLoadProjectProfile({
+					cwd: args.cwd,
+					profilePath: options.profile
+				})?.profile);
 				try {
 					publishFactoryCheckSafely(createFactoryCheckPublisher(output), {
 						conclusion: record.status === "ready" ? "success" : "failure",
@@ -8880,7 +8742,710 @@ function createBoundaryCheckCommand(output, action) {
 		}
 		output.stdout.write(options.json ? `${JSON.stringify(record, null, 2)}\n` : renderReport(record));
 		if (record.status !== "ready") throw new Error(`boundary:check refused: ${record.blockingReasons.join("; ")}`);
+	})));
+}
+/** `tool` discriminator every emitted report carries. */
+const CI_ANALYZE_TOOL = "psf-ci-analyze";
+/** Cohort label for runs the caller did not assign to a cohort. */
+const UNGROUPED_COHORT = "ungrouped";
+const available = (value) => ({
+	available: true,
+	value
+});
+const unavailable = (reason) => ({
+	available: false,
+	reason
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stringField$1 = (source, key, where) => {
+	const value = source[key];
+	return typeof value === "string" && value.length > 0 ? available(value) : unavailable(`${where} has no ${key}`);
+};
+const numberField = (source, key, where) => {
+	const value = source[key];
+	return typeof value === "number" && Number.isFinite(value) ? available(value) : unavailable(`${where} has no ${key}`);
+};
+/**
+* An instant is only usable when it names its own timezone. `Date.parse`
+* interprets an offset-less `2026-08-06T12:00:00` in the *host's* zone, which
+* would make a duration depend on where the analyzer ran. The GitHub API
+* always sends `Z`-form, so requiring an explicit `Z` or numeric offset
+* rejects nothing genuine — anything else becomes explicitly unavailable.
+*/
+const EXPLICIT_OFFSET_PATTERN = /(?:Z|[+-]\d{2}:?\d{2})$/u;
+const parseInstantMs = (value) => {
+	if (!value.available) return;
+	if (!EXPLICIT_OFFSET_PATTERN.test(value.value)) return;
+	const parsed = Date.parse(value.value);
+	return Number.isNaN(parsed) ? void 0 : parsed;
+};
+/**
+* Wall clock between two ISO instants. Unavailable — with the missing side
+* named — whenever either instant is absent or unparsable; a negative span is
+* refused rather than clamped to a fake zero.
+*/
+const durationBetween = (start, end, label) => {
+	const startMs = parseInstantMs(start);
+	if (startMs === void 0) return unavailable(`${label}: start instant is ${start.available ? "unparsable" : `unavailable (${start.reason})`}`);
+	const endMs = parseInstantMs(end);
+	if (endMs === void 0) return unavailable(`${label}: end instant is ${end.available ? "unparsable" : `unavailable (${end.reason})`}`);
+	if (endMs < startMs) return unavailable(`${label}: end instant precedes start instant`);
+	return available(endMs - startMs);
+};
+const GITHUB_SETUP_STEP_NAME = "Set up job";
+const INSTALL_STEP_PATTERN = /install/iu;
+const analyzeStep = (step) => {
+	const startedAt = stringField$1(step, "started_at", "step");
+	const completedAt = stringField$1(step, "completed_at", "step");
+	return {
+		completedAt,
+		conclusion: stringField$1(step, "conclusion", "step"),
+		durationMs: durationBetween(startedAt, completedAt, "step duration"),
+		name: typeof step.name === "string" ? step.name : "(unnamed step)",
+		number: numberField(step, "number", "step"),
+		startedAt
+	};
+};
+const namedStepDuration = (steps, matches, description) => {
+	const step = steps.find((candidate) => matches(candidate.name));
+	return step === void 0 ? unavailable(`no ${description} step in this job`) : step.durationMs;
+};
+const analyzeJob = (job) => {
+	const steps = Array.isArray(job.steps) ? job.steps.filter(isRecord).map(analyzeStep) : [];
+	const createdAt = stringField$1(job, "created_at", "job");
+	const startedAt = stringField$1(job, "started_at", "job");
+	const completedAt = stringField$1(job, "completed_at", "job");
+	const labels = Array.isArray(job.labels) ? job.labels.filter((label) => typeof label === "string") : void 0;
+	return {
+		completedAt,
+		conclusion: stringField$1(job, "conclusion", "job"),
+		createdAt,
+		installMs: namedStepDuration(steps, (name) => INSTALL_STEP_PATTERN.test(name), "install"),
+		jobId: numberField(job, "id", "job"),
+		name: typeof job.name === "string" ? job.name : "(unnamed job)",
+		queueMs: durationBetween(createdAt, startedAt, "job queue"),
+		runnerLabels: labels === void 0 ? unavailable("job has no labels array") : available(labels),
+		setupMs: namedStepDuration(steps, (name) => name === GITHUB_SETUP_STEP_NAME, `"${GITHUB_SETUP_STEP_NAME}"`),
+		startedAt,
+		steps,
+		totalMs: durationBetween(startedAt, completedAt, "job duration"),
+		url: stringField$1(job, "html_url", "job")
+	};
+};
+/**
+* Classify proof reuse from step conclusions alone. A job whose gate step is
+* followed by at least one skipped step reused proof; a job whose post-gate
+* steps all executed ran the full fallback. No gate step anywhere means the
+* workflow does not expose the outcome, which is unavailable — not
+* full-fallback.
+*/
+const classifyProofReuse = (jobs) => {
+	const gateJobs = [];
+	const verdicts = /* @__PURE__ */ new Set();
+	for (const job of jobs) {
+		const gateIndex = job.steps.findIndex((step) => step.name === FACTORY_PROOF_GATE_STEP_NAME);
+		if (gateIndex === -1) continue;
+		const skippedStepsAfterGate = job.steps.slice(gateIndex + 1).filter((step) => step.conclusion.available && step.conclusion.value === "skipped").length;
+		verdicts.add(skippedStepsAfterGate > 0 ? "proof-reuse" : "full-fallback");
+		gateJobs.push({
+			gateConclusion: job.steps[gateIndex]?.conclusion ?? unavailable("gate step vanished"),
+			jobName: job.name,
+			skippedStepsAfterGate
+		});
+	}
+	if (gateJobs.length === 0) return unavailable(`no "${FACTORY_PROOF_GATE_STEP_NAME}" step in any job; this workflow does not expose a proof-reuse outcome`);
+	const [single] = [...verdicts];
+	return available({
+		classification: verdicts.size === 1 && single ? single : "mixed",
+		gateJobs
+	});
+};
+const parseArtifactListing = (value) => {
+	if (!isRecord(value) || !Array.isArray(value.artifacts)) return {
+		artifacts: [],
+		totalCount: void 0
+	};
+	return {
+		artifacts: value.artifacts.filter(isRecord).flatMap((artifact) => {
+			const { id, name } = artifact;
+			return typeof id === "number" && typeof name === "string" ? [{
+				expired: artifact.expired === true,
+				id,
+				name
+			}] : [];
+		}),
+		totalCount: typeof value.total_count === "number" ? value.total_count : void 0
+	};
+};
+const profileFromDocument = (artifactName, value) => {
+	const read = readVitestProfileDocument(value);
+	if (read.kind === "unrecognized") return {
+		artifactName,
+		kind: "unreadable",
+		reason: read.reason
+	};
+	const { profile } = read;
+	const testCounts = profile.runs.flatMap((run) => run.counts === null ? [] : [run.counts.tests]);
+	return {
+		artifactName,
+		kind: "profile",
+		profile: {
+			cpuCount: profile.environment.cpuCount,
+			cpuModel: profile.environment.cpuModel,
+			maxWorkers: profile.options.maxWorkers,
+			sampleDurationsMs: profile.runs.map((run) => run.durationMs),
+			scope: profile.command.join(" "),
+			slowFiles: profile.summary.slowFiles.map((file) => ({
+				medianMs: file.durationMs.median,
+				path: file.path
+			})),
+			slowTests: profile.summary.slowTests.map((test) => ({
+				file: test.file,
+				medianMs: test.durationMs.median,
+				name: test.name
+			})),
+			summaryDurationMs: profile.summary.durationMs,
+			testCount: testCounts.length === 0 ? unavailable("no sample in this profile carries test counts") : available(Math.max(...testCounts))
+		}
+	};
+};
+const collectProfiles = async (client, runId) => {
+	let listing;
+	try {
+		listing = parseArtifactListing(await client.listArtifacts(runId));
+	} catch (error) {
+		return unavailable(`artifact listing failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const { artifacts } = listing;
+	if (listing.totalCount !== void 0 && listing.totalCount > artifacts.length) return unavailable(`artifact listing is truncated: ${artifacts.length} of ${listing.totalCount} artifacts served`);
+	if (artifacts.length === 0) return unavailable("this run has no artifacts");
+	const analyses = [];
+	for (const artifact of artifacts) {
+		if (artifact.expired) {
+			analyses.push({
+				artifactName: artifact.name,
+				kind: "unreadable",
+				reason: "the artifact is expired and can no longer be downloaded"
+			});
+			continue;
+		}
+		let files;
+		try {
+			files = await client.readArtifactTextFiles(artifact.id);
+		} catch (error) {
+			analyses.push({
+				artifactName: artifact.name,
+				kind: "unreadable",
+				reason: `artifact download failed: ${error instanceof Error ? error.message : String(error)}`
+			});
+			continue;
+		}
+		for (const file of files) {
+			let parsed;
+			try {
+				parsed = JSON.parse(file.text);
+			} catch {
+				analyses.push({
+					artifactName: `${artifact.name}/${file.name}`,
+					kind: "unreadable",
+					reason: "the file is not valid JSON"
+				});
+				continue;
+			}
+			const analysis = profileFromDocument(`${artifact.name}/${file.name}`, parsed);
+			if (analysis.kind === "profile" || isRecord(parsed) && parsed.tool === "factory-ci-vitest-profile") analyses.push(analysis);
+		}
+	}
+	return analyses.length === 0 ? unavailable("no compatible factory-ci Vitest profile artifacts on this run") : available(analyses);
+};
+const earliest = (instants) => instants.length === 0 ? void 0 : Math.min(...instants);
+const latest = (instants) => instants.length === 0 ? void 0 : Math.max(...instants);
+const runQueueDuration = (createdAt, jobs) => {
+	const createdMs = parseInstantMs(createdAt);
+	if (createdMs === void 0) return unavailable("the run object has no parsable created_at");
+	const firstStart = earliest(jobs.flatMap((job) => {
+		const started = parseInstantMs(job.startedAt);
+		return started === void 0 ? [] : [started];
 	}));
+	if (firstStart === void 0) return unavailable("no job carries a parsable started_at");
+	return firstStart < createdMs ? unavailable("the earliest job start precedes the run creation instant") : available(firstStart - createdMs);
+};
+const runCompletionInstant = (jobs) => {
+	const completions = jobs.flatMap((job) => {
+		const completed = parseInstantMs(job.completedAt);
+		return completed === void 0 ? [] : [{
+			completed,
+			iso: job.completedAt
+		}];
+	});
+	const last = latest(completions.map((entry) => entry.completed));
+	const match = completions.find((entry) => entry.completed === last);
+	return match?.iso.available === true ? available(match.iso.value) : unavailable("no job carries a parsable completed_at");
+};
+/**
+* `cpuModel` never comes from the Actions API — only readable profile
+* artifacts carry silicon attribution, so both absence cases say so.
+*/
+const cpuModelsField = (cpuModels, profiles) => {
+	if (cpuModels === void 0) return unavailable(`CPU models come only from profile artifacts (${profiles.available ? "none usable" : profiles.reason}); the Actions API does not expose silicon`);
+	if (cpuModels.length === 0) return unavailable("no readable profile artifact recorded a CPU model");
+	return available(cpuModels);
+};
+const analyzeOneRun = async (client, request, entry) => {
+	const cohort = entry.cohort ?? "ungrouped";
+	let runValue;
+	let jobsValue;
+	try {
+		runValue = await client.getRun(entry.runId);
+		jobsValue = await client.listJobs(entry.runId);
+	} catch (error) {
+		return {
+			cohort,
+			kind: "unreadable",
+			reason: error instanceof Error ? error.message : String(error),
+			repository: request.repository,
+			runId: entry.runId
+		};
+	}
+	if (!isRecord(runValue)) return {
+		cohort,
+		kind: "unreadable",
+		reason: "the run response is not an object",
+		repository: request.repository,
+		runId: entry.runId
+	};
+	const jobRows = isRecord(jobsValue) && Array.isArray(jobsValue.jobs) ? jobsValue.jobs.filter(isRecord) : [];
+	if (isRecord(jobsValue) && typeof jobsValue.total_count === "number" && jobsValue.total_count > jobRows.length) return {
+		cohort,
+		kind: "unreadable",
+		reason: `jobs listing is truncated: ${jobRows.length} of ${jobsValue.total_count} jobs served`,
+		repository: request.repository,
+		runId: entry.runId
+	};
+	const jobs = jobRows.map(analyzeJob);
+	const createdAt = stringField$1(runValue, "created_at", "run");
+	const startedAt = stringField$1(runValue, "run_started_at", "run");
+	const completedAt = runCompletionInstant(jobs);
+	const profiles = request.includeProfiles ? await collectProfiles(client, entry.runId) : unavailable("profile artifacts were not requested (pass --profiles)");
+	const cpuModels = profiles.available ? [...new Set(profiles.value.flatMap((profile) => profile.kind === "profile" && profile.profile.cpuModel !== null ? [profile.profile.cpuModel] : []))] : void 0;
+	const labels = [...new Set(jobs.flatMap((job) => job.runnerLabels.available ? job.runnerLabels.value : []))];
+	return {
+		cohort,
+		completedAt,
+		conclusion: stringField$1(runValue, "conclusion", "run"),
+		cpuModels: cpuModelsField(cpuModels, profiles),
+		createdAt,
+		durations: {
+			queueMs: runQueueDuration(createdAt, jobs),
+			totalMs: durationBetween(startedAt, completedAt, "run duration")
+		},
+		event: stringField$1(runValue, "event", "run"),
+		headSha: stringField$1(runValue, "head_sha", "run"),
+		jobs,
+		kind: "analyzed",
+		profiles,
+		proofReuse: classifyProofReuse(jobs),
+		repository: request.repository,
+		runId: entry.runId,
+		runnerLabels: labels.length === 0 ? unavailable("no job carries runner labels") : available(labels),
+		startedAt,
+		url: stringField$1(runValue, "html_url", "run"),
+		workflowName: stringField$1(runValue, "name", "run")
+	};
+};
+/**
+* Quantile by the floor-index convention: over `sorted` (ascending), the
+* q-quantile is the element at index `floor(q * (n - 1))`. No interpolation —
+* every reported quantile is a duration that actually happened, and the
+* convention is stable for the small sample counts (3–10 runs) this command
+* exists for. median = q(0.5), p25 = q(0.25), p75 = q(0.75).
+*/
+const quantileFloorIndex = (sorted, q) => sorted[Math.floor(q * (sorted.length - 1))] ?? NaN;
+const quantileSummary = (values) => {
+	const sorted = values.toSorted((left, right) => left - right);
+	return {
+		count: sorted.length,
+		maximum: sorted.at(-1) ?? NaN,
+		median: quantileFloorIndex(sorted, .5),
+		minimum: sorted[0] ?? NaN,
+		p25: quantileFloorIndex(sorted, .25),
+		p75: quantileFloorIndex(sorted, .75)
+	};
+};
+const classificationOf = (run) => run.proofReuse.available ? run.proofReuse.value.classification : "unclassified";
+const aggregateCohorts = (runs) => {
+	const cells = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (run.kind !== "analyzed") continue;
+		const key = `${run.cohort}\0${classificationOf(run)}`;
+		const cell = cells.get(key) ?? [];
+		cell.push(run);
+		cells.set(key, cell);
+	}
+	return [...cells.entries()].map(([key, cellRuns]) => {
+		const [cohort = UNGROUPED_COHORT] = key.split("\0");
+		const totals = cellRuns.flatMap((run) => run.durations.totalMs.available ? [run.durations.totalMs.value] : []);
+		const excludedRunIds = cellRuns.filter((run) => !run.durations.totalMs.available).map((run) => run.runId);
+		return {
+			classification: classificationOf(cellRuns[0]),
+			cohort,
+			count: cellRuns.length,
+			excludedRunIds,
+			runIds: cellRuns.map((run) => run.runId),
+			totalDurationMs: totals.length === 0 ? unavailable("no run in this cell has an available total duration") : available(quantileSummary(totals))
+		};
+	}).toSorted((left, right) => `${left.cohort}\0${left.classification}`.localeCompare(`${right.cohort}\0${right.classification}`));
+};
+const cohortWarnings = (runs) => {
+	const warnings = [];
+	const byCohort = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (run.kind !== "analyzed") continue;
+		const cohort = byCohort.get(run.cohort) ?? [];
+		cohort.push(run);
+		byCohort.set(run.cohort, cohort);
+	}
+	for (const [cohort, cohortRuns] of [...byCohort.entries()].toSorted(([left], [right]) => left.localeCompare(right))) {
+		const workflows = [...new Set(cohortRuns.flatMap((run) => run.workflowName.available ? [run.workflowName.value] : []))].toSorted();
+		if (workflows.length > 1) warnings.push(`cohort "${cohort}" spans workflow shapes: ${workflows.join(", ")} — durations across different workflows are not comparable`);
+		const models = [...new Set(cohortRuns.flatMap((run) => run.cpuModels.available ? run.cpuModels.value : []))].toSorted();
+		if (models.length > 1) warnings.push(`cohort "${cohort}" spans CPU models: ${models.join(", ")} — stratify by cpuModel before comparing (see the CI runner analysis docs)`);
+	}
+	return warnings;
+};
+/**
+* Analyze the requested runs. Read-only: the client is only ever asked to GET.
+* One unreadable run never aborts the report — it is carried as an explicit
+* `unreadable` entry so a partially-served API answer stays auditable.
+*/
+const analyzeCiRuns = async (request, client, dependencies = {}) => {
+	if (request.runs.length === 0) throw new Error("ci:analyze requires at least one run id (--run, --runs-file, or --cohort).");
+	const runs = [];
+	for (const entry of request.runs) runs.push(await analyzeOneRun(client, request, entry));
+	return {
+		cohorts: aggregateCohorts(runs),
+		generatedAt: (dependencies.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+		repository: request.repository,
+		runs,
+		schemaVersion: 1,
+		tool: CI_ANALYZE_TOOL,
+		warnings: cohortWarnings(runs)
+	};
+};
+const formatSeconds = (ms) => `${(ms / 1e3).toFixed(1)}s`;
+const formatMaybeDuration = (value) => value.available ? formatSeconds(value.value) : `unavailable (${value.reason})`;
+const CLASSIFICATION_HEADINGS = {
+	"full-fallback": "full hosted fallback",
+	mixed: "mixed proof outcomes",
+	"proof-reuse": "proof reuse",
+	unclassified: "no proof-gate signal"
+};
+const renderRunLine = (run) => {
+	const lines = [
+		`  run ${run.runId} — ${run.workflowName.available ? run.workflowName.value : "unknown workflow"} (${run.conclusion.available ? run.conclusion.value : "no conclusion"})`,
+		`    total ${formatMaybeDuration(run.durations.totalMs)}, queue ${formatMaybeDuration(run.durations.queueMs)}`,
+		`    ${run.url.available ? run.url.value : "run URL unavailable"}`
+	];
+	if (run.cpuModels.available) lines.push(`    cpu: ${run.cpuModels.value.join(", ")}`);
+	if (run.profiles.available) for (const profile of run.profiles.value) {
+		if (profile.kind === "unreadable") {
+			lines.push(`    profile ${profile.artifactName}: unreadable (${profile.reason})`);
+			continue;
+		}
+		const p = profile.profile;
+		lines.push(`    profile ${profile.artifactName}: median ${formatSeconds(p.summaryDurationMs.median)} over ${p.sampleDurationsMs.length} sample(s), ${p.testCount.available ? `${p.testCount.value} tests` : "test count unavailable"}, cpu ${p.cpuModel ?? "unrecorded"}`);
+		const [slowFile] = p.slowFiles;
+		if (slowFile) lines.push(`      slowest file ${slowFile.path} (${formatSeconds(slowFile.medianMs)} median)`);
+		const [slowTest] = p.slowTests;
+		if (slowTest) lines.push(`      slowest test ${slowTest.name} (${formatSeconds(slowTest.medianMs)} median)`);
+	}
+	return lines;
+};
+/**
+* Human rendering. Structure mirrors the aggregation rule: one section per
+* cohort × classification cell, so full fallback and proof reuse are never
+* visually blended, and before/after cohorts stay separate.
+*/
+const renderCiAnalyzeReport = (report) => {
+	const lines = [`ci:analyze — ${report.repository} (schema v${report.schemaVersion})`];
+	const analyzed = report.runs.filter((run) => run.kind === "analyzed");
+	for (const cohort of report.cohorts) {
+		lines.push("", `cohort "${cohort.cohort}" — ${CLASSIFICATION_HEADINGS[cohort.classification]} (${cohort.count} run(s))`);
+		if (cohort.totalDurationMs.available) {
+			const stats = cohort.totalDurationMs.value;
+			lines.push(`  total duration over ${stats.count} run(s): median ${formatSeconds(stats.median)}, p25 ${formatSeconds(stats.p25)}, p75 ${formatSeconds(stats.p75)}, min ${formatSeconds(stats.minimum)}, max ${formatSeconds(stats.maximum)}`);
+		} else lines.push(`  total duration: unavailable (${cohort.totalDurationMs.reason})`);
+		if (cohort.excludedRunIds.length > 0) lines.push(`  excluded from aggregates (total unavailable): ${cohort.excludedRunIds.join(", ")}`);
+		for (const run of analyzed.filter((candidate) => candidate.cohort === cohort.cohort && classificationOf(candidate) === cohort.classification)) lines.push(...renderRunLine(run));
+	}
+	const unreadable = report.runs.filter((run) => run.kind === "unreadable");
+	const unreadableCohorts = [...new Set(unreadable.map((run) => run.cohort))].toSorted((left, right) => left.localeCompare(right));
+	for (const cohort of unreadableCohorts) {
+		lines.push("", `cohort "${cohort}" — unreadable runs:`);
+		for (const run of unreadable.filter((candidate) => candidate.cohort === cohort)) lines.push(`  run ${run.runId}: ${run.reason}`);
+	}
+	if (report.warnings.length > 0) {
+		lines.push("", "warnings:");
+		for (const warning of report.warnings) lines.push(`  - ${warning}`);
+	}
+	return `${lines.join("\n")}\n`;
+};
+//#endregion
+//#region src/commands/ci-analyze.ts
+/**
+* `ci:analyze` command wiring (#647).
+*
+* The analysis itself lives in `../ci-analyze.js`; this module owns the flag
+* grammar, the run-id assembly (`--run`, `--runs-file`, `--cohort`), the
+* report output paths, and the default `gh`-backed {@link CiAnalyzeClient}.
+* Authentication is entirely the caller's: every request goes through the
+* `gh` CLI, which resolves its own token (GH_TOKEN / GITHUB_TOKEN / login) —
+* no credential is stored or minted here.
+*/
+const REPOSITORY_PATTERN = /^[\w.-]+\/[\w.-]+$/u;
+const parseRepository = (value) => {
+	if (!REPOSITORY_PATTERN.test(value)) throw new Error(`--repo must be owner/name, got "${value}"`);
+	return value;
+};
+const parseRunId = (value) => {
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`run id must be a positive integer, got "${value}"`);
+	return parsed;
+};
+const collectRunOption = (value, previous = []) => [...previous, parseRunId(value)];
+/**
+* `--cohort label=id,id` — the same `name=value` grammar the existing psf
+* flags use for structured values, repeatable once per label.
+*
+* The label `ungrouped` is reserved: it is what the report calls runs the
+* caller left unlabeled, so accepting it as a caller cohort would silently
+* blend a named population with the genuinely unlabeled one.
+*/
+const parseCohortOption = (value, previous = []) => {
+	const separator = value.indexOf("=");
+	const label = separator === -1 ? "" : value.slice(0, separator).trim();
+	const ids = separator === -1 ? "" : value.slice(separator + 1);
+	if (label === "" || ids.trim() === "") throw new Error(`--cohort must be <label>=<runId>[,<runId>...], got "${value}"`);
+	if (label === "ungrouped") throw new Error(`--cohort label "${UNGROUPED_COHORT}" is reserved for runs passed without a cohort; pick another label`);
+	return [...previous, {
+		label,
+		runIds: ids.split(",").map((id) => parseRunId(id.trim()))
+	}];
+};
+/** One run id per line; blank lines and `#` comments are ignored. */
+const parseRunsFile = (content) => content.split("\n").map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#")).map(parseRunId);
+/**
+* Assemble the requested run set. A run id may appear in exactly one cohort;
+* uncohorted ids (from `--run` / `--runs-file`) stay unlabeled. Conflicting
+* cohort labels for one id are a hard error rather than a silent pick.
+*/
+const assembleRunRequests = (input) => {
+	const cohortByRun = /* @__PURE__ */ new Map();
+	for (const cohort of input.cohorts) for (const runId of cohort.runIds) {
+		const existing = cohortByRun.get(runId);
+		if (existing !== void 0 && existing !== cohort.label) throw new Error(`run ${runId} is assigned to both cohort "${existing}" and cohort "${cohort.label}"`);
+		cohortByRun.set(runId, cohort.label);
+	}
+	const ordered = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const cohort of input.cohorts) for (const runId of cohort.runIds) if (!seen.has(runId)) {
+		seen.add(runId);
+		ordered.push({
+			cohort: cohort.label,
+			runId
+		});
+	}
+	for (const runId of input.runIds) if (!seen.has(runId)) {
+		seen.add(runId);
+		ordered.push({
+			cohort: cohortByRun.get(runId) ?? null,
+			runId
+		});
+	}
+	return ordered;
+};
+const GH_ARTIFACT_MAX_BYTES = 256 * 1024 * 1024;
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+/**
+* Follow GitHub's pagination for one collection endpoint: request pages until
+* the served rows reach the response's `total_count` (or a page comes back
+* empty). The merged document keeps the `total_count` field, so if the page
+* budget is ever exhausted the analyzer's truncation guard reports the
+* shortfall as explicit unavailability instead of a silent partial read.
+*/
+const listActionsCollection = (basePath, key) => {
+	const rows = [];
+	let totalCount;
+	for (let page = 1; page <= MAX_PAGES; page += 1) {
+		const response = runGhJson(["api", `${basePath}?per_page=${PAGE_SIZE}&page=${page}`]);
+		const served = Array.isArray(response[key]) ? response[key] : [];
+		rows.push(...served);
+		totalCount = typeof response.total_count === "number" ? response.total_count : totalCount;
+		if (served.length === 0 || rows.length >= (totalCount ?? 0)) break;
+	}
+	return {
+		[key]: rows,
+		total_count: totalCount ?? rows.length
+	};
+};
+/**
+* A Unix-host entry line: permissions, zip version, host OS, decompressed
+* size, text/binary flags, method, date, time, then the member name (which
+* may itself contain spaces). This is the one form GitHub's artifact service
+* actually emits; other host forms are deliberately *not* supported — they
+* fail reconciliation below rather than being half-parsed.
+*/
+const ZIP_ENTRY_PATTERN = /^(?<perms>[-dl][a-srwxt-]{9})\s+\d+\.\d+\s+\S+\s+(?<size>\d+)\s+\S\S\s+\S+\s+\S+\s+\S+\s(?<name>.+)$/u;
+/** `Zip file size: 12109 bytes, number of entries: 2` */
+const ZIP_HEADER_PATTERN = /^Zip file size: \d+ bytes, number of entries: (?<count>\d+)$/u;
+/** `2 files, 81410 bytes uncompressed, 11689 bytes compressed:  85.6%` */
+const ZIP_TRAILER_PATTERN = /^(?<count>\d+) files?, \d+ bytes? uncompressed, \d+ bytes? compressed:\s+-?[\d.]+%$/u;
+/**
+* Parse zipinfo's default listing and *reconcile* it against the archive's
+* own declared entry count — fail closed, never a partial view.
+*
+* The security property the caps and member policy rest on is that the parsed
+* set is the WHOLE central directory. A listing line this parser does not
+* recognize (a FAT-host form, a future zipinfo change) therefore refuses the
+* whole artifact rather than being skipped: a skipped line would let
+* `unzip <name>` extract members the caps never counted. Three refusals:
+* an unrecognized line, a parsed count that differs from the declared count
+* (every header and trailer declaration must agree — a listing that
+* contradicts itself has no unambiguous count and is refused), and any
+* duplicate member name across the full parsed set — a parsed safe name
+* shadowed by an unparsed or differently-shaped duplicate is exactly the
+* bypass this closes.
+*/
+const parseZipInfoListing = (text) => {
+	const members = [];
+	const declaredCounts = [];
+	for (const line of text.split("\n")) {
+		if (line.trim() === "" || line.startsWith("Archive:")) continue;
+		const header = ZIP_HEADER_PATTERN.exec(line);
+		if (header?.groups) {
+			declaredCounts.push(Number(header.groups.count));
+			continue;
+		}
+		const trailer = ZIP_TRAILER_PATTERN.exec(line);
+		if (trailer?.groups) {
+			declaredCounts.push(Number(trailer.groups.count));
+			continue;
+		}
+		const entry = ZIP_ENTRY_PATTERN.exec(line);
+		if (entry?.groups) {
+			members.push({
+				isSymlink: entry.groups.perms?.startsWith("l") === true,
+				name: entry.groups.name ?? "",
+				sizeBytes: Number(entry.groups.size)
+			});
+			continue;
+		}
+		throw new Error(`zip listing reconciliation failed: unrecognized listing line "${line}"`);
+	}
+	const [declaredEntries] = declaredCounts;
+	if (declaredEntries === void 0) throw new Error("zip listing reconciliation failed: the listing declares no entry count");
+	if (declaredCounts.some((count) => count !== declaredEntries)) throw new Error(`zip listing reconciliation failed: contradictory declared entry counts (${declaredCounts.join(", ")})`);
+	if (members.length !== declaredEntries) throw new Error(`zip listing reconciliation failed: parsed ${members.length} of ${declaredEntries} declared entries`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const member of members) {
+		if (seen.has(member.name)) throw new Error(`zip listing reconciliation failed: duplicate member name "${member.name}"`);
+		seen.add(member.name);
+	}
+	return members;
+};
+const MAX_ARTIFACT_DECOMPRESSED_BYTES = 256 * 1024 * 1024;
+const UNSAFE_MEMBER_CHARACTERS = /[*?[\]]/u;
+/**
+* The member policy for artifact zips, as a pure function so the security
+* decisions are testable without `unzip`. The archive is refused outright —
+* not partially read — when any member is a symlink, an absolute path, a
+* `..` traversal, option-shaped (leading `-`), or glob-ambiguous, or when the
+* archive exceeds the count or decompressed-size caps. What survives is the
+* `*.json` member list actually handed to extraction.
+*/
+const selectProfileZipMembers = (members) => {
+	if (members.length > 512) throw new Error(`artifact zip refused: ${members.length} members exceeds the 512-member cap`);
+	let totalBytes = 0;
+	for (const member of members) {
+		if (member.isSymlink) throw new Error(`artifact zip refused: member "${member.name}" is a symlink`);
+		if (member.name.startsWith("/") || /^[A-Za-z]:/u.test(member.name)) throw new Error(`artifact zip refused: member "${member.name}" is an absolute path`);
+		if (member.name.split("/").includes("..")) throw new Error(`artifact zip refused: member "${member.name}" traverses with ..`);
+		if (member.name.startsWith("-")) throw new Error(`artifact zip refused: member "${member.name}" is option-shaped`);
+		if (UNSAFE_MEMBER_CHARACTERS.test(member.name)) throw new Error(`artifact zip refused: member "${member.name}" contains glob metacharacters`);
+		if (!Number.isFinite(member.sizeBytes) || member.sizeBytes < 0) throw new Error(`artifact zip refused: member "${member.name}" reports no usable size`);
+		totalBytes += member.sizeBytes;
+	}
+	if (totalBytes > 268435456) throw new Error(`artifact zip refused: ${totalBytes} decompressed bytes exceeds the ${MAX_ARTIFACT_DECOMPRESSED_BYTES}-byte cap`);
+	return members.filter((member) => !member.name.endsWith("/") && member.name.endsWith(".json")).map((member) => member.name).toSorted();
+};
+/**
+* The default client: `gh api` for JSON endpoints (paginated), `gh api` plus
+* system `unzip` for artifact zips, with every member vetted by
+* {@link selectProfileZipMembers} before extraction. The exec adapter itself
+* is deliberately thin and untested networked code — every decision made from
+* these bytes lives behind {@link CiAnalyzeClient} or the pure policy
+* functions above, where fixtures drive it.
+*/
+const createGhCiAnalyzeClient = (repository) => ({
+	getRun: (runId) => Promise.resolve(runGhJson(["api", `/repos/${repository}/actions/runs/${runId}`])),
+	listArtifacts: (runId) => Promise.resolve(listActionsCollection(`/repos/${repository}/actions/runs/${runId}/artifacts`, "artifacts")),
+	listJobs: (runId) => Promise.resolve(listActionsCollection(`/repos/${repository}/actions/runs/${runId}/jobs`, "jobs")),
+	readArtifactTextFiles: (artifactId) => {
+		const scratch = mkdtempSync(path.join(tmpdir(), "psf-ci-analyze-"));
+		try {
+			const zip = execFileSync("gh", ["api", `/repos/${repository}/actions/artifacts/${artifactId}/zip`], { maxBuffer: GH_ARTIFACT_MAX_BYTES });
+			const zipPath = path.join(scratch, "artifact.zip");
+			writeFileSync(zipPath, zip);
+			const selected = selectProfileZipMembers(parseZipInfoListing(execFileSync("unzip", ["-Z", zipPath], {
+				encoding: "utf-8",
+				maxBuffer: GH_ARTIFACT_MAX_BYTES
+			})));
+			if (selected.length === 0) return Promise.resolve([]);
+			const extracted = path.join(scratch, "extracted");
+			execFileSync("unzip", [
+				"-o",
+				"-qq",
+				zipPath,
+				"-d",
+				extracted,
+				...selected
+			], { stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			] });
+			return Promise.resolve(selected.map((name) => ({
+				name,
+				text: readFileSync(path.join(extracted, name), "utf-8")
+			})));
+		} finally {
+			rmSync(scratch, {
+				force: true,
+				recursive: true
+			});
+		}
+	}
+});
+const defaultAction = (request) => analyzeCiRuns(request, createGhCiAnalyzeClient(request.repository));
+function createCiAnalyzeCommand(output, action = defaultAction) {
+	return new Command("ci:analyze").description("Read-only GitHub Actions run lifecycle analysis: queue/setup/install/step/total durations, proof-reuse classification, cohort aggregates, and optional factory-ci Vitest profile readback").requiredOption("--repo <owner/name>", "repository the run ids belong to", parseRepository).option("--run <id>", "workflow run id to analyze (repeatable)", collectRunOption).option("--runs-file <path>", "file of run ids, one per line (# comments allowed)").option("--cohort <label=ids>", "label a comma-separated run-id list as one cohort, e.g. --cohort before=1,2 (repeatable; the label \"ungrouped\" is reserved for runs passed without a cohort)", parseCohortOption).option("--profiles", "download run artifacts and read compatible factory-ci Vitest profiles (the only source of cpuModel)").option("--output <path>", "write the versioned JSON report to a path").option("--json", "print the JSON report to stdout instead of prose").action(async (options) => {
+		const fromFile = options.runsFile === void 0 ? [] : parseRunsFile(readFileSync(path.resolve(options.runsFile), "utf-8"));
+		const report = await action({
+			includeProfiles: options.profiles === true,
+			repository: options.repo,
+			runs: assembleRunRequests({
+				cohorts: options.cohort ?? [],
+				runIds: [...options.run ?? [], ...fromFile]
+			})
+		});
+		if (options.output !== void 0) {
+			const outputPath = path.resolve(options.output);
+			writeFileSync(outputPath, `${JSON.stringify(report, null, 2)}\n`);
+			output.stderr.write(`ci:analyze report written to ${outputPath}\n`);
+		}
+		output.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderCiAnalyzeReport(report));
+	});
 }
 //#endregion
 //#region src/checkout-repository.ts
@@ -9547,6 +10112,8 @@ const buildRetroEnvelope = (input) => {
 const RETRO_ENVELOPE_LEDGER_DIR = ".factory-memory/retro-envelope";
 const safeEnvelopeName = (agentRunId) => agentRunId.replaceAll(/[^\w.-]/gu, "-").slice(0, 120);
 const retroEnvelopePath = (root, agentRunId) => path.join(root, RETRO_ENVELOPE_LEDGER_DIR, `${safeEnvelopeName(agentRunId)}.json`);
+const CLAUDE_CODE_SESSION_ID_ENV = "CLAUDE_CODE_SESSION_ID";
+const resolveNativeSessionId = (env) => normalizeSessionId(env[CLAUDE_CODE_SESSION_ID_ENV]);
 const splitRepo = (repo) => {
 	const [owner, name] = repo.split("/");
 	return {
@@ -9572,11 +10139,11 @@ const otherLedgersExist = (repoRoot) => {
 const buildAndPersistRetroEnvelope = (input) => {
 	const env = input.env ?? process.env;
 	const now = input.now ?? (() => /* @__PURE__ */ new Date());
-	const laneIdentity = resolveGateTimingAgentRunId(env);
+	const laneIdentity = resolveGateTimingAgentRunId(env) ?? resolveNativeSessionId(env);
 	const agentRunId = laneIdentity ?? `closeout-${safeEnvelopeName(input.epic)}`;
 	const ledgerPath = gateTimingLedgerPath(input.repoRoot, agentRunId);
 	const ledger = laneIdentity === void 0 ? [] : readGateTimingLedger(ledgerPath);
-	const claudeSessionId = discoverFactorySessionId(env);
+	const claudeSessionId = discoverFactorySessionId(env) ?? resolveNativeSessionId(env);
 	const dataGaps = [];
 	if (laneIdentity === void 0) dataGaps.push("agentRunId is synthetic (no lane run identity exported): keyed to the epic, ledger not folded.");
 	else if (!existsSync(ledgerPath) && otherLedgersExist(input.repoRoot)) dataGaps.push(`gates[] empty: no gate-timing ledger for agentRunId "${agentRunId}" although other lane ledgers exist under ${GATE_TIMING_LEDGER_DIR} — possible identity drift between ledger writes and closeout.`);
@@ -9855,6 +10422,7 @@ function createCloseoutCommand(output, dependencies = {}) {
 		});
 		const retro = buildRetroGate({
 			codexThreadIds: codexThreadIdsForCloseout(dependencies.env),
+			...dependencies.env === void 0 ? {} : { env: dependencies.env },
 			epic: options.epic,
 			...options.issue === void 0 ? {} : { issue: options.issue },
 			...options.pr === void 0 ? {} : { pr: options.pr },
@@ -11167,12 +11735,14 @@ function runPrVerify(args, dependencies = {}) {
 		impactStamp = computeImpactStamp({
 			changedFiles: files,
 			profile,
+			profilePath: relativeProfile,
 			readLockfile: (side) => readLockfileAtRef(cwd, side === "base" ? proofMergeBaseSha : headSha, path.resolve(cwd, LOCKFILE_PATH))
 		});
 	} catch (error) {
 		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,
@@ -11479,7 +12049,7 @@ const runDemandWaive = (args, dependencies = {}) => {
 * offers no way to declare a demand met, only to waive it on the record.
 */
 function createDemandWaiveCommand(_output, action = runDemandWaive) {
-	return new Command("demand:waive").description("Waive one resolved demand for one candidate, on the operator's identity, with the rationale recorded in the proof").requiredOption("--pr <number>", "pull request number", positiveInteger("--pr")).requiredOption("--demand <key>", "resolved demand key, e.g. review-rung:human, required-check:core, merge-freeze").requiredOption("--rationale <text>", "why this demand is being waived").option("--cwd <path>", "working directory to evaluate", ".").option("--json", "print the recorded waiver as JSON").option("--output <path>", "waiver record JSON path").action((options) => {
+	return markCwdOptionDefault(new Command("demand:waive").description("Waive one resolved demand for one candidate, on the operator's identity, with the rationale recorded in the proof").requiredOption("--pr <number>", "pull request number", positiveInteger("--pr")).requiredOption("--demand <key>", "resolved demand key, e.g. review-rung:human, required-check:core, merge-freeze").requiredOption("--rationale <text>", "why this demand is being waived").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--json", "print the recorded waiver as JSON").option("--output <path>", "waiver record JSON path").action((options) => {
 		action({
 			cwd: resolveCwdOption(options.cwd),
 			demand: options.demand,
@@ -11488,7 +12058,7 @@ function createDemandWaiveCommand(_output, action = runDemandWaive) {
 			pr: options.pr,
 			rationale: options.rationale
 		});
-	});
+	}));
 }
 //#endregion
 //#region src/demand-resolution.ts
@@ -11592,20 +12162,32 @@ const defaultFetchIssueBody = ({ issue, owner, repo }) => runGhJson([
 * closed: an absent, unparseable, or unmatched manifest binds nothing and
 * names its refusal.
 */
-const resolveWaveDemand = ({ epic, fetchClosingPullRequests = defaultFetchClosingPullRequests, fetchIssueBody = defaultFetchIssueBody, owner, pr, repo }) => {
+const resolveWaveDemand = ({ baseRefName, epic, fetchClosingPullRequests = defaultFetchClosingPullRequests, fetchIssueBody = defaultFetchIssueBody, headRefName, owner, pr, repo }) => {
 	const parsed = parseBoundaryManifest(fetchIssueBody({
 		issue: epic,
 		owner,
 		repo
 	}));
 	if (!parsed.ok) return { reasons: [`Epic #${epic} boundary manifest refused: ${parsed.error}`] };
-	return waveDemandForPullRequest({
+	const resolution = waveDemandForPullRequest({
 		fetchClosingPullRequests,
 		manifest: parsed.manifest,
 		owner,
 		pr,
 		repo
 	});
+	if (!resolution.demand) return resolution;
+	return {
+		demand: resolution.demand,
+		reasons: pullRequestTopologyReasons({
+			manifest: parsed.manifest,
+			pullRequest: {
+				...baseRefName === void 0 ? {} : { baseRefName },
+				...headRefName === void 0 ? {} : { headRefName },
+				number: pr
+			}
+		})
+	};
 };
 /**
 * Whether recorded typed review evidence satisfies the demanded review rung.
@@ -12081,10 +12663,10 @@ const describeOrphans = (orphans) => {
 	return ` ${orphans.length} spool location(s) hold this repository's evidence under an earlier key it no longer resolves to — a key-format change strands evidence there where no drain looks: ${described}. Drain each with \`psf hq:flush --dir <path>\`.`;
 };
 /**
-* Red when HQ evidence is waiting for this repository: its own spool or legacy
-* journal, or a sibling location written under an earlier key of its own that
-* it no longer resolves to (#420). Another repository's spool under the shared
-* root is that repository's business, never this check's (#446).
+* Warns when HQ evidence is waiting for this repository: its own spool or a
+* sibling location written under an earlier key of its own that it no longer
+* resolves to (#420). Another repository's spool under the shared root is that
+* repository's business, never this check's (#446).
 *
 * Reuses `countHqSpoolWork` (#414) — the same read-only, credential-free
 * inspection `hq:flush` itself consults before ever resolving a secret — so
@@ -12094,19 +12676,23 @@ const describeOrphans = (orphans) => {
 * the spool resolve exactly one key, so evidence written under an older one is
 * invisible to a drain and, before this, to doctor: the failure epic #389 was
 * chartered to end is evidence that is neither delivered nor visibly stranded.
-* An orphan holding pending events is red for the same reason the repo-keyed
-* spool is.
+* An orphan holding pending events warns for the same reason the repo-keyed
+* spool does.
+*
+* `warning`, not `error` (#659, epic #663 wave 1): a spooled event is real
+* HQ-delivery lag, but doctor is a read-only diagnostic that must never gain a
+* flush side-effect, and a preflight gate that treats doctor's exit code as
+* the bar must not block admission on delivery lag it cannot fix from here.
+* `psf hq:flush` — a trusted local session, not doctor — is still how the
+* spool actually drains.
 */
 async function hqSpoolDoctorCheck(input, dependencies = {}) {
 	const countSpool = dependencies.countSpool ?? countHqSpoolWork;
 	const sweepOrphans = dependencies.sweepOrphans ?? sweepHqSpoolOrphans;
-	const [counted, swept] = await Promise.all([countSpool({
-		cwd: input.cwd,
-		repository: input.repository
-	}, { env: input.env }), sweepOrphans({ repository: input.repository }, { env: input.env })]);
+	const [counted, swept] = await Promise.all([countSpool({ repository: input.repository }, { env: input.env }), sweepOrphans({ repository: input.repository }, { env: input.env })]);
 	const orphanNote = swept.orphans.length === 0 ? "" : describeOrphans(swept.orphans);
 	if (counted.pending === 0 && counted.unlistable === 0 && swept.orphans.length === 0) return {
-		message: "HQ spool and journal are empty; no evidence is waiting to be drained.",
+		message: "HQ spool is empty; no evidence is waiting to be drained.",
 		name: HQ_SPOOL_CHECK_NAME,
 		status: "ok"
 	};
@@ -12115,17 +12701,17 @@ async function hqSpoolDoctorCheck(input, dependencies = {}) {
 	if (counted.pending > 0) return {
 		message: `${counted.pending} HQ event(s) are spooled locally.${oldestNote}${locationsNote} ${FLUSH_REMEDY}${orphanNote}`,
 		name: HQ_SPOOL_CHECK_NAME,
-		status: "error"
+		status: "warning"
 	};
 	if (counted.unlistable > 0) return {
 		message: `${counted.unlistable} spool location(s) exist but could not be listed within budget, so this cannot be reported as empty.${locationsNote} ${FLUSH_REMEDY}${orphanNote}`,
 		name: HQ_SPOOL_CHECK_NAME,
-		status: "error"
+		status: "warning"
 	};
 	return {
 		message: `This repository's HQ spool is empty, but stranded evidence is waiting under the spool root ${swept.root}.${orphanNote}`,
 		name: HQ_SPOOL_CHECK_NAME,
-		status: "error"
+		status: "warning"
 	};
 }
 const readJsonFiles = async (dir, readFileImpl) => {
@@ -12310,7 +12896,6 @@ async function doctorProjectProfile(input = {}) {
 	const cwd = input.cwd ?? process.cwd();
 	const userConfig = resolveDoctorUserConfig(env, input.userConfig);
 	const [hqSpoolCheck, hqRetroReadbackCheck] = await Promise.all([hqSpoolDoctorCheck({
-		cwd,
 		env,
 		repository: {
 			owner: profile.repository.owner,
@@ -12477,7 +13062,7 @@ function repositoryUrlMatches(origin, profile) {
 //#endregion
 //#region src/commands/doctor.ts
 function createDoctorCommand(output) {
-	return new Command("doctor").description("Validate a project profile without mutating GitHub or local files").option("--base <ref>", "base branch or ref for --preflight", "origin/main").option("--cwd <path>", "working directory to validate", ".").option("--json", "print the doctor report as JSON").option("--preflight", "also list the pre-checkable admission requirements for the current candidate (read-only; never blocks); findings-file shape and wave membership have no read-only pre-check").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
+	return markCwdOptionDefault(new Command("doctor").description("Validate a project profile without mutating GitHub or local files").option("--base <ref>", "base branch or ref for --preflight", "origin/main").option("--cwd <path>", "working directory to validate", collectCwdOption).option("--json", "print the doctor report as JSON").option("--preflight", "also list the pre-checkable admission requirements for the current candidate (read-only; never blocks); findings-file shape and wave membership have no read-only pre-check").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
 		const report = await doctorProjectProfile({
 			base: options.base,
 			cwd: resolveCwdOption(options.cwd),
@@ -12487,7 +13072,7 @@ function createDoctorCommand(output) {
 		if (options.json) output.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 		else output.stdout.write(formatHumanReport(report));
 		if (!report.ok) process.exitCode = 1;
-	});
+	}));
 }
 function formatHumanReport(report) {
 	return [
@@ -12895,7 +13480,7 @@ function optionalString(key, flagValue, stdinValue) {
 	return resolved ? { [key]: resolved } : {};
 }
 function createEvidenceEmitCommand(output, action = runEvidenceEmit, readInput = readStdin) {
-	return new Command("evidence:emit").description("Build, validate, and write an external-evidence envelope (ADR 0014)").option("--cwd <path>", "repository working directory", ".").option("--base <ref>", "base branch or ref for the three-way binding", "origin/main").option("--check <name>", "declared requiredChecks name this evidence satisfies").option("--outcome <pass|fail>", "the check outcome").option("--producer <id>", "the producing identity (recorded, not gated)").option("--policy-version <version>", "canonical prompt / Warden rules version").option("--session-id <id>", "producer session id (independence join key)").option("--request-id <id>", "producer request id (join key)").option("--findings-pointer <ref>", "pointer to findings (never embedded)").option("--profile <path>", "path to the project profile JSON file (accepted for a uniform consumer-wrapper flag set and loaded strictly when supplied)").option("--output <path>", "write the envelope to a specific path").option("--stdin", "merge JSON field values from stdin (flags win)").option("--json", "print the written envelope as JSON").action((options) => {
+	return markCwdOptionDefault(new Command("evidence:emit").description("Build, validate, and write an external-evidence envelope (ADR 0014)").option("--cwd <path>", "repository working directory", collectCwdOption).option("--base <ref>", "base branch or ref for the three-way binding", "origin/main").option("--check <name>", "declared requiredChecks name this evidence satisfies").option("--outcome <pass|fail>", "the check outcome").option("--producer <id>", "the producing identity (recorded, not gated)").option("--policy-version <version>", "canonical prompt / Warden rules version").option("--session-id <id>", "producer session id (independence join key)").option("--request-id <id>", "producer request id (join key)").option("--findings-pointer <ref>", "pointer to findings (never embedded)").option("--profile <path>", "path to the project profile JSON file (accepted for a uniform consumer-wrapper flag set and loaded strictly when supplied)").option("--output <path>", "write the envelope to a specific path").option("--stdin", "merge JSON field values from stdin (flags win)").option("--json", "print the written envelope as JSON").action((options) => {
 		const cwd = resolveCwdOption(options.cwd);
 		const fromStdin = options.stdin ? readInput() : {};
 		rejectRetiredStdinFields(fromStdin);
@@ -12922,7 +13507,7 @@ function createEvidenceEmitCommand(output, action = runEvidenceEmit, readInput =
 		});
 		output.stdout.write(`evidence:emit wrote envelope for "${result.envelope.check}" to ${result.path}\n`);
 		if (options.json && "envelope" in result) output.stdout.write(`${JSON.stringify(result.envelope, null, 2)}\n`);
-	});
+	}));
 }
 //#endregion
 //#region src/hq-flush.ts
@@ -12988,7 +13573,6 @@ async function runHqFlush(args, dependencies = {}) {
 	};
 	const explicitDirectories = args.dir && args.dir.length > 0 ? { explicitDirectories: args.dir } : {};
 	const pending = await (dependencies.countSpool ?? countHqSpoolWork)({
-		cwd: args.cwd,
 		...explicitDirectories,
 		repository
 	}, { env });
@@ -13033,7 +13617,6 @@ async function runHqFlush(args, dependencies = {}) {
 		...await (dependencies.flush ?? flushHqSpool)({
 			clientId: resolution.credentials.clientId,
 			clientSecret: resolution.credentials.clientSecret,
-			cwd: args.cwd,
 			endpoint: profile.hq.endpoint,
 			...explicitDirectories,
 			repository
@@ -13060,7 +13643,7 @@ function renderHqFlush(result) {
 		`hq:flush ${result.endpoint}`,
 		...result.spools.length === 0 ? ["no spool directory found"] : result.spools.map((spool) => `spool: ${spool}`),
 		...result.outcomes.map(outcomeLine),
-		`delivered ${result.delivered}, duplicate ${result.duplicate}, rejected ${result.rejected}, undeliverable ${result.undeliverable}, unreachable ${result.unreachable}, migrated ${result.outcomes.filter((outcome) => outcome.status === "migrated").length}`,
+		`delivered ${result.delivered}, duplicate ${result.duplicate}, rejected ${result.rejected}, undeliverable ${result.undeliverable}, unreachable ${result.unreachable}`,
 		...result.undeliverable > 0 ? [`${result.undeliverable} event(s) can never be delivered and were dispositioned in place, renamed with \`.undeliverable\` and left readable; they no longer count as work waiting.`] : [],
 		result.incomplete ? `INCOMPLETE: ${result.remaining} event(s) still spooled; the drain did not finish. Run hq:flush again.` : `spool drained: ${result.remaining} event(s) remain (rejections stay until HQ accepts them)`,
 		...orphanLines(result.orphans)
@@ -13087,7 +13670,7 @@ const hqFlushExitCode = (result) => {
 //#endregion
 //#region src/commands/hq-flush.ts
 function createHqFlushCommand(output, action = runHqFlush) {
-	return new Command("hq:flush").description("Drain this repository's spooled HQ evidence and report every event; exits 1 when transport failed and 2 when the drain did not finish").option("--cwd <path>", "working directory to evaluate", ".").option("--dir <path>", "drain an explicit spool directory instead of the default locations; repeatable", (value, previous = []) => [...previous, value]).option("--json", "print the flush result as JSON").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
+	return markCwdOptionDefault(new Command("hq:flush").description("Drain this repository's spooled HQ evidence and report every event; exits 1 when transport failed and 2 when the drain did not finish").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--dir <path>", "drain an explicit spool directory instead of the default locations; repeatable", (value, previous = []) => [...previous, value]).option("--json", "print the flush result as JSON").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
 		const result = await action({
 			cwd: resolveCwdOption(options.cwd),
 			...options.dir ? { dir: options.dir } : {},
@@ -13097,7 +13680,7 @@ function createHqFlushCommand(output, action = runHqFlush) {
 		output.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderHqFlush(result));
 		const exitCode = hqFlushExitCode(result);
 		if (exitCode !== 0) process.exitCode = exitCode;
-	});
+	}));
 }
 //#endregion
 //#region src/follow-up.ts
@@ -13133,6 +13716,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()),
@@ -14248,15 +14838,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));
@@ -14615,6 +15208,7 @@ const PR_VIEW_JSON_FIELDS = [
 	"autoMergeRequest",
 	"baseRefName",
 	"body",
+	"headRefName",
 	"headRefOid",
 	"isDraft",
 	"mergeStateStatus",
@@ -14817,9 +15411,11 @@ async function runPrReady(args, dependencies = {}) {
 		});
 		const { ladderPolicy } = demands;
 		const waveDemand = args.epic === void 0 ? void 0 : resolveWaveDemand({
+			baseRefName: pr.baseRefName,
 			epic: args.epic,
 			...github.fetchClosingPullRequests ? { fetchClosingPullRequests: github.fetchClosingPullRequests } : {},
 			...github.fetchIssueBody ? { fetchIssueBody: github.fetchIssueBody } : {},
+			headRefName: pr.headRefName,
 			owner: repository.owner,
 			pr: args.pr,
 			repo: repository.name
@@ -14920,12 +15516,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,
@@ -15468,6 +16059,15 @@ const defaultPrPublishCliInvocation = () => {
 };
 const prPublishCliInvocation = (explicit) => explicit ?? defaultPrPublishCliInvocation();
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+/**
+* GitHub creates a pull request against a branch name, while the rest of the
+* publish transaction treats `--base` as an exact local Git-ref assertion.
+* Keep those representations separate: only the creation adapter drops the
+* canonical remote qualifier, and callers downstream retain the original ref.
+*/
+function githubCreationBranchForBaseAssertion(base) {
+	return base.startsWith("origin/") ? base.slice(7) : base;
+}
 function discoverOrCreatePullRequestNumber({ args, branch, cwd, gh }) {
 	if (args.pr !== void 0) return args.pr;
 	if (!branch) throw new Error("pr:publish cannot discover a PR from a detached HEAD; pass --pr.");
@@ -15483,12 +16083,14 @@ function discoverOrCreatePullRequestNumber({ args, branch, cwd, gh }) {
 	];
 	const existing = JSON.parse(gh(lookupArgs, cwd));
 	if (existing[0]) return existing[0].number;
-	gh([
+	const createArgs = [
 		"pr",
 		"create",
 		"--draft",
 		"--fill"
-	], cwd);
+	];
+	if (args.base.length > 0) createArgs.push("--base", githubCreationBranchForBaseAssertion(args.base));
+	gh(createArgs, cwd);
 	const created = JSON.parse(gh(lookupArgs, cwd));
 	if (!created[0]) throw new Error(`gh pr create completed but no PR was found for branch ${branch}.`);
 	return created[0].number;
@@ -15724,6 +16326,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
@@ -15858,6 +16504,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
@@ -15882,13 +16533,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) => {
@@ -15903,13 +16569,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,
@@ -15960,7 +16626,7 @@ async function deliverSpooledEvidence({ awaitPending, cwd, flush, profilePath })
 //#endregion
 //#region src/commands/pr-publish.ts
 function createPrPublishCommand(_output, action = runPrPublish) {
-	return 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", ".").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>", "local base Git ref assertion; origin/<branch> creates against GitHub <branch>").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 ?? "",
@@ -15974,12 +16640,12 @@ function createPrPublishCommand(_output, action = runPrPublish) {
 			reviewProof: options.reviewProof,
 			verifyProof: options.verifyProof
 		});
-	});
+	}));
 }
 //#endregion
 //#region src/commands/pr-ready.ts
 function createPrReadyCommand(output, action) {
-	return new Command("pr:ready").description("Evaluate typed proof and GitHub state for final readiness").requiredOption("--pr <number>", "pull request number", positiveInteger("--pr")).option("--base <ref>", "explicit base branch or ref override").option("--authoring-session <id...>", "recorded authoring session id(s) for review-type requiredCheck independence (ADR 0014 §5)").option("--cwd <path>", "working directory to evaluate", ".").option("--epic <number>", "epic issue containing the factory-boundary manifest; readiness then evaluates the wave-demanded review rung (#351)", positiveInteger("--epic")).option("--json", "print the readiness proof as JSON").option("--output <path>", "write 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(withGateTiming({
+	return markCwdOptionDefault(new Command("pr:ready").description("Evaluate typed proof and GitHub state for final readiness").requiredOption("--pr <number>", "pull request number", positiveInteger("--pr")).option("--base <ref>", "explicit base branch or ref override").option("--authoring-session <id...>", "recorded authoring session id(s) for review-type requiredCheck independence (ADR 0014 §5)").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--epic <number>", "epic issue containing the factory-boundary manifest; readiness then evaluates the wave-demanded review rung (#351)", positiveInteger("--epic")).option("--json", "print the readiness proof as JSON").option("--output <path>", "write 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(withGateTiming({
 		gate: "pr:ready",
 		resolveLedgerRoot: (options) => resolveCwdOption(options.cwd),
 		stderr: output.stderr
@@ -15997,7 +16663,7 @@ function createPrReadyCommand(output, action) {
 			verifyProof: options.verifyProof
 		};
 		await (action ? action(args) : runPrReady(args));
-	}));
+	})));
 }
 //#endregion
 //#region src/gate-foreground-guard.ts
@@ -16026,7 +16692,7 @@ function assertForegroundGate({ gate, env = process.env }) {
 //#endregion
 //#region src/commands/pr-review.ts
 function createPrReviewCommand(output, action) {
-	return new Command("pr:review").description("Validate clean-session findings and write typed review proof").option("--base <ref>", "base branch or ref", "origin/main").option("--cwd <path>", "working directory to review", ".").option("--cycle <number>", "review cycle number", positiveInteger("--cycle"), 1).option("--mode <mode>", "correctness, security, or all", "all").option("--findings <path>", "typed clean-session findings JSON file").option("--dispositions <path>", "JSON file of ladder disposition declarations (waived / follow-up-filed / fixed-in-thread) for previously flagged findings").option("--issue <number>", "issue number recorded on the review ladder trace", positiveInteger("--issue")).option("--output <path>", "write proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--verify-proof <path>", "pr:verify proof JSON path").action(withGateTiming({
+	return markCwdOptionDefault(new Command("pr:review").description("Validate clean-session findings and write typed review proof").option("--base <ref>", "base branch or ref", "origin/main").option("--cwd <path>", "working directory to review", collectCwdOption).option("--cycle <number>", "review cycle number", positiveInteger("--cycle"), 1).option("--mode <mode>", "correctness, security, or all", "all").option("--findings <path>", "typed clean-session findings JSON file").option("--dispositions <path>", "JSON file of ladder disposition declarations (waived / follow-up-filed / fixed-in-thread) for previously flagged findings").option("--issue <number>", "issue number recorded on the review ladder trace", positiveInteger("--issue")).option("--output <path>", "write proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--verify-proof <path>", "pr:verify proof JSON path").action(withGateTiming({
 		gate: "pr:review",
 		resolveCycle: (options) => options.cycle,
 		resolveLedgerRoot: (options) => resolveCwdOption(options.cwd),
@@ -16051,12 +16717,12 @@ function createPrReviewCommand(output, action) {
 			verifyProof: options.verifyProof
 		};
 		await (action ? action(args) : runPrReview(args, { publishCheckRun: createFactoryCheckPublisher(output) }));
-	}));
+	})));
 }
 //#endregion
 //#region src/commands/pr-verify.ts
 function createPrVerifyCommand(output, action = runPrVerify) {
-	return new Command("pr:verify").description("Run project-profile verification commands and write typed proof").option("--base <ref>", "base branch or ref", "origin/main").option("--cwd <path>", "working directory to verify", ".").option("--docs-only", "run the docs/process verification gate").option("--trivial", "run the trivial verification gate").option("--full", "run the full verification gate").option("--authoring-session <id>", "explicit authoring session identity (required for review evidence)").option("--json", "print the proof as JSON after verification").option("--output <path>", "write proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--no-status", "skip posting the patronage-factory/pr-verify commit status").action(withGateTiming({
+	return markCwdOptionDefault(new Command("pr:verify").description("Run project-profile verification commands and write typed proof").option("--base <ref>", "base branch or ref", "origin/main").option("--cwd <path>", "working directory to verify", collectCwdOption).option("--docs-only", "run the docs/process verification gate").option("--trivial", "run the trivial verification gate").option("--full", "run the full verification gate").option("--authoring-session <id>", "explicit authoring session identity (required for review evidence)").option("--json", "print the proof as JSON after verification").option("--output <path>", "write proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--no-status", "skip posting the patronage-factory/pr-verify commit status").action(withGateTiming({
 		gate: "pr:verify",
 		resolveLedgerRoot: (options) => resolveCwdOption(options.cwd),
 		stderr: output.stderr
@@ -16078,7 +16744,7 @@ function createPrVerifyCommand(output, action = runPrVerify) {
 			requireKnownAuthoringSession: true
 		}, dependencies);
 		if (options.json) output.stdout.write(`${JSON.stringify(proof, null, 2)}\n`);
-	}));
+	})));
 }
 function modeFor(options) {
 	if (options.docsOnly) return "docs-only";
@@ -16086,6 +16752,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({
@@ -16373,9 +17179,11 @@ function createProgram(options = {}) {
 	program.addCommand(createDoctorCommand(output));
 	program.addCommand(createConfigCommand(output));
 	program.addCommand(createEvidenceEmitCommand(output));
+	program.addCommand(createCiAnalyzeCommand(output));
 	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));