ccqa 1.11.0 → 1.13.0

package/dist/bin/ccqa.mjs

@@ -3326,7 +3326,7 @@ const DEFAULT_CONCURRENCY$1 = 3;
 /**
 * Run drift checks against a list of pre-collected targets. Pure library
 * function: no commander, no process.exit, no stdout writes. Callers handle
-* presentation. `cli/drift` does the full sweep with `--changed` scoping;
+* presentation. `cli/audit` does the full sweep with `--only-affected-by` scoping;
 * `cli/run` calls this with just the failing specs after vitest.
 */
 async function analyzeDrift(input) {
@@ -4426,16 +4426,6 @@ Write the runbook to \`${suggestedPath}\` unless the conventions/examples clearl
 //#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. Used by `ccqa run`'s resolveAnalysisBase (`src/run/git-context.ts`),
-* which both `ccqa run --changed` and `ccqa drift --changed` resolve their
-* base through, so the rule can't drift between them.
-*/
-function normalizeGithubBaseRef(ref) {
-	return ref.startsWith("origin/") ? ref : `origin/${ref}`;
-}
-/**
 * Paths that differ between `base` and `head` (two-dot: `git diff base..head`),
 * from `cwd`. Renames are reported under their NEW path with status
 * "renamed" — the OLD path is dropped since only the current layout matters.
@@ -5225,7 +5215,7 @@ const DraftNamingSchema = z.object({
 //#endregion
 //#region src/cli/draft.ts
 const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
-const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("--apply", "Auto-apply each generated patch without [y/N] confirmation", false)).action(withUsageErrors(async (specPath, opts) => {
+const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("-y, --yes", "Apply each generated patch without asking [y/N]", false)).action(withUsageErrors(async (specPath, opts) => {
 	await ensureCcqaDir();
 	let featureName;
 	let specName;
@@ -5262,7 +5252,7 @@ async function runDraft(featureName, specName, opts, prefilledIntent) {
 			specName,
 			existing,
 			userInput: userInput.trim(),
-			autoApply: opts.apply === true,
+			autoApply: opts.yes === true,
 			language: opts.language
 		});
 		if (oneShot) process.exit(turnResult.hasError && !turnResult.applied ? 1 : 0);
@@ -5482,7 +5472,7 @@ async function proposeNaming(opts) {
 	const final = ensureUnique(tree, sanitized.featureName, sanitized.specName);
 	meta("proposed", `${final.featureName}/${final.specName}`);
 	if (proposed.reason) meta("reason", proposed.reason);
-	if (oneShot || opts.apply === true) return {
+	if (oneShot || opts.yes === true) return {
 		naming: final,
 		intent: intent.trim()
 	};
@@ -6531,15 +6521,13 @@ function createDiffProvider(args) {
 }
 //#endregion
 //#region src/run/git-context.ts
-/** The `--failure-analysis` value that selects per-spec hub-ledger baselines. */
-const LAST_GREEN = "last-green";
 /**
-* The `--changed` value that selects specs from the hub's re-run verdicts
-* (`rerun-selection.ts` acts on it). Kept here beside `LAST_GREEN` so the two
-* "not a git ref" keywords, and the rules that reject each on the flag it does
-* not belong to, sit in one place.
+* Marks a baseline as "each spec's own last green commit" rather than one
+* shared ref. Not a flag value — `--on-fail-explain` uses per-spec baselines
+* unless `--on-fail-explain-base` names a ref — but the report and the log
+* lines need a word for it.
 */
-const LAST_RUN = "last-run";
+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 {
@@ -6555,35 +6543,17 @@ async function resolveCommitSha(ref, cwd) {
 	}
 }
 /**
-* 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.
+* Resolve a base ref to a verified baseline, failing fast — before any spec
+* runs — when it cannot be resolved. 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, baseExample) {
-	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 (flagValue === "last-run") throw new RunUsageError(`${flagName}=${LAST_RUN} is not supported — last-run selects which specs to run and only applies to --changed`);
-	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. ${baseExample ?? `${flagName}=origin/main`}`);
-		ref = normalizeGithubBaseRef(ghBase);
-		source = "github-base-ref";
-	}
+async function resolveAnalysisBase(ref, flagName, cwd) {
+	const source = "explicit";
 	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>.`);
+	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.`);
 	return {
 		ref,
 		sha,
@@ -6655,7 +6625,7 @@ async function fetchLastGreenLedger(hubCtx, profile, cwd) {
 			...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)}`);
+		throw new RunUsageError(`--on-fail-explain: 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}`;
@@ -6774,6 +6744,50 @@ function formatDryRunLines(agentBrowser, routed) {
 	return tagged.map((t) => `  ${t.key.padEnd(width)}  ${t.tag}`);
 }
 //#endregion
+//#region src/run/audited-clean.ts
+/**
+* Fetch the drift ledger and reduce it to the specs that are safe to run.
+*
+* A spec qualifies only when the ledger holds an entry for it *and* that entry
+* found no drift. A spec that has never been audited does not qualify: the
+* point of the flag is to spend a run only where a cheap audit already said
+* the spec still describes the code, and "never looked" is not that.
+*/
+async function fetchAuditedLedger(hubCtx) {
+	let ledger;
+	try {
+		ledger = await hubCtx.hub.getDriftLedger(hubCtx.project);
+	} catch (err) {
+		throw new RunUsageError(`--only-audited-clean: could not fetch the drift ledger from the hub: ${errMessage(err)}`);
+	}
+	const clean = /* @__PURE__ */ new Set();
+	const audited = /* @__PURE__ */ new Set();
+	for (const [key, entry] of Object.entries(ledger.specs)) {
+		audited.add(key);
+		if (entry.label === null) clean.add(key);
+	}
+	return {
+		clean,
+		audited
+	};
+}
+function selectAuditedClean(specs, ledger) {
+	const selected = [];
+	let unaudited = 0;
+	let drifted = 0;
+	for (const spec of specs) {
+		const key = specKey(spec);
+		if (ledger.clean.has(key)) selected.push(spec);
+		else if (ledger.audited.has(key)) drifted++;
+		else unaudited++;
+	}
+	return {
+		selected,
+		unaudited,
+		drifted
+	};
+}
+//#endregion
 //#region src/run/rerun-selection.ts
 /**
 * `ccqa run --changed=last-run`: select specs from the hub's re-run verdicts
@@ -6793,7 +6807,7 @@ const RERUN_MIN_HUB_VERSION = "1.9";
 * has no profile-free answer.
 */
 function requireRerunProfile(profile) {
-	if (profile === void 0) throw new RunUsageError(`--changed=${LAST_RUN} requires --profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one`);
+	if (profile === void 0) throw new RunUsageError("--only-stale requires --profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one");
 	return profile;
 }
 /**
@@ -6806,9 +6820,9 @@ async function fetchRerunReport(hubCtx, profile) {
 		report = await hubCtx.hub.getRerun(hubCtx.project, { profile });
 	} catch (err) {
 		if (err instanceof HubApiError && err.status === 404) throw new RunUsageError(explainNotFound(hubCtx, err));
-		throw new RunUsageError(`--changed=${LAST_RUN}: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
+		throw new RunUsageError(`--only-stale: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
 	}
-	if (report.deployHead === null) throw new RunUsageError(`--changed=${LAST_RUN}: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or pass an explicit baseline (--changed=<ref>).`);
+	if (report.deployHead === null) throw new RunUsageError(`--only-stale: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or pass an explicit baseline (--changed=<ref>).`);
 	return {
 		...report,
 		deployHead: report.deployHead
@@ -6820,8 +6834,8 @@ async function fetchRerunReport(hubCtx, profile) {
 * means the hub does not serve this route at all.
 */
 function explainNotFound(hubCtx, err) {
-	if (err.code === "no_perspectives") return `--changed=${LAST_RUN}: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
-	return `--changed=${LAST_RUN}: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or pass an explicit baseline (--changed=<ref>).`;
+	if (err.code === "no_perspectives") return `--only-stale: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
+	return `--only-stale: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or pass an explicit baseline (--changed=<ref>).`;
 }
 /** States the summary line reports, worst-known-first. */
 const SUMMARY_ORDER = [
@@ -8463,6 +8477,101 @@ function oneLine$1(text) {
 	return text.trim().replace(/\s+/g, " ");
 }
 //#endregion
+//#region src/cli/session.ts
+const AB = resolveAgentBrowserBin$1();
+/**
+* Run agent-browser attached to the user's terminal (no timeout, inherited
+* stdio) so a human can complete an interactive login during `bootstrap`.
+* Distinct from runtime/spawn-ab.ts, which pipes stdio and hard-times-out for
+* non-interactive automation.
+*/
+function runAbInteractive(args) {
+	return spawnSync(AB, args, { stdio: "inherit" }).status ?? 1;
+}
+function validateName(name) {
+	const parsed = SessionNameSchema.safeParse(name);
+	if (!parsed.success) {
+		error(`invalid session name "${name}": ${parsed.error.issues[0]?.message ?? "bad name"}`);
+		process.exit(2);
+	}
+	return parsed.data;
+}
+const profileOption$1 = ["--profile <name>", "Sessions bucket to read/write on the hub. Defaults to 'default'."];
+const projectOption$1 = ["--project <name>", "Project the session belongs to on the hub. Defaults to the current directory's name."];
+const sessionCaptureCommand = new Command("capture").description("Open a headed browser so you can log in by hand, then upload the resulting session (cookies + localStorage) to the hub for `session:` specs to restore.").argument("<name>", "Session name to save").option("--url <url>", "URL to open first (e.g. the login page). Omit to start with a blank tab.").option(...profileOption$1).option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option("--cwd <path>", "Directory the default --project name is derived from (defaults to the current directory).").action(async (rawName, opts) => {
+	const name = validateName(rawName);
+	resolveCwd(opts.cwd);
+	const project = resolveProject(opts);
+	let hub;
+	try {
+		hub = requireHubClient(opts);
+	} catch (err) {
+		if (!(err instanceof HubConnectionError)) throw err;
+		error(err.message);
+		process.exit(2);
+	}
+	header("session bootstrap", name);
+	meta("project", project);
+	meta("profile", opts.profile ?? "default");
+	blank();
+	const openArgs = [
+		"--headed",
+		"open",
+		...opts.url ? [opts.url] : ["about:blank"]
+	];
+	info("opening a browser — log in by hand, then return here.");
+	const openStatus = runAbInteractive(openArgs);
+	if (openStatus !== 0) {
+		error(`agent-browser open exited ${openStatus}`);
+		process.exit(1);
+	}
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	await rl.question("\nPress Enter once you are fully logged in to save the session… ");
+	rl.close();
+	const tmpDir = await mkdtemp(join(tmpdir(), "ccqa-session-bootstrap-"));
+	try {
+		const tmpPath = join(tmpDir, "state.json");
+		const saveStatus = runAbInteractive([
+			"state",
+			"save",
+			tmpPath
+		]);
+		runAbInteractive(["close"]);
+		if (saveStatus !== 0) {
+			error(`agent-browser state save exited ${saveStatus}`);
+			process.exit(1);
+		}
+		const state = await loadStorageState(tmpPath);
+		let payload = state;
+		if (opts.url) {
+			info("verifying the saved session restores to a signed-in page…");
+			const check = verifySessionRestores(tmpPath, opts.url);
+			if (!check.restored) {
+				error(`session did not restore cleanly: ${check.reason}`);
+				hint("fully load the application (sign in, open the target workspace/page, wait for it to settle) before pressing Enter, then run bootstrap again. Nothing was uploaded.");
+				process.exit(1);
+			}
+			info("restore verified — the session starts signed in.");
+			payload = {
+				...state,
+				[SESSION_VERIFY_URL_KEY]: opts.url
+			};
+		} else warn("no --url given — the session can't be verified now, and runs can't health-check it before executing steps; strongly consider re-running with --url <a signed-in page URL>.");
+		await hub.putSession(project, opts.profile ?? "default", name, payload);
+	} finally {
+		await rm(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	blank();
+	info(`uploaded session "${name}" to the hub (encrypted at rest)`);
+	hint("reference it from a spec with:  session: " + name);
+});
+//#endregion
 //#region src/cli/hub.ts
 /**
 * `ccqa hub` — the client side of the ccqa hub (a results/secret control
@@ -8473,8 +8582,8 @@ function oneLine$1(text) {
 * talk to the hub over the same public REST API (docs/hub-api.md) via
 * `ccqa/hub-client`.
 */
-const profileOption$1 = ["--profile <name>", "Profile bucket the session/variable belongs to. Defaults to 'default'."];
-const projectOption$1 = ["--project <name>", "Project the session/variable belongs to on the hub. Defaults to the current directory's name."];
+const profileOption = ["--profile <name>", "Profile bucket the session/variable belongs to. Defaults to 'default'."];
+const projectOption = ["--project <name>", "Project the session/variable belongs to on the hub. Defaults to the current directory's name."];
 const cwdOption = ["--cwd <path>", "Directory the default --project name is derived from (defaults to the current directory)."];
 /**
 * The hub base URL from flags / env (trailing slashes trimmed), or exit 2.
@@ -8511,7 +8620,7 @@ async function readStdin() {
 	for await (const chunk of process.stdin) chunks.push(chunk);
 	return Buffer.concat(chunks).toString("utf8");
 }
-const sessionPush = new Command("push").description("Upload a locally-saved browser session (.ccqa/sessions/<profile>/<name>.json) to the hub, so it's available for `ccqa run` to fetch at run time. Encrypted at rest on the hub.").argument("<name>", "Session name to upload (resolves to .ccqa/sessions/<profile>/<name>.json)").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option("--cwd <path>", "Project root containing .ccqa/ (defaults to the current directory).").action(withHubErrors(async (rawName, opts) => {
+const sessionPush = new Command("push").description("Upload a locally-saved browser session (.ccqa/sessions/<profile>/<name>.json) to the hub, so it's available for `ccqa run` to fetch at run time. Encrypted at rest on the hub.").argument("<name>", "Session name to upload (resolves to .ccqa/sessions/<profile>/<name>.json)").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option("--cwd <path>", "Project root containing .ccqa/ (defaults to the current directory).").action(withHubErrors(async (rawName, opts) => {
 	const name = validateSessionName(rawName);
 	const cwd = resolveCwd(opts.cwd);
 	const project = resolveProject(opts);
@@ -8531,7 +8640,7 @@ const sessionPush = new Command("push").description("Upload a locally-saved brow
 	meta("profile", profile);
 	info(`uploaded session "${name}" to the hub (encrypted at rest)`);
 }));
-const sessionLs = new Command("ls").description("List sessions stored on the hub for a project/profile (names + last-updated times). `ls` shows metadata only.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option(...cwdOption).action(withHubErrors(async (opts) => {
+const sessionLs = new Command("ls").description("List sessions stored on the hub for a project/profile (names + last-updated times). `ls` shows metadata only.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option(...cwdOption).action(withHubErrors(async (opts) => {
 	const project = resolveProject(opts);
 	const profile = opts.profile ?? "default";
 	const sessions = await connect(opts).listSessions(project, profile);
@@ -8542,7 +8651,7 @@ const sessionLs = new Command("ls").description("List sessions stored on the hub
 	}
 	for (const s of sessions) meta(s.name, `updated ${s.updatedAt}`);
 }));
-const sessionRm = new Command("rm").description("Delete a session from the hub.").argument("<name>", "Session name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
+const sessionRm = new Command("rm").description("Delete a session from the hub.").argument("<name>", "Session name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
 	const name = validateSessionName(rawName);
 	const project = resolveProject(opts);
 	const profile = opts.profile ?? "default";
@@ -8550,8 +8659,8 @@ const sessionRm = new Command("rm").description("Delete a session from the hub."
 	header("hub session rm", name);
 	info(`deleted session "${name}" from the hub`);
 }));
-const sessionCommand$1 = new Command("session").description("Manage browser sessions stored on the hub (fetched automatically by `ccqa run` / `ccqa record` at run time).").addCommand(sessionPush).addCommand(sessionLs).addCommand(sessionRm);
-const varSet = new Command("set").description("Store an environment variable on the hub, fetched at run time by `ccqa run` / `ccqa record`. Use --sensitive to hide the value from `ls` output (it is still returned in full to the run).").argument("<name>", "Variable name (e.g. BASE_URL)").option("--value <value>", "Variable value. Omit to read the value from stdin (better for secrets).").option("--sensitive", "Hide the value in `ls` output. Any token holder can still read it via the run-time fetch.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option(...cwdOption).action(withHubErrors(async (name, opts) => {
+const sessionCommand = new Command("session").description("Manage browser sessions stored on the hub (fetched automatically by `ccqa run` / `ccqa record` at run time).").addCommand(sessionCaptureCommand).addCommand(sessionPush).addCommand(sessionLs).addCommand(sessionRm);
+const varSet = new Command("set").description("Store an environment variable on the hub, fetched at run time by `ccqa run` / `ccqa record`. Use --sensitive to hide the value from `ls` output (it is still returned in full to the run).").argument("<name>", "Variable name (e.g. BASE_URL)").option("--value <value>", "Variable value. Omit to read the value from stdin (better for secrets).").option("--sensitive", "Hide the value in `ls` output. Any token holder can still read it via the run-time fetch.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option(...cwdOption).action(withHubErrors(async (name, opts) => {
 	const project = resolveProject(opts);
 	const profile = opts.profile ?? "default";
 	const value = opts.value ?? (await readStdin()).trim();
@@ -8569,7 +8678,7 @@ const varSet = new Command("set").description("Store an environment variable on
 	meta("sensitive", String(opts.sensitive ?? false));
 	info(`stored variable "${name}" on the hub`);
 }));
-const varLs = new Command("ls").description("List variables stored on the hub for a project/profile. Non-sensitive values are shown inline; sensitive ones are hidden here but still fetched at run time by `ccqa run` / `ccqa record`.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option(...cwdOption).action(withHubErrors(async (opts) => {
+const varLs = new Command("ls").description("List variables stored on the hub for a project/profile. Non-sensitive values are shown inline; sensitive ones are hidden here but still fetched at run time by `ccqa run` / `ccqa record`.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option(...cwdOption).action(withHubErrors(async (opts) => {
 	const project = resolveProject(opts);
 	const profile = opts.profile ?? "default";
 	const variables = await connect(opts).listVariables(project, profile);
@@ -8583,7 +8692,7 @@ const varLs = new Command("ls").description("List variables stored on the hub fo
 		meta(v.name, shown);
 	}
 }));
-const varRm = new Command("rm").description("Delete a variable from the hub.").argument("<name>", "Variable name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...profileOption$1).option(...cwdOption).action(withHubErrors(async (name, opts) => {
+const varRm = new Command("rm").description("Delete a variable from the hub.").argument("<name>", "Variable name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...profileOption).option(...cwdOption).action(withHubErrors(async (name, opts) => {
 	const project = resolveProject(opts);
 	const profile = opts.profile ?? "default";
 	await connect(opts).deleteVariable(project, profile, name);
@@ -8599,7 +8708,7 @@ function validatePromptName(rawName) {
 	}
 	return rawName;
 }
-const promptPush = new Command("push").description("Upload a locally-generated prompt asset to the hub, so it's available to other environments running against this project.").argument("<name>", `Prompt name (${PROMPT_NAMES.join(", ")})`).option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
+const promptPush = new Command("push").description("Upload a locally-generated prompt asset to the hub, so it's available to other environments running against this project.").argument("<name>", `Prompt name (${PROMPT_NAMES.join(", ")})`).option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
 	const name = validatePromptName(rawName);
 	const cwd = resolveCwd(opts.cwd);
 	const project = resolveProject(opts);
@@ -8622,7 +8731,7 @@ const promptPush = new Command("push").description("Upload a locally-generated p
 	meta("project", project);
 	info(`uploaded prompt "${name}" to the hub`);
 }));
-const promptLs = new Command("ls").description("List prompts stored on the hub for a project (name, kind, last-updated). Prompts are project-wide (not per-profile). `ls` shows metadata only.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...cwdOption).action(withHubErrors(async (opts) => {
+const promptLs = new Command("ls").description("List prompts stored on the hub for a project (name, kind, last-updated). Prompts are project-wide (not per-profile). `ls` shows metadata only.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (opts) => {
 	const project = resolveProject(opts);
 	const prompts = await connect(opts).listPrompts(project);
 	header("hub prompts", project);
@@ -8632,7 +8741,7 @@ const promptLs = new Command("ls").description("List prompts stored on the hub f
 	}
 	for (const p of prompts) meta(p.name, `${p.kind}, updated ${p.updatedAt}`);
 }));
-const promptRm = new Command("rm").description("Delete a prompt from the hub.").argument("<name>", "Prompt name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption$1).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
+const promptRm = new Command("rm").description("Delete a prompt from the hub.").argument("<name>", "Prompt name to delete").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (rawName, opts) => {
 	const name = validatePromptName(rawName);
 	const project = resolveProject(opts);
 	await connect(opts).deletePrompt(project, name);
@@ -8720,9 +8829,9 @@ function describeSelection(selection, diffAvailable) {
 	return `${values.filter((s) => s.verdict === "needed").length} needed / ${values.filter((s) => s.verdict === "unknown").length} unknown / ${values.length} specs`;
 }
 const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --changed=last-run`.").addCommand(deployRecord);
-const pushCommand = new Command("push").description("Upload the report directory of a finished `ccqa run --report` to the hub as a run. Run this after `ccqa run` (use `if: always()` in CI so failing runs are pushed too).").option("--report <dir>", `Report directory to push. Default: ${DEFAULT_REPORT_DIR}/`).option("--project <name>", "Logical project name for the run. Defaults to the current directory's name.").option("--branch <name>", "Branch label. Defaults to $GITHUB_HEAD_REF / $GITHUB_REF_NAME / current git branch.").option("--profile <name>", "Profile (environment) the run executed against. Recorded for display; runs are not scoped by profile.").option(...hubUrlOption).option(...hubTokenOption).option("--cwd <path>", "Directory the report dir is resolved against (defaults to the current directory).").action(withHubErrors(async (opts) => {
+const pushCommand = new Command("push").description("Upload the report directory of a finished `ccqa run --report` to the hub as a run. Run this after `ccqa run` (use `if: always()` in CI so failing runs are pushed too).").option("--report-dir <dir>", `Report directory to push. Default: ${DEFAULT_REPORT_DIR}/`).option("--project <name>", "Logical project name for the run. Defaults to the current directory's name.").option("--branch <name>", "Branch label. Defaults to $GITHUB_HEAD_REF / $GITHUB_REF_NAME / current git branch.").option("--profile <name>", "Profile (environment) the run executed against. Recorded for display; runs are not scoped by profile.").option(...hubUrlOption).option(...hubTokenOption).option("--cwd <path>", "Directory the report dir is resolved against (defaults to the current directory).").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
-	const reportDir = join(cwd, opts.report ?? "ccqa-report");
+	const reportDir = join(cwd, opts.reportDir ?? "ccqa-report");
 	const project = resolveProject(opts);
 	let report;
 	try {
@@ -8754,7 +8863,7 @@ const pushCommand = new Command("push").description("Upload the report directory
 	meta("specs", `${run.specs.passed}/${run.specs.total} passed`);
 	info(`${resolveBaseUrl(opts)}/#/runs/${run.id}`);
 }));
-const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(sessionCommand$1).addCommand(varCommand).addCommand(promptCommand);
+const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
 /** Loose check that a fetched session is agent-browser storage-state, mirroring loadStorageState. */
 function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
@@ -11929,14 +12038,14 @@ Write the new contents of \`${agentMdLabel}\`. Output ONLY the file contents —
 * so the run exit code is unaffected by this opt-in side step.
 */
 async function updateAgentPrompt(args) {
-	const { kind, runSummary, hubContext, model, language } = args;
+	const { kind, flag, runSummary, hubContext, model, language } = args;
 	const auth = driftAuthAvailable();
 	if (!auth.ok) {
-		warn(`--update-agent-prompt skipped (${auth.reason})`);
+		warn(`${flag} skipped (${auth.reason})`);
 		return;
 	}
 	if (!hubContext) {
-		warn("--update-agent-prompt skipped (hub connection required; pass --hub-url/--hub-token or set CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		warn(`${flag} skipped (hub connection required; pass --hub-url/--hub-token or set CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
 		return;
 	}
 	const { hub, project } = hubContext;
@@ -11950,7 +12059,7 @@ async function updateAgentPrompt(args) {
 		};
 		const systemPrompt = buildAgentUpdateSystemPrompt(promptInput);
 		const userPrompt = buildAgentUpdateUserPrompt(promptInput);
-		info(`--update-agent-prompt: refreshing prompt "${promptName}" on the hub (project ${project})`);
+		info(`${flag}: refreshing prompt "${promptName}" on the hub (project ${project})`);
 		const { result, isError } = await invokeClaudeStreaming({
 			prompt: userPrompt,
 			systemPrompt,
@@ -11960,20 +12069,20 @@ async function updateAgentPrompt(args) {
 			...model ? { model } : {}
 		}, () => {});
 		if (isError || !result || result.trim().length === 0) {
-			warn(`--update-agent-prompt: Claude returned no usable output${isError ? " (SDK error)" : ""}; leaving prompt "${promptName}" unchanged`);
+			warn(`${flag}: Claude returned no usable output${isError ? " (SDK error)" : ""}; leaving prompt "${promptName}" unchanged`);
 			return;
 		}
 		if (result.trim() === "NO_UPDATE") {
-			info(`--update-agent-prompt: no new learnings from this run; prompt "${promptName}" left unchanged`);
+			info(`${flag}: no new learnings from this run; prompt "${promptName}" left unchanged`);
 			return;
 		}
 		const newText = stripCodeFences(result.trim()) + "\n";
 		await hub.putPrompt(project, promptName, newText);
-		info(`--update-agent-prompt: updated prompt "${promptName}" on the hub`);
-		info("--update-agent-prompt: review it in the hub UI's Prompts tab");
+		info(`${flag}: updated prompt "${promptName}" on the hub`);
+		info(`${flag}: review it in the hub UI's Prompts tab`);
 	} catch (err) {
 		if (err instanceof HubApiError) {
-			warn(`--update-agent-prompt skipped (hub request failed: ${err.status} ${err.code}: ${err.message})`);
+			warn(`${flag} skipped (hub request failed: ${err.status} ${err.code}: ${err.message})`);
 			return;
 		}
 		throw err;
@@ -11992,7 +12101,7 @@ function stripCodeFences(text) {
 //#region src/cli/changed-specs.ts
 /**
 * Filter specs to those a range of commits reaches. Powers `ccqa run
-* --changed <ref>`; `ccqa drift --changed` uses the same call.
+* --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
@@ -12003,8 +12112,8 @@ function stripCodeFences(text) {
 * the safe reading of that is to run the spec.
 */
 async function collectChangedSpecs(specs, opts) {
-	const { cwd, base, model, quiet, baseExample } = opts;
-	const resolved = await resolveAnalysisBase(base, "--changed", cwd, baseExample);
+	const { cwd, base, model, quiet, flagName } = opts;
+	const resolved = await resolveAnalysisBase(base, flagName ?? "--only-affected-by", cwd);
 	const meta$2 = (key, value) => {
 		if (!quiet) meta(key, value);
 	};
@@ -12055,12 +12164,10 @@ async function resolveVitestConfig(cwd) {
 }
 /**
 * Resolve the report directory. A report (report.json + evidence) is always
-* written now, so this is never undefined: `--report <dir>` only picks *where*
-* it lands, defaulting to `DEFAULT_REPORT_DIR`. `--report` with no value (a
-* bare boolean flag) also means "default location".
+* written, so `--report-dir` only picks *where* it lands.
 */
-function resolveReportDir(report, cwd) {
-	return resolve(cwd, typeof report === "string" ? report : DEFAULT_REPORT_DIR);
+function resolveReportDir(reportDir, cwd) {
+	return resolve(cwd, reportDir ?? "ccqa-report");
 }
 /** De-dupe by `featureName/specName`, keeping first-seen order. */
 function dedupeSpecs(specs) {
@@ -12082,13 +12189,14 @@ function dedupeSpecs(specs) {
 * maps it to `process.exit(2)`).
 */
 async function executeRun(targets, opts) {
-	if (opts.changed && targets.length > 0) throw new RunUsageError("--changed and an explicit spec target cannot be combined");
-	const rerunProfile = opts.changed === "last-run" ? requireRerunProfile(opts.profile) : null;
-	if (opts.includeUnknown && rerunProfile === null) warn(`--include-unknown is ignored: it only applies to --changed=${LAST_RUN}`);
+	const filtering = Boolean(opts.onlyAffectedBy || opts.onlyStale || opts.onlyAuditedClean);
+	if (filtering && targets.length > 0) throw new RunUsageError("a --only-* filter and an explicit spec target cannot be combined");
+	const rerunProfile = opts.onlyStale === true ? requireRerunProfile(opts.profile) : null;
+	if (opts.onlyStaleWithUnknown && rerunProfile === null) warn("--only-stale-with-unknown is ignored: it only applies to --only-stale");
 	const forExecution = opts.dryRun !== true;
 	const cwd = opts.cwd ?? process.cwd();
-	const wantsLastGreen = opts.failureAnalysis === LAST_GREEN;
-	const [head, fixedBase] = await Promise.all([getGitHead(cwd), forExecution && opts.failureAnalysis && !wantsLastGreen ? resolveAnalysisBase(opts.failureAnalysis, "--failure-analysis", cwd) : null]);
+	const wantsLastGreen = opts.onFailExplain === true && opts.onFailExplainBase === void 0;
+	const [head, fixedBase] = await Promise.all([getGitHead(cwd), forExecution && opts.onFailExplain && opts.onFailExplainBase !== void 0 ? resolveAnalysisBase(opts.onFailExplainBase, "--on-fail-explain-base", cwd) : null]);
 	const git = {
 		head,
 		base: wantsLastGreen ? {
@@ -12140,15 +12248,17 @@ async function executeRun(targets, opts) {
 	} catch {
 		hubCtx = null;
 	}
-	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)`);
+	if (wantsLastGreen && hubCtx == null) throw new RunUsageError("--on-fail-explain needs a hub connection for the per-spec last-green baselines (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN), or an explicit --on-fail-explain-base <ref>");
 	const ledgerHub = wantsLastGreen ? hubCtx : null;
-	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError(`--changed=${LAST_RUN} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
-	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead] = await Promise.all([
+	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError("--only-stale requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.onlyAuditedClean && hubCtx == null) throw new RunUsageError("--only-audited-clean requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead, auditedLedger] = await Promise.all([
 		forExecution ? fetchCustomPrompt(hubCtx) : null,
 		forExecution ? fetchTriageUserPrompt(hubCtx) : null,
 		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.profile, cwd) : null,
 		rerunProfile !== null && hubCtx ? fetchRerunReport(hubCtx, rerunProfile) : null,
-		forExecution && hubCtx && opts.profile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.profile) : null
+		forExecution && hubCtx && opts.profile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.profile) : null,
+		opts.onlyAuditedClean && hubCtx ? fetchAuditedLedger(hubCtx) : null
 	]);
 	const deployedSha = rerunReport?.deployHead.sha ?? fetchedDeployHead;
 	if (ledgerEntries) diffProvider = createDiffProvider({
@@ -12156,7 +12266,7 @@ async function executeRun(targets, opts) {
 		cwd
 	});
 	const triageUserPromptHash = triageUserPrompt ? hashTriageUserPrompt(triageUserPrompt) : null;
-	const reportDir = resolveReportDir(opts.report, cwd);
+	const reportDir = resolveReportDir(opts.reportDir, cwd);
 	const analysisDeps = {
 		diffProvider,
 		auth: diffProvider ? driftAuthAvailable() : {
@@ -12172,22 +12282,28 @@ async function executeRun(targets, opts) {
 	};
 	const enumerateAll = () => listAllSpecsWithSpecFile(cwd);
 	let specs = dedupeSpecs((await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)))).flat());
-	if (opts.changed) {
+	if (filtering) {
 		const before = specs.length;
 		let unanswerable = 0;
 		if (rerunReport) {
-			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.includeUnknown === true });
+			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.onlyStaleWithUnknown === true });
 			specs = selection.selected;
 			unanswerable = selection.excludedUnanswerable;
-			meta("rerun-base", `deploy ${rerunReport.deployHead.sha.slice(0, 12)} (profile ${rerunReport.profile})`);
-			meta("rerun-states", selection.summary);
-		} else specs = (await collectChangedSpecs(specs, {
+			meta("stale-base", `deploy ${rerunReport.deployHead.sha.slice(0, 12)} (profile ${rerunReport.profile})`);
+			meta("stale-states", selection.summary);
+		}
+		if (auditedLedger) {
+			const picked = selectAuditedClean(specs, auditedLedger);
+			specs = picked.selected;
+			meta("audit-states", `${picked.selected.length} clean, ${picked.drifted} drifted, ${picked.unaudited} never audited`);
+		}
+		if (opts.onlyAffectedBy) specs = (await collectChangedSpecs(specs, {
 			cwd,
-			base: opts.changed,
+			base: opts.onlyAffectedBy,
 			...opts.model ? { model: opts.model } : {}
 		})).specs;
-		meta("changed-scoped", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
-		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --include-unknown to run them anyway`);
+		meta("selected", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
+		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --only-stale-with-unknown to run them anyway`);
 	}
 	if (specs.length === 0) {
 		warn("no specs to run");
@@ -12210,11 +12326,11 @@ async function executeRun(targets, opts) {
 	if (dispatch.external.length > 0) meta("external", dispatch.external.map((g) => `${g.targetId} ${g.specs.length}`).join(" / "));
 	if (liveSpecs.length === 0) {
 		const why = "it only applies to agent-browser 'mode: live' specs, and this run has none";
-		if (typeof opts.retry === "number" && opts.retry > 0) warn(`--retry is ignored: ${why}`);
-		if (opts.out) warn(`--out is ignored: ${why}`);
-		if (opts.updateAgentPrompt) warn(`--update-agent-prompt is ignored: ${why}`);
-	} else if (opts.out && liveSpecs.length > 1) warn("--out is ignored when running multiple live specs");
-	if (detSpecs.length === 0 && opts.evidence === false) warn("--no-evidence is ignored: it only applies to agent-browser 'mode: deterministic' specs, and this run has none");
+		if (typeof opts.liveStepRetry === "number" && opts.liveStepRetry > 0) warn(`--live-step-retry is ignored: ${why}`);
+		if (opts.liveArtifactsDir) warn(`--live-artifacts-dir is ignored: ${why}`);
+		if (opts.learnLivePrompt) warn(`--learn-live-prompt is ignored: ${why}`);
+	} else if (opts.liveArtifactsDir && liveSpecs.length > 1) warn("--out is ignored when running multiple live specs");
+	if (detSpecs.length === 0 && opts.replaySkipEvidence === true) warn("--no-evidence is ignored: it only applies to agent-browser 'mode: deterministic' specs, and this run has none");
 	blank();
 	if (opts.dryRun) {
 		for (const line of formatDryRunLines(withMode, dispatch)) emitRaw(line + "\n");
@@ -12227,10 +12343,10 @@ async function executeRun(targets, opts) {
 		};
 	}
 	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir);
-	if (opts.pushReport && hubCtx == null) warn("--push-report requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN); skipping push");
+	if (opts.reportToHub && hubCtx == null) warn("--push-report requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN); skipping push");
 	let hubRunId = null;
 	let hubSink;
-	if (hubCtx != null && opts.pushReport) try {
+	if (hubCtx != null && opts.reportToHub) try {
 		const branch = await detectBranch(cwd);
 		const ciRunId = githubRunId();
 		const runUrl = githubRunUrl();
@@ -12293,10 +12409,10 @@ async function executeRun(targets, opts) {
 	const live = await runLiveSpecs(liveSpecs, {
 		...opts.model ? { model: opts.model } : {},
 		...opts.language ? { language: opts.language } : {},
-		...opts.out && liveSpecs.length === 1 ? { out: opts.out } : {},
+		...opts.liveArtifactsDir && liveSpecs.length === 1 ? { out: opts.liveArtifactsDir } : {},
 		cwd,
 		reportDir,
-		...typeof opts.retry === "number" ? { retry: opts.retry } : {},
+		...typeof opts.liveStepRetry === "number" ? { retry: opts.liveStepRetry } : {},
 		concurrency: opts.concurrency ?? 1,
 		...opts.profile ? { profile: opts.profile } : {},
 		diffProvider,
@@ -12360,10 +12476,11 @@ async function executeRun(targets, opts) {
 			}
 		}
 	}
-	if (opts.updateAgentPrompt && liveSpecs.length > 0) {
+	if (opts.learnLivePrompt && liveSpecs.length > 0) {
 		blank();
 		await updateAgentPrompt({
 			kind: "live",
+			flag: "--learn-live-prompt",
 			runSummary: buildLiveRunSummary(live.reportResults),
 			hubContext: hubCtx,
 			...opts.model ? { model: opts.model } : {},
@@ -12449,8 +12566,8 @@ async function runDeterministicSpecs(specs, opts, cwd, reportDirAbs) {
 	};
 	const tmpDir = await mkdtemp(join(tmpdir(), "ccqa-run-"));
 	const vitestConfig = await resolveVitestConfig(cwd);
-	const captureOutput = opts.failureAnalysis !== false;
-	const captureEvidence = opts.evidence !== false;
+	const captureOutput = true;
+	const captureEvidence = opts.replaySkipEvidence !== true;
 	const concurrency = Math.max(1, opts.concurrency ?? 1);
 	const ctx = {
 		cwd,
@@ -12658,7 +12775,7 @@ async function writeUnifiedReport(args) {
 	const jsonPath = join(reportDir, "report.json");
 	await writeFile(jsonPath, JSON.stringify(data, null, 2) + "\n", "utf8");
 	info(`run report (json) written to ${jsonPath}`);
-	if (opts.format === "github") for (const line of emitGithubAnnotations(data)) emitRaw(line + "\n");
+	if (opts.reportFormat === "github") for (const line of emitGithubAnnotations(data)) emitRaw(line + "\n");
 	return data;
 }
 /**
@@ -12901,14 +13018,14 @@ 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, 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 --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 ccqa select-specs judges needed against 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), or pass 'last-run' to run the specs the hub says need one — each spec's own last run compared against the deploy log (requires a hub connection and --profile; no git diff involved). Cannot be combined with an explicit spec id.").option("--include-unknown", "(--changed=last-run only) Also run specs whose re-run need the hub cannot answer ('unknown') and specs that have never run ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").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 mode.").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("--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) => {
+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-stale", "Only specs whose last result no longer holds — each spec's own last run compared against the hub's deploy log. No git diff involved. Requires a hub connection and --profile.").option("--only-stale-with-unknown", "With --only-stale: also take specs whose re-run need the hub cannot answer ('unknown') and specs that never ran ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").option("--only-audited-clean", "Only specs `ccqa audit` last found no drift in. A spec that has never been audited is not taken: this flag spends a run where a cheap audit already cleared the spec, and \"never looked\" is not that. Requires a hub connection.").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). 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(`--retry must be a non-negative integer, got "${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;
-}, 0).option("--out <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.").option("--update-agent-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
+}, 0).option("--live-artifacts-dir <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.").option("--replay-skip-evidence", `(deterministic replay only) Skip step-boundary evidence capture (PNG + meta JSON written to ${DEFAULT_REPORT_DIR}/${EVIDENCE_SUBDIR}/ by default).`).optionsGroup("What to do about failures:").option("--on-fail-explain", "Classify each failure against the source diff since the commit where that spec last passed (per-spec baselines from the hub). Off by default — no Claude calls without it.").option("--on-fail-explain-base <ref>", "With --on-fail-explain: diff against <ref> instead of each spec's last green. Use when there is no hub to hold the baselines.").optionsGroup("What to do with the results:").option("--report-dir <dir>", `Directory for the structured run results (report.json + evidence PNGs), which are always written. Default: ${DEFAULT_REPORT_DIR}/.`).option("--report-format <fmt>", "Additional output format alongside HTML: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
+	if (REPORT_FORMATS.includes(raw)) return raw;
+	throw new Error(`--report-format must be one of ${REPORT_FORMATS.join(" | ")}`);
+}, "text").option("--report-to-hub", "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.").optionsGroup("Learning:").option("--learn-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
 	await runCliAction(targets, opts);
 });
 /** Parse --concurrency: a positive integer. Rejects 0, negatives, non-integers. */
@@ -12920,12 +13037,16 @@ function parseConcurrency$1(raw) {
 	}
 	return n;
 }
-/** Header label shown after `ccqa run`: the lone target, a count, or a mode marker. */
+/** Header label shown after `ccqa run`: the lone target, a count, or how they were selected. */
 function headerTarget(targets, opts) {
 	if (targets.length === 1) return targets[0];
 	if (targets.length > 1) return `${targets.length} targets`;
-	if (opts.changed === "last-run") return "(needs re-run)";
-	return opts.changed ? "(changed)" : "(all specs)";
+	const filters = [
+		opts.onlyAffectedBy ? "affected" : null,
+		opts.onlyStale ? "stale" : null,
+		opts.onlyAuditedClean ? "audited clean" : null
+	].filter((s) => s !== null);
+	return filters.length === 0 ? "(all specs)" : `(${filters.join(" + ")})`;
 }
 /**
 * CLI entry point: calls the library pipeline and maps its result back to a
@@ -13183,8 +13304,8 @@ For each step:
 3. Execute the action using an ALLOWED selector (see Selector Rules), prefixing the command with \`CCQA_STEP=<step-id>\` like every agent-browser command in the step.
 4. Emit \`AB_ACTION|...\` for every browser action (see AB_ACTION Protocol).
 5. Run \`snapshot\` again to verify the outcome.
-6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...).
-7. Record each verified signal as an assertion by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Only the assert types markers cannot express fall back to \`AB_ACTION|assert|...\` text lines.
+6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...). This is how *you* decide the step worked and it is safe to continue. It is not what gets recorded.
+7. Record as assertions only the signals the step's own \`expected\` asks about, by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Only the assert types markers cannot express fall back to \`AB_ACTION|assert|...\` text lines.
 8. Emit \`STEP_DONE\`, \`ASSERTION_FAILED\`, or \`STEP_SKIPPED\`.
 
 **Protocol lines are recorded ONLY from your plain assistant text.** Every
@@ -13315,7 +13436,9 @@ CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session
 - A marked command that exits non-zero records nothing — fix the check and re-run it.
 - A marker that doesn't match its command (e.g. \`CCQA_ASSERT=1\` on a \`click\`) is ignored with a warning — never do that.
 - \`get count\` and \`get url\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL contradicts the marker, the signal did NOT verify — treat it as a failed verification (emit \`ASSERTION_FAILED\` if the step cannot be confirmed another way).
-- **\`url_contains\` is opt-in, not a habit.** Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
+- **Assert what the step asks about, nothing else.** The \`expected\` is the contract; anything else you happened to see on the way is not. A nav item, a heading or a greeting that the step never mentions adds no coverage, differs between recordings of the same spec, and is the first thing to break on replay — so the next recording quietly drops it and the test gets weaker without anyone deciding that.
+
+- **\`url_contains\` is opt-in, not a habit.** The same rule, in the form that gets broken most. Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
 - **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/policies\`, assert \`\${APP_URL}/policies\` (or the tail \`/policies\`); the recorder resolves \`\${APP_URL}\` per environment. Never assert on a URL you merely *observed* — login redirects, identity-provider pages, and OAuth callbacks all live on a **different, environment-named origin** than the app, so any substring of them (host, origin, OR path) names the environment.
 - **A leading slash does NOT make a substring safe.** \`/auth-staging\`, \`/env-qa\`, \`/tenant-acme\` look like paths but are environment labels — the first segment of an identity-provider or tenant URL, not an application route. If a substring contains an environment name, a stage token (\`dev\`, \`stg\`, \`prod\`), a tenant/org name, or any fragment of a hostname, it is forbidden even with a leading slash. The only safe path substrings are stable *application* routes off the app's own origin (\`/dashboard\`, \`/policies/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
 
@@ -14423,8 +14546,8 @@ For each test case above, write a 1–2 sentence factual \`summary\` of what it
 }
 //#endregion
 //#region src/cli/perspectives.ts
-const perspectivesCommand = addHubOptions(addLanguageOption(new Command("perspectives").description("Generate/update the project's perspectives document on the hub — a factual inventory of existing test coverage (no severity, no gap analysis)").option("--instruction <text>", "Hint to steer how summaries are written").option("--apply", "Auto-apply without [y/N] confirmation", false).option("--check", "Verify the hub document still matches the local specs (mechanical fields only) and exit 1 when it is stale. No Claude calls — cheap enough for CI.", false).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID").option("--project <name>", "Hub project to store the document under (default: cwd directory name)"))).action(withHubErrors(async (opts) => {
-	if (opts.check) await runPerspectivesCheck(opts);
+const perspectivesCommand = addHubOptions(addLanguageOption(new Command("perspectives").description("Generate/update the project's perspectives document on the hub — a factual inventory of existing test coverage (no severity, no gap analysis)").option("--instruction <text>", "Hint to steer how summaries are written").option("-y, --yes", "Apply without asking [y/N]", false).option("--verify", "Check the hub document against the local specs (mechanical fields only) and exit 1 when it is stale. No Claude calls — cheap enough for CI.", false).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID").option("--project <name>", "Hub project to store the document under (default: cwd directory name)"))).action(withHubErrors(async (opts) => {
+	if (opts.verify) await runPerspectivesCheck(opts);
 	else await runPerspectives(opts);
 }));
 /**
@@ -14547,7 +14670,7 @@ async function runPerspectives(opts) {
 	info("--- proposed changes (YAML view of the hub document) ---");
 	printUnifiedDiff(existingYaml, next);
 	blank();
-	if (!(opts.apply === true || /^y/i.test(await prompt(useJapanesePrompts(opts.language) ? "hub に perspectives を保存しますか? [y/N] " : "Push perspectives to the hub? [y/N] ")))) {
+	if (!(opts.yes === true || /^y/i.test(await prompt(useJapanesePrompts(opts.language) ? "hub に perspectives を保存しますか? [y/N] " : "Push perspectives to the hub? [y/N] ")))) {
 		info("aborted — no changes written.");
 		return;
 	}
@@ -14978,7 +15101,7 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 	}, cwd) ?? null;
 	if (existingOutput && !opts.force) {
 		if (!await confirmOverwrite(existingOutput)) {
-			info("aborted; pass --force to overwrite without prompting");
+			info("aborted; pass --overwrite to replace it without prompting");
 			return;
 		}
 	}
@@ -15033,6 +15156,7 @@ async function runGenerateAgentPromptUpdate(target, featureName, specName, resul
 	blank();
 	await updateAgentPrompt({
 		kind: target.guidanceKind,
+		flag: "--learn-codegen-prompt",
 		runSummary: buildGenerateRunSummary(target.id, featureName, specName, result, cwd),
 		hubContext: opts.hubContext ?? null,
 		...opts.model ? { model: opts.model } : {},
@@ -15058,7 +15182,7 @@ async function confirmOverwrite(path) {
 		rl.close();
 	}
 }
-const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite previously generated test code without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").option("--update-agent-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace previously generated test code without warning").optionsGroup("Learning:").option("--learn-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	const { featureName, specName } = parseSpecPath(specPath);
 	const language = opts.language ?? "auto";
 	const cwd = resolveCwd(opts.cwd);
@@ -15087,16 +15211,16 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 	} : null;
 	try {
 		await runGenerate(featureName, specName, {
-			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
+			maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
 			fixMode: toFixMode(opts.autoFix ?? "interactive"),
-			force: opts.force ?? false,
-			useSnapshot: opts.snapshot !== false,
+			force: opts.overwrite ?? false,
+			useSnapshot: opts.sessionPin !== false,
 			language,
 			model: opts.model,
 			targetOverride: opts.target,
 			cwd,
 			hubContext,
-			updateAgentPrompt: opts.updateAgentPrompt ?? false
+			updateAgentPrompt: opts.learnCodegenPrompt ?? false
 		});
 	} catch (e) {
 		if (e instanceof SpecLockedError) {
@@ -15132,10 +15256,10 @@ function reportCost() {
 //#endregion
 //#region src/cli/record.ts
 const VALIDATION_MODES = ["lenient", "strict"];
-const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--validation-mode <mode>", "Post-trace validation behaviour: 'lenient' (default) tags failing actions; 'strict' drops them.", (raw) => {
+const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
-	throw new Error(`--validation-mode must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite an existing test.spec.ts without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").option("--skip-trace", "Skip the trace step and run codegen against an existing ir.json").option("--skip-codegen", "Run only the trace step (do not generate test.spec.ts)").option("--update-agent-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").optionsGroup("Learning:").option("--learn-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostTally(async () => {
 		try {
 			await runRecord(specPath, opts);
@@ -15147,10 +15271,6 @@ const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Comma
 async function runRecord(specPath, opts) {
 	const { featureName, specName } = parseSpecPath(specPath);
 	const language = opts.language ?? "auto";
-	if (opts.skipTrace && opts.skipCodegen) {
-		error("--skip-trace and --skip-codegen cannot be combined; nothing would run");
-		process.exit(2);
-	}
 	const cwdForProfile = resolveCwd(opts.cwd);
 	const spec = parseTestSpec(await readSpecFile(featureName, specName, cwdForProfile));
 	const config = await loadProjectConfig(cwdForProfile);
@@ -15192,18 +15312,16 @@ async function runRecord(specPath, opts) {
 	});
 	let traceResult = null;
 	try {
-		if (!opts.skipTrace) {
-			traceResult = await runTrace(featureName, specName, opts.model, opts.validationMode ?? "lenient", language, {
-				cwd: cwdForProfile,
-				hubContext
-			});
-			blank();
-		}
-		if (!opts.skipCodegen) await runGenerate(featureName, specName, {
-			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
+		traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
+			cwd: cwdForProfile,
+			hubContext
+		});
+		blank();
+		if (!opts.traceOnly) await runGenerate(featureName, specName, {
+			maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
 			fixMode: toFixMode(opts.autoFix ?? "interactive"),
-			force: opts.force ?? false,
-			useSnapshot: opts.snapshot !== false,
+			force: opts.overwrite ?? false,
+			useSnapshot: opts.sessionPin !== false,
 			language,
 			model: opts.model,
 			cwd: cwdForProfile,
@@ -15212,11 +15330,11 @@ async function runRecord(specPath, opts) {
 	} finally {
 		await releaseLock();
 	}
-	if (opts.updateAgentPrompt) if (traceResult === null) warn("--update-agent-prompt is ignored when --skip-trace is set (no run summary available)");
-	else {
+	if (opts.learnTracePrompt && traceResult !== null) {
 		blank();
 		await updateAgentPrompt({
 			kind: "record",
+			flag: "--learn-trace-prompt",
 			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
 			hubContext,
 			...opts.model ? { model: opts.model } : {},
@@ -15498,7 +15616,7 @@ function specStatus(result, threshold) {
 }
 /**
 * Adapts `ccqa drift` results into the shared RunReportData shape so they can
-* be pushed to the hub (`ccqa drift --push`) and rendered by the same report
+* be pushed to the hub (`ccqa audit --report-to-hub`) and rendered by the same report
 * UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
 * evidence, liveRun, ...) don't apply to a drift audit and are always null —
 * which is why `mode` is carried separately: nothing ran, but which surfaces
@@ -15544,35 +15662,34 @@ function driftResultsToReport(results, meta) {
 	};
 }
 //#endregion
-//#region src/cli/drift.ts
+//#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const driftCommand = addLanguageOption(new Command("drift").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Standalone spec ↔ codebase static audit. Use for PR checks where the browser isn't run. For run-time audit with a structured report, see `ccqa run --report`.").option("--format <fmt>", "Output format: text | json | github", "text").option("--severity <level>", "Exit non-zero on this severity or higher: warn | error", "error").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.").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--changed", "Restrict drift checks to the specs a change reaches, decided by `ccqa select-specs` against --base (or, in CI, $GITHUB_BASE_REF). Costs one model call; specs it cannot decide are checked rather than skipped.").option("--base <ref>", "Base ref to diff against when --changed is set. Defaults to $GITHUB_BASE_REF (CI pull_request runs); required otherwise.").option("--push", "Push the drift result to a ccqa hub as a run (kind: drift).").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 withCostTally(() => runDrift(specPath, opts));
+const auditCommand = 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.").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 `ccqa run --only-audited-clean` reads.").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 withCostTally(() => runAudit(specPath, opts));
 }));
-async function runDrift(specPath, opts) {
-	const format = parseFormat$1(opts.format);
-	const threshold = parseSeverity(opts.severity);
+async function runAudit(specPath, opts) {
+	const format = parseFormat$1(opts.reportFormat);
+	const threshold = parseSeverity(opts.exitOn);
 	const concurrency = parseConcurrency(opts.concurrency);
 	const cwd = resolveCwd(opts.cwd);
 	await ensureCcqaDir(cwd);
-	if (opts.changed && specPath) {
-		error("--changed and an explicit spec id cannot be combined; --changed only applies to a full sweep");
+	if (opts.onlyAffectedBy && specPath) {
+		error("--only-affected-by and an explicit spec id cannot be combined; it only applies to a full sweep");
 		process.exit(2);
 	}
 	let targets = await collectTargets(specPath, cwd);
 	if (targets.length === 0) exitWithNoSpecs(format, "no test specs found under .ccqa/features/");
 	if (format === "text") {
-		header("drift", specPath ?? `${targets.length} spec${targets.length > 1 ? "s" : ""}`);
+		header("audit", specPath ?? `${targets.length} spec${targets.length > 1 ? "s" : ""}`);
 		if (opts.cwd) meta("cwd", cwd);
 	}
 	let baseRef = null;
-	if (opts.changed) {
+	if (opts.onlyAffectedBy) {
 		const total = targets.length;
 		const selection = await collectChangedSpecs(targets, {
 			cwd,
-			base: opts.base ?? true,
+			base: opts.onlyAffectedBy,
 			quiet: format !== "text",
-			baseExample: "--base origin/main",
 			...opts.model ? { model: opts.model } : {}
 		});
 		targets = selection.specs;
@@ -15593,7 +15710,7 @@ async function runDrift(specPath, opts) {
 		}
 	});
 	process.stdout.write(renderDrift(results, format, cwd));
-	if (opts.push) await pushDriftResults({
+	if (opts.reportToHub) await pushDriftResults({
 		results,
 		threshold,
 		cwd,
@@ -15607,7 +15724,7 @@ async function runDrift(specPath, opts) {
 /**
 * Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
 * shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
-* hub connection warns and returns rather than failing the command (`--push`
+* hub connection warns and returns rather than failing the command (`--report-to-hub`
 * never changes drift's own exit code).
 *
 * `resolveHub` is injectable so tests can supply a fake `HubClient` without
@@ -15617,7 +15734,7 @@ async function pushDriftResults(args, resolveHub = resolveHubClient) {
 	const { results, threshold, cwd, opts, format, baseRef } = args;
 	const hub = resolveHub(opts);
 	if (!hub) {
-		warn("--push requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
+		warn("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
 		return;
 	}
 	try {
@@ -15803,102 +15920,6 @@ function parseFormat(raw) {
 	process.exit(2);
 }
 //#endregion
-//#region src/cli/session.ts
-const AB = resolveAgentBrowserBin$1();
-/**
-* Run agent-browser attached to the user's terminal (no timeout, inherited
-* stdio) so a human can complete an interactive login during `bootstrap`.
-* Distinct from runtime/spawn-ab.ts, which pipes stdio and hard-times-out for
-* non-interactive automation.
-*/
-function runAbInteractive(args) {
-	return spawnSync(AB, args, { stdio: "inherit" }).status ?? 1;
-}
-function validateName(name) {
-	const parsed = SessionNameSchema.safeParse(name);
-	if (!parsed.success) {
-		error(`invalid session name "${name}": ${parsed.error.issues[0]?.message ?? "bad name"}`);
-		process.exit(2);
-	}
-	return parsed.data;
-}
-const profileOption = ["--profile <name>", "Sessions bucket to read/write on the hub. Defaults to 'default'."];
-const projectOption = ["--project <name>", "Project the session belongs to on the hub. Defaults to the current directory's name."];
-const bootstrapCommand = new Command("bootstrap").description("Open a headed browser so you can log in by hand, then upload the resulting session (cookies + localStorage) to the hub for `session:` specs to restore.").argument("<name>", "Session name to save").option("--url <url>", "URL to open first (e.g. the login page). Omit to start with a blank tab.").option(...profileOption).option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option("--cwd <path>", "Directory the default --project name is derived from (defaults to the current directory).").action(async (rawName, opts) => {
-	const name = validateName(rawName);
-	resolveCwd(opts.cwd);
-	const project = resolveProject(opts);
-	let hub;
-	try {
-		hub = requireHubClient(opts);
-	} catch (err) {
-		if (!(err instanceof HubConnectionError)) throw err;
-		error(err.message);
-		process.exit(2);
-	}
-	header("session bootstrap", name);
-	meta("project", project);
-	meta("profile", opts.profile ?? "default");
-	blank();
-	const openArgs = [
-		"--headed",
-		"open",
-		...opts.url ? [opts.url] : ["about:blank"]
-	];
-	info("opening a browser — log in by hand, then return here.");
-	const openStatus = runAbInteractive(openArgs);
-	if (openStatus !== 0) {
-		error(`agent-browser open exited ${openStatus}`);
-		process.exit(1);
-	}
-	const rl = createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	await rl.question("\nPress Enter once you are fully logged in to save the session… ");
-	rl.close();
-	const tmpDir = await mkdtemp(join(tmpdir(), "ccqa-session-bootstrap-"));
-	try {
-		const tmpPath = join(tmpDir, "state.json");
-		const saveStatus = runAbInteractive([
-			"state",
-			"save",
-			tmpPath
-		]);
-		runAbInteractive(["close"]);
-		if (saveStatus !== 0) {
-			error(`agent-browser state save exited ${saveStatus}`);
-			process.exit(1);
-		}
-		const state = await loadStorageState(tmpPath);
-		let payload = state;
-		if (opts.url) {
-			info("verifying the saved session restores to a signed-in page…");
-			const check = verifySessionRestores(tmpPath, opts.url);
-			if (!check.restored) {
-				error(`session did not restore cleanly: ${check.reason}`);
-				hint("fully load the application (sign in, open the target workspace/page, wait for it to settle) before pressing Enter, then run bootstrap again. Nothing was uploaded.");
-				process.exit(1);
-			}
-			info("restore verified — the session starts signed in.");
-			payload = {
-				...state,
-				[SESSION_VERIFY_URL_KEY]: opts.url
-			};
-		} else warn("no --url given — the session can't be verified now, and runs can't health-check it before executing steps; strongly consider re-running with --url <a signed-in page URL>.");
-		await hub.putSession(project, opts.profile ?? "default", name, payload);
-	} finally {
-		await rm(tmpDir, {
-			recursive: true,
-			force: true
-		});
-	}
-	blank();
-	info(`uploaded session "${name}" to the hub (encrypted at rest)`);
-	hint("reference it from a spec with:  session: " + name);
-});
-const sessionCommand = new Command("session").description("Manage saved browser sessions (cookies + localStorage) for `session:` specs. Use `ccqa hub session ls` to list sessions stored on the hub.").addCommand(bootstrapCommand);
-//#endregion
 //#region src/hub/api/respond.ts
 /** The message of an unknown throwable, for a log line or an error body. */
 function errMsg(err) {
@@ -23364,17 +23385,21 @@ function resolvePackageJson() {
 const { version } = JSON.parse(readFileSync(resolvePackageJson(), "utf8"));
 const program = new Command();
 program.name("ccqa").description("E2E test CLI powered by Claude Code — agent-browser by default, or Playwright / runn targets").version(version);
+program.commandsGroup("Write specs:");
 program.addCommand(initCommand);
 program.addCommand(draftCommand);
 program.addCommand(perspectivesCommand);
+program.commandsGroup("Build tests from them:");
 program.addCommand(recordCommand);
 program.addCommand(generateCommand);
+program.commandsGroup("Check them:");
 program.addCommand(runCommand);
-program.addCommand(driftCommand);
-program.addCommand(selectSpecsCommand);
-program.addCommand(sessionCommand);
-program.addCommand(serveCommand);
+program.addCommand(auditCommand);
+program.commandsGroup("Hub:");
 program.addCommand(hubCommand);
+program.addCommand(serveCommand);
+program.commandsGroup("Building blocks:");
+program.addCommand(selectSpecsCommand);
 program.parse();
 //#endregion
 export {};