ccqa 1.38.0 → 1.40.0

package/dist/bin/ccqa.mjs

@@ -4130,10 +4130,11 @@ const execFileP = promisify(execFile);
 * `.ccqa/`. Changes outside `cwd` are kept under their repo-root path and
 * flagged `outsideCwd` (see `ChangedFile`) rather than dropped.
 *
-* `detectRenames` defaults on. `ccqa hub deploy record` turns it off (via
-* `changedPathsBetween`): with rename detection, a rename is one entry naming
-* only the destination, so a file's old path would silently drop out of the
-* report — off, it appears as a delete plus an add and both paths are kept.
+* `detectRenames` defaults on. Callers whose diff is held against past facts
+* — `ccqa hub deploy record` and spec selection — turn it off: with rename
+* detection, a rename is one entry naming only the destination, so a file's
+* old path would silently drop out — off, it appears as a delete plus an add
+* and both paths are kept.
 */
 async function getChangedFilesBetween(base, head, cwd, options = {}) {
 	return diffNameStatus(`${base}..${head}`, cwd, options.detectRenames ?? true);
@@ -7340,7 +7341,9 @@ async function closeMeasurement(collector, ref, coverageDir) {
 * Every failure here is otherwise silent and identical to success: a root that
 * does not exist, or does not contain the project, sends every relative source
 * outside it, and the run reports a smaller file set with no error at all —
-* the answer this measurement exists to prevent.
+* the answer this measurement exists to prevent. Spec selection
+* (src/select/analyze.ts) resolves the same key through this function too, so
+* both sides of an intersection agree on what the root means.
 */
 async function resolveRoot(cwd, declared) {
 	if (declared === void 0) return void 0;
@@ -9390,8 +9393,8 @@ z.object({
 *
 * This is the whole re-run computation, not an accelerator for it. Each spec's
 * baseline sits at a different position in the log, so the question is always
-* "since *this* spec last ran, was it ever needed" — two integer comparisons
-* against the positions kept here. Re-deriving it per read is impossible
+* "since *this* spec last ran, was it ever needed" — one integer comparison
+* against the `needed` position kept here. Re-deriving it per read is impossible
 * anyway: the selections were made by a model against each deploy's diff, and
 * neither the diff nor the model is available at read time.
 *
@@ -10835,159 +10838,170 @@ function capDeployPaths(paths) {
 	return paths.slice(0, MAX_SENT_CHANGED_PATHS);
 }
 //#endregion
-//#region src/prompts/select-specs.ts
+//#region src/config/project-config.ts
 /**
-* The prompt behind `ccqa select-specs`.
+* Loader for the consumer project's `.ccqa/config.yaml` — per-target
+* generation settings (default target, output dirs, reusable code resources,
+* generation conventions).
 *
-* It replaces a stored path mapping with a judgement made against the actual
-* diff. That trade is worth making only if the judgement is honest about its
-* own limits, so the whole prompt is built around one rule: clearing a spec is
-* a claim that has to be earned, and `unknown` is always available instead.
+* This module only validates and holds the config. `path` / `guides` /
+* `examples` entries may be glob patterns; they are kept verbatim here and
+* expanded by the generation engine, which owns size limits and warnings.
 */
-function buildSelectSystemPrompt() {
-	return `You decide which end-to-end test specs have to be re-run after a set of source changes.
-
-You are given the files that changed between two commits, and an inventory of every test spec: what each one does, step by step. Return one verdict per spec.
-
-## The three verdicts
-
-- **needed** — at least one changed file plausibly affects what this spec verifies. Name the file(s) in \`touchedBy\`.
-- **notNeeded** — you have accounted for the changed files and none of them reach what this spec does.
-- **unknown** — you cannot tell.
-
-## Why \`notNeeded\` is the only answer that can hurt
-
-Re-running a spec that did not need it costs a few minutes of CI. NOT re-running a spec that needed it lets a regression reach users with the suite still green — the failure mode this tool exists to prevent.
-
-So the two answers are not symmetric:
-
-- \`needed\` and \`unknown\` are both safe. The caller runs them.
-- \`notNeeded\` is a **positive claim**. Make it only when you have actually looked at what the spec exercises and at what changed, and can say the two do not meet.
-
-When you cannot make that claim — a file whose purpose you cannot infer, a change whose blast radius you cannot bound, a spec whose steps are missing or unclear — answer \`unknown\`. That is a correct answer, not a failure. Guessing \`notNeeded\` is the one thing that causes damage.
-
-**Do not over-correct.** Marking every spec \`needed\` throws away the entire point: the caller ends up running the full suite on every change. When a change is confined to an area that a spec demonstrably never touches, say \`notNeeded\` and say why. Both a reflexive "run everything" and a careless "skip it" are wrong; judge each spec on the evidence.
-
-## How to judge
-
-1. Read the changed paths. Most are self-describing — a path naming a screen, a component, a handler, or a route tells you what it belongs to.
-2. For a path whose purpose is not obvious from its name, use \`Read\` or \`Grep\` to find out what it does before judging. Prefer this over guessing. Stay focused: this is a routing decision, not a code review.
-3. Match against what each spec actually does — the screens its steps open, the controls they drive, the strings they assert on.
-4. Remember indirect reach: shared layout, navigation, authentication, permission checks, and data-access code are touched by specs that never mention them. A change to a sign-in path can break every spec that has to sign in first.
-
-## What does not affect any spec
-
-Treat these as irrelevant unless something specific says otherwise: documentation and Markdown, changes to test files of the product's own unit-test suite, lockfile-only churn, formatting-only changes, and code paths that only run in a build or tooling context.
-
-## Output (STRICT)
-
-Output ONE fenced \`\`\`json block, and nothing else outside it.
-
-\`\`\`json
-{
-  "specs": [
-    {
-      "spec": "<feature>/<spec>",
-      "verdict": "needed" | "notNeeded" | "unknown",
-      "reason": "<one sentence>",
-      "touchedBy": ["<changed path>"]
-    }
-  ]
-}
-\`\`\`
-
-Rules for the output:
-
-- Include **every** spec from the inventory, exactly once, using the key as it was given to you.
-- \`touchedBy\` is required for \`needed\` and must name paths from the changed-file list. Omit it otherwise.
-- \`reason\` for \`notNeeded\` must say what you checked, not just "unrelated".
-- \`reason\` for \`unknown\` must name what you could not determine.
-`;
-}
-/** Cap on how many changed paths are spelled out before the list is summarised. */
-const MAX_LISTED_PATHS = 400;
-function buildSelectPrompt(input) {
-	return `## Changed files (${input.base} → ${input.head})
-
-${formatChangedFiles(input.changed)}
-
-## Test spec inventory
-
-${input.specs.map(formatSpec).join("\n\n")}
-
-## Task
-
-Return one verdict for each of the ${input.specs.length} specs above. Clear a spec only when you can account for the changes; otherwise answer \`needed\` or \`unknown\`.
-`;
-}
-function formatChangedFiles(changed) {
-	if (changed.length === 0) return "(none)";
-	const listed = changed.slice(0, MAX_LISTED_PATHS);
-	const lines = listed.map((f) => `- ${f.status.padEnd(8)} ${f.path}${f.outsideCwd ? "  (outside the tested package)" : ""}`);
-	if (changed.length > listed.length) lines.push(`- ... and ${changed.length - listed.length} more paths, not listed. You have NOT seen the full change set: do not answer \`notNeeded\` for a spec unless the listed paths alone rule it out.`);
-	return lines.join("\n");
-}
-function formatSpec(spec) {
-	const steps = spec.steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
-	return `### ${specKey(spec)}\n${spec.title}\n${steps}`;
-}
-//#endregion
-//#region src/select/types.ts
 /**
-* How the verdict was reached. Kept because the two sources have different
-* trust: `mechanical` is set arithmetic on paths and cannot be wrong,
-* `model` is a judgement and can be.
+* An existing code asset the generated tests should reuse (import), in one of
+* two forms — exactly one of:
+*   - `path`: code inside the consumer repo (literal path or glob pattern);
+*   - `package`: an installed npm package (imported by name).
+* `description` tells the generator what the asset contains.
 */
-const SelectSourceSchema = z.enum(["mechanical", "model"]);
-const SpecSelectionSchema = z.object({
-	featureName: z.string().min(1),
-	specName: z.string().min(1),
-	verdict: SelectVerdictSchema,
-	source: SelectSourceSchema,
-	reason: z.string(),
-	touchedBy: z.array(z.string()).optional()
-});
-z.object({
-	base: z.string(),
-	head: z.string(),
-	changedFiles: z.number().int().nonnegative(),
-	specs: z.array(SpecSelectionSchema)
-});
-/** Specs the caller should actually run: everything not positively cleared. */
-function specsToRun(report) {
-	return report.specs.filter((s) => s.verdict !== "notNeeded");
-}
+const ResourceRefSchema = z.union([z.object({
+	path: z.string().min(1),
+	description: z.string().optional()
+}).strict(), z.object({
+	package: z.string().min(1),
+	description: z.string().optional()
+}).strict()], { error: "a resource must have exactly one of `path` (code in this repo) or `package` (installed npm package), plus an optional `description`" });
+/**
+* How generated code should be written, as guide inputs to the prompt (never
+* imported as code): `guides` are convention documents, `examples` are
+* existing tests whose style to imitate. Entries may be glob patterns.
+*/
+const ConventionsSchema = z.object({
+	guides: z.array(z.string().min(1)).default([]),
+	examples: z.array(z.string().min(1)).default([])
+}).strict();
+/**
+* Per-target settings. `outDir` (where generated tests are written) and
+* `runCommand` (how to execute them; `{files}` expands to the generated
+* paths, `{artifactsDir}` to the spec's report artifacts dir — see
+* src/targets/run-artifacts.ts) are optional at this layer because not every
+* target needs them — e.g. agent-browser stores its output in the spec
+* directory. A target that requires either must validate its presence itself.
+*/
+const TargetConfigSchema = z.object({
+	outDir: z.string().min(1).optional(),
+	runCommand: z.string().min(1).optional(),
+	resources: z.array(ResourceRefSchema).default([]),
+	conventions: ConventionsSchema.default({
+		guides: [],
+		examples: []
+	})
+}).strict();
 /**
-* One spec's verdict as the selection model's JSON reply states it, before
-* `touchedBy` is cross-checked against the actual diff.
+* Specs that must not run at the same time, grouped by the thing they share.
 *
-* Parsed with `safeParse`, per element, rather than `z.array(...).parse` on
-* the whole reply: a model reply is untrusted input, and one malformed entry
-* (an invented verdict, a missing `spec` field) must not discard every other
-* spec's answer in the same reply. `touchedBy` keeps the same tolerance one
-* level down — a non-string element is dropped, not fatal to the entry.
+* The key names the shared thing (a chat channel, a seeded account, a tenant);
+* the list names the specs that write to it. `ccqa run` never runs two members
+* of one group concurrently, and specs sharing no group still run in parallel.
+*
+* Kept here rather than on each spec so there is one place to read the whole
+* picture, and so a mistyped member is a spec key that does not resolve —
+* caught — rather than a resource name that silently matches nothing.
 */
-const SelectRawAnswerSchema = z.object({
-	spec: z.string(),
-	verdict: SelectVerdictSchema,
-	reason: z.string().default(""),
-	touchedBy: z.array(z.unknown()).default([]).transform((paths) => paths.filter((p) => typeof p === "string"))
-});
-/** The selection model's reply shape: `{ specs: [...] }`, entries unvalidated at this level. */
-const SelectModelReplySchema = z.object({ specs: z.array(z.unknown()) });
+const SerialGroupsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "serial group name must be a slug (letters, digits, '.', '_', '-')"), z.array(z.string().min(1)).min(1));
+/**
+* Which specs act as which external identity, for the flows whose requests
+* cannot carry a spec id at all.
+*
+* A chat platform's webhook is sent by the platform, not the browser, so no
+* cookie rides along and everything the flow reaches would be unattributed.
+* What the request does carry is who caused it, and if only one spec is allowed
+* to act as that identity at a time, "who" plus "when" is enough.
+*
+* ```yaml
+* coverage:
+*   actors:
+*     slack:                      # the preset's tag prefix
+*       ${TEST_USER_ID}: [chat/create-item, chat/resolve-item]
+* ```
+*
+* The provider name is the prefix the matching preset stamps, and the key is an
+* identity expression the run's variables resolve. Only the unexpanded text is
+* ever displayed or used as a lock key, so the identity itself stays out of
+* reports and the hub.
+*/
+const CoverageActorsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "actor provider must be a slug (letters, digits, '.', '_', '-')"), z.record(z.string().min(1), z.array(z.string().min(1)).min(1)));
+/**
+* Settings for `ccqa run --coverage`, which measures what each spec actually
+* reached in the application under test.
+*/
+const CoverageConfigSchema = z.object({
+	instrumentedOrigins: z.array(z.string().min(1)).min(1),
+	sink: z.string().min(1).default("http://127.0.0.1:4757"),
+	projectRoot: z.string().min(1).optional(),
+	include: z.array(z.string().min(1)).optional(),
+	actors: CoverageActorsSchema.default({})
+}).strict();
+/**
+* Top-level `.ccqa/config.yaml` schema. `defaultTarget` is used by specs
+* with no `target:` of their own. Both defaults make a missing config file
+* equivalent to "agent-browser only, no extra settings".
+*/
+const ProjectConfigSchema = z.object({
+	defaultTarget: TargetIdSchema.default(AGENT_BROWSER_TARGET),
+	targets: z.record(TargetIdSchema, TargetConfigSchema).default({}),
+	serialGroups: SerialGroupsSchema.default({}),
+	coverage: CoverageConfigSchema.optional()
+}).strict();
+/** Config file location, relative to the project root (`--cwd`). */
+const PROJECT_CONFIG_PATH = ".ccqa/config.yaml";
+/**
+* Load `<cwd>/.ccqa/config.yaml`. A missing file yields the defaults (an
+* empty file too); a present but broken file is an error — never silently
+* fall back when the user wrote a config.
+*/
+async function loadProjectConfig(cwd) {
+	let content;
+	try {
+		content = await readFile(join(cwd, PROJECT_CONFIG_PATH), "utf8");
+	} catch (e) {
+		if (e.code === "ENOENT") return ProjectConfigSchema.parse({});
+		throw e;
+	}
+	return parseProjectConfig(content);
+}
+/** Parse config YAML. Schema rejections are rewritten with actionable messages. */
+function parseProjectConfig(content, source = PROJECT_CONFIG_PATH) {
+	let raw;
+	try {
+		raw = parse(content);
+	} catch (e) {
+		throw new Error(`Failed to parse YAML (${source}): ${e.message}`);
+	}
+	try {
+		return ProjectConfigSchema.parse(raw ?? {});
+	} catch (e) {
+		throw enrichZodError(e, source);
+	}
+}
+/** Flatten a ZodError into one `Invalid <source>:` message, path per line. */
+function enrichZodError(error, source) {
+	if (!(error instanceof ZodError)) return error;
+	const lines = [`Invalid ${source}:`];
+	for (const issue of error.issues) {
+		const path = issue.path.join(".") || "(root)";
+		const message = issue.code === "invalid_key" && issue.issues[0] ? issue.issues[0].message : issue.message;
+		lines.push(`  - ${path}: ${message}`);
+	}
+	return new Error(lines.join("\n"));
+}
 //#endregion
 //#region src/select/analyze.ts
 /**
 * Decide which specs a change set reaches.
 *
-* Two passes, in this order and for this reason: what can be settled by
-* looking at paths is settled that way, and only the remainder is put to a
-* model. A change to a spec's own file, or to a block it includes, means that
-* spec must re-run — that is set membership, not a judgement, and asking a
-* model would only introduce a way to get it wrong.
+* Two passes, in this order and for this reason: what a change to ccqa's own
+* tree settles is settled first, and only the remainder is held against
+* measured reach. A change to a spec's own file, or to a block it includes,
+* means that spec must re-run — reach cannot see the test's own definition,
+* so no measurement is consulted for it. Everything else intersects the diff
+* with the files the spec's last measured run actually reached (ADR-0024);
+* a spec with no measurement stays `unknown`, because an unmeasured edge is
+* not an unreached one.
 */
 async function selectSpecs(input) {
-	const { changed, specs, cwd, base, head, model } = input;
+	const { changed, specs, cwd, base, head, edges } = input;
 	const { productChanges, mechanicallyNeeded } = partitionChanges(changed, specs);
 	const byInventoryKey = new Map(specs.map((s) => [specKey(s), s]));
 	const byKey = /* @__PURE__ */ new Map();
@@ -11011,13 +11025,11 @@ async function selectSpecs(input) {
 		source: "mechanical",
 		reason: "no file outside .ccqa/ changed in this range"
 	});
-	else if (undecided.length > 0) for (const selection of await judgeWithModel({
+	else if (undecided.length > 0) for (const selection of await judgeWithCoverage({
+		pending: undecided,
 		productChanges,
-		undecided,
 		cwd,
-		base,
-		head,
-		model
+		edges
 	})) byKey.set(specKey(selection), selection);
 	return {
 		base,
@@ -11027,12 +11039,12 @@ async function selectSpecs(input) {
 	};
 }
 /**
-* Split the diff into the part a model has to reason about and the part that
-* decides itself.
+* Split the diff into the part measured reach has to answer for and the part
+* that decides itself.
 *
 * `.ccqa/` paths are ccqa's own: a spec directory names the spec it belongs
 * to, a block names the specs that include it. Product paths carry no such
-* mapping — that is the whole problem this command exists to solve.
+* mapping — those are what the coverage intersection exists to answer.
 */
 function partitionChanges(changed, specs) {
 	const productChanges = [];
@@ -11079,118 +11091,214 @@ function isCcqaPath(path) {
 	return /(?:^|\/)\.ccqa\//.test(path);
 }
 /**
-* A malformed reply costs the whole selection, so it is worth one more call
-* before giving up. `ccqa audit` retries per spec for the same reason; this
-* call carries every undecided spec at once, so the blast radius is larger,
-* not smaller. Observed in practice: three runs over one commit produced a
-* parse failure, a clean answer, and a different clean answer.
-*/
-const MAX_ATTEMPTS = 2;
-/**
-* One model call for the whole undecided set, not one per spec: the specs are
-* judged against the same diff, and seeing them together is what lets the
-* model tell them apart.
-*
-* A failed or unparsable reply resolves every undecided spec to `unknown`
-* rather than clearing it. The caller runs `unknown`, so a broken selection
-* degrades to running more than necessary — never to skipping something.
-*/
-async function judgeWithModel(input) {
-	const { productChanges, undecided, cwd, base, head, model } = input;
-	let parsed;
-	let lastError = "";
-	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-		const { result, isError } = await invokeClaudeStreaming({
-			prompt: buildSelectPrompt({
-				changed: productChanges,
-				specs: undecided,
-				base,
-				head
-			}),
-			systemPrompt: buildSelectSystemPrompt(),
-			allowedTools: [
-				"Read",
-				"Grep",
-				"Glob"
-			],
-			silenceBashLog: true,
-			cwd,
-			...model ? { model } : {}
-		}, (_msg) => {});
-		if (isError) {
-			lastError = "the selection model returned an error";
-			continue;
-		}
-		const json = extractJsonBlock(result);
-		if (!json) {
-			lastError = "the selection model returned no JSON block";
-			continue;
-		}
-		try {
-			parsed = JSON.parse(json);
-			lastError = "";
-			break;
-		} catch (e) {
-			lastError = `the selection model's JSON did not parse: ${e.message}`;
-		}
-	}
-	if (lastError) return abandonSelection(undecided, `${lastError} (${MAX_ATTEMPTS} attempts)`);
-	const changedPaths = new Set(productChanges.map((f) => f.path));
-	const byUndecidedKey = new Map(undecided.map((s) => [specKey(s), s]));
-	const answers = /* @__PURE__ */ new Map();
-	for (const raw of readSpecArray(parsed)) {
-		const spec = byUndecidedKey.get(raw.spec);
-		if (!spec) continue;
-		answers.set(raw.spec, {
+* Hold each undecided spec's last measured reach against the diff.
+*
+* Three outcomes, and only the middle one is a positive claim: no
+* measurement means `unknown` (an unmeasured edge is not an unreached one —
+* the absence of evidence runs the spec); a non-empty intersection means
+* `needed`, with the intersecting paths as the reason; an empty one means
+* `notNeeded` — the measurement accounts for everything the spec reached,
+* and the diff missed all of it. Changes outside the measured root fall out
+* of the comparison entirely: the root is the declared boundary of what
+* measurement governs, so what lies beyond it clears specs quietly — one
+* warning names the dropped paths, because a root configured too narrow
+* looks exactly like this and hides real reach (see docs/coverage.md).
+*/
+async function judgeWithCoverage(input) {
+	const { pending, productChanges, cwd, edges } = input;
+	const noMeasurement = "no measurement to consult: the hub holds no measured reach for this spec";
+	if (edges.size === 0) return pending.map((s) => unknownSelection(s, noMeasurement));
+	const measuredChanges = rerootChangesForCoverage(productChanges, await resolveCoverageRoots(productChanges, cwd));
+	const dropped = productChanges.length - measuredChanges.length;
+	if (dropped > 0) warn(`select-specs: ${dropped} of ${productChanges.length} changed files fall outside coverage.projectRoot and cannot be compared against measured reach`);
+	return pending.map((spec) => {
+		const edge = edges.get(specKey(spec));
+		if (!edge) return unknownSelection(spec, noMeasurement);
+		const touchedBy = measuredChanges.filter((c) => edge.files.has(c.measured)).map((c) => c.original);
+		if (touchedBy.length > 0) return {
 			featureName: spec.featureName,
 			specName: spec.specName,
-			verdict: raw.verdict,
-			source: "model",
-			reason: raw.reason,
-			...raw.verdict === "needed" ? { touchedBy: raw.touchedBy.filter((p) => changedPaths.has(p)) } : {}
-		});
-	}
-	const missing = undecided.filter((s) => !answers.has(specKey(s)));
-	if (missing.length > 0) warn(`select-specs: the model omitted ${missing.length} spec(s); treating them as unknown`);
-	return [...answers.values(), ...allUnknown(missing, "the selection model did not return a verdict for this spec")];
+			verdict: "needed",
+			source: "coverage",
+			reason: "the change touches files this spec's last measured run reached",
+			touchedBy
+		};
+		return {
+			featureName: spec.featureName,
+			specName: spec.specName,
+			verdict: "notNeeded",
+			source: "coverage",
+			reason: "the spec's last measured run reached none of the changed files"
+		};
+	});
+}
+function unknownSelection(spec, reason) {
+	return {
+		featureName: spec.featureName,
+		specName: spec.specName,
+		verdict: "unknown",
+		source: "coverage",
+		reason
+	};
 }
 /**
-* Pull the well-formed entries out of the model's reply, ignoring the rest.
-* Validated per element (`safeParse`), not as one `z.array(...)`, so one
-* malformed entry doesn't discard every other spec's verdict — see
-* `SelectRawAnswerSchema`'s doc.
+* Re-root diff paths to the measurement's own base. The two sides must speak
+* the same paths or every intersection silently misses (ADR-0024): the diff
+* is cwd-relative (repo-root relative for `outsideCwd` entries) while
+* measured files are `coverage.projectRoot`-relative. A file resolving
+* outside the coverage root is dropped — the measurement drops those files
+* too, so it could never intersect an edge.
 */
-function readSpecArray(parsed) {
-	const reply = SelectModelReplySchema.safeParse(parsed);
-	if (!reply.success) return [];
+function rerootChangesForCoverage(changed, roots) {
 	const out = [];
-	for (const entry of reply.data.specs) {
-		const raw = SelectRawAnswerSchema.safeParse(entry);
-		if (raw.success) out.push(raw.data);
+	for (const file of changed) {
+		const base = file.outsideCwd ? roots.repoRoot : roots.cwd;
+		if (base === null) continue;
+		const measured = relative(roots.coverageRoot, resolve(base, file.path)).replaceAll("\\", "/");
+		if (measured.startsWith("..")) continue;
+		out.push({
+			original: file.path,
+			measured
+		});
 	}
 	return out;
 }
 /**
-* The selection call failed as a whole: every spec becomes `unknown`, and the
-* reason is warned about rather than only recorded per spec.
+* The roots `rerootChangesForCoverage` needs: `coverage.projectRoot` from
+* `.ccqa/config.yaml` (defaults to cwd), and the git repo root — resolved
+* only when an `outsideCwd` entry exists to anchor.
 *
-* Without the warning the caller reports "N specs could not be decided" and
-* runs them all — which is the safe outcome, but indistinguishable from a
-* genuinely ambiguous diff. A wrong model name or an expired credential would
-* quietly cost a full suite run every time.
+* The projectRoot goes through the measurement's own `resolveRoot` — env refs
+* expanded, the directory verified to exist and contain cwd — and a config it
+* rejects fails here too. Resolving it any other way would silently re-root
+* every path somewhere the measurement never stored files under.
 */
-function abandonSelection(specs, reason) {
-	warn(`select-specs: ${reason} — every spec is left undecided and will run`);
-	return allUnknown(specs, reason);
+async function resolveCoverageRoots(changed, cwd) {
+	const coverageRoot = await resolveRoot(cwd, (await loadProjectConfig(cwd)).coverage?.projectRoot) ?? resolve(cwd);
+	let repoRoot = null;
+	if (changed.some((f) => f.outsideCwd)) try {
+		const { stdout } = await execFileP("git", ["rev-parse", "--show-toplevel"], { cwd });
+		repoRoot = stdout.trim();
+	} catch {}
+	return {
+		cwd: resolve(cwd),
+		repoRoot,
+		coverageRoot
+	};
 }
-function allUnknown(specs, reason) {
-	return specs.map((s) => ({
-		featureName: s.featureName,
-		specName: s.specName,
-		verdict: "unknown",
-		source: "model",
-		reason
-	}));
+//#endregion
+//#region src/select/coverage-edges.ts
+/**
+* How many recent hub runs are probed for report-row coverage. Bounded
+* because every probe downloads a whole report.json; past this many runs a
+* measurement is old enough that treating it as absent — `unknown`, so the
+* spec runs — is the safer answer anyway. The stream side carries its own
+* bound: the hub lists at most its newest twenty measured runs.
+*/
+const MAX_REPORT_RUNS = 20;
+/**
+* How old a measurement may be and still decide a spec. The same fourteen
+* days the stream store retains events for (`COVERAGE_RETENTION_DAYS`): past
+* it an edge is too stale to clear a spec with confidence, so it is not
+* adopted and the spec degrades to `unknown` — which runs.
+*/
+const EDGE_MAX_AGE_MS = 336 * 60 * 60 * 1e3;
+/**
+* Read every spec's most recent measured reach from the hub.
+*
+* Never throws: a hub that cannot be read yields an empty map (warned), which
+* the selection degrades to `unknown` across the board — the caller runs
+* those specs, so an unreadable hub costs runs, never a skipped regression.
+*/
+async function loadCoverageEdges(input) {
+	const edges = /* @__PURE__ */ new Map();
+	const freshAfter = Date.now() - EDGE_MAX_AGE_MS;
+	const merge = (key, edge) => {
+		if (edge.measuredAt < freshAfter) return;
+		const existing = edges.get(key);
+		if (!existing || edge.measuredAt > existing.measuredAt) edges.set(key, edge);
+	};
+	const results = await Promise.allSettled([collectStreamEdges(input, merge), collectReportEdges(input, merge)]);
+	let skipped = 0;
+	for (const result of results) if (result.status === "rejected") warn(`select-specs: could not read coverage measurements from the hub (${errMessage(result.reason)})`);
+	else skipped += result.value;
+	if (skipped > 0) warn(`select-specs: ${skipped} measured run(s) on the hub could not be read; their reach is treated as absent`);
+	return edges;
+}
+/**
+* Edges from the coverage event stream. The plain read answers for the most
+* recently measured run and lists every run the stream retains; each older
+* run is then resolved individually. Returns how many runs could not be read.
+*/
+async function collectStreamEdges(input, merge) {
+	const { hub, project } = input;
+	const latest = await hub.getCoverage(project);
+	ingestResolved(latest.resolved, merge);
+	const older = latest.runIds.filter((runId) => runId !== latest.resolved?.runId);
+	return (await Promise.allSettled(older.map(async (runId) => ingestResolved((await hub.getCoverage(project, { runId })).resolved, merge)))).filter((r) => r.status === "rejected").length;
+}
+function ingestResolved(resolved, merge) {
+	if (!resolved) return;
+	for (const spec of resolved.specs) {
+		const key = stripRunIdPrefix(spec.specId, resolved.runId);
+		if (key === null) continue;
+		if (spec.files.length === 0) continue;
+		merge(key, {
+			files: new Set(spec.files),
+			measuredAt: resolved.asOf
+		});
+	}
+}
+/**
+* A stream specId is `<runId>.<feature>/<spec>` (src/coverage/session.ts).
+* The runId itself may contain `.`, so the known prefix is stripped by
+* length, never by splitting on the dot.
+*/
+function stripRunIdPrefix(specId, runId) {
+	return specId.startsWith(`${runId}.`) ? specId.slice(runId.length + 1) : null;
+}
+/**
+* The one slice of report.json this consumer reads. Parsed with its own
+* narrow schema rather than the full report schema so a report from another
+* ccqa version still yields its edges as long as this shape holds.
+*/
+const ReportCoverageRowsSchema = z.object({ results: z.array(z.object({
+	feature: z.string(),
+	spec: z.string(),
+	coverage: z.object({ files: z.array(z.string()) }).optional()
+})) });
+/**
+* Edges from pushed run reports, newest first. Only `kind: run` runs are
+* probed — audits and recordings execute no specs, so they carry no reach —
+* and a still-`running` run is skipped: its rows are still arriving, so its
+* measurement is not settled. Returns how many reports could not be read.
+*/
+async function collectReportEdges(input, merge) {
+	const { hub, project } = input;
+	const eligible = (await hub.listRuns({
+		project,
+		kind: "run",
+		limit: MAX_REPORT_RUNS
+	})).flatMap((run) => {
+		if (run.status === "running") return [];
+		const measuredAt = Date.parse(run.createdAt);
+		if (Number.isNaN(measuredAt)) return [];
+		return [{
+			id: run.id,
+			measuredAt
+		}];
+	});
+	return (await Promise.allSettled(eligible.map(async ({ id, measuredAt }) => {
+		const parsed = ReportCoverageRowsSchema.safeParse(await hub.getReport(id));
+		if (!parsed.success) return;
+		for (const row of parsed.data.results) {
+			if (!row.coverage || row.coverage.files.length === 0) continue;
+			merge(`${row.feature}/${row.spec}`, {
+				files: new Set(row.coverage.files),
+				measuredAt
+			});
+		}
+	}))).filter((r) => r.status === "rejected").length;
 }
 //#endregion
 //#region src/select/inventory.ts
@@ -11243,6 +11351,68 @@ function describeStep(step) {
 function oneLine$1(text) {
 	return text.trim().replace(/\s+/g, " ");
 }
+function emptyDeployLog() {
+	return {
+		nextIndex: 0,
+		entries: []
+	};
+}
+/** Append `input` to `current`; the appended entry is always the last of `entries`. */
+function appendDeploy(current, input) {
+	const log = current ?? emptyDeployLog();
+	const head = log.entries[log.entries.length - 1];
+	const gapBefore = head ? head.sha !== input.previousSha : log.nextIndex > 0;
+	const entries = [...log.entries, {
+		...input,
+		index: log.nextIndex,
+		changedPaths: input.changedPaths === null ? null : input.changedPaths.slice(0, 500),
+		gapBefore
+	}];
+	if (entries.length > 200) {
+		entries.splice(0, entries.length - 200);
+		entries[0] = {
+			...entries[0],
+			gapBefore: true
+		};
+	}
+	return {
+		nextIndex: log.nextIndex + 1,
+		entries
+	};
+}
+/**
+* Fold one deploy's selection into the touch index.
+*
+* Only `needed` moves a position a verdict reads. An `unknown` records the
+* newest undecided position too, but that one is record-only (ADR-0023) —
+* freshness reads an undecided judgment as "did not reach". A `notNeeded`
+* writes neither — it is the absence of a marker at this position, which is
+* exactly what a later baseline comparison reads it as.
+*
+* Positions only ever advance. Deploys are folded in log order, so a spec
+* needed at #7 and cleared at #9 keeps `needed.index: 7`: a baseline at #5
+* must still see that #7 touched it.
+*/
+function foldTouchIndex(current, entry, selection) {
+	const out = { ...current };
+	for (const [key, decision] of Object.entries(selection)) {
+		const previous = out[key] ?? {};
+		if (decision.verdict === "needed") out[key] = {
+			...previous,
+			needed: {
+				index: entry.index,
+				sha: entry.sha,
+				at: entry.at,
+				matchedPaths: (decision.touchedBy ?? []).slice(0, 10)
+			}
+		};
+		else if (decision.verdict === "unknown") out[key] = {
+			...previous,
+			undecidedIndex: entry.index
+		};
+	}
+	return out;
+}
 //#endregion
 //#region src/cli/session.ts
 const AB = resolveAgentBrowserBin$1();
@@ -11530,8 +11700,8 @@ const promptRm = new Command("rm").description("Delete a prompt from the hub.").
 	info(`deleted prompt "${name}" from the hub`);
 }));
 const promptCommand = new Command("prompt").description("Manage prompt assets (per-flow user/agent guidance, triage/audit user guidance, learned calibration prompts) stored on the hub (fetched automatically by `ccqa run` / `ccqa audit` at run time).").addCommand(promptPush).addCommand(promptLs).addCommand(promptRm);
-const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --only-hub-rerun-needed`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Omit it and the hub's current log head is used — the normal case, recording no discontinuity. Pass a sha that differs from the head and the hub records one (gapBefore) in the chain: use this for a first record with a real baseline, or to re-anchor a head that no longer matches reality. With no head and nothing passed, there's nothing to diff against: changedPaths is unset and the spec selection is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--no-select-specs", "Record the deploy without deciding which specs it reaches. The entry then becomes a hole in the range — every spec behind it is assumed reached rather than being cleared, and nothing can fill it in later, since the hub has no checkout to diff. Only pass this when no Claude credential is available; it costs one model call to leave the range clearable.").option("-m, --model <name>", "Model for the spec selection. Claude alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
-	await withCostReporting("hub deploy record", () => runDeployRecord(opts));
+const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --only-hub-rerun-needed`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Omit it and the hub's current log head is used — the normal case, recording no discontinuity. Pass a sha that differs from the head and the hub records one (gapBefore) in the chain: use this for a first record with a real baseline, or to re-anchor a head that no longer matches reality. With no head and nothing passed, there's nothing to diff against: changedPaths is unset and the spec selection is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--no-select-specs", "Record the deploy without deciding which specs it reaches. The entry then becomes a hole in the range — every spec behind it is assumed reached rather than being cleared, and nothing can fill it in later, since the hub has no checkout to diff. The decision intersects the diff with measured coverage from the hub and calls no model, so there is rarely a reason to skip it.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
+	await runDeployRecord(opts);
 }));
 async function runDeployRecord(opts) {
 	const cwd = resolveCwd(opts.cwd);
@@ -11541,7 +11711,7 @@ async function runDeployRecord(opts) {
 	const runUrl = githubRunUrl();
 	const diff = previous === null ? null : await diffOrNull(previous, opts.sha, cwd);
 	const changedPaths = diff ? capDeployPaths(diff.map((f) => f.path)) : null;
-	const selection = opts.selectSpecs !== false && previous !== null && diff !== null ? await selectionForDeploy(diff, previous, opts.sha, cwd, opts.model) : void 0;
+	const selection = opts.selectSpecs !== false && previous !== null && diff !== null ? await selectionForDeploy(hub, project, diff, previous, opts.sha, cwd) : void 0;
 	const entry = await hub.recordDeploy(project, opts.profile, {
 		sha: opts.sha,
 		previousSha: previous,
@@ -11569,11 +11739,13 @@ async function runDeployRecord(opts) {
 * Takes the diff `deployRecord` already fetched for `changedPaths`, rather
 * than diffing again — the decision needs the diff and the spec tree, and the
 * hub has neither, but there's no reason to ask git for the same range twice.
+* The hub does hold the coverage measurements the verdicts rest on, so those
+* are read back through the same connection the entry is posted over.
 * `undefined` on failure rather than a half-answer: the deploy is then
 * recorded without a selection, and specs behind it read `unknown` instead of
 * being cleared by a selection that isn't there.
 */
-async function selectionForDeploy(changed, previous, sha, cwd, model) {
+async function selectionForDeploy(hub, project, changed, previous, sha, cwd) {
 	try {
 		const specs = await loadSpecInventory(cwd);
 		if (specs.length === 0) return void 0;
@@ -11583,12 +11755,15 @@ async function selectionForDeploy(changed, previous, sha, cwd, model) {
 			cwd,
 			base: previous,
 			head: sha,
-			...model ? { model } : {}
+			edges: await loadCoverageEdges({
+				hub,
+				project
+			})
 		});
 		return Object.fromEntries(report.specs.map((s) => [specKey(s), {
 			verdict: s.verdict,
 			reason: s.reason,
-			...s.touchedBy?.length ? { touchedBy: s.touchedBy } : {}
+			...s.touchedBy?.length ? { touchedBy: s.touchedBy.slice(0, 10) } : {}
 		}]));
 	} catch (err) {
 		warn(`could not decide which specs this deploy reaches (${errMessage(err)}); recording the deploy without a selection`);
@@ -12851,155 +13026,6 @@ function oneLine(s) {
 	return s.replace(/\s+/g, " ").trim();
 }
 //#endregion
-//#region src/config/project-config.ts
-/**
-* Loader for the consumer project's `.ccqa/config.yaml` — per-target
-* generation settings (default target, output dirs, reusable code resources,
-* generation conventions).
-*
-* This module only validates and holds the config. `path` / `guides` /
-* `examples` entries may be glob patterns; they are kept verbatim here and
-* expanded by the generation engine, which owns size limits and warnings.
-*/
-/**
-* An existing code asset the generated tests should reuse (import), in one of
-* two forms — exactly one of:
-*   - `path`: code inside the consumer repo (literal path or glob pattern);
-*   - `package`: an installed npm package (imported by name).
-* `description` tells the generator what the asset contains.
-*/
-const ResourceRefSchema = z.union([z.object({
-	path: z.string().min(1),
-	description: z.string().optional()
-}).strict(), z.object({
-	package: z.string().min(1),
-	description: z.string().optional()
-}).strict()], { error: "a resource must have exactly one of `path` (code in this repo) or `package` (installed npm package), plus an optional `description`" });
-/**
-* How generated code should be written, as guide inputs to the prompt (never
-* imported as code): `guides` are convention documents, `examples` are
-* existing tests whose style to imitate. Entries may be glob patterns.
-*/
-const ConventionsSchema = z.object({
-	guides: z.array(z.string().min(1)).default([]),
-	examples: z.array(z.string().min(1)).default([])
-}).strict();
-/**
-* Per-target settings. `outDir` (where generated tests are written) and
-* `runCommand` (how to execute them; `{files}` expands to the generated
-* paths, `{artifactsDir}` to the spec's report artifacts dir — see
-* src/targets/run-artifacts.ts) are optional at this layer because not every
-* target needs them — e.g. agent-browser stores its output in the spec
-* directory. A target that requires either must validate its presence itself.
-*/
-const TargetConfigSchema = z.object({
-	outDir: z.string().min(1).optional(),
-	runCommand: z.string().min(1).optional(),
-	resources: z.array(ResourceRefSchema).default([]),
-	conventions: ConventionsSchema.default({
-		guides: [],
-		examples: []
-	})
-}).strict();
-/**
-* Specs that must not run at the same time, grouped by the thing they share.
-*
-* The key names the shared thing (a chat channel, a seeded account, a tenant);
-* the list names the specs that write to it. `ccqa run` never runs two members
-* of one group concurrently, and specs sharing no group still run in parallel.
-*
-* Kept here rather than on each spec so there is one place to read the whole
-* picture, and so a mistyped member is a spec key that does not resolve —
-* caught — rather than a resource name that silently matches nothing.
-*/
-const SerialGroupsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "serial group name must be a slug (letters, digits, '.', '_', '-')"), z.array(z.string().min(1)).min(1));
-/**
-* Which specs act as which external identity, for the flows whose requests
-* cannot carry a spec id at all.
-*
-* A chat platform's webhook is sent by the platform, not the browser, so no
-* cookie rides along and everything the flow reaches would be unattributed.
-* What the request does carry is who caused it, and if only one spec is allowed
-* to act as that identity at a time, "who" plus "when" is enough.
-*
-* ```yaml
-* coverage:
-*   actors:
-*     slack:                      # the preset's tag prefix
-*       ${TEST_USER_ID}: [chat/create-item, chat/resolve-item]
-* ```
-*
-* The provider name is the prefix the matching preset stamps, and the key is an
-* identity expression the run's variables resolve. Only the unexpanded text is
-* ever displayed or used as a lock key, so the identity itself stays out of
-* reports and the hub.
-*/
-const CoverageActorsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "actor provider must be a slug (letters, digits, '.', '_', '-')"), z.record(z.string().min(1), z.array(z.string().min(1)).min(1)));
-/**
-* Settings for `ccqa run --coverage`, which measures what each spec actually
-* reached in the application under test.
-*/
-const CoverageConfigSchema = z.object({
-	instrumentedOrigins: z.array(z.string().min(1)).min(1),
-	sink: z.string().min(1).default("http://127.0.0.1:4757"),
-	projectRoot: z.string().min(1).optional(),
-	include: z.array(z.string().min(1)).optional(),
-	actors: CoverageActorsSchema.default({})
-}).strict();
-/**
-* Top-level `.ccqa/config.yaml` schema. `defaultTarget` is used by specs
-* with no `target:` of their own. Both defaults make a missing config file
-* equivalent to "agent-browser only, no extra settings".
-*/
-const ProjectConfigSchema = z.object({
-	defaultTarget: TargetIdSchema.default(AGENT_BROWSER_TARGET),
-	targets: z.record(TargetIdSchema, TargetConfigSchema).default({}),
-	serialGroups: SerialGroupsSchema.default({}),
-	coverage: CoverageConfigSchema.optional()
-}).strict();
-/** Config file location, relative to the project root (`--cwd`). */
-const PROJECT_CONFIG_PATH = ".ccqa/config.yaml";
-/**
-* Load `<cwd>/.ccqa/config.yaml`. A missing file yields the defaults (an
-* empty file too); a present but broken file is an error — never silently
-* fall back when the user wrote a config.
-*/
-async function loadProjectConfig(cwd) {
-	let content;
-	try {
-		content = await readFile(join(cwd, PROJECT_CONFIG_PATH), "utf8");
-	} catch (e) {
-		if (e.code === "ENOENT") return ProjectConfigSchema.parse({});
-		throw e;
-	}
-	return parseProjectConfig(content);
-}
-/** Parse config YAML. Schema rejections are rewritten with actionable messages. */
-function parseProjectConfig(content, source = PROJECT_CONFIG_PATH) {
-	let raw;
-	try {
-		raw = parse(content);
-	} catch (e) {
-		throw new Error(`Failed to parse YAML (${source}): ${e.message}`);
-	}
-	try {
-		return ProjectConfigSchema.parse(raw ?? {});
-	} catch (e) {
-		throw enrichZodError(e, source);
-	}
-}
-/** Flatten a ZodError into one `Invalid <source>:` message, path per line. */
-function enrichZodError(error, source) {
-	if (!(error instanceof ZodError)) return error;
-	const lines = [`Invalid ${source}:`];
-	for (const issue of error.issues) {
-		const path = issue.path.join(".") || "(root)";
-		const message = issue.code === "invalid_key" && issue.issues[0] ? issue.issues[0].message : issue.message;
-		lines.push(`  - ${path}: ${message}`);
-	}
-	return new Error(lines.join("\n"));
-}
-//#endregion
 //#region src/coverage/inbox.ts
 /**
 * The run's side of the hub coverage inbox (ADR-0022). Under
@@ -15289,28 +15315,58 @@ function stripCodeFences(text) {
 	return m && m[1] !== void 0 ? m[1] : text;
 }
 //#endregion
+//#region src/select/types.ts
+/**
+* How the verdict was reached. Kept because the two sources have different
+* trust: `mechanical` is set arithmetic on paths and cannot be wrong;
+* `coverage` intersects the diff with the spec's last measured reach
+* (ADR-0024), which can only be wrong through staleness — and staleness
+* degrades to `unknown`, never to a guess.
+*/
+const SelectSourceSchema = z.enum(["mechanical", "coverage"]);
+const SpecSelectionSchema = z.object({
+	featureName: z.string().min(1),
+	specName: z.string().min(1),
+	verdict: SelectVerdictSchema,
+	source: SelectSourceSchema,
+	reason: z.string(),
+	touchedBy: z.array(z.string()).optional()
+});
+z.object({
+	base: z.string(),
+	head: z.string(),
+	changedFiles: z.number().int().nonnegative(),
+	specs: z.array(SpecSelectionSchema)
+});
+/** Specs the caller should actually run: everything not positively cleared. */
+function specsToRun(report) {
+	return report.specs.filter((s) => s.verdict !== "notNeeded");
+}
+//#endregion
 //#region src/cli/changed-specs.ts
 /**
 * Filter specs to those a range of commits reaches. Powers `ccqa run
 * --only-affected-by <ref>`; `ccqa audit` uses the same call.
 *
-* The decision is made by `ccqa select-specs`, which reads the diff against
-* what each spec actually does. That costs one model call, against saving the
-* runs it excludes — the specs it clears are the expensive part.
+* The decision is made by `ccqa select-specs`, which intersects the diff with
+* each spec's last measured reach from the hub (ADR-0024). Deterministic and
+* free — no model call — and wrong in only one direction: a spec without a
+* measurement comes back `unknown` and runs.
 *
 * Specs come back `needed`, `notNeeded` or `unknown`; everything but
-* `notNeeded` runs. `unknown` is the selector saying it could not tell, and
-* the safe reading of that is to run the spec.
+* `notNeeded` runs. `unknown` is the selector saying it has no measurement to
+* consult, and the safe reading of that is to run the spec.
 */
 async function collectChangedSpecs(specs, opts) {
-	const { cwd, base, model, quiet, flagName } = opts;
-	const resolved = await resolveAnalysisBase(base, flagName ?? "--only-affected-by", cwd);
+	const { cwd, base, hub, quiet, flagName } = opts;
+	const flag = flagName ?? "--only-affected-by";
+	const resolved = await resolveAnalysisBase(base, flag, cwd);
 	const meta$1 = (key, value) => {
 		if (!quiet) meta(key, value);
 	};
 	let changed;
 	try {
-		changed = await getChangedFilesBetween(resolved.sha, "HEAD", cwd);
+		changed = await getChangedFilesBetween(resolved.sha, "HEAD", cwd, { detectRenames: false });
 	} catch (e) {
 		throw new RunUsageError(`failed to run 'git diff' against ${resolved.ref}: ${e.message}`);
 	}
@@ -15326,13 +15382,16 @@ async function collectChangedSpecs(specs, opts) {
 	} catch (e) {
 		throw new RunUsageError(e.message);
 	}
+	let edges = /* @__PURE__ */ new Map();
+	if (hub) edges = await loadCoverageEdges(hub);
+	else warn(`${flag}: no hub connection, so coverage measurements cannot be consulted — undecided specs will run`);
 	const report = await selectSpecs({
 		changed,
 		specs: inventory,
 		cwd,
 		base: resolved.sha,
 		head: "HEAD",
-		...model ? { model } : {}
+		edges
 	});
 	const toRun = new Set(specsToRun(report).map(specKey));
 	const undecided = report.specs.filter((s) => s.verdict === "unknown").length;
@@ -15588,7 +15647,7 @@ async function executeRun(targets, opts) {
 		if (opts.onlyAffectedBy) specs = (await collectChangedSpecs(specs, {
 			cwd,
 			base: opts.onlyAffectedBy,
-			...opts.model ? { model: opts.model } : {}
+			hub: hubCtx
 		})).specs;
 		meta("selected", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
 		if (specs.length === 0 && inProgress > 0) {
@@ -16501,7 +16560,7 @@ function installTeardownSignalHandlers(teardown, onSignal) {
 }
 //#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, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed — including every spec the deploy log cannot place, which is assumed reached rather than skipped. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Specs in the same `serialGroups` entry of .ccqa/config.yaml still take turns. Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (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, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed — including every spec the deploy log cannot place, which is assumed reached rather than skipped. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Specs in the same `serialGroups` entry of .ccqa/config.yaml still take turns. Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--live-step-retry must be a non-negative integer, got "${raw}"`);
 	return n;
@@ -19041,8 +19100,7 @@ function freshness(baselineSha, key, range) {
 	const baselinePos = positionBySha.get(baselineSha);
 	if (baselinePos === void 0) return unanswerable("deployedShaNotInLog");
 	const baselineIndex = log.entries[baselinePos].index;
-	const touch = touchIndex[key];
-	const touched = touch?.needed;
+	const touched = touchIndex[key]?.needed;
 	if (touched && touched.index > baselineIndex) {
 		const entry = range.entryByIndex.get(touched.index);
 		return {
@@ -19053,7 +19111,6 @@ function freshness(baselineSha, key, range) {
 	}
 	if (range.gapFromPos[baselinePos + 1]) return unanswerable("gapInRange");
 	if (range.noSelectionFromPos[baselinePos + 1]) return unanswerable("noSelectionInRange");
-	if (touch?.undecidedIndex !== void 0 && touch.undecidedIndex > baselineIndex) return unanswerable("selectionUnknown");
 	return { kind: "current" };
 }
 function deployRef(entry) {
@@ -19220,7 +19277,7 @@ function selectSpecsNeedingAudit(targets, report, stillDrifted = /* @__PURE__ */
 //#endregion
 //#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Costs one model call; specs it cannot decide are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, one the hub cannot answer for is audited rather than skipped, and one whose drift entry is still open is always re-audited — a merged fix changes only the spec tree, which no deploy answer covers. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
+const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Specs without a measurement are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, one the hub cannot answer for is audited rather than skipped, and one whose drift entry is still open is always re-audited — a merged fix changes only the spec tree, which no deploy answer covers. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("audit", () => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {
@@ -19289,7 +19346,7 @@ async function runAudit(specPath, opts) {
 			cwd,
 			base: opts.onlyAffectedBy,
 			quiet: format !== "text",
-			...opts.model ? { model: opts.model } : {}
+			hub: resolveAuditHubContext(opts, cwd)
 		});
 		targets = selection.specs;
 		baseRef = selection.base.ref;
@@ -20062,26 +20119,40 @@ function parseSummaries(json) {
 //#endregion
 //#region src/cli/select-specs.ts
 const DEFAULT_HEAD = "HEAD";
-const selectSpecsCommand = new Command("select-specs").description("Decide which specs a range of commits reaches. Reads the diff and the spec inventory and returns one verdict per spec: needed | notNeeded | unknown.").requiredOption("--base <ref>", "Commit the range starts at — typically what is currently deployed, or the previous commit on the branch.").option("--head <ref>", `Commit the range ends at (default: ${DEFAULT_HEAD})`).option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Changes outside it are reported but never attributed to a spec. Defaults to process.cwd().").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--format <fmt>", "Output format: text | json", "text").action(async (opts) => {
-	await withCostReporting("select-specs", () => runSelectSpecs(opts));
-});
+const selectSpecsCommand = new Command("select-specs").description("Decide which specs a range of commits reaches. Intersects the diff with each spec's last measured reach from the hub (`ccqa run --coverage`) and returns one verdict per spec: needed | notNeeded | unknown. Requires a hub connection; a spec with no measurement is unknown, which runs.").requiredOption("--base <ref>", "Commit the range starts at — typically what is currently deployed, or the previous commit on the branch.").option("--head <ref>", `Commit the range ends at (default: ${DEFAULT_HEAD})`).option("--cwd <path>", "Working directory used as the .ccqa root. Changes outside it are reported but never attributed to a spec. Defaults to process.cwd().").option("--project <name>", "Project whose coverage measurements are read from the hub. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption).option("--format <fmt>", "Output format: text | json", "text").action(runSelectSpecs);
 async function runSelectSpecs(opts) {
 	const format = parseFormat(opts.format);
 	const cwd = resolveCwd(opts.cwd);
 	const head = opts.head ?? DEFAULT_HEAD;
-	const [specsResult, changedResult] = await Promise.all([loadSpecInventory(cwd).then((specs) => ({
-		ok: true,
-		specs
-	}), (e) => ({
-		ok: false,
-		error: e
-	})), getChangedFilesBetween(opts.base, head, cwd).then((changed) => ({
-		ok: true,
-		changed
-	}), (e) => ({
-		ok: false,
-		error: e
-	}))]);
+	const hub = resolveHubClient(opts);
+	if (!hub) {
+		error(needsHubConnection("select-specs"));
+		process.exit(2);
+	}
+	const project = resolveProject({
+		project: opts.project,
+		cwd: opts.cwd
+	});
+	const [specsResult, changedResult, edges] = await Promise.all([
+		loadSpecInventory(cwd).then((specs) => ({
+			ok: true,
+			specs
+		}), (e) => ({
+			ok: false,
+			error: e
+		})),
+		getChangedFilesBetween(opts.base, head, cwd, { detectRenames: false }).then((changed) => ({
+			ok: true,
+			changed
+		}), (e) => ({
+			ok: false,
+			error: e
+		})),
+		loadCoverageEdges({
+			hub,
+			project
+		})
+	]);
 	if (!specsResult.ok) {
 		error(specsResult.error.message);
 		process.exit(1);
@@ -20099,8 +20170,10 @@ async function runSelectSpecs(opts) {
 	if (format === "text") {
 		header("select-specs", `${opts.base} → ${head}`);
 		if (opts.cwd) meta("cwd", cwd);
+		meta("project", project);
 		meta("changed-files", changed.length);
 		meta("specs", specs.length);
+		meta("measured-specs", edges.size);
 	}
 	const report = await selectSpecs({
 		changed,
@@ -20108,7 +20181,7 @@ async function runSelectSpecs(opts) {
 		cwd,
 		base: opts.base,
 		head,
-		...opts.model ? { model: opts.model } : {}
+		edges
 	});
 	process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderText(report));
 	process.exit(0);
@@ -21268,67 +21341,6 @@ function createGetDriftLedgerHandler(storage) {
 		});
 	};
 }
-function emptyDeployLog() {
-	return {
-		nextIndex: 0,
-		entries: []
-	};
-}
-/** Append `input` to `current`; the appended entry is always the last of `entries`. */
-function appendDeploy(current, input) {
-	const log = current ?? emptyDeployLog();
-	const head = log.entries[log.entries.length - 1];
-	const gapBefore = head ? head.sha !== input.previousSha : log.nextIndex > 0;
-	const entries = [...log.entries, {
-		...input,
-		index: log.nextIndex,
-		changedPaths: input.changedPaths === null ? null : input.changedPaths.slice(0, 500),
-		gapBefore
-	}];
-	if (entries.length > 200) {
-		entries.splice(0, entries.length - 200);
-		entries[0] = {
-			...entries[0],
-			gapBefore: true
-		};
-	}
-	return {
-		nextIndex: log.nextIndex + 1,
-		entries
-	};
-}
-/**
-* Fold one deploy's selection into the touch index.
-*
-* Only the two positions that decide a verdict move: the newest deploy that
-* needed a spec, and the newest that could not decide it. A `notNeeded` writes
-* neither — it is the absence of a marker at this position, which is exactly
-* what a later baseline comparison reads it as.
-*
-* Positions only ever advance. Deploys are folded in log order, so a spec
-* needed at #7 and cleared at #9 keeps `needed.index: 7`: a baseline at #5
-* must still see that #7 touched it.
-*/
-function foldTouchIndex(current, entry, selection) {
-	const out = { ...current };
-	for (const [key, decision] of Object.entries(selection)) {
-		const previous = out[key] ?? {};
-		if (decision.verdict === "needed") out[key] = {
-			...previous,
-			needed: {
-				index: entry.index,
-				sha: entry.sha,
-				at: entry.at,
-				matchedPaths: (decision.touchedBy ?? []).slice(0, 10)
-			}
-		};
-		else if (decision.verdict === "unknown") out[key] = {
-			...previous,
-			undecidedIndex: entry.index
-		};
-	}
-	return out;
-}
 //#endregion
 //#region src/hub/api/handlers/deploys.ts
 /** `changedPaths` for a wide refactor can run to tens of thousands of entries. */
@@ -21366,7 +21378,7 @@ function createRecordDeployHandler(storage) {
 }
 /**
 * Record what this deploy's selection decided, so a later read can answer each
-* spec's own range with two integer comparisons.
+* spec's own range by comparing positions.
 *
 * It does not fail the request: the log is the record of what shipped and has
 * to land even if the fold cannot. What a lost fold must not do is *look* like