ccqa 1.12.0 → 1.14.0

package/dist/bin/ccqa.mjs

@@ -477,7 +477,7 @@ function getBlocksDir(cwd) {
 /**
 * Inverse of `getBlockDir`. Given a file path that appears in a git diff,
 * return the block name if the path points at the block's spec.yaml, else
-* null. Used by `drift --changed` to invalidate specs whose included blocks
+* null. Used by `audit --only-affected-by` to invalidate specs whose included blocks
 * were edited. (v0.4 inlines blocks into every spec's own trace, so the
 * block directory holds only spec.yaml — no per-block recording lives
 * here anymore.)
@@ -524,24 +524,22 @@ const USER_PROMPT_MAX_BYTES = 32768;
 * Load the prompt bundle from the hub for one guidance kind ("record" /
 * "live" / an LLM-generation target such as "playwright" or "runn").
 * Best-effort: no hub client, a fetch failure, or both prompts absent all
-* resolve to null — a broken/missing hub prompt must never stop a run.
+* A prompt that was never stored resolves to null. A hub that cannot be
+* reached throws: running with silently different guidance than the project
+* configured is worse than stopping.
 */
 async function loadPromptBundleFromHub(ctx, kind) {
 	if (!ctx) return null;
 	const userName = `${kind}.user`;
 	const agentName = `${kind}.agent`;
-	try {
-		const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
-		return assemblePromptBundle({
-			text: userText,
-			label: userName
-		}, {
-			text: agentText,
-			label: agentName
-		});
-	} catch {
-		return null;
-	}
+	const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
+	return assemblePromptBundle({
+		text: userText,
+		label: userName
+	}, {
+		text: agentText,
+		label: agentName
+	});
 }
 /**
 * Shared concatenation logic behind `loadPromptBundleFromHub`: section
@@ -557,7 +555,7 @@ function assemblePromptBundle(user, agent) {
 		loaded.push(user.label);
 	}
 	if (agent.text !== null) {
-		sections.push(`### Agent learnings (auto-updated by ccqa --update-agent-prompt)\n\n${agent.text}`);
+		sections.push(`### Agent learnings (auto-updated by ccqa's --learn-*-prompt flags)\n\n${agent.text}`);
 		loaded.push(agent.label);
 	}
 	let text = sections.join("\n\n");
@@ -2475,7 +2473,7 @@ const FailureAnalysisSchema = z.object({
 });
 /**
 * What a drift audit may conclude, in the same vocabulary `ccqa run
-* --failure-analysis` uses for a failure. One question, one answer, the same
+* --on-fail-explain` uses for a failure. One question, one answer, the same
 * words whether it was reached by running the spec or by reading the code — so
 * a reader never translates between two taxonomies, and the hub renders,
 * grades and learns from both through one path.
@@ -3312,7 +3310,7 @@ function relativeToCwd(path, cwd) {
 /** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
 const DriftReplySchema = z.object({ drift: DriftDiagnosisSchema.nullable() });
 /**
-* How a label reads against `--severity`. The threshold asks "would a
+* How a label reads against `--exit-on`. The threshold asks "would a
 * deterministic replay fail today", which is what the label already answers:
 * both findings mean the spec no longer describes the code, while `UNKNOWN`
 * means the audit could not tell and should not fail a build on its own.
@@ -3326,7 +3324,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) {
@@ -3971,14 +3969,10 @@ ${customPrompt.guidance}
 */
 async function fetchCustomPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
-		if (raw === null) return null;
-		const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
-		return parsed.success ? parsed.data : null;
-	} catch {
-		return null;
-	}
+	const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
+	if (raw === null) return null;
+	const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
+	return parsed.success ? parsed.data : null;
 }
 /**
 * Render the human-maintained `triage.user` guidance as a prompt section, or
@@ -4006,12 +4000,8 @@ ${trimmed}
 */
 async function fetchTriageUserPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
-		return trimmed ? trimmed : null;
-	} catch {
-		return null;
-	}
+	const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
+	return trimmed ? trimmed : null;
 }
 /**
 * Short, stable content hash for a `triage.user` prompt. The Markdown body
@@ -4426,16 +4416,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.
@@ -4822,12 +4802,12 @@ async function readDotenv(path) {
 	}
 	return parseDotenv(content);
 }
-/** Absolute path of the default `.env` ccqa loads when `--profile` is absent. */
+/** Absolute path of the default `.env` ccqa loads when `--hub-profile` is absent. */
 function defaultEnvPath(cwd) {
 	return join(cwd, ".env");
 }
 /**
-* Load `<cwd>/.env`, the default when no `--profile` is given. A missing `.env`
+* Load `<cwd>/.env`, the default when no `--hub-profile` is given. A missing `.env`
 * is fine (returns `null`) — the run falls back to the existing `process.env`.
 */
 async function loadDefaultEnv(cwd) {
@@ -5033,7 +5013,7 @@ function addLanguageOption(command) {
 * `record`), registered identically so help text and behaviour don't drift.
 */
 function addProfileOption(command) {
-	return command.option("--profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can target dev/stg/prd without per-environment copies. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
+	return command.option("--hub-profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can target dev/stg/prd without per-environment copies. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
 }
 /**
 * Shared `--hub-url` / `--hub-token` flags for commands that optionally talk
@@ -5225,7 +5205,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 +5242,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 +5462,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()
 	};
@@ -5911,7 +5891,7 @@ async function runVerificationLoop(p, ref, state) {
 	const runCommand = p.ctx.targetConfig.runCommand;
 	if (!runCommand) return true;
 	const maxRetries = p.ctx.fix.mode === "non-interactive" ? 0 : p.ctx.fix.maxRetries;
-	if (!p.ctx.fix.useSnapshot) warn(`--no-snapshot has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
+	if (!p.ctx.fix.useSnapshot) warn(`--no-session-pin has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
 	for (let attempt = 0;; attempt++) {
 		const testFiles = [...state.entries()].filter(([, f]) => f.kind === "test").map(([rel]) => rel);
 		const artifactsDir = await mkdtemp(join(tmpdir(), "ccqa-verify-artifacts-"));
@@ -6099,8 +6079,8 @@ const C$1 = {
 * script, so it keeps its own caller in `cli/run-live.ts`; only the
 * `ANALYSIS_DISABLED` string is shared with it.
 */
-/** `analysisSkipped` for a failed row when `--failure-analysis` was not requested. */
-const ANALYSIS_DISABLED = "skipped: --failure-analysis not enabled";
+/** `analysisSkipped` for a failed row when `--on-fail-explain` was not requested. */
+const ANALYSIS_DISABLED = "skipped: --on-fail-explain not enabled";
 /**
 * Create one analysis pass. The returned object is stateful on purpose: the
 * "source diff unavailable" notice and the summary block's header are printed
@@ -6531,15 +6511,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 +6533,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,
@@ -6640,7 +6600,7 @@ async function detectDefaultBranch(cwd) {
 /**
 * Fetch the last-green ledger for this run — one hub round trip, logged as
 * the run's analysis-base meta line. Fails fast (RunUsageError) when the hub
-* can't serve it: `--failure-analysis=last-green` explicitly opted into
+* can't serve it: `--on-fail-explain` explicitly opted into
 * hub-backed baselines, so a broken hub connection is a usage error, never a
 * silent no-baseline run.
 */
@@ -6655,7 +6615,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}`;
@@ -6663,7 +6623,7 @@ async function fetchLastGreenLedger(hubCtx, profile, cwd) {
 	return entries;
 }
 /**
-* Per-spec baseline resolver for `--failure-analysis=last-green`. A spec
+* Per-spec baseline resolver for `--on-fail-explain` without an explicit base. A spec
 * missing from the ledger (never green on a pushed run yet) or whose
 * baseline commit isn't in this checkout resolves to a skip — the run
 * continues; only that spec's classification is withheld, with the reason
@@ -6717,7 +6677,7 @@ async function deployHeadSha(hub, project, profile) {
 *
 * Captured before any spec executes and asserted on both push paths
 * (`?deployedSha=` on `POST /runs` via `ccqa hub push`, and on `POST
-* /runs/open` for `--push-report`). Left to itself the hub reads its own
+* /runs/open` for `--report-to-hub`). Left to itself the hub reads its own
 * deploy-log head when the call lands — after the whole run for a single-shot
 * push, after the deterministic phase for an incremental one — so a deploy
 * landing in that window would be recorded as the run's baseline and
@@ -6742,7 +6702,7 @@ async function tryDeployHeadSha(hubCtx, profile) {
 *
 * This exists because a selection can be wrong in a way that costs money.
 * `ccqa select-specs`'s model judgment is not infallible, and both
-* `--changed <ref>` and `--changed=last-run` decide from it, so a human has to
+* `--only-affected-by` and `--only-hub-stale` decide from it, so a human has to
 * be able to read the selection back before a live spec spends a Claude
 * budget on it.
 *
@@ -6774,9 +6734,53 @@ 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-hub-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
+* `ccqa run --only-hub-stale`: select specs from the hub's re-run verdicts
 * instead of from a git diff (ADR-0010). The baseline is not a ref at all —
 * it is each spec's own last run, positioned against the deploy log the
 * consuming deploy job feeds the hub — so this path does no git work.
@@ -6788,12 +6792,12 @@ function formatDryRunLines(agentBrowser, routed) {
 /** First ccqa release whose hub serves `GET /projects/:project/rerun`. */
 const RERUN_MIN_HUB_VERSION = "1.9";
 /**
-* The profile `--changed=last-run` asks about. Mandatory: two environments sit
+* The profile `--only-hub-stale` asks about. Mandatory: two environments sit
 * at different commits and the deploy log is per-profile, so "needs re-run"
 * 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-hub-stale requires --hub-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 +6810,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-hub-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-hub-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 select with --only-affected-by <ref> instead.`);
 	return {
 		...report,
 		deployHead: report.deployHead
@@ -6820,8 +6824,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-hub-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-hub-stale: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or select with --only-affected-by <ref> instead.`;
 }
 /** States the summary line reports, worst-known-first. */
 const SUMMARY_ORDER = [
@@ -6842,7 +6846,7 @@ const UNANSWERABLE = new Set([
 *
 * `needed` is always selected. `unknown` and `neverRun` are "the question
 * cannot be answered", so they are excluded by default and opted into with
-* `--include-unknown` — fail-open on request, never silently. `notNeeded` and
+* `--only-hub-stale-with-unknown` — fail-open on request, never silently. `notNeeded` and
 * `notEvaluated` are never selected.
 */
 function selectSpecsNeedingRerun(specs, report, opts) {
@@ -7620,7 +7624,7 @@ function safeOriginPath(href) {
 *
 * Two kinds share one namespace:
 *  - "guidance": the record/live prompt bundle — `.user.md` (human-maintained)
-*    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`) —
+*    and `.agent.md` (auto-rewritten by `ccqa run --learn-hub-live-prompt`) —
 *    plus `triage.user`, the human-maintained guidance injected into the
 *    failure-analysis (triage) prompt.
 *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
@@ -8089,7 +8093,7 @@ z.object({
 	lastRed: z.record(z.string(), SpecLedgerEntrySchema).default({})
 });
 /**
-* One spec's last drift audit, as recorded by `ccqa drift --push`. Unlike the
+* One spec's last drift audit, as recorded by `ccqa audit --report-to-hub`. Unlike the
 * spec ledger above, this carries no profile: drift asks whether a spec still
 * describes the code, which has nothing to do with which environment is
 * running it (ADR-0010 draws the same line for "needs re-run").
@@ -8299,7 +8303,7 @@ function isCcqaPath(path) {
 }
 /**
 * A malformed reply costs the whole selection, so it is worth one more call
-* before giving up. `ccqa drift` retries per spec for the same reason; this
+* 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.
@@ -8463,6 +8467,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 capture", 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 +8572,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 +8610,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);
@@ -8522,7 +8621,7 @@ const sessionPush = new Command("push").description("Upload a locally-saved brow
 		state = await loadStorageState(path);
 	} catch (err) {
 		error(`could not read session "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint(`create it first with:  ccqa session bootstrap ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
+		hint(`create it first with:  ccqa hub session capture ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
 		process.exit(2);
 	}
 	await connect(opts).putSession(project, profile, name, state);
@@ -8531,7 +8630,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 +8641,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 +8649,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 +8668,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 +8682,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 +8698,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);
@@ -8609,12 +8708,12 @@ const promptPush = new Command("push").description("Upload a locally-generated p
 		body = await readFile(path, "utf8");
 	} catch (err) {
 		error(`could not read prompt "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	if (body.trim().length === 0) {
 		error(`prompt "${name}" at ${path} is empty`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	await connect(opts).putPrompt(project, name, body);
@@ -8622,7 +8721,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 +8731,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);
@@ -8640,7 +8739,7 @@ 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 user guidance, analysis custom prompt) stored on the hub (fetched automatically by `ccqa run` 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 --changed=last-run`). 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. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. 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) => {
+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-stale`). 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. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. 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) => {
 	const cwd = resolveCwd(opts.cwd);
 	const project = resolveProject(opts);
 	const hub = connect(opts);
@@ -8719,10 +8818,10 @@ function describeSelection(selection, diffAvailable) {
 	const values = Object.values(selection);
 	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 deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --only-hub-stale`.").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 <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 +8853,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);
@@ -8862,7 +8961,7 @@ function generateLiveSessionName() {
 * Project-specific guidance ("the admin tenant is foo.example", "session
 * times out at X minutes", …) is appended from
 * `.ccqa/prompts/live.user.md` (human-maintained) and
-* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --update-agent-prompt`)
+* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --learn-hub-live-prompt`)
 * by the caller, so ccqa stays clean of downstream-product context.
 *
 * Constraint posture: `ccqa record` (trace) enforces a strict selector
@@ -9617,7 +9716,7 @@ const verifiedSessions = /* @__PURE__ */ new Set();
 * each named session from the hub (`.ccqa/sessions/*.json` is no longer
 * read here). Every name must load as a valid agent-browser state (the spec
 * assumes it starts signed-in); a missing/malformed session fails with a
-* `ccqa session bootstrap` hint instead of running unauthenticated.
+* `ccqa hub session capture` hint instead of running unauthenticated.
 *
 * If a session carries an embedded verify URL (bootstrap saved it), the
 * restore is health-checked before the run starts, so an expired/unusable
@@ -9660,7 +9759,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 				if (!check.restored) return {
 					ok: false,
 					error: `session '${name}' did not restore to a signed-in page — ${check.reason}`,
-					hint: `re-bootstrap it: ccqa session bootstrap ${name}${profileFlag}`
+					hint: `re-bootstrap it: ccqa hub session capture ${name}${profileFlag}`
 				};
 				verifiedSessions.add(memoKey);
 			}
@@ -9670,7 +9769,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 	if (broken.length > 0) return {
 		ok: false,
 		error: `session not usable on the hub: ${broken.join(", ")}`,
-		hint: `create it with: ${broken.map((name) => `ccqa session bootstrap ${name}${profileFlag}`).join("  ·  ")}`
+		hint: `create it with: ${broken.map((name) => `ccqa hub session capture ${name}${profileFlag}`).join("  ·  ")}`
 	};
 	const statePath = await writeMergedTempState(mergeStorageStates(loaded));
 	return {
@@ -11543,7 +11642,7 @@ async function groupSpecsByTarget(specs, config, cwd, resolve = resolveTarget) {
 * then each external target group through its runner. Every row is upserted
 * into the incremental report the moment it exists — the runner reports each
 * spec through `onSpecComplete` as it finishes — so an interrupt keeps what
-* already ran and `--push-report` streams spec by spec. Rows are also
+* already ran and `--report-to-hub` streams spec by spec. Rows are also
 * returned for the tail phase (failure analysis) and the final batch write. A
 * crashing runner marks its own specs failed instead of aborting the run.
 */
@@ -11679,7 +11778,7 @@ function createIncrementalReport(reportDir, envelope, sink) {
 //#endregion
 //#region src/prompts/agent-update.ts
 /**
-* Build the prompts used by `--update-agent-prompt` to refresh
+* Build the prompts used by the `--learn-*-prompt` flags to refresh
 * `.ccqa/prompts/<kind>.agent.md` after a run:
 *   - `ccqa run` (live) → `live.agent`
 *   - `ccqa record` (trace) → `record.agent`
@@ -11929,16 +12028,13 @@ 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})`);
-		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 (${auth.reason})`);
 		return;
 	}
+	if (!hubContext) throw new Error(`${flag} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
 	const { hub, project } = hubContext;
 	const promptName = `${kind}.agent`;
 	try {
@@ -11950,7 +12046,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 +12056,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 +12088,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 +12099,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 +12151,23 @@ 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");
+}
+/**
+* Turn a hub transport failure into a usage error, as a `.catch` so the
+* tuple types of the `Promise.all` it guards survive.
+*
+* Without it the raw `fetch failed` escapes as an unhandled rejection: a stack
+* trace and exit 1, where the user needs "the hub is unreachable" and exit 2.
+* Errors the callers already shaped pass through — they say more than this
+* wrapper could.
+*/
+function asHubReadError(err) {
+	if (err instanceof RunUsageError) throw err;
+	throw new RunUsageError(`could not read from the hub: ${errMessage(err)}`);
 }
 /** 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.onlyHubStale || opts.onlyHubAuditedClean);
+	if (filtering && targets.length > 0) throw new RunUsageError("a --only-* filter and an explicit spec target cannot be combined");
+	const rerunProfile = opts.onlyHubStale === true ? requireRerunProfile(opts.hubProfile) : null;
+	if (opts.onlyHubStaleWithUnknown && rerunProfile === null) warn("--only-hub-stale-with-unknown is ignored: it only applies to --only-hub-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 ? {
@@ -12109,8 +12217,8 @@ async function executeRun(targets, opts) {
 		meta("analysis-base", `${fixedBase.ref} (${fixedBase.sha.slice(0, 12)}, ${fixedBase.source})`);
 	}
 	if (forExecution) try {
-		if (opts.profile !== void 0) await resolveProfileEnv({
-			profile: opts.profile,
+		if (opts.hubProfile !== void 0) await resolveProfileEnv({
+			profile: opts.hubProfile,
 			project: resolveProjectOrThrow(opts.project, cwd),
 			cwd,
 			hubUrl: opts.hubUrl,
@@ -12126,7 +12234,7 @@ async function executeRun(targets, opts) {
 		if (err instanceof RunUsageError) throw err;
 		if (err instanceof ProjectNameError) throw new RunUsageError(err.message);
 		if (err instanceof HubConnectionError || err instanceof HubApiError) throw new RunUsageError(err.message);
-		throw new RunUsageError(`failed to load profile "${opts.profile}": ${errMessage(err)}`);
+		throw new RunUsageError(`failed to load profile "${opts.hubProfile}": ${errMessage(err)}`);
 	}
 	let hubCtx = null;
 	try {
@@ -12140,23 +12248,27 @@ 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-hub-stale requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.onlyHubAuditedClean && hubCtx == null) throw new RunUsageError("--only-hub-audited-clean requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.reportToHub && hubCtx == null) throw new RunUsageError("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError("--learn-hub-live-prompt 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,
+		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.hubProfile, cwd) : null,
 		rerunProfile !== null && hubCtx ? fetchRerunReport(hubCtx, rerunProfile) : null,
-		forExecution && hubCtx && opts.profile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.profile) : null
-	]);
+		forExecution && hubCtx && opts.hubProfile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.hubProfile) : null,
+		opts.onlyHubAuditedClean && hubCtx ? fetchAuditedLedger(hubCtx) : null
+	]).catch(asHubReadError);
 	const deployedSha = rerunReport?.deployHead.sha ?? fetchedDeployHead;
 	if (ledgerEntries) diffProvider = createDiffProvider({
 		resolveBase: createLastGreenResolver(ledgerEntries, cwd),
 		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 +12284,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.onlyHubStaleWithUnknown === 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-hub-stale-with-unknown to run them anyway`);
 	}
 	if (specs.length === 0) {
 		warn("no specs to run");
@@ -12210,11 +12328,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.learnHubLivePrompt) 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,17 +12345,16 @@ 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");
 	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();
 		const opened = await hubCtx.hub.openRun({
 			project: hubCtx.project,
 			...branch ? { branch } : {},
-			...opts.profile ? { profile: opts.profile } : {},
+			...opts.hubProfile ? { profile: opts.hubProfile } : {},
 			...git.head ? { gitHead: git.head } : {},
 			...deployedSha ? { deployedSha } : {},
 			...ciRunId ? { ciRunId } : {},
@@ -12259,7 +12376,7 @@ async function executeRun(targets, opts) {
 			}
 		} };
 	} catch (err) {
-		warn(`hub: could not open incremental run (${errMessage(err)}); continuing with local report only`);
+		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
 		git,
@@ -12293,12 +12410,12 @@ 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 } : {},
+		...opts.hubProfile ? { profile: opts.hubProfile } : {},
 		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
@@ -12360,10 +12477,11 @@ async function executeRun(targets, opts) {
 			}
 		}
 	}
-	if (opts.updateAgentPrompt && liveSpecs.length > 0) {
+	if (opts.learnHubLivePrompt && 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 +12567,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 +12776,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;
 }
 /**
@@ -12672,7 +12790,7 @@ const PATCH_FILES_RAW_BUDGET = 20 * 1024 * 1024;
 /**
 * Add one row's file assets to `acc` as `{ reportDir-relative posix path →
 * base64 }`. Every kind of screenshot a row can carry has to be collected here,
-* or `--push-report` — the way CI publishes — silently ships a report whose
+* or `--report-to-hub` — the way CI publishes — silently ships a report whose
 * images 404 on the hub: a live row's per-step PNGs
 * (`liveRun.steps[].beforePng/afterPng`), a script-driven row's step evidence
 * (`evidence[].pngPath` / `beforePngPath`, written by agent-browser replays and
@@ -12901,14 +13019,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-hub-stale", "Only specs the hub says are no longer covered by their last result — each spec's own last run compared against the hub's deploy log. No git diff involved. Requires a hub connection and --hub-profile.").option("--only-hub-stale-with-unknown", "With --only-hub-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-hub-audited-clean", "Only specs the hub's drift ledger records as audited with no drift. 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-hub-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 +13038,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.onlyHubStale ? "stale" : null,
+		opts.onlyHubAuditedClean ? "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
@@ -14425,8 +14547,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);
 }));
 /**
@@ -14549,7 +14671,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;
 	}
@@ -14980,7 +15102,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;
 		}
 	}
@@ -15021,20 +15143,21 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
 }
 /**
-* `ccqa generate --update-agent-prompt`: refresh the target's learned
+* `ccqa generate --learn-hub-codegen-prompt`: refresh the target's learned
 * `<target>.agent` playbook from this generation. Only targets that declare a
 * `guidanceKind` (the LLM-generating ones: playwright, runn) have such a
 * prompt — agent-browser's codegen is mechanical, so point at `ccqa record
-* --update-agent-prompt` for its tracer instead.
+* --learn-hub-trace-prompt` for its tracer instead.
 */
 async function runGenerateAgentPromptUpdate(target, featureName, specName, result, opts, cwd) {
 	if (target.guidanceKind === void 0) {
-		warn(`--update-agent-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
+		warn(`--learn-hub-codegen-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
 		return;
 	}
 	blank();
 	await updateAgentPrompt({
 		kind: target.guidanceKind,
+		flag: "--learn-hub-codegen-prompt",
 		runSummary: buildGenerateRunSummary(target.id, featureName, specName, result, cwd),
 		hubContext: opts.hubContext ?? null,
 		...opts.model ? { model: opts.model } : {},
@@ -15060,7 +15183,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-hub-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);
@@ -15069,9 +15192,9 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		hubToken: opts.hubToken,
 		hubHeader: opts.hubHeader
 	});
-	const project = opts.profile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd,
 		hubUrl: opts.hubUrl,
@@ -15083,22 +15206,26 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		project: "",
 		cwd
 	});
+	if (opts.learnHubCodegenPrompt && hubClient === null) {
+		error("--learn-hub-codegen-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
+	}
 	const hubContext = hubClient && project ? {
 		hub: hubClient,
 		project
 	} : 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.learnHubCodegenPrompt ?? false
 		});
 	} catch (e) {
 		if (e instanceof SpecLockedError) {
@@ -15134,10 +15261,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-hub-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);
@@ -15149,10 +15276,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);
@@ -15161,9 +15284,9 @@ async function runRecord(specPath, opts) {
 		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${featureName}/${specName}' instead`);
 		process.exit(2);
 	}
-	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd: cwdForProfile,
 		hubUrl: opts.hubUrl,
@@ -15185,6 +15308,10 @@ async function runRecord(specPath, opts) {
 		hub: hubClientForTrace,
 		project: hubProject
 	} : null;
+	if (opts.learnHubTracePrompt && hubContext === null) {
+		error("--learn-hub-trace-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
+	}
 	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
 		if (e instanceof SpecLockedError) {
 			error(e.message);
@@ -15194,18 +15321,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,
@@ -15214,11 +15339,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.learnHubTracePrompt && traceResult !== null) {
 		blank();
 		await updateAgentPrompt({
 			kind: "record",
+			flag: "--learn-hub-trace-prompt",
 			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
 			hubContext,
 			...opts.model ? { model: opts.model } : {},
@@ -15499,8 +15624,8 @@ function specStatus(result, threshold) {
 	return "passed";
 }
 /**
-* 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
+* Adapts `ccqa audit` results into the shared RunReportData shape so they can
+* 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
@@ -15546,35 +15671,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-hub-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;
@@ -15595,7 +15719,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,
@@ -15608,9 +15732,9 @@ 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`
-* never changes drift's own exit code).
+* shows up alongside `ccqa run` runs in the hub UI. A missing hub connection
+* is a usage error, not a silent skip — a CI job that asked to publish and
+* did not must say so.
 *
 * `resolveHub` is injectable so tests can supply a fake `HubClient` without
 * a real hub connection; it defaults to the real flag/env resolution.
@@ -15619,8 +15743,8 @@ 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");
-		return;
+		error("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
 	}
 	try {
 		const project = resolveProject({
@@ -15697,7 +15821,7 @@ function parseFormat$1(raw) {
 function parseSeverity(raw) {
 	const v = raw ?? "error";
 	if (v === "warn" || v === "error") return v;
-	error(`invalid --severity: ${v} (expected warn|error)`);
+	error(`invalid --exit-on: ${v} (expected warn|error)`);
 	process.exit(2);
 }
 function parseConcurrency(raw) {
@@ -15805,102 +15929,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) {
@@ -16263,7 +16291,7 @@ function countSpecs(results) {
 * or `red` (the last outcome), which are orthogonal axes.
 *
 * Best-effort — a ledger failure must not fail the push; the ledger is an
-* accelerator for `--failure-analysis=last-green` and re-run selection, not
+* accelerator for `--on-fail-explain` baselines and re-run selection, not
 * part of the run record. Runs without a branch or gitHead can't be placed in
 * the ledger and are skipped.
 *
@@ -16907,7 +16935,7 @@ function createGetLastGreenHandler(storage) {
 /**
 * GET /api/v1/projects/:project/drift
 *
-* Every spec's last `ccqa drift --push` audit, keyed by "feature/spec". No
+* Every spec's last `ccqa audit --report-to-hub` result, keyed by "feature/spec". No
 * `?profile=` — drift asks whether a spec still describes the code, which
 * has nothing to do with which environment is running it, unlike the
 * `/rerun` and `/last-green` endpoints. Merged across every branch (newest
@@ -18009,7 +18037,7 @@ const HTML_BODY = `
           <div style="font-weight:600" data-i18n="session.help.title">How to get this JSON</div>
           <ol class="help-steps">
             <li><span class="step-n">1</span><div class="step-b"><span data-i18n="session.help.step1">Run this in your terminal and log in by hand when the browser opens:</span>
-              <div class="cmd"><code id="session-help-cmd">ccqa session bootstrap &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
+              <div class="cmd"><code id="session-help-cmd">ccqa hub session capture &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
             </div></li>
             <li><span class="step-n">2</span><div class="step-b"><span data-i18n="session.help.step2">Open the saved file and paste its contents below:</span>
               <div style="margin-top:5px"><span class="path">.ccqa/sessions/&lt;profile&gt;/&lt;name&gt;.json</span></div>
@@ -20135,7 +20163,7 @@ const CLIENT_JS = `
     }
 
     // A drift-kind row's diagnosis lives in analysis regardless of status
-    // (an UNKNOWN-labelled finding below the --severity threshold still
+    // (an UNKNOWN-labelled finding below the --exit-on threshold still
     // "passes" but has something to show); a normal run only ever classifies
     // a failed spec.
     var hasAnalysis = isDrift ? !!r.analysis : r.status === "failed" && r.analysis;
@@ -21128,7 +21156,7 @@ const CLIENT_JS = `
   //
   // "unknown" keeps its own state rather than folding into the last result:
   // it means the hub cannot say whether that result still holds, and
-  // --changed=last-run does not re-run it without --include-unknown. Showing
+  // --only-hub-stale does not re-run it without --only-hub-stale-with-unknown. Showing
   // it as passed or failed would claim a confidence nothing supports.
   function perspRunState(rr) {
     if (!rr) return null;
@@ -23366,17 +23394,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 {};