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

package/README.md

@@ -37,7 +37,7 @@ A stacked release train has one terminal release-owning slice. Interior slices d
 A stable cut has two phases. Phase 1 is the verified package candidate: steps 1 through 4 below, ending in the attended npm publish, tag, and GitHub release. Phase 2 is post-publication stable-doc convergence: steps 5 and 6, a normal admitted docs PR followed by the read-only convergence assertion from a clean `main`. Stable docs must never claim an unpublished version, so they cannot land in the phase-1 change. Prerelease behavior is unchanged: prerelease notes may land before publish while stable docs keep naming the prior stable version.
 
 1. Bump `package.json` to valid SemVer. The assertion derives its expected stable or prerelease channel from the version; it accepts no channel flag.
-2. Publish to npm per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended, hand-cut, `pnpm publish` only). Both factory packages pin `publishConfig.tag: next`, so a bare `pnpm --filter @patronage/software-factory publish` lands on `next` and cannot move `latest`. A prerelease is therefore the bare command; a stable version must say it out loud: `pnpm --filter @patronage/software-factory publish --tag latest`. Forgetting the flag on a stable cut leaves `latest` untouched for the convergence assertion to flag — the safe failure direction.
+2. Publish to npm per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended, hand-cut, `pnpm publish` only). **Always pass `--tag` explicitly, on every publish, prerelease or stable** — `pnpm --filter @patronage/software-factory publish --tag next` for a prerelease, `--tag latest` for a stable cut. A filtered publish takes pnpm's recursive path, which passes its own `--tag` (defaulting to `latest`) to npm and therefore ignores the `publishConfig.tag: next` pin both factory packages carry; that is how 1.0.0-alpha.6 briefly took `latest` (#658). The pins stay as belt and braces, but they are not the control. Omitting the flag is not a safe failure: on the filtered command it moves `latest`, which the convergence assertion can only report after the fact.
 3. Cut the `software-factory-vX.Y.Z` tag and push it.
 4. Cut the GitHub release for that tag, with notes covering features, deletions, breaking changes, and closed issues. Mark it as a prerelease exactly when its SemVer version has a prerelease component. When the release changes the profile `schemaVersion`, state it in the notes — the profile schema version is a separate axis from the package version.
 5. Converge the stable docs after publication. Update affected `software-factory-docs/` pages through a normal admitted docs PR. Stable docs must state the current stable version. Prerelease docs may record the candidate and its migration notes, but must not represent it as the current stable release.

package/dist/index.d.ts

@@ -743,8 +743,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    stale: "stale";
     active: "active";
+    stale: "stale";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1224,8 +1224,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       "run-interior-cycle": "run-interior-cycle";
     }>;
     stage: z.ZodEnum<{
-      interior: "interior";
       gate: "gate";
+      interior: "interior";
       "interior-complete": "interior-complete";
     }>;
   }, z.core.$strip>>;
@@ -1241,10 +1241,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        "not-required": "not-required";
         blocked: "blocked";
-        current: "current";
+        "not-required": "not-required";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1253,10 +1253,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        "not-required": "not-required";
         blocked: "blocked";
-        current: "current";
+        "not-required": "not-required";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1267,8 +1267,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      passed: "passed";
       stale: "stale";
+      passed: "passed";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1768,10 +1768,10 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 //#region src/review-proof-applicability.d.ts
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
-  "not-required": "not-required";
   blocked: "blocked";
-  current: "current";
+  "not-required": "not-required";
   stale: "stale";
+  current: "current";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2177,9 +2177,9 @@ declare const retroEnvelopeV1Schema: z.ZodObject<{
   kind: z.ZodLiteral<"retro-envelope">;
   outcome: z.ZodOptional<z.ZodObject<{
     status: z.ZodEnum<{
+      blocked: "blocked";
       success: "success";
       fail: "fail";
-      blocked: "blocked";
       "ship-with-followups": "ship-with-followups";
     }>;
     verdict: z.ZodOptional<z.ZodString>;
@@ -2939,8 +2939,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     sessionId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
   stage: z.ZodEnum<{
-    interior: "interior";
     gate: "gate";
+    interior: "interior";
   }>;
   usage: z.ZodOptional<z.ZodObject<{
     estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -2992,8 +2992,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     sessionId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
   stage: z.ZodEnum<{
-    interior: "interior";
     gate: "gate";
+    interior: "interior";
   }>;
   usage: z.ZodOptional<z.ZodObject<{
     estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -3036,8 +3036,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
       sessionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     stage: z.ZodEnum<{
-      interior: "interior";
       gate: "gate";
+      interior: "interior";
     }>;
     usage: z.ZodOptional<z.ZodObject<{
       estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -3067,7 +3067,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     staleRepeats: number;
   };
   observedAt: string;
-  stage: "interior" | "gate";
+  stage: "gate" | "interior";
   issue?: number | undefined;
   pr?: number | undefined;
   threadId?: string | undefined;
@@ -3323,8 +3323,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3402,8 +3402,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3472,8 +3472,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      code: "code";
       review: "review";
+      code: "code";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3545,7 +3545,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "code" | "review";
+  purpose: "review" | "code";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -4066,13 +4066,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4080,7 +4080,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     schemaVersion: 1;
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "passed" | "stale" | "missing";
+      prVerify: "stale" | "passed" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;
@@ -4123,7 +4123,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
         interior: number;
       };
       nextAction: "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human" | "advance-to-gate" | "run-interior-cycle";
-      stage: "interior" | "gate" | "interior-complete";
+      stage: "gate" | "interior" | "interior-complete";
       forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
     } | undefined;
     reviewRuns?: PrReviewResult[] | undefined;

package/dist/index.js

@@ -8,16 +8,16 @@ 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 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 { GitHubApiError, mintInstallationToken } from "@patronage/factory-ci";
+import { FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, readVitestProfileDocument } from "@patronage/factory-ci";
 //#region package.json
-var version = "1.0.0-alpha.6";
+var version = "1.0.0-alpha.8";
 //#endregion
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS$1 = [
@@ -1082,7 +1082,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) => {
@@ -1131,13 +1131,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 {}
@@ -1149,25 +1149,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));
@@ -3690,17 +3690,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 {
@@ -8553,8 +8553,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);
@@ -8577,7 +8593,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("--profile <path>", "path to the project profile JSON file").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
@@ -8616,7 +8632,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
@@ -11219,7 +11938,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,
@@ -11228,7 +11947,7 @@ function createDemandWaiveCommand(_output, action = runDemandWaive) {
 			pr: options.pr,
 			rationale: options.rationale
 		});
-	});
+	}));
 }
 //#endregion
 //#region src/demand-resolution.ts
@@ -11821,7 +12540,7 @@ 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 a
+* 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).
@@ -11834,8 +12553,15 @@ 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;
@@ -11852,17 +12578,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) => {
@@ -12213,7 +12939,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),
@@ -12223,7 +12949,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 [
@@ -12631,7 +13357,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);
@@ -12658,7 +13384,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
@@ -12821,7 +13547,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 } : {},
@@ -12831,7 +13557,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
@@ -15694,7 +16420,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("Compose supplied proof into a ready-for-human handoff; never launches review").option("--pr <number>", "pull request number", positiveInteger("--pr")).option("--base <ref>", "explicit base branch or ref override").option("--authoring-session <id>", "known authoring session identity for verification retries").option("--cwd <path>", "working directory to evaluate", collectCwdOption).option("--epic <number>", "epic issue containing the factory-boundary manifest; the composed readiness evaluation then applies the wave-demanded review rung (#351)", positiveInteger("--epic")).option("--findings <path>", "clean-session findings to validate when no current review proof is available").option("--json", "print the publish result as JSON").option("--output <path>", "write readiness proof JSON to a file").option("--profile <path>", "path to the project profile JSON file").option("--review-proof <path>", "pr:review proof JSON path").option("--verify-proof <path>", "pr:verify proof JSON path").action(async (options) => {
 		await action({
 			authoringSessionIds: options.authoringSession ? [options.authoringSession] : void 0,
 			base: options.base ?? "",
@@ -15708,12 +16434,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
@@ -15731,7 +16457,7 @@ function createPrReadyCommand(output, action) {
 			verifyProof: options.verifyProof
 		};
 		await (action ? action(args) : runPrReady(args));
-	}));
+	})));
 }
 //#endregion
 //#region src/gate-foreground-guard.ts
@@ -15760,7 +16486,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),
@@ -15785,12 +16511,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
@@ -15812,7 +16538,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";
@@ -16107,6 +16833,7 @@ 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "picomatch": "^4.0.5",
     "yaml": "^2.9.0",
     "zod": "4.4.3",
-    "@patronage/factory-ci": "1.0.0-alpha.6"
+    "@patronage/factory-ci": "1.0.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "24.13.3",