ccqa 1.3.1 → 1.5.0

package/dist/bin/ccqa.mjs

@@ -11,10 +11,10 @@ import { basename, dirname, isAbsolute, join, normalize, posix, relative, resolv
 import { parse, stringify } from "yaml";
 import { ZodError, z } from "zod";
 import { execFile, spawn, spawnSync } from "node:child_process";
-import { query } from "@anthropic-ai/claude-agent-sdk";
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { promisify } from "node:util";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { createInterface } from "node:readline";
 import { createInterface as createInterface$1 } from "node:readline/promises";
@@ -1287,7 +1287,7 @@ function warnOnceIfNativeBinaryMissing() {
 	if (missing) warn(missingNativeBinaryMessage(missing));
 }
 async function invokeClaudeStreaming(options, onEvent) {
-	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, disableThinking = false, maxTurns, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, relaxAbConstraints = false } = options;
+	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, disableThinking = false, mcpServers, maxTurns, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, relaxAbConstraints = false } = options;
 	const resolvedModel = resolveModel(model);
 	const hasEndpointEnv = Object.keys(resolveEndpointEnv()).length > 0;
 	const mergedEnv = env || hasEndpointEnv ? {
@@ -1309,6 +1309,7 @@ async function invokeClaudeStreaming(options, onEvent) {
 		...resolvedModel ? { model: resolvedModel } : {},
 		...cwd ? { cwd } : {},
 		...mergedEnv ? { env: mergedEnv } : {},
+		...mcpServers ? { mcpServers } : {},
 		...disableBuiltinTools ? { tools: [] } : {},
 		...disableThinking ? { thinking: { type: "disabled" } } : {},
 		hooks: onAbAction || onAbActionFailed ? {
@@ -2284,171 +2285,6 @@ async function checkSpec(target, opts) {
 	};
 }
 //#endregion
-//#region src/drift/affected.ts
-const execFileP = promisify(execFile);
-/**
-* Resolve the base ref to diff against for `ccqa drift --changed`.
-* Precedence: explicit override > GITHUB_BASE_REF > origin/main.
-*/
-function resolveBaseRef(explicit) {
-	if (explicit && explicit.length > 0) return explicit;
-	const ghBase = process.env["GITHUB_BASE_REF"];
-	if (ghBase && ghBase.length > 0) return ghBase.startsWith("origin/") ? ghBase : `origin/${ghBase}`;
-	return "origin/main";
-}
-/**
-* Run `git diff --name-status base...HEAD` from `cwd` and return one entry per
-* changed file. Renames are reported under their NEW path with status
-* "renamed" — the OLD path is dropped because the spec mapping is against the
-* post-rename layout.
-*
-* Paths are re-rooted to be relative to `cwd`, not the git repo root. In a
-* monorepo where `cwd` is a sub-package (e.g. `apps/foo`), git emits paths
-* relative to the repo root, but specs declare relatedPaths relative to
-* their own package. Changes outside `cwd` are kept under their repo-root
-* path and flagged `outsideCwd` — they only scope a spec in when the spec
-* explicitly declares a repo-root-relative glob, so an unrelated PR can
-* never accidentally match the app-relative globs.
-*/
-async function getChangedFiles(base, cwd) {
-	const [{ stdout: rootOut }, { stdout: diffOut }] = await Promise.all([execFileP("git", ["rev-parse", "--show-toplevel"], { cwd }), execFileP("git", [
-		"diff",
-		"--name-status",
-		"-M",
-		`${base}...HEAD`
-	], {
-		cwd,
-		maxBuffer: 32 * 1024 * 1024
-	})]);
-	return rerootChangedFiles(parseGitDiffOutput(diffOut), rootOut.trim(), cwd);
-}
-/**
-* Convert paths in `entries` from git-repo-root relative to `cwd` relative.
-* Entries outside `cwd` keep their repo-root path and are flagged
-* `outsideCwd`. Exported for unit tests.
-*/
-function rerootChangedFiles(entries, repoRoot, cwd) {
-	const prefix = relative(repoRoot, cwd);
-	if (!prefix) return entries;
-	const out = [];
-	for (const e of entries) {
-		const rel = relative(prefix, e.path);
-		if (rel.startsWith("..") || rel === "") out.push({
-			...e,
-			outsideCwd: true
-		});
-		else out.push({
-			...e,
-			path: rel
-		});
-	}
-	return out;
-}
-function parseGitDiffOutput(stdout) {
-	const out = [];
-	for (const line of stdout.split("\n")) {
-		if (!line.trim()) continue;
-		const parts = line.split("	");
-		const code = parts[0];
-		if (!code) continue;
-		if (code.startsWith("R")) {
-			const newPath = parts[2];
-			if (newPath) out.push({
-				path: newPath,
-				status: "renamed"
-			});
-			continue;
-		}
-		if (code.startsWith("C")) {
-			const newPath = parts[2];
-			if (newPath) out.push({
-				path: newPath,
-				status: "added"
-			});
-			continue;
-		}
-		const path = parts[1];
-		if (!path) continue;
-		switch (code[0]) {
-			case "A":
-				out.push({
-					path,
-					status: "added"
-				});
-				break;
-			case "M":
-			case "T":
-				out.push({
-					path,
-					status: "modified"
-				});
-				break;
-			case "D":
-				out.push({
-					path,
-					status: "deleted"
-				});
-				break;
-			default: out.push({
-				path,
-				status: "modified"
-			});
-		}
-	}
-	return out;
-}
-function stripLeadingDotSlash(s) {
-	return s.startsWith("./") ? s.slice(2) : s;
-}
-const REGEX_CACHE = /* @__PURE__ */ new Map();
-/** Compiles `pattern` to a RegExp, memoized so repeated `--changed` matches don't re-build. */
-function compileGlob(pattern) {
-	const cached = REGEX_CACHE.get(pattern);
-	if (cached) return cached;
-	const compiled = globToRegExp(stripLeadingDotSlash(pattern));
-	REGEX_CACHE.set(pattern, compiled);
-	return compiled;
-}
-function globToRegExp(pattern) {
-	let re = "^";
-	let i = 0;
-	while (i < pattern.length) {
-		const ch = pattern[i];
-		if (ch === "?") {
-			re += "[^/]";
-			i++;
-			continue;
-		}
-		if (ch !== "*") {
-			re += /[.+^${}()|[\]\\]/.test(ch) ? "\\" + ch : ch;
-			i++;
-			continue;
-		}
-		if (pattern[i + 1] !== "*") {
-			re += "[^/]*";
-			i++;
-			continue;
-		}
-		const hasLeadingSlash = re.endsWith("/");
-		const hasTrailingSlash = pattern[i + 2] === "/";
-		if (hasLeadingSlash) re = re.slice(0, -1);
-		if (hasLeadingSlash || hasTrailingSlash) re += "(?:/?.*)?";
-		else re += ".*";
-		i += hasTrailingSlash ? 3 : 2;
-	}
-	return new RegExp(re + "$");
-}
-/**
-* Returns true if `changedPath` is covered by any of `relatedPaths`. An empty
-* `relatedPaths` returns false — callers handle the "unscoped spec" case
-* separately (treat the spec as always-affected) before calling this.
-*/
-function isPathAffectedBy(changedPath, relatedPaths) {
-	const stripped = stripLeadingDotSlash(changedPath);
-	for (const pattern of relatedPaths) if (compileGlob(pattern).test(stripped)) return true;
-	return false;
-}
-//#endregion
 //#region src/drift/auth.ts
 /**
 * Probe whether the host has any credential the Anthropic SDK can pick up:
@@ -3153,6 +2989,10 @@ const ReportSpecResultSchema = z.object({
 	assertions: z.array(ReportAssertionSchema).nullable(),
 	analysis: FailureAnalysisSchema.nullable(),
 	analysisSkipped: z.string().nullable(),
+	analysisBase: z.object({
+		ref: z.string(),
+		sha: z.string()
+	}).nullable().optional(),
 	driftIssues: z.array(DraftIssueSchema).nullable(),
 	failureLogExcerpt: z.string().nullable(),
 	diffExcerpt: z.string().nullable(),
@@ -3161,15 +3001,33 @@ const ReportSpecResultSchema = z.object({
 	artifacts: z.array(ReportArtifactSchema).optional(),
 	liveRun: LiveReportRunSchema.nullable()
 });
+/**
+* Which rule produced the analysis baseline: "explicit" (a value was
+* passed), "github-base-ref" (derived from a pull_request event), or
+* "last-green" (per-spec baselines from the hub ledger — `baseSha` is then
+* null and each analyzed row carries its own `analysisBase`). Lets accuracy
+* numbers be stratified by baseline provenance. Single source of truth —
+* `src/run/git-context.ts`'s `BaseSource` type and the hub's PATCH schema
+* both derive from this.
+*/
+const BaseSourceSchema = z.enum([
+	"explicit",
+	"github-base-ref",
+	"last-green"
+]);
+/** The report envelope's git block; also referenced by the hub's PATCH reportMeta schema. */
+const GitEnvelopeSchema = z.object({
+	head: z.string().nullable(),
+	base: z.string().nullable(),
+	baseSha: z.string().nullable().optional(),
+	baseSource: BaseSourceSchema.nullable().optional()
+});
 const RunReportDataSchema = z.object({
 	schemaVersion: z.literal(1),
 	kind: z.enum(["run", "drift"]).default("run"),
 	createdAt: z.string(),
 	runId: z.string().nullable(),
-	git: z.object({
-		head: z.string().nullable(),
-		base: z.string().nullable()
-	}),
+	git: GitEnvelopeSchema,
 	model: z.string().nullable(),
 	language: z.string().nullable().default(null),
 	promptVersion: z.string(),
@@ -3294,13 +3152,54 @@ function hashTriageUserPrompt(text) {
 }
 //#endregion
 //#region src/report/prompt.ts
+/**
+* Fully-qualified name of the on-demand file-diff tool, as the model calls
+* it. Lives here (not analyze.ts) because the prompt text below references
+* it — one source of truth. The name is the SDK's `mcp__<server>__<tool>`
+* composition of the server ("diff") and tool ("changed_file_diff") that
+* analyze.ts registers; changing either side must keep the two in sync.
+*/
+const CHANGED_FILE_DIFF_TOOL = "mcp__diff__changed_file_diff";
 function buildFailureAnalysisPrompt(input) {
-	const { script, specYaml, failureLog, liveTranscriptExcerpt, diffPatch, changedFiles, baseRef, driftIssues, outputLanguage = "auto", triageUserPrompt, customPrompt } = input;
+	const { script, specYaml, failureLog, liveTranscriptExcerpt, diffPatch, changedFiles, baseRef, baseSource = null, range = null, driftIssues, outputLanguage = "auto", triageUserPrompt, customPrompt } = input;
+	const lastGreen = baseSource === "last-green";
 	const triageUserPromptBlock = buildTriageUserPromptBlock(triageUserPrompt);
 	const customPromptBlock = buildCustomPromptBlock(customPrompt);
-	return `You are analyzing a failing E2E regression test right after a source change landed. Your job is a root-cause CALL, not a fix: decide which of three categories explains the failure, using the source diff as your primary context.
+	const languageBlock = outputLanguageBlock(outputLanguage, "`reasoning`, `detail`", "label names (TEST_DRIFT, etc.)");
+	const executionBlock = buildExecutionEvidenceBlock(script, failureLog, liveTranscriptExcerpt);
+	const baseLabel = lastGreen ? `this spec's last passing commit${baseRef && baseRef !== "last-green" ? ` (${baseRef})` : ""}` : baseRef ?? "base";
+	const rangeNote = range ? ` — spans ${range.commitCount} commit${range.commitCount === 1 ? "" : "s"} over ${range.days} day${range.days === 1 ? "" : "s"}` : "";
+	let diffBlock;
+	if (diffPatch === null) diffBlock = `## Source changes
+
+No diff context is available (the base ref could not be resolved, or there are no changes). Classify from the failure log, the spec, and what you can read in the repository — and be correspondingly more conservative: prefer UNKNOWN over a confident SPEC_CHANGE/PRODUCT_BUG call without diff evidence.
+`;
+	else if (diffPatch.length === 0) diffBlock = `## Source changes since ${baseLabel}${rangeNote}
+
+### Changed files (name-status)
+${changedFiles && changedFiles.length > 0 ? changedFiles : "(no changes in range)"}
+
+No changed file matches this spec's relatedPaths, so no hunks are inlined. "No related change" is a real signal — but before concluding, scan the name-status list for anything that could plausibly reach this spec and fetch its hunk with \`${CHANGED_FILE_DIFF_TOOL}\`.
+`;
+	else diffBlock = `## Source changes since ${baseLabel}${rangeNote} (git diff, scoped to this spec's relatedPaths, may be truncated)
 
-${outputLanguageBlock(outputLanguage, "`reasoning`, `detail`", "label names (TEST_DRIFT, etc.)")}## The three categories
+### Changed files (name-status)
+${changedFiles ?? "(unavailable)"}
+
+### Patch
+\`\`\`diff
+${diffPatch}
+\`\`\`
+`;
+	const driftBlock = driftIssues && driftIssues.length > 0 ? `## Spec↔code drift audit findings
+
+A separate read-only audit compared the spec against the current source. Treat these as hints, not verdicts:
+
+${driftIssues.map((i) => `- [${i.severity}] (${DRAFT_CATEGORY_LABEL[i.category]}${i.stepId ? `, step ${i.stepId}` : ""}) ${i.message}${i.detail ? ` — ${i.detail}` : ""}`).join("\n")}
+` : "";
+	return `You are analyzing a failing E2E regression test against the source changes since a known-good baseline. Your job is a root-cause CALL, not a fix: decide which of three categories explains the failure, using the source diff as your primary context.
+
+${languageBlock}## The three categories
 
 The question that separates them: **is the behavior the spec describes still what the product intends?**
 
@@ -3317,14 +3216,19 @@ You can call \`Grep\`, \`Glob\`, and \`Read\` against the current repository (po
 - read the changed files in full when the truncated patch is not enough,
 - check whether the element/flow the spec describes still exists in the source.
 
+You can also call \`${CHANGED_FILE_DIFF_TOOL}\` with a file path to fetch that file's diff hunk for this run's base...HEAD range. The inline patch below is scoped to this spec's relatedPaths — files OUTSIDE that scope still appear in "Changed files (name-status)" but their hunks are not inlined. Before blaming (or ruling out) such a file, fetch its diff with this tool; Read only shows you its post-change state, not what changed.
+
 You have **up to 12 tool turns**. Do NOT write, edit, run shell commands, or hit the network.
 
 ## Decision guidance
 
+${lastGreen ? `The baseline is the commit where THIS spec last passed, so the range strictly covers the window in which it broke: the cause is either inside these changes or outside the code entirely (flaky timing, environment, an external service, test data). The range may mix several unrelated merges — most of the diff is noise; what matters is the specific change you can tie to the failing step.` : `The baseline is a fixed ref (typically the PR base): the spec is NOT guaranteed to have passed there, so the range is not guaranteed to contain the cause.`}
+
 - Diff touches only attributes/identifiers the test selects on (labels, testids, class names, timing) while the user-visible flow is intact → TEST_DRIFT.
 - Diff intentionally removes/reworks the UI or flow that a spec step verifies (component deleted, page restructured, copy redefined, feature flag flipped) → SPEC_CHANGE.
 - Diff UNINTENTIONALLY breaks behavior the spec still intends — e.g. a refactor that drops a side effect, an inverted condition, a regression hiding inside a cleanup commit — → PRODUCT_BUG, citing the diff hunk as evidence. A product bug is often introduced BY the diff; what separates it from SPEC_CHANGE is intent: does the change read as a deliberate redesign of what the spec verifies, or as collateral damage?
-- Diff is unrelated to the failing step (or there is no relevant diff) and the test was passing before → lean PRODUCT_BUG; first rule out timing/data flakiness and infrastructure errors (daemon not running, network down, missing credentials) — those read as UNKNOWN with low confidence, not PRODUCT_BUG.
+${lastGreen ? `- No change in the range explains the failing step (after checking the inline patch, the name-status list, and any hunks you fetched) → the cause is outside the code: answer UNKNOWN with low confidence and name the suspected external cause (flaky timing, environment, external service, test data). Do NOT default to PRODUCT_BUG here — under this baseline a product regression must be tied to an in-range change.` : `- Diff is unrelated to the failing step (or there is no relevant diff) and the test was passing before → lean PRODUCT_BUG; first rule out timing/data flakiness and infrastructure errors (daemon not running, network down, missing credentials) — those read as UNKNOWN with low confidence, not PRODUCT_BUG.`}${range ? `
+- This range spans ${range.commitCount} commit${range.commitCount === 1 ? "" : "s"} over ${range.days} day${range.days === 1 ? "" : "s"}. The wider the range, the more unrelated changes are mixed in: SPEC_CHANGE and TEST_DRIFT still require citing the specific hunk — do not infer intent from the bulk of a large diff, and lower confidence when the evidence is spread thin.` : ""}
 - The drift audit findings (when present) flag spec↔code mismatches; an ERROR there usually supports TEST_DRIFT or SPEC_CHANGE over PRODUCT_BUG.
 
 ## Sub-diagnosis vocabulary
@@ -3364,32 +3268,15 @@ Your **final** assistant message must start with \`{\` and end with \`}\` — a
 - 0.4-0.7: plausible but another category could explain it
 - < 0.4: answer UNKNOWN instead of guessing
 
-Evidence rules: TEST_DRIFT and SPEC_CHANGE require at least one concrete \`file\` reference (diff hunk or file:line you actually read). PRODUCT_BUG should explain why the diff does NOT account for the failure.
+Evidence rules: TEST_DRIFT and SPEC_CHANGE require at least one concrete \`file\` reference (diff hunk or file:line you actually read). PRODUCT_BUG should cite the in-range change that unintentionally broke the behavior when one exists; ${lastGreen ? "under this last-green baseline, if no in-range change explains the failure, that is UNKNOWN (external cause), not PRODUCT_BUG" : "when no such change exists, explain why the diff does NOT account for the failure"}.
 
 ## Test Spec (spec.yaml)
 ${specYaml}
 
-${buildExecutionEvidenceBlock(script, failureLog, liveTranscriptExcerpt)}
+${executionBlock}
 
-${diffPatch ? `## Source changes since ${baseRef ?? "base"} (git diff, may be truncated)
-
-### Changed files (name-status)
-${changedFiles ?? "(unavailable)"}
-
-### Patch
-\`\`\`diff
-${diffPatch}
-\`\`\`
-` : `## Source changes
-
-No diff context is available (the base ref could not be resolved, or there are no changes). Classify from the failure log, the spec, and what you can read in the repository — and be correspondingly more conservative: prefer UNKNOWN over a confident SPEC_CHANGE/PRODUCT_BUG call without diff evidence.
-`}
-${driftIssues && driftIssues.length > 0 ? `## Spec↔code drift audit findings
-
-A separate read-only audit compared the spec against the current source. Treat these as hints, not verdicts:
-
-${driftIssues.map((i) => `- [${i.severity}] (${DRAFT_CATEGORY_LABEL[i.category]}${i.stepId ? `, step ${i.stepId}` : ""}) ${i.message}${i.detail ? ` — ${i.detail}` : ""}`).join("\n")}
-` : ""}`;
+${diffBlock}
+${driftBlock}`;
 }
 /**
 * Render the execution-evidence section the model needs to classify the
@@ -3421,19 +3308,45 @@ ${liveTranscriptExcerpt}`);
 //#endregion
 //#region src/report/analyze.ts
 /**
+* In-process MCP server exposing one tool: the diff hunk of a named changed
+* file. The inline patch in the prompt is only the relatedPaths-scoped seed;
+* this is the pull side — the model fetches hunks for files outside that
+* scope (or truncated inside it) only when it decides they matter, so the
+* full diff never has to ride in the prompt. Read-only over data already
+* captured in memory: no shell, no git access granted. The server/tool
+* names must compose to CHANGED_FILE_DIFF_TOOL (prompt.ts), which is how
+* the prompt tells the model to call it.
+*/
+function buildDiffMcpServer(getFileDiff) {
+	return createSdkMcpServer({
+		name: "diff",
+		version: "1.0.0",
+		tools: [tool("changed_file_diff", "Return the unified diff (base...HEAD) of one changed file from this run's diff range. Works for ANY file listed in 'Changed files (name-status)', including files outside the spec's relatedPaths scope whose hunks are not in the inline patch.", { path: z.string().describe("File path exactly as it appears in the name-status list") }, async ({ path }) => {
+			const hunk = getFileDiff(path);
+			if (hunk) info(`  diff tool: ${path}`);
+			return { content: [{
+				type: "text",
+				text: hunk ?? `No diff found for "${path}" in this run's diff range. Check the exact path in the name-status list (paths are relative to the working directory).`
+			}] };
+		})]
+	});
+}
+/**
 * Classify one failing spec into TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG /
 * UNKNOWN. Same resilience contract as diagnose(): read-only tools, JSON-only
 * final message, and any parse failure degrades to UNKNOWN with confidence 0
 * rather than throwing — the report must always render.
 */
-async function analyzeFailure(input, options = {}) {
+async function analyzeFailure(input, options) {
 	const { result: raw, isError } = await invokeClaudeStreaming({
 		prompt: buildFailureAnalysisPrompt(input),
 		allowedTools: [
 			"Read",
 			"Grep",
-			"Glob"
+			"Glob",
+			CHANGED_FILE_DIFF_TOOL
 		],
+		mcpServers: { diff: buildDiffMcpServer(options.getFileDiff) },
 		silenceBashLog: true,
 		maxTurns: 12,
 		...options.model ? { model: options.model } : {},
@@ -3504,15 +3417,194 @@ function normaliseFailureAnalysis(parsed) {
 		} : { detail });
 		if (evidence.length >= 3) break;
 	}
-	return {
-		label,
-		confidence,
-		subDiagnosis,
-		headline,
-		recommendation,
-		evidence,
-		reasoning
-	};
+	return {
+		label,
+		confidence,
+		subDiagnosis,
+		headline,
+		recommendation,
+		evidence,
+		reasoning
+	};
+}
+//#endregion
+//#region src/drift/affected.ts
+const execFileP = promisify(execFile);
+/**
+* GITHUB_BASE_REF holds a bare branch name (e.g. "main"); the local checkout
+* only has it as a remote-tracking ref, so prefix `origin/` unless already
+* qualified. Shared by `ccqa drift`'s resolveBaseRef and `ccqa run`'s
+* resolveAnalysisBase so the rule can't drift between them.
+*/
+function normalizeGithubBaseRef(ref) {
+	return ref.startsWith("origin/") ? ref : `origin/${ref}`;
+}
+/**
+* Resolve the base ref to diff against for `ccqa drift --changed`.
+* Precedence: explicit override > GITHUB_BASE_REF > origin/main.
+*
+* Note: this is the `ccqa drift` rule. `ccqa run` resolves its baseline via
+* `src/run/git-context.ts` instead, which has no origin/main fallback — see
+* the rationale there.
+*/
+function resolveBaseRef(explicit) {
+	if (explicit && explicit.length > 0) return explicit;
+	const ghBase = process.env["GITHUB_BASE_REF"];
+	if (ghBase && ghBase.length > 0) return normalizeGithubBaseRef(ghBase);
+	return "origin/main";
+}
+/**
+* Run `git diff --name-status base...HEAD` from `cwd` and return one entry per
+* changed file. Renames are reported under their NEW path with status
+* "renamed" — the OLD path is dropped because the spec mapping is against the
+* post-rename layout.
+*
+* Paths are re-rooted to be relative to `cwd`, not the git repo root. In a
+* monorepo where `cwd` is a sub-package (e.g. `apps/foo`), git emits paths
+* relative to the repo root, but specs declare relatedPaths relative to
+* their own package. Changes outside `cwd` are kept under their repo-root
+* path and flagged `outsideCwd` — they only scope a spec in when the spec
+* explicitly declares a repo-root-relative glob, so an unrelated PR can
+* never accidentally match the app-relative globs.
+*/
+async function getChangedFiles(base, cwd) {
+	const [{ stdout: rootOut }, { stdout: diffOut }] = await Promise.all([execFileP("git", ["rev-parse", "--show-toplevel"], { cwd }), execFileP("git", [
+		"diff",
+		"--name-status",
+		"-M",
+		`${base}...HEAD`
+	], {
+		cwd,
+		maxBuffer: 32 * 1024 * 1024
+	})]);
+	return rerootChangedFiles(parseGitDiffOutput(diffOut), rootOut.trim(), cwd);
+}
+/**
+* Convert paths in `entries` from git-repo-root relative to `cwd` relative.
+* Entries outside `cwd` keep their repo-root path and are flagged
+* `outsideCwd`. Exported for unit tests.
+*/
+function rerootChangedFiles(entries, repoRoot, cwd) {
+	const prefix = relative(repoRoot, cwd);
+	if (!prefix) return entries;
+	const out = [];
+	for (const e of entries) {
+		const rel = relative(prefix, e.path);
+		if (rel.startsWith("..") || rel === "") out.push({
+			...e,
+			outsideCwd: true
+		});
+		else out.push({
+			...e,
+			path: rel
+		});
+	}
+	return out;
+}
+function parseGitDiffOutput(stdout) {
+	const out = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		const parts = line.split("	");
+		const code = parts[0];
+		if (!code) continue;
+		if (code.startsWith("R")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "renamed"
+			});
+			continue;
+		}
+		if (code.startsWith("C")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "added"
+			});
+			continue;
+		}
+		const path = parts[1];
+		if (!path) continue;
+		switch (code[0]) {
+			case "A":
+				out.push({
+					path,
+					status: "added"
+				});
+				break;
+			case "M":
+			case "T":
+				out.push({
+					path,
+					status: "modified"
+				});
+				break;
+			case "D":
+				out.push({
+					path,
+					status: "deleted"
+				});
+				break;
+			default: out.push({
+				path,
+				status: "modified"
+			});
+		}
+	}
+	return out;
+}
+/** Normalize a leading `./` away so diff paths and relatedPaths globs compare. */
+function stripLeadingDotSlash(s) {
+	return s.startsWith("./") ? s.slice(2) : s;
+}
+const REGEX_CACHE = /* @__PURE__ */ new Map();
+/** Compiles `pattern` to a RegExp, memoized so repeated `--changed` matches don't re-build. */
+function compileGlob(pattern) {
+	const cached = REGEX_CACHE.get(pattern);
+	if (cached) return cached;
+	const compiled = globToRegExp(stripLeadingDotSlash(pattern));
+	REGEX_CACHE.set(pattern, compiled);
+	return compiled;
+}
+function globToRegExp(pattern) {
+	let re = "^";
+	let i = 0;
+	while (i < pattern.length) {
+		const ch = pattern[i];
+		if (ch === "?") {
+			re += "[^/]";
+			i++;
+			continue;
+		}
+		if (ch !== "*") {
+			re += /[.+^${}()|[\]\\]/.test(ch) ? "\\" + ch : ch;
+			i++;
+			continue;
+		}
+		if (pattern[i + 1] !== "*") {
+			re += "[^/]*";
+			i++;
+			continue;
+		}
+		const hasLeadingSlash = re.endsWith("/");
+		const hasTrailingSlash = pattern[i + 2] === "/";
+		if (hasLeadingSlash) re = re.slice(0, -1);
+		if (hasLeadingSlash || hasTrailingSlash) re += "(?:/?.*)?";
+		else re += ".*";
+		i += hasTrailingSlash ? 3 : 2;
+	}
+	return new RegExp(re + "$");
+}
+/**
+* Returns true if `changedPath` is covered by any of `relatedPaths`. An empty
+* `relatedPaths` returns false — callers handle the "unscoped spec" case
+* separately (treat the spec as always-affected) before calling this.
+*/
+function isPathAffectedBy(changedPath, relatedPaths) {
+	const stripped = stripLeadingDotSlash(changedPath);
+	for (const pattern of relatedPaths) if (compileGlob(pattern).test(stripped)) return true;
+	return false;
 }
 /**
 * Capture the PR diff used as context for failure analysis. `--relative`
@@ -3598,17 +3690,20 @@ function splitPatchByFile(patch) {
 /**
 * Scope a full patch down to the files a spec depends on, then truncate so
 * the analysis prompt stays bounded. `relatedPaths` null/empty means the
-* spec is unscoped — keep the whole patch (still truncated). Callers scoping
-* the same patch for many specs can pass pre-split sections instead.
+* spec is unscoped — keep the whole patch (still truncated). When
+* relatedPaths are declared but nothing in the diff matches, the result is
+* the empty string: "no related change" is itself a signal the prompt
+* renders explicitly, and the model can inspect any unmatched file's hunk
+* via the on-demand diff tool — inlining the full unrelated diff (the old
+* fallback) just burned the prompt budget, especially under wide last-green
+* baselines. Callers scoping the same patch for many specs can pass
+* pre-split sections instead.
 */
 function scopePatchForSpec(patch, relatedPaths, caps = {}) {
 	const perFile = caps.perFile ?? 8192;
 	const total = caps.total ?? 49152;
 	let sections = typeof patch === "string" ? splitPatchByFile(patch) : patch;
-	if (relatedPaths && relatedPaths.length > 0) {
-		const scoped = sections.filter((s) => isPathAffectedBy(s.path, relatedPaths));
-		if (scoped.length > 0) sections = scoped;
-	}
+	if (relatedPaths && relatedPaths.length > 0) sections = sections.filter((s) => isPathAffectedBy(s.path, relatedPaths));
 	const parts = [];
 	let used = 0;
 	let droppedFiles = 0;
@@ -3627,6 +3722,286 @@ function scopePatchForSpec(patch, relatedPaths, caps = {}) {
 	return parts.join("\n");
 }
 //#endregion
+//#region src/run/diff-provider.ts
+/**
+* Cap on one on-demand file-diff response. Larger than the inline seed's
+* per-file cap (the model explicitly asked for this file), but still bounded
+* so a generated-file hunk can't blow the context — the truncation note
+* points at Read for the file's full current state.
+*/
+const FILE_DIFF_RESPONSE_CAP = 16 * 1024;
+/** Find `path`'s section in a split patch and cap it. Exported for tests. */
+function lookupFileDiff(sections, path) {
+	const normalized = stripLeadingDotSlash(path);
+	const section = sections.find((s) => s.path === normalized);
+	if (!section) return null;
+	if (section.body.length <= 16384) return section.body;
+	return `${section.body.slice(0, FILE_DIFF_RESPONSE_CAP)}\n[truncated: ${section.body.length - FILE_DIFF_RESPONSE_CAP} more chars — Read the file for its full current state]`;
+}
+/**
+* Best-effort width of the base..HEAD range. Two-dot rev-list matches what
+* the three-dot diff shows: commits on the HEAD side since the merge base.
+*/
+async function measureRange(sha, cwd) {
+	try {
+		const [{ stdout: count }, { stdout: baseTime }, { stdout: headTime }] = await Promise.all([
+			execFileP("git", [
+				"rev-list",
+				"--count",
+				`${sha}..HEAD`
+			], { cwd }),
+			execFileP("git", [
+				"log",
+				"-1",
+				"--format=%ct",
+				sha
+			], { cwd }),
+			execFileP("git", [
+				"log",
+				"-1",
+				"--format=%ct",
+				"HEAD"
+			], { cwd })
+		]);
+		const seconds = Number(headTime.trim()) - Number(baseTime.trim());
+		return {
+			commitCount: Number(count.trim()),
+			days: Math.max(0, Math.round(seconds / 86400))
+		};
+	} catch {
+		return null;
+	}
+}
+function createDiffProvider(args) {
+	const { resolveBase, cwd } = args;
+	const captures = /* @__PURE__ */ new Map();
+	let relatedPathsIndex = null;
+	function capture(sha) {
+		const cached = captures.get(sha);
+		if (cached) return cached;
+		const pending = (async () => {
+			const [result, range] = await Promise.all([capturePrDiff(sha, cwd), measureRange(sha, cwd)]);
+			if (!result.ok) return {
+				sections: null,
+				nameStatus: null,
+				error: result.error,
+				range
+			};
+			const { patch, nameStatus } = result.diff;
+			return {
+				sections: patch.length > 0 ? splitPatchByFile(patch) : [],
+				nameStatus,
+				error: null,
+				range
+			};
+		})();
+		captures.set(sha, pending);
+		return pending;
+	}
+	/** relatedPaths for every spec, read once from the feature tree. */
+	function relatedPaths() {
+		relatedPathsIndex ??= listFeatureTree(cwd).then((tree) => new Map(tree.flatMap((f) => f.specs.map((s) => [specKey({
+			featureName: f.featureName,
+			specName: s.specName
+		}), s.relatedPaths ?? null]))));
+		return relatedPathsIndex;
+	}
+	return { async forSpec(spec) {
+		const resolved = await resolveBase(spec);
+		if (!resolved.ok) return resolved;
+		const [captured, index] = await Promise.all([capture(resolved.base.sha), relatedPaths()]);
+		const scope = index.get(specKey(spec)) ?? null;
+		const sections = captured.sections;
+		return {
+			ok: true,
+			base: resolved.base,
+			patch: sections ? scopePatchForSpec(sections, scope) : null,
+			nameStatus: captured.nameStatus,
+			error: captured.error,
+			range: captured.range,
+			fileDiff: (path) => sections ? lookupFileDiff(sections, path) : null
+		};
+	} };
+}
+//#endregion
+//#region src/run/errors.ts
+/**
+* Usage error (bad flag combination, broken profile, failed `git diff`, …)
+* thrown by the `run` pipeline and the helpers it calls, e.g.
+* `collectChangedSpecs`. `executeRun` never calls `process.exit`, so each
+* host maps this itself: the CLI action catches it and exits with
+* `exitCode`; the hub runner records it as a run-level error.
+*/
+var RunUsageError = class extends Error {
+	exitCode = 2;
+	constructor(message) {
+		super(message);
+		this.name = "RunUsageError";
+	}
+};
+//#endregion
+//#region src/run/git-context.ts
+/** The `--failure-analysis` value that selects per-spec hub-ledger baselines. */
+const LAST_GREEN = "last-green";
+/** Resolve `ref` to a full commit sha, or null when it does not exist locally. */
+async function resolveCommitSha(ref, cwd) {
+	try {
+		const { stdout } = await execFileP("git", [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`${ref}^{commit}`
+		], { cwd });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolve a `[base]` flag value (from `--failure-analysis [base]` or
+* `--changed [base]`) to a verified baseline, failing fast — before any spec
+* runs — when it cannot be resolved.
+*
+*   - a string value is an explicit ref;
+*   - bare `true` derives the ref from GITHUB_BASE_REF (pull_request events)
+*     and errors outside that context;
+*   - the ref must resolve to a local commit, so a shallow CI checkout that
+*     never fetched the base surfaces here as an actionable error instead of
+*     an empty diff downstream.
+*
+* `flagName` only shapes the error messages.
+*/
+async function resolveAnalysisBase(flagValue, flagName, cwd) {
+	let ref;
+	let source;
+	if (flagValue === "last-green") throw new RunUsageError(`${flagName}=${LAST_GREEN} is not supported — last-green baselines are per-spec and only apply to --failure-analysis`);
+	if (typeof flagValue === "string") {
+		ref = flagValue;
+		source = "explicit";
+	} else {
+		const ghBase = process.env["GITHUB_BASE_REF"];
+		if (!ghBase) throw new RunUsageError(`${flagName} without a base needs GITHUB_BASE_REF (a pull_request workflow); outside that context pass the base explicitly, e.g. ${flagName}=origin/main`);
+		ref = normalizeGithubBaseRef(ghBase);
+		source = "github-base-ref";
+	}
+	const sha = await resolveCommitSha(ref, cwd);
+	if (sha === null) throw new RunUsageError(`${flagName}: '${ref}' is not a resolvable git ref in this checkout. If this is CI, the base may not be fetched (try fetch-depth: 0). If '${ref}' was meant as a spec target, put spec targets before flags or use ${flagName}=<ref>.`);
+	return {
+		ref,
+		sha,
+		source
+	};
+}
+//#endregion
+//#region src/cli/git-branch.ts
+/** Best-effort current branch: CI env vars first, then git, else null. */
+async function detectBranch(cwd) {
+	const fromEnv = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+	if (fromEnv) return fromEnv;
+	try {
+		const { stdout } = await execFileP("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], { cwd });
+		const branch = stdout.trim();
+		return branch && branch !== "HEAD" ? branch : null;
+	} catch {
+		return null;
+	}
+}
+/** Best-effort current commit SHA, or null (e.g. not a git repo). */
+async function getGitHead(cwd) {
+	try {
+		const { stdout } = await execFileP("git", ["rev-parse", "HEAD"], { cwd });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/run/last-green.ts
+/**
+* The repo's default branch name (e.g. "main"), from origin's HEAD ref.
+* Falls back to "main" when origin isn't configured — the lookup then just
+* queries a possibly-empty ledger bucket, which is harmless.
+*/
+async function detectDefaultBranch(cwd) {
+	try {
+		const { stdout } = await execFileP("git", [
+			"symbolic-ref",
+			"--short",
+			"refs/remotes/origin/HEAD"
+		], { cwd });
+		const ref = stdout.trim();
+		return ref.startsWith("origin/") ? ref.slice(7) : ref || "main";
+	} catch {
+		return "main";
+	}
+}
+/**
+* Fetch the last-green ledger for this run — one hub round trip, logged as
+* the run's analysis-base meta line. Fails fast (RunUsageError) when the hub
+* can't serve it: `--failure-analysis=last-green` explicitly opted into
+* hub-backed baselines, so a broken hub connection is a usage error, never a
+* silent no-baseline run.
+*/
+async function fetchLastGreenLedger(hubCtx, profile, cwd) {
+	const [fallbackBranch, detectedBranch] = await Promise.all([detectDefaultBranch(cwd), detectBranch(cwd)]);
+	const branch = detectedBranch ?? fallbackBranch;
+	let entries;
+	try {
+		entries = await hubCtx.hub.getLastGreen(hubCtx.project, {
+			branch,
+			fallbackBranch,
+			...profile ? { profile } : {}
+		});
+	} catch (err) {
+		throw new RunUsageError(`--failure-analysis=${LAST_GREEN}: could not fetch the last-green ledger from the hub: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const n = Object.keys(entries).length;
+	const scope = branch === fallbackBranch ? branch : `${branch} → ${fallbackBranch}`;
+	meta("analysis-base", `${LAST_GREEN} (${n} spec baseline${n === 1 ? "" : "s"}, branch ${scope})`);
+	return entries;
+}
+/**
+* Per-spec baseline resolver for `--failure-analysis=last-green`. A spec
+* missing from the ledger (never green on a pushed run yet) or whose
+* baseline commit isn't in this checkout resolves to a skip — the run
+* continues; only that spec's classification is withheld, with the reason
+* recorded in its report row. Sha existence checks are memoized per commit.
+*/
+function createLastGreenResolver(entries, cwd) {
+	const shaChecks = /* @__PURE__ */ new Map();
+	const checkSha = (sha) => {
+		const cached = shaChecks.get(sha);
+		if (cached) return cached;
+		const pending = resolveCommitSha(sha, cwd);
+		shaChecks.set(sha, pending);
+		return pending;
+	};
+	return async (spec) => {
+		const entry = entries[specKey(spec)];
+		if (!entry) return {
+			ok: false,
+			skip: "no last-green baseline for this spec on the hub yet (recorded once the spec passes on a pushed run)"
+		};
+		const sha = await checkSha(entry.gitHead);
+		if (!sha) return {
+			ok: false,
+			skip: `last-green commit ${entry.gitHead.slice(0, 12)} is not in this checkout (shallow clone? try fetch-depth: 0)`
+		};
+		return {
+			ok: true,
+			base: {
+				ref: LAST_GREEN,
+				sha,
+				source: "last-green"
+			}
+		};
+	};
+}
+//#endregion
 //#region src/report/github-format.ts
 /**
 * Build GitHub Actions `::error::` annotation lines for every failed spec in
@@ -4584,33 +4959,6 @@ function resolvePromptLocalPath(name, cwd) {
 	return join(cwd ?? process.cwd(), PROMPT_LOCAL_PATHS[name]);
 }
 //#endregion
-//#region src/cli/git-branch.ts
-/** Best-effort current branch: CI env vars first, then git, else null. */
-async function detectBranch(cwd) {
-	const fromEnv = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
-	if (fromEnv) return fromEnv;
-	try {
-		const { stdout } = await execFileP("git", [
-			"rev-parse",
-			"--abbrev-ref",
-			"HEAD"
-		], { cwd });
-		const branch = stdout.trim();
-		return branch && branch !== "HEAD" ? branch : null;
-	} catch {
-		return null;
-	}
-}
-/** Best-effort current commit SHA, or null (e.g. not a git repo). */
-async function getGitHead(cwd) {
-	try {
-		const { stdout } = await execFileP("git", ["rev-parse", "HEAD"], { cwd });
-		return stdout.trim() || null;
-	} catch {
-		return null;
-	}
-}
-//#endregion
 //#region src/cli/hub.ts
 /**
 * `ccqa hub` — the client side of the ccqa hub (a results/secret control
@@ -5540,22 +5888,14 @@ async function runLiveSpecs(specs, opts) {
 	const userPromptBundle = await loadPromptBundleFromHub(opts.hubContext ?? null, "live");
 	if (userPromptBundle !== null) meta("prompt", userPromptBundle.loaded.join(" + "));
 	const userPromptSuffix = userPromptBundle?.text ?? null;
-	const failureAnalysisEnabled = opts.failureAnalysis !== false;
+	const diffProvider = opts.diffProvider ?? null;
+	const failureAnalysisEnabled = diffProvider != null;
 	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
 	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "disabled"
 	};
 	if (failureAnalysisEnabled && !auth.ok) info(`failure analysis skipped (${auth.reason})`);
-	const baseRef = resolveBaseRef(opts.base);
-	let diff = {
-		ok: false,
-		error: "diff not captured"
-	};
-	if (failureAnalysisEnabled && auth.ok) {
-		diff = await capturePrDiff(baseRef, cwd);
-		if (!diff.ok) info(`failure analysis: source diff unavailable (${diff.error}) — analyzing without diff context`);
-	}
 	const reportDir = opts.reportDir ?? ".";
 	const concurrency = Math.max(1, opts.concurrency ?? 1);
 	const built = await runPool(specs, concurrency, (spec, i) => {
@@ -5577,10 +5917,8 @@ async function runLiveSpecs(specs, opts) {
 			};
 			const row = await buildLiveReportRow(outcome, {
 				auth,
-				diff,
-				baseRef,
+				diffProvider,
 				reportDir,
-				failureAnalysisEnabled,
 				driftAuditEnabled
 			}, opts, cwd);
 			await opts.report?.upsert(row);
@@ -5616,26 +5954,29 @@ async function buildLiveReportRow(r, ctx, opts, cwd) {
 		reportDir: ctx.reportDir
 	});
 	const driftForSpec = ctx.driftAuditEnabled && r.result.status === "failed" ? await runDriftAuditOne(r, opts, cwd) : null;
-	const analysis = ctx.failureAnalysisEnabled && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diff, ctx.baseRef, driftForSpec, ctx.auth, opts, cwd) : void 0;
+	const analysis = ctx.diffProvider && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diffProvider, driftForSpec, ctx.auth, opts, cwd) : void 0;
 	return {
 		...base,
 		driftIssues: driftForSpec,
-		...analysisFieldsFor(analysis, r.result.status, ctx.failureAnalysisEnabled)
+		...analysisFieldsFor(analysis, r.result.status)
 	};
 }
 /**
 * Merge analysis-related fields into the report row. The unattempted-failure
 * branch exists so the report distinguishes "we tried and gave up" (auth /
-* spec.yaml missing) from "we deliberately did not run the classifier".
+* spec.yaml missing) from "we deliberately did not run the classifier" —
+* `a` is undefined for a failed spec exactly when analysis was not requested
+* (no diffProvider), so no separate flag is needed.
 */
-function analysisFieldsFor(a, status, failureAnalysisEnabled) {
+function analysisFieldsFor(a, status) {
 	if (a) return {
 		analysis: a.analysis,
 		analysisSkipped: a.analysisSkipped,
 		failureLogExcerpt: a.failureLogExcerpt,
-		diffExcerpt: a.diffExcerpt
+		diffExcerpt: a.diffExcerpt,
+		...a.analysisBase ? { analysisBase: a.analysisBase } : {}
 	};
-	if (!failureAnalysisEnabled && status === "failed") return { analysisSkipped: "skipped by --no-failure-analysis" };
+	if (status === "failed") return { analysisSkipped: "skipped: --failure-analysis not enabled" };
 	return {};
 }
 /**
@@ -5825,11 +6166,13 @@ function logBatchCost(runs) {
 /**
 * Classify one failed live run via `analyzeFailure` — same prompt as the
 * deterministic path (Issue #47), fed the live transcript instead of the
-* vitest log. `auth`, `diff`, and `baseRef` are hoisted once by the caller and
-* shared across specs. Auth-unavailable / no-failed-step degrade to
-* `analysisSkipped` rather than throwing.
+* vitest log. `auth` is hoisted once by the caller; the diff comes from the
+* shared provider, already scoped to this spec's relatedPaths and truncated
+* (the live path used to feed the whole unscoped patch — in a monorepo that
+* ballooned the prompt with unrelated changes). Auth-unavailable /
+* no-failed-step degrade to `analysisSkipped` rather than throwing.
 */
-async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts, cwd) {
+async function analyzeOneLiveFailure(r, diffProvider, driftForSpec, auth, opts, cwd) {
 	const key = `${r.featureName}/${r.specName}`;
 	if (!auth.ok) return {
 		analysis: null,
@@ -5845,19 +6188,33 @@ async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts,
 		failureLogExcerpt: null,
 		diffExcerpt: null
 	};
+	const specDiff = await diffProvider.forSpec({
+		featureName: r.featureName,
+		specName: r.specName
+	});
+	if (!specDiff.ok) return {
+		analysis: null,
+		analysisSkipped: specDiff.skip,
+		failureLogExcerpt: excerpt,
+		diffExcerpt: null
+	};
+	if (specDiff.error) info(`failure analysis: source diff unavailable (${specDiff.error}) — analyzing without diff context`);
 	const outcome = await analyzeFailure({
 		liveTranscriptExcerpt: excerpt,
 		specYaml: r.specYaml,
-		diffPatch: diff.ok ? diff.diff.patch : null,
-		changedFiles: diff.ok ? diff.diff.nameStatus : null,
-		baseRef: diff.ok ? baseRef : null,
+		diffPatch: specDiff.patch,
+		changedFiles: specDiff.nameStatus,
+		baseRef: specDiff.base.ref,
+		baseSource: specDiff.base.source,
+		range: specDiff.range,
 		driftIssues: driftForSpec,
 		...opts.language ? { outputLanguage: opts.language } : {},
 		...opts.triageUserPrompt ? { triageUserPrompt: opts.triageUserPrompt } : {},
 		...opts.customPrompt ? { customPrompt: opts.customPrompt } : {}
 	}, {
 		...opts.model ? { model: opts.model } : {},
-		cwd
+		cwd,
+		getFileDiff: specDiff.fileDiff
 	});
 	const pct = Math.round(outcome.analysis.confidence * 100);
 	const headline = outcome.analysis.headline.trim() || (outcome.analysis.reasoning.split("\n")[0] ?? "").trim();
@@ -5866,7 +6223,11 @@ async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts,
 		analysis: outcome.analysis,
 		analysisSkipped: null,
 		failureLogExcerpt: excerpt,
-		diffExcerpt: diff.ok ? diff.diff.patch : null
+		diffExcerpt: specDiff.patch,
+		analysisBase: {
+			ref: specDiff.base.ref,
+			sha: specDiff.base.sha
+		}
 	};
 }
 function count(steps, target) {
@@ -8937,27 +9298,12 @@ function stripCodeFences(text) {
 	return m && m[1] !== void 0 ? m[1] : text;
 }
 //#endregion
-//#region src/run/errors.ts
-/**
-* Usage error (bad flag combination, broken profile, failed `git diff`, …)
-* thrown by the `run` pipeline and the helpers it calls, e.g.
-* `collectChangedSpecs`. `executeRun` never calls `process.exit`, so each
-* host maps this itself: the CLI action catches it and exits with
-* `exitCode`; the hub runner records it as a run-level error.
-*/
-var RunUsageError = class extends Error {
-	exitCode = 2;
-	constructor(message) {
-		super(message);
-		this.name = "RunUsageError";
-	}
-};
-//#endregion
 //#region src/cli/changed-specs.ts
 /**
-* Filter specs to those affected by the git diff against the resolved base
-* ref. Powers `ccqa run --changed`; mirrors `ccqa drift --changed` minus the
-* LLM new-file router (kept off here for predictable CI cost).
+* Filter specs to those affected by the git diff against the `--changed
+* [base]` baseline. Powers `ccqa run --changed`; mirrors `ccqa drift
+* --changed` minus the LLM new-file router (kept off here for predictable CI
+* cost).
 *
 * A spec is "affected" when it has no `relatedPaths` (conservatively
 * included), any changed file matches one of its `relatedPaths` globs, or it
@@ -8965,14 +9311,14 @@ var RunUsageError = class extends Error {
 */
 async function collectChangedSpecs(specs, opts) {
 	const { cwd, base } = opts;
-	const baseRef = resolveBaseRef(base);
+	const resolved = await resolveAnalysisBase(base, "--changed", cwd);
 	let changed;
 	try {
-		changed = await getChangedFiles(baseRef, cwd);
+		changed = await getChangedFiles(resolved.sha, cwd);
 	} catch (e) {
-		throw new RunUsageError(`failed to run 'git diff' against ${baseRef}: ${e.message}`);
+		throw new RunUsageError(`failed to run 'git diff' against ${resolved.ref}: ${e.message}`);
 	}
-	meta("changed-base", baseRef);
+	meta("changed-base", `${resolved.ref} (${resolved.sha.slice(0, 12)})`);
 	meta("changed-files", changed.length);
 	return filterAffectedSpecs(specs, changed, cwd);
 }
@@ -9036,6 +9382,27 @@ function dedupeSpecs(specs) {
 async function executeRun(targets, opts) {
 	if (opts.changed && targets.length > 0) throw new RunUsageError("--changed and an explicit spec target cannot be combined");
 	const cwd = opts.cwd ?? process.cwd();
+	const wantsLastGreen = opts.failureAnalysis === LAST_GREEN;
+	const [head, fixedBase] = await Promise.all([getGitHead(cwd), opts.failureAnalysis && !wantsLastGreen ? resolveAnalysisBase(opts.failureAnalysis, "--failure-analysis", cwd) : null]);
+	const git = {
+		head,
+		base: wantsLastGreen ? {
+			ref: LAST_GREEN,
+			sha: null,
+			source: "last-green"
+		} : fixedBase
+	};
+	let diffProvider = null;
+	if (fixedBase) {
+		diffProvider = createDiffProvider({
+			resolveBase: async () => ({
+				ok: true,
+				base: fixedBase
+			}),
+			cwd
+		});
+		meta("analysis-base", `${fixedBase.ref} (${fixedBase.sha.slice(0, 12)}, ${fixedBase.source})`);
+	}
 	let projectForProfile;
 	try {
 		if (opts.profile !== void 0) {
@@ -9071,7 +9438,17 @@ async function executeRun(targets, opts) {
 	} catch {
 		hubCtx = null;
 	}
-	const [customPrompt, triageUserPrompt] = await Promise.all([fetchCustomPrompt(hubCtx), fetchTriageUserPrompt(hubCtx)]);
+	if (wantsLastGreen && hubCtx == null) throw new RunUsageError(`--failure-analysis=${LAST_GREEN} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
+	const ledgerHub = wantsLastGreen ? hubCtx : null;
+	const [customPrompt, triageUserPrompt, ledgerEntries] = await Promise.all([
+		fetchCustomPrompt(hubCtx),
+		fetchTriageUserPrompt(hubCtx),
+		ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.profile, cwd) : null
+	]);
+	if (ledgerEntries) diffProvider = createDiffProvider({
+		resolveBase: createLastGreenResolver(ledgerEntries, cwd),
+		cwd
+	});
 	const triageUserPromptHash = triageUserPrompt ? hashTriageUserPrompt(triageUserPrompt) : null;
 	const enumerateAll = () => listAllSpecsWithSpecFile(cwd);
 	let specs = dedupeSpecs((await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)))).flat());
@@ -9079,7 +9456,7 @@ async function executeRun(targets, opts) {
 		const before = specs.length;
 		specs = await collectChangedSpecs(specs, {
 			cwd,
-			base: opts.base
+			base: opts.changed
 		});
 		meta("changed-scoped", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
 	}
@@ -9121,6 +9498,7 @@ async function executeRun(targets, opts) {
 			project: hubCtx.project,
 			...branch ? { branch } : {},
 			...opts.profile ? { profile: opts.profile } : {},
+			...git.head ? { gitHead: git.head } : {},
 			kind: "run"
 		});
 		hubRunId = opened.id;
@@ -9141,11 +9519,7 @@ async function executeRun(targets, opts) {
 		warn(`hub: could not open incremental run (${errMessage(err)}); continuing with local report only`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
-		diff: {
-			ok: false,
-			error: "diff not yet captured"
-		},
-		baseRef: null,
+		git,
 		customPromptVersion: customPrompt?.customPromptVersion ?? null,
 		triageUserPromptHash,
 		opts
@@ -9177,13 +9551,12 @@ async function executeRun(targets, opts) {
 		...opts.language ? { language: opts.language } : {},
 		...opts.out && liveSpecs.length === 1 ? { out: opts.out } : {},
 		cwd,
-		...opts.base ? { base: opts.base } : {},
 		reportDir,
 		...typeof opts.retry === "number" ? { retry: opts.retry } : {},
 		concurrency: opts.concurrency ?? 1,
 		...opts.profile ? { profile: opts.profile } : {},
 		...opts.driftAudit !== false ? { driftAudit: true } : {},
-		...opts.failureAnalysis === false ? { failureAnalysis: false } : {},
+		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
 		triageUserPrompt,
@@ -9195,7 +9568,7 @@ async function executeRun(targets, opts) {
 	if (externalRows.some((r) => r.status === "failed")) overallExitCode = 1;
 	let report;
 	{
-		const detReport = await analyzeDeterministicSummaries(det.summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt);
+		const detReport = await analyzeDeterministicSummaries(det.summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt, diffProvider);
 		report = await writeUnifiedReport({
 			reportDir,
 			results: [
@@ -9203,8 +9576,7 @@ async function executeRun(targets, opts) {
 				...externalRows,
 				...live.reportResults
 			],
-			diff: detReport.diff,
-			baseRef: detReport.baseRef,
+			git,
 			customPromptVersion: detReport.customPromptVersion,
 			triageUserPromptHash,
 			opts
@@ -9213,8 +9585,7 @@ async function executeRun(targets, opts) {
 		if (hubRunId) {
 			const finalStatus = overallExitCode === 0 ? "passed" : "failed";
 			const reportMeta = buildReportEnvelope({
-				diff: detReport.diff,
-				baseRef: detReport.baseRef,
+				git,
 				customPromptVersion: detReport.customPromptVersion,
 				triageUserPromptHash,
 				opts
@@ -9412,24 +9783,15 @@ function failedSpec(s) {
 * failure analysis when `--report` is on; degrades (no throw) when Claude
 * auth or git diff aren't available. Caller writes the HTML / JSON.
 */
-async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt) {
-	const failureAnalysisEnabled = opts.failureAnalysis !== false;
+async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt, diffProvider) {
+	const failureAnalysisEnabled = diffProvider != null;
 	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
-	const auth = failureAnalysisEnabled || driftAuditEnabled ? driftAuthAvailable() : {
+	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "skipped by flags"
 	};
 	const failed = summaries.filter(failedSpec);
 	if (failureAnalysisEnabled && !auth.ok && failed.length > 0) info(`failure analysis skipped (${auth.reason})`);
-	const baseRef = resolveBaseRef(opts.base);
-	let diff = {
-		ok: false,
-		error: "diff not captured (no failures)"
-	};
-	if (failed.length > 0) {
-		diff = await capturePrDiff(baseRef, cwd);
-		if (!diff.ok) info(`drift-report: source diff unavailable (${diff.error}) — analyzing without diff context`);
-	}
 	const tree = failed.length > 0 ? await listFeatureTree(cwd) : [];
 	const specInfoByKey = new Map(tree.flatMap((f) => f.specs.map((sp) => [`${f.featureName}/${sp.specName}`, sp])));
 	const findSpecInfo = (s) => specInfoByKey.get(`${s.featureName}/${s.specName}`) ?? null;
@@ -9456,9 +9818,9 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			onSpecStart: (t) => info(`drift audit: ${t.featureName}/${t.specName}`)
 		});
 	}
-	const patchSections = diff.ok && diff.diff.patch.length > 0 ? splitPatchByFile(diff.diff.patch) : null;
 	const allBlocks = await loadAllBlocks(cwd);
 	let printedHeader = false;
+	let warnedDiffUnavailable = false;
 	const results = [];
 	for (const s of summaries) {
 		const assertions = collectAssertions(s);
@@ -9493,14 +9855,23 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			});
 			continue;
 		}
-		const relatedPaths = findSpecInfo(s)?.relatedPaths ?? null;
-		const diffExcerpt = patchSections ? scopePatchForSpec(patchSections, relatedPaths) : null;
+		const specDiffResult = diffProvider ? await diffProvider.forSpec({
+			featureName: s.featureName,
+			specName: s.specName
+		}) : null;
+		const specDiff = specDiffResult?.ok ? specDiffResult : null;
+		if (specDiff?.error && !warnedDiffUnavailable) {
+			warnedDiffUnavailable = true;
+			info(`failure analysis: source diff unavailable (${specDiff.error}) — analyzing without diff context`);
+		}
+		const diffExcerpt = specDiff?.patch ?? null;
 		const driftResult = driftResults.find((r) => r.target.featureName === s.featureName && r.target.specName === s.specName);
 		const driftIssues = driftResult?.ok ? driftResult.issues : null;
 		const failureLog = buildFailureLog(s);
 		let analysis = null;
 		let analysisSkipped = null;
-		if (!failureAnalysisEnabled) analysisSkipped = "skipped by --no-failure-analysis";
+		if (!specDiffResult) analysisSkipped = "skipped: --failure-analysis not enabled";
+		else if (!specDiffResult.ok) analysisSkipped = specDiffResult.skip;
 		else if (!auth.ok) analysisSkipped = auth.reason;
 		else if (specYaml === null) analysisSkipped = "no spec.yaml found for this spec";
 		else {
@@ -9511,15 +9882,18 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 				specYaml,
 				failureLog,
 				diffPatch: diffExcerpt,
-				changedFiles: diff.ok ? diff.diff.nameStatus : null,
-				baseRef: diff.ok ? baseRef : null,
+				changedFiles: specDiffResult.nameStatus,
+				baseRef: specDiffResult.base.ref,
+				baseSource: specDiffResult.base.source,
+				range: specDiffResult.range,
 				driftIssues,
 				...opts.language ? { outputLanguage: opts.language } : {},
 				...triageUserPrompt ? { triageUserPrompt } : {},
 				...customPrompt ? { customPrompt } : {}
 			}, {
 				...opts.model ? { model: opts.model } : {},
-				cwd
+				cwd,
+				getFileDiff: specDiffResult.fileDiff
 			});
 			analysis = outcome.analysis;
 			if (!printedHeader) {
@@ -9537,6 +9911,10 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			status: "failed",
 			analysis,
 			analysisSkipped,
+			...specDiff ? { analysisBase: {
+				ref: specDiff.base.ref,
+				sha: specDiff.base.sha
+			} } : {},
 			driftIssues,
 			failureLogExcerpt: failureLog.length > 0 ? failureLog : null,
 			diffExcerpt,
@@ -9546,8 +9924,6 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 	}
 	return {
 		results,
-		diff,
-		baseRef,
 		customPromptVersion: customPrompt?.customPromptVersion ?? null
 	};
 }
@@ -9559,30 +9935,33 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 * final report.json stays byte-identical (existing e2e goldens compare it).
 */
 function buildReportEnvelope(args) {
-	const { diff, baseRef, customPromptVersion, triageUserPromptHash, opts } = args;
+	const { git, customPromptVersion, triageUserPromptHash, opts } = args;
 	return {
 		schemaVersion: 1,
 		kind: "run",
 		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 		runId: process.env["GITHUB_RUN_ID"] ?? null,
 		git: {
-			head: diff.ok ? diff.diff.head : null,
-			base: diff.ok ? baseRef : null
+			head: git.head,
+			base: git.base?.ref ?? null,
+			...git.base ? {
+				baseSha: git.base.sha,
+				baseSource: git.base.source
+			} : {}
 		},
 		model: opts.model ?? null,
 		language: opts.language ?? null,
-		promptVersion: "4",
+		promptVersion: "6",
 		customPromptVersion,
 		...triageUserPromptHash !== null ? { triageUserPromptHash } : {}
 	};
 }
 /** Write the unified JSON (+ optional GitHub-annotation) report for one run. Returns the report data. */
 async function writeUnifiedReport(args) {
-	const { reportDir, results, diff, baseRef, customPromptVersion, triageUserPromptHash, opts } = args;
+	const { reportDir, results, git, customPromptVersion, triageUserPromptHash, opts } = args;
 	const data = {
 		...buildReportEnvelope({
-			diff,
-			baseRef,
+			git,
 			customPromptVersion,
 			triageUserPromptHash,
 			opts
@@ -9896,7 +10275,7 @@ function installTeardownSignalHandlers(teardown) {
 }
 //#endregion
 //#region src/cli/run.ts
-const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs. Each spec's execution mode comes from its spec.yaml `mode:` field (default deterministic; set `mode: live` to have Claude drive agent-browser live per step). Deterministic specs replay the recorded test.spec.ts under vitest. A structured report (report.json + evidence) is always written; use --push-report to also stream it to a hub.").option("--report [dir]", `Directory for the structured run results (report.json + evidence PNGs) that are always written. Default: ${DEFAULT_REPORT_DIR}/. Pass this only to change the location.`).option("--push-report", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").option("--changed", "Restrict execution to specs whose relatedPaths intersect the git diff against --base (or, in CI, $GITHUB_BASE_REF, else origin/main). Cannot be combined with an explicit spec id.").option("--no-failure-analysis", "Skip the per-failure root-cause classification (TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG). --report only.").option("--no-drift-audit", "Skip the spec↔code drift audit shown in the report. --report only.").option("--base <ref>", "Base ref the source diff is taken against for failure analysis (default: GITHUB_BASE_REF, then origin/main).").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--format <fmt>", "Additional output format alongside HTML when --report is set: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
+const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs. Each spec's execution mode comes from its spec.yaml `mode:` field (default deterministic; set `mode: live` to have Claude drive agent-browser live per step). Deterministic specs replay the recorded test.spec.ts under vitest. A structured report (report.json + evidence) is always written; use --push-report to also stream it to a hub.").option("--report [dir]", `Directory for the structured run results (report.json + evidence PNGs) that are always written. Default: ${DEFAULT_REPORT_DIR}/. Pass this only to change the location.`).option("--push-report", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").option("--changed [base]", "Restrict execution to specs whose relatedPaths intersect the git diff against [base]. Without a value the base comes from $GITHUB_BASE_REF (pull_request CI); elsewhere pass it explicitly (e.g. --changed=origin/main). Cannot be combined with an explicit spec id.").option("--failure-analysis [base]", "Classify each failure (TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG) against the source diff since [base]. Without a value the base comes from $GITHUB_BASE_REF (pull_request CI); elsewhere pass it explicitly (e.g. --failure-analysis=origin/main), or pass 'last-green' to diff each spec against the commit where it last passed (per-spec baselines from the hub; requires a hub connection). Off by default — no Claude calls without it.").option("--no-drift-audit", "With --failure-analysis: skip the spec↔code drift audit shown in the report.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--format <fmt>", "Additional output format alongside HTML when --report is set: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
 	if (REPORT_FORMATS.includes(raw)) return raw;
 	throw new Error(`--format must be one of ${REPORT_FORMATS.join(" | ")}`);
 }, "text").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--no-evidence", `(deterministic only) Skip step-boundary evidence capture (PNG + meta JSON written to ${DEFAULT_REPORT_DIR}/${EVIDENCE_SUBDIR}/ by default).`).option("--retry <n>", "(live only) Retry each failed step up to N more times before recording failure. Default 0.", (raw) => {
@@ -13390,6 +13769,11 @@ z.object({ error: z.object({
 	code: z.string(),
 	message: z.string()
 }) });
+z.object({
+	gitHead: z.string(),
+	runId: z.string(),
+	at: z.string()
+});
 /**
 * A triage-learning job. Grading failing specs in the hub UI produces the
 * "actual cause" labels this reads; the job turns them into an improved
@@ -13505,6 +13889,7 @@ function createPushRunHandler(config) {
 			};
 			await config.storage.artifacts.putDir(run.id, dir);
 			await config.storage.runs.create(run);
+			await updateLastGreenLedger(config.storage, run, report.results);
 			sendJson(ctx.res, 201, run);
 		} finally {
 			await rm(dir, {
@@ -13515,14 +13900,17 @@ function createPushRunHandler(config) {
 	};
 }
 /**
-* POST /api/v1/runs/open?project=&branch=&profile=&kind= — start a "running"
-* run with no report yet. Unlike `POST /runs`, nothing is pushed up front:
-* the caller patches results in as they finish (`PATCH /runs/:id`), so an
-* interrupted run still leaves a partial report on the hub instead of none.
+* POST /api/v1/runs/open?project=&branch=&profile=&kind=&gitHead= — start a
+* "running" run with no report yet. Unlike `POST /runs`, nothing is pushed up
+* front: the caller patches results in as they finish (`PATCH /runs/:id`), so
+* an interrupted run still leaves a partial report on the hub instead of
+* none. `gitHead` (optional) attributes the run to a commit from the start —
+* without it an interrupted run would never learn its commit.
 */
 function createOpenRunHandler(config) {
 	return async (ctx) => {
 		const { project, branch, profile, kind } = parseRunScope(ctx);
+		const gitHead = ctx.url.searchParams.get("gitHead");
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		const run = {
 			id: randomUUID(),
@@ -13537,7 +13925,7 @@ function createOpenRunHandler(config) {
 				passed: 0,
 				failed: 0
 			},
-			gitHead: null,
+			gitHead: gitHead || null,
 			promptVersion: "",
 			ciRunId: null,
 			reportCreatedAt: now,
@@ -13553,10 +13941,7 @@ const PatchRunRequestSchema = z.object({
 	done: z.boolean().optional(),
 	finalStatus: z.enum(["passed", "failed"]).optional(),
 	reportMeta: z.object({
-		git: z.object({
-			head: z.string().nullable(),
-			base: z.string().nullable()
-		}).partial().optional(),
+		git: GitEnvelopeSchema.partial().optional(),
 		model: z.string().nullable().optional(),
 		language: z.string().nullable().optional(),
 		promptVersion: z.string().optional(),
@@ -13580,6 +13965,38 @@ function countSpecs(results) {
 	};
 }
 /**
+* Advance the last-green ledger for every passed spec of a terminal
+* `kind: "run"` run. Spec-level, not run-level: a run with one chronically
+* failing spec still moves the baseline of every spec that did pass.
+* Best-effort — a ledger failure must not fail the push; the ledger is an
+* accelerator for `--failure-analysis=last-green`, not part of the run
+* record. Runs without a branch or gitHead can't be placed in the ledger and
+* are skipped.
+*
+* Ordering caveat (known approximation): `at` is the run's reportCreatedAt —
+* open time for incremental runs, report time for immutable pushes. When two
+* runs on the same branch+profile overlap, "newest at wins" can pick either
+* of the two genuinely-green commits, since the hub has no git ancestry to
+* order them properly. Accepted: CI serializes per branch in practice, and a
+* baseline can only ever point at a commit where the spec really passed.
+*/
+async function updateLastGreenLedger(storage, run, results) {
+	const { gitHead, branch } = run;
+	if (run.kind !== "run" || !gitHead || !branch) return;
+	const passed = results.filter((r) => r.status === "passed");
+	if (passed.length === 0) return;
+	const entries = Object.fromEntries(passed.map((r) => [`${r.feature}/${r.spec}`, {
+		gitHead,
+		runId: run.id,
+		at: run.reportCreatedAt
+	}]));
+	try {
+		await storage.lastGreen.merge(run.project, run.profile ?? "default", branch, entries);
+	} catch (err) {
+		console.error(`hub: last-green ledger update failed for run "${run.id}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
 * PATCH /api/v1/runs/:id — incrementally add spec results (and evidence) to a
 * "running" run. Once the run is terminal (`done: true` was sent, or it was
 * pushed immutably via `POST /runs`), further patches are rejected with 409.
@@ -13601,6 +14018,7 @@ function createPatchRunHandler(config) {
 		if (!parsed.success) throw new HttpError(400, "invalid_body", `request body is invalid: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`);
 		const { rows, evidence, done, finalStatus, reportMeta } = parsed.data;
 		let specs = run.specs;
+		let mergedResults = [];
 		await config.storage.artifacts.updateJsonFile(id, "report.json", (current) => {
 			const base = current ?? {
 				schemaVersion: 1,
@@ -13620,7 +14038,9 @@ function createPatchRunHandler(config) {
 				...base,
 				...reportMeta?.git ? { git: {
 					head: reportMeta.git.head ?? base.git.head,
-					base: reportMeta.git.base ?? base.git.base
+					base: reportMeta.git.base ?? base.git.base,
+					baseSha: reportMeta.git.baseSha ?? base.git.baseSha ?? null,
+					baseSource: reportMeta.git.baseSource ?? base.git.baseSource ?? null
 				} } : {},
 				...reportMeta?.model !== void 0 ? { model: reportMeta.model } : {},
 				...reportMeta?.language !== void 0 ? { language: reportMeta.language } : {},
@@ -13630,6 +14050,7 @@ function createPatchRunHandler(config) {
 			};
 			const merged = mergeResults(current?.results ?? [], rows);
 			specs = countSpecs(merged);
+			mergedResults = merged;
 			return {
 				...envelope,
 				results: merged
@@ -13643,6 +14064,7 @@ function createPatchRunHandler(config) {
 			...reportMeta?.promptVersion ? { promptVersion: reportMeta.promptVersion } : {}
 		} : { specs };
 		const updated = await config.storage.runs.update(id, patch);
+		if (done) await updateLastGreenLedger(config.storage, updated, mergedResults);
 		sendJson(ctx.res, 200, updated);
 	};
 }
@@ -13759,9 +14181,11 @@ function parseRunScope(ctx) {
 	};
 }
 /**
-* A branch is a free-form label (e.g. `feature/foo`), stored verbatim and
-* never used to build a filesystem path, so `/` is allowed — only length is
-* bounded. null when the client didn't send one.
+* A branch is a free-form label (e.g. `feature/foo`), so `/` is allowed —
+* only length is bounded (a sanity cap; the last-green ledger separately
+* hash-truncates long percent-encoded names into a safe filename, see
+* paths.ts). Run records store it verbatim. null when the client didn't
+* send one. Exported for the last-green handler.
 */
 function requireBranch(raw) {
 	if (raw === null || raw === "") return null;
@@ -14014,6 +14438,32 @@ function createListProfilesHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/last-green.ts
+/**
+* GET /api/v1/projects/:project/last-green?profile=&branch=&fallbackBranch=
+*
+* Returns the last-green ledger entries for one project/profile, keyed by
+* "feature/spec". `branch` is the caller's current branch; `fallbackBranch`
+* (optional, typically the default branch) is overlaid *under* it, so a PR
+* branch with no greens of its own still inherits the default branch's
+* baselines while its own greens take precedence. One round trip serves the
+* whole run.
+*/
+function createGetLastGreenHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const profile = requireSafeSegment(ctx.url.searchParams.get("profile") ?? "default", "profile");
+		const branch = requireBranch(ctx.url.searchParams.get("branch"));
+		if (!branch) throw new HttpError(400, "missing_param", "branch query parameter is required");
+		const fallbackBranch = requireBranch(ctx.url.searchParams.get("fallbackBranch"));
+		const [primary, fallback] = await Promise.all([storage.lastGreen.get(project, profile, branch), fallbackBranch && fallbackBranch !== branch ? storage.lastGreen.get(project, profile, fallbackBranch) : Promise.resolve({})]);
+		sendJson(ctx.res, 200, { entries: {
+			...fallback,
+			...primary
+		} });
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/prompts.ts
 const MAX_PROMPT_BODY_BYTES = 256 * 1024;
 /** Validate the `:project` route param (prompts are project-scoped, not per-profile). */
@@ -18022,7 +18472,7 @@ function createLearningWorker(deps) {
 		const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const customPrompt = {
 			schemaVersion: 1,
-			basePromptVersion: "4",
+			basePromptVersion: "6",
 			customPromptVersion: `${generatedAt}-c${cases.length}`,
 			generatedAt,
 			guidance
@@ -18141,6 +18591,7 @@ function registerRoutes(router, config, queue) {
 	router.put("/api/v1/runs/:id/triage/actual-causes", createImportActualCausesHandler(storage));
 	router.get("/api/v1/projects", createListProjectsHandler(storage));
 	router.get("/api/v1/projects/:project/profiles", createListProfilesHandler(storage));
+	router.get("/api/v1/projects/:project/last-green", createGetLastGreenHandler(storage));
 	const sessionConfig = {
 		store: storage.sessions,
 		encryptionKey: config.encryptionKey
@@ -18373,6 +18824,10 @@ function perspectivesKindDir(root) {
 function perspectivesPath(root, project) {
 	return join(perspectivesKindDir(root), `${project}.json`);
 }
+function lastGreenPath(root, project, profile, branch) {
+	const encoded = encodeURIComponent(branch);
+	return join(root, "last-green", project, profile, `${encoded.length <= 200 ? encoded : `${encoded.slice(0, 64)}-${createHash("sha256").update(branch).digest("hex").slice(0, 32)}`}.json`);
+}
 //#endregion
 //#region src/hub/core/storage/file/artifact-store.ts
 /**
@@ -18460,6 +18915,25 @@ function createFileJobStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/last-green-store.ts
+function createFileLastGreenStore(root) {
+	return {
+		async get(project, profile, branch) {
+			return await readJson(lastGreenPath(root, project, profile, branch)) ?? {};
+		},
+		async merge(project, profile, branch, entries) {
+			await updateJson(lastGreenPath(root, project, profile, branch), (current) => {
+				const out = { ...current ?? {} };
+				for (const [key, entry] of Object.entries(entries)) {
+					const prev = out[key];
+					if (!prev || prev.at <= entry.at) out[key] = entry;
+				}
+				return out;
+			});
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/perspectives-store.ts
 /**
 * Defense-in-depth path validation: the HTTP layer already checks the project
@@ -18713,7 +19187,8 @@ function createFileHubStorage(dataDir) {
 		triage: createFileTriageStore(dataDir),
 		prompts: createFilePromptStore(dataDir),
 		perspectives: createFilePerspectivesStore(dataDir),
-		jobs: createFileJobStore(dataDir)
+		jobs: createFileJobStore(dataDir),
+		lastGreen: createFileLastGreenStore(dataDir)
 	};
 }
 //#endregion