ccqa 1.55.0 → 1.57.0

package/dist/bin/ccqa.mjs

@@ -16323,6 +16323,88 @@ function resolveTargetFrom(spec, config, registry) {
 	return plugin;
 }
 //#endregion
+//#region src/drift/renames.ts
+/**
+* What the audit says was renamed, and which of a case's files still say it.
+*
+* A rename is the one finding a machine can act on without reading prose, but
+* only once it is known *where* the old string survives: the case's document
+* decides whether an edit is needed, and the saved recording decides whether
+* recompiling that document is enough (ADR-0035). Both answers are string
+* comparisons against text ccqa already holds, which is what keeps them out of
+* the model's hands.
+*/
+/**
+* A string the test case still uses, and what the product renders in its place.
+*
+* Answered by the audit, never parsed back out of its prose: a quoted run is a
+* guess about one project's punctuation (ADR-0035).
+*/
+const RenameSchema = z.object({
+	from: z.string(),
+	to: z.string()
+});
+/**
+* The audit's renames, sanitized and checked against the document.
+*
+* A blank `from` matches everywhere and an identity pair edits nothing, so
+* neither is an instruction. Blank is tested after trimming and kept
+* untrimmed: a trimmed `from` is a string ccqa never checked the document for.
+* Two pairs naming the same `from` differently are the audit contradicting
+* itself, and both go — picking a winner would invent an answer nobody gave.
+*/
+function auditedRenames(document, renames) {
+	const byFrom = /* @__PURE__ */ new Map();
+	for (const r of renames) {
+		if (r.from.trim() === "" || r.to.trim() === "" || r.from === r.to) continue;
+		const kept = byFrom.get(r.from);
+		if (kept === void 0) byFrom.set(r.from, r);
+		else if (kept !== null && kept.to !== r.to) byFrom.set(r.from, null);
+	}
+	return [...byFrom.values()].filter((r) => r !== null).map((r) => ({
+		...r,
+		inDocument: document.includes(r.from)
+	}));
+}
+/**
+* Whether the saved recording still names a string the audit says was renamed.
+*
+* It decides between the two machine repairs: a recording that names the old
+* string compiles it back in, so the case has to be recorded again rather than
+* regenerated. Missing one is not dangerous — the case routes to `regenerate`,
+* whose replay gate then refuses the dead recording — but it costs a browser
+* run to find that out.
+*
+* Walked value by value rather than over a serialization: `JSON.stringify`
+* escapes quotes and backslashes, so a `from` holding one would silently miss.
+*/
+function recordingNamesRenamed(recording, renames) {
+	if (renames.length === 0) return false;
+	return [...recording.actions, ...recording.cleanup ?? []].some((action) => actionStrings(action).some((text) => renames.some((r) => text.includes(r.from))));
+}
+/**
+* The strings a recorded action takes from the product: what it typed or
+* asserted, and how it addressed the element. What the recorder wrote about an
+* action — its observation, its step id, why it replayed badly — is ccqa's own
+* prose and would match on words the product never rendered.
+*/
+function actionStrings(action) {
+	return [
+		action.value,
+		action.label,
+		...locatorStrings(action.locator),
+		...locatorStrings(action.target)
+	].filter((s) => s !== void 0 && s !== "");
+}
+/**
+* A role locator is addressed by its accessible name; its `value` is the ARIA
+* role, which is that vocabulary rather than anything the product wrote.
+*/
+function locatorStrings(locator) {
+	if (locator === void 0) return [];
+	return locator.by === "role" ? [locator.name] : [locator.value];
+}
+//#endregion
 //#region src/drift/types.ts
 /** How everything downstream spells this case: its intent-source id, or `feature/spec`. */
 function caseIdOf(target) {
@@ -16344,7 +16426,8 @@ const LocatorVerdictSchema = z.object({
 /** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
 const DriftReplySchema = z.object({
 	drift: DriftDiagnosisSchema.nullable(),
-	locators: z.array(LocatorVerdictSchema).default([])
+	locators: z.array(LocatorVerdictSchema).default([]),
+	renames: z.array(RenameSchema.nullable().catch(null)).transform((rs) => rs.filter((r) => r !== null)).default([]).catch([])
 });
 /**
 * How a label reads against `--exit-on`. The threshold asks "would a
@@ -27338,7 +27421,7 @@ These are the same definitions failure analysis uses on a case that actually fai
 
 ## What separates TEST_DRIFT from SPEC_CHANGE
 
-This is the distinction that matters, because the two lead to different actions: TEST_DRIFT gets the test re-recorded, SPEC_CHANGE gets a human to rewrite the spec.
+This is the distinction that matters, because the two lead to different actions: TEST_DRIFT gets the stale string replaced wherever it is written and the test recompiled, SPEC_CHANGE gets a human to decide what the case should now say.
 
 Ask whether the **intent** the step describes still exists in the product:
 
@@ -27433,12 +27516,17 @@ Drift found:
     "evidence": [
       { "file": "<path:line>", "detail": "<what this proves>" }
     ]
-  }
+  },
+  "renames": [
+    { "from": "<the string as the test case writes it>", "to": "<what the source renders in its place>" }
+  ]
 }
 \`\`\`
 
 \`subDiagnosis\`: \`SELECTOR_DRIFT\` when a selector or string was renamed, \`OVER_ASSERTION\` when the case asserts something narrower than the product ever promised, \`NONE\` otherwise.
 
+\`renames\`: one entry per renamed string, when the label is \`TEST_DRIFT\` and \`subDiagnosis\` is \`SELECTOR_DRIFT\` — a finding that says a string was renamed and does not name the pair leaves the repair to a person. Omit the key otherwise. It sits beside \`drift\`, and beside \`locators\` where that was asked for. \`from\` is the string as the test case writes it — in the generated code, in the case's own document, or both — and \`to\` is what the source you cited renders in its place. Give each verbatim, with no quotes, ellipses or paraphrase of your own: each pair is looked up character for character in the file it claims to be about, and one that does not match is dropped. Naming a rename neither settles the label nor stands in for the citation the finding still needs.
+
 \`specChangeKind\`: set it only when the label is \`SPEC_CHANGE\`, and omit the field entirely otherwise. It says which repair the case needs — deleting it, or rewriting and re-recording it:
 
 - \`FEATURE_REMOVED\` — the code no longer implements the behaviour at all: removed, moved elsewhere, or deliberately disabled. This is the stronger claim, so earn it: your evidence must point at where the implementation would be if it still existed.
@@ -27996,7 +28084,7 @@ async function checkSpec(target, opts) {
 		locators,
 		systemPrompt,
 		userPrompt
-	}).then((path) => meta("inputs", path), (err) => warn(`${name}: could not write the audit inputs (${err.message})`));
+	}).catch((err) => warn(`${name}: could not write the audit inputs (${err.message})`));
 	const MAX_ATTEMPTS = 2;
 	let lastError = "";
 	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
@@ -28048,7 +28136,8 @@ async function checkSpec(target, opts) {
 				drift,
 				live: artifacts.live,
 				title: artifacts.title,
-				documentPath: artifacts.intent.path
+				documentPath: artifacts.intent.path,
+				renames: auditedRenames(artifacts.intent.body, reply.renames)
 			};
 		} catch (e) {
 			lastError = `failed to parse drift reply: ${e.message}`;
@@ -28066,12 +28155,12 @@ async function checkSpec(target, opts) {
 //#endregion
 //#region src/drift/format.ts
 /**
-* Render drift results as a string. The CLI commands and the `run` failure
-* hook are the only callers; both want the formatted output returned so
-* they can prefix / interleave / pipe it as needed.
+* Render drift results for a terminal. `json` is not one of these: it prints
+* the same payload the report file holds, which is assembled asynchronously
+* and so is built once by the caller rather than rendered from results here
+* (`buildAuditReport`).
 */
 function renderDrift(results, format, cwd) {
-	if (format === "json") return renderJson(results);
 	if (format === "github") return renderGithub(results, cwd);
 	return renderText$1(results);
 }
@@ -28106,16 +28195,6 @@ function renderText$1(results) {
 	out.push("");
 	return out.join("\n");
 }
-function renderJson(results) {
-	const payload = { specs: results.map((r) => ({
-		feature: r.target.featureName,
-		spec: r.target.specName,
-		ok: r.ok,
-		...r.error ? { error: r.error } : {},
-		drift: r.drift
-	})) };
-	return `${JSON.stringify(payload, null, 2)}\n`;
-}
 function renderGithub(results, cwd) {
 	const repoRoot = process.env["GITHUB_WORKSPACE"] ?? process.cwd();
 	const lines = [];
@@ -28187,7 +28266,7 @@ function determineExitCode(results, threshold) {
 //#endregion
 //#region src/drift/to-report.ts
 /** Tracks the drift prompt's own version — the two must never drift apart. */
-const DRIFT_REPORT_PROMPT_VERSION = "11";
+const DRIFT_REPORT_PROMPT_VERSION = "12";
 /**
 * Spec-level status under the given threshold, mirroring determineExitCode's
 * per-spec logic (exit-code.ts) but scoped to a single SpecResult.
@@ -28246,71 +28325,97 @@ function driftResultsToReport(results, meta) {
 	};
 }
 //#endregion
-//#region src/drift/brief.ts
+//#region src/drift/audit-report.ts
 /**
-* Write one JSON file per finding, named by the case id below `dir`. Returns
-* the paths written, in the order the results came in.
+* What `ccqa audit` leaves behind for a machine.
+*
+* The audit has three audiences: the person reading the terminal, the hub's
+* ledger, and whatever repairs the test. This is the third, and it is one
+* payload — written to `<report-dir>/audit.json` by every completed sweep and
+* printed verbatim by `--report-format json` (ADR-0036).
 */
-async function writeAuditBriefs(input) {
-	const findings = input.results.filter((r) => r.drift !== null);
-	if (findings.length === 0) return [];
-	const ctx = input.context ?? await loadSpecArtifactsContext(input.cwd);
-	const dirAbs = resolve(input.cwd, input.dir);
-	return Promise.all(findings.map(async (result) => {
-		const brief = await buildBrief(result, input.cwd, ctx);
-		const path = join(dirAbs, `${brief.case}.json`);
-		await mkdir(dirname(path), { recursive: true });
-		await writeFile(path, `${JSON.stringify(brief, null, 2)}\n`, "utf8");
-		return path;
-	}));
+/** The file the report is written as, inside the report directory. */
+const AUDIT_REPORT_FILE = "audit.json";
+/**
+* The payload, for both the file and `--report-format json`. Each row's reads
+* are independent, so they resolve together rather than one case at a time.
+*/
+async function buildAuditReport(results, cwd, ctx) {
+	return { specs: await Promise.all(results.map((r) => buildRow(r, cwd, ctx))) };
+}
+/** Write the report as `<dirAbs>/audit.json`, creating the directory. Returns its path. */
+async function writeAuditReport(report, dirAbs) {
+	await mkdir(dirAbs, { recursive: true });
+	const path = join(dirAbs, AUDIT_REPORT_FILE);
+	await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+	return path;
 }
-async function buildBrief(result, cwd, ctx) {
+async function buildRow(result, cwd, ctx) {
 	const drift = result.drift;
-	const id = caseIdOf(result.target);
+	const row = {
+		feature: result.target.featureName,
+		spec: result.target.specName,
+		case: caseIdOf(result.target),
+		ok: result.ok,
+		...result.error ? { error: result.error } : {},
+		drift
+	};
+	if (drift === null) return row;
 	const test = result.live ? null : await caseTestPath(result.target, ctx);
+	const rewrite = drift.label === "TEST_DRIFT" ? (result.renames ?? []).filter((r) => r.inDocument).map(({ from, to }) => ({
+		from,
+		to
+	})) : [];
 	return {
-		case: id,
-		kind: drift.label,
-		surface: drift.surface,
-		confidence: drift.confidence,
-		headline: drift.headline,
-		recommendation: drift.recommendation,
-		reasoning: drift.reasoning,
-		evidence: drift.evidence,
+		...row,
 		test,
-		repair: await repairRoute(result, test, cwd, ctx)
+		document: documentOf(result, cwd),
+		repair: await buildRepair(result, test, rewrite, cwd, ctx)
 	};
 }
-async function repairRoute(result, test, cwd, ctx) {
+/**
+* The case's document as something that can be opened from anywhere. A case
+* filed outside the project relativizes to `../…`, which resolves against
+* whatever directory the fix job happens to be in rather than this one.
+*/
+function documentOf(result, cwd) {
+	const rel = result.documentPath;
+	if (rel === void 0) return null;
+	return rel.startsWith("..") ? resolve(cwd, rel) : rel;
+}
+async function buildRepair(result, test, rewrite, cwd, ctx) {
 	const drift = result.drift;
-	if (result.live || test === null) return {
+	const renames = result.renames ?? [];
+	const external = (reason) => ({
 		route: "external",
-		reason: "this case runs live: the document is the test"
-	};
-	if (drift.label !== "TEST_DRIFT") return {
-		route: "external",
-		reason: `${drift.label} is not repaired by regenerating: the same document would compile to the same test`
-	};
-	if (drift.surface !== "generated") return {
-		route: "external",
-		reason: "the finding is not on the generated test — the document, or a file the test imports and a regeneration only reads. Either way, regenerating rewrites neither"
+		reason,
+		rewrite
+	});
+	if (drift.label !== "TEST_DRIFT") return external(`${drift.label} names no repair a machine can make: recompiling or re-recording reproduces the case as it stands`);
+	if (result.live) return rewrite.length === 0 ? external("a live case is repaired by rewriting its document, and nothing the audit named is in it") : {
+		route: "rewrite",
+		reason: "a live case runs its document, so rewriting it is the whole repair — apply 'rewrite' to 'document', then run the case to verify.",
+		rewrite
 	};
+	if (test === null) return external("this case resolves to no generated test: there is nothing to regenerate");
 	const testAbs = resolve(cwd, test);
-	const stamp = (await getRecording(caseRefFor(result.target.caseId ?? {
+	const recording = await getRecording(caseRefFor(result.target.caseId ?? {
 		featureName: result.target.featureName,
 		specName: result.target.specName
-	}, cwd, await caseRecordingPath(result.target, ctx) ?? void 0)).catch(() => null))?.generated;
-	if (!stamp) return {
-		route: "external",
-		reason: "no generation stamp: ccqa did not write this test, or it predates the stamp"
-	};
-	if (!await matchesGenerationStamp(stamp, testAbs)) return {
-		route: "external",
-		reason: "the test has been edited since it was generated"
-	};
+	}, cwd, await caseRecordingPath(result.target, ctx) ?? void 0)).catch(() => null);
+	if (!recording?.generated) return external("no generation stamp: ccqa did not write this test, or it predates the stamp");
+	if (!await matchesGenerationStamp(recording.generated, testAbs)) return external("the test has been edited since it was generated");
+	const apply = (why) => rewrite.length > 0 ? ` Apply 'rewrite' to 'document' first: ${why}.` : "";
+	if (recordingNamesRenamed(recording, renames)) return {
+		route: "rerecord",
+		reason: `the saved recording names a renamed string, so a regeneration would compile it back in — re-record and verify.${apply("a re-recording drives the case as its document states it")}`,
+		rewrite
+	};
+	if (drift.surface !== "generated" && rewrite.length === 0) return external("the finding is not on the generated test, and nothing it named is in the document — it is on a file the test imports, which a regeneration only reads, or no replacement was named");
 	return {
 		route: "regenerate",
-		reason: `test drift in generated code, unchanged since ccqa generated it on ${stamp.at} — regenerate and verify: regenerating makes the case eligible for repair, not repaired`
+		reason: `test drift, and the saved recording names no renamed string — regenerate and verify.${apply("regenerating alone recompiles the same document")}`,
+		rewrite
 	};
 }
 //#endregion
@@ -28530,7 +28635,7 @@ function selectSpecsNeedingAudit(targets, report, stillDrifted = /* @__PURE__ */
 //#endregion
 //#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Specs without a measurement are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, one the hub cannot answer for is audited rather than skipped, and one whose drift entry is still open is always re-audited — a merged fix changes only the spec tree, which no deploy answer covers. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--brief <dir>", "Also write one JSON file per finding under <dir>, named by case id: the verdict, its citations, and whether the test can be regenerated or has to be repaired by hand. What reads them is outside ccqa.").option("--dump-inputs <dir>", "Also write what each case's audit was given — its document, every file it was handed and the import that reached it, the source roots, and the prompt — as one markdown file per case under <dir>. For telling 'this never reached the audit' apart from 'it did, and nothing was reported'.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
+const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Specs without a measurement are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, one the hub cannot answer for is audited rather than skipped, and one whose drift entry is still open is always re-audited — a merged fix changes only the spec tree, which no deploy answer covers. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-dir <dir>", `Directory for the structured audit results (audit.json), which are always written. Default: ${DEFAULT_REPORT_DIR}/.`).option("--report-format <fmt>", "Terminal output format: text | json | github. 'json' prints the same payload audit.json holds, and nothing else.", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--dump-inputs <dir>", "Also write what each case's audit was given — its document, every file it was handed and the import that reached it, the source roots, and the prompt — as one markdown file per case under <dir>. For telling 'this never reached the audit' apart from 'it did, and nothing was reported'.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("audit", () => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {
@@ -28538,6 +28643,11 @@ async function runAudit(specPath, opts) {
 	const threshold = parseSeverity(opts.exitOn);
 	const concurrency = parseConcurrency(opts.concurrency);
 	const cwd = resolveCwd(opts.cwd);
+	const reportDir = resolve(cwd, opts.reportDir ?? "ccqa-report");
+	await rm(join(reportDir, AUDIT_REPORT_FILE), {
+		force: true,
+		recursive: true
+	}).catch(() => {});
 	await ensureCcqaDir(cwd);
 	if (opts.onlyAffectedBy && specPath) {
 		error("--only-affected-by and an explicit spec id cannot be combined; it only applies to a full sweep");
@@ -28571,11 +28681,18 @@ async function runAudit(specPath, opts) {
 	const intent = artifactsContext.reader.target;
 	const sourceRoots = await resolveSourceRoots(cwd, config.sourceRoots);
 	let targets = await collectTargets(specPath, cwd, artifactsContext.reader);
-	if (targets.length === 0) exitWithNoSpecs(format, "noSpecsFound", `no test cases found under ${intent ? intent.module : ".ccqa/features/"}`);
+	if (targets.length === 0) {
+		const where = intent ? intent.module : ".ccqa/features/";
+		await exitWithNoSpecs({
+			format,
+			reportDir
+		}, "noSpecsFound", `no test cases found under ${where}`);
+	}
 	if (format === "text") {
 		header("audit", specPath ?? `${targets.length} case${targets.length > 1 ? "s" : ""}`);
 		if (opts.cwd) meta("cwd", cwd);
 		for (const root of sourceRoots) meta("source", root.abs);
+		if (opts.dumpInputs) meta("inputs", resolve(cwd, opts.dumpInputs));
 	}
 	if (opts.onlyHubAuditNeeded) {
 		const total = targets.length;
@@ -28590,12 +28707,18 @@ async function runAudit(specPath, opts) {
 			meta("hub", selection.summary);
 			meta("scoped", `${targets.length} of ${total} spec${total > 1 ? "s" : ""}`);
 		}
-		if (targets.length === 0) exitWithNoSpecs(format, "allCurrent", "every spec has been audited since the last deploy that reached it");
+		if (targets.length === 0) await exitWithNoSpecs({
+			format,
+			reportDir
+		}, "allCurrent", "every spec has been audited since the last deploy that reached it");
 		holder = randomUUID();
 		const claimed = await claimSpecs(hub, hubProject, opts.hubProfile, targets, holder);
 		if (claimed.length < targets.length && format === "text") meta("held-elsewhere", `${targets.length - claimed.length} spec(s) another job is auditing`);
 		targets = claimed;
-		if (targets.length === 0) exitWithNoSpecs(format, "allHeld", "every spec that needs auditing is already being audited by another job");
+		if (targets.length === 0) await exitWithNoSpecs({
+			format,
+			reportDir
+		}, "allHeld", "every spec that needs auditing is already being audited by another job");
 	}
 	let baseRef = null;
 	if (opts.onlyAffectedBy) {
@@ -28609,7 +28732,10 @@ async function runAudit(specPath, opts) {
 		targets = selection.specs;
 		baseRef = selection.base.ref;
 		if (format === "text") meta("scoped", `${targets.length} of ${total} spec${total > 1 ? "s" : ""}`);
-		if (targets.length === 0) exitWithNoSpecs(format, "noDiffIntersection", "no specs intersect the changed file set; nothing to check");
+		if (targets.length === 0) await exitWithNoSpecs({
+			format,
+			reportDir
+		}, "noDiffIntersection", "no specs intersect the changed file set; nothing to check");
 	}
 	const blocks = await loadAvailableBlocks(cwd);
 	let pushConn = null;
@@ -28650,7 +28776,10 @@ async function runAudit(specPath, opts) {
 	} finally {
 		if (holder) await releaseSpecs(hub, hubProject, opts.hubProfile, holder);
 	}
-	process.stdout.write(renderDrift(results, format, cwd));
+	const report = await buildAuditReport(results, cwd, artifactsContext);
+	if (format === "json") process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	else process.stdout.write(renderDrift(results, format, cwd));
+	const written = await tryWriteReport(report, reportDir, format);
 	if (push) await sealDriftPush(push, {
 		results,
 		threshold,
@@ -28659,18 +28788,22 @@ async function runAudit(specPath, opts) {
 		baseRef,
 		promptCtx
 	});
-	if (opts.brief) try {
-		const written = await writeAuditBriefs({
-			results,
-			cwd,
-			dir: opts.brief,
-			context: artifactsContext
-		});
-		if (format === "text") meta("briefs", `${written.length} written to ${opts.brief}`);
+	process.exit(written ? determineExitCode(results, threshold) : 2);
+}
+/**
+* Write the report, saying whether it landed. A sweep whose results never
+* landed has to fail: the next reader of `audit.json` would otherwise act on
+* the previous invocation's findings with nothing saying so.
+*/
+async function tryWriteReport(report, dirAbs, format) {
+	try {
+		const path = await writeAuditReport(report, dirAbs);
+		if (format === "text") meta("report", path);
+		return true;
 	} catch (e) {
-		error(`could not write briefs to ${opts.brief}: ${errMessage(e)}`);
+		error(`could not write the audit report to ${dirAbs}: ${errMessage(e)}`);
+		return false;
 	}
-	process.exit(determineExitCode(results, threshold));
 }
 /** Longer than the audit's own timeout, so a sweep cannot outlive its claim. */
 const AUDIT_LOCK_TTL_SECONDS = 5400;
@@ -28796,14 +28929,21 @@ async function resolveAuditPromptContext(opts, cwd, resolveCtx = resolveAuditHub
 function asHubReadError(err) {
 	throw new RunUsageError(`could not read from the hub: ${errMessage(err)}`);
 }
-function exitWithNoSpecs(format, reason, message) {
-	if (format === "json") process.stdout.write(`${JSON.stringify({
+/**
+* Nothing to audit — still a result, and still written. A reader that found
+* yesterday's `audit.json` where this sweep left none would act on findings
+* nothing had re-checked.
+*/
+async function exitWithNoSpecs(ctx, reason, message) {
+	const { format, reportDir } = ctx;
+	const report = {
 		specs: [],
 		skipped: reason
-	}, null, 2)}\n`);
+	};
+	if (format === "json") process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 	else if (format === "text") info(message);
 	else if (format === "github" && reason === "noSpecsFound") process.stdout.write(`::warning::${message}\n`);
-	process.exit(0);
+	process.exit(await tryWriteReport(report, reportDir, format) ? 0 : 2);
 }
 /**
 * The cases this sweep audits.

package/dist/hub-client/index.d.cts

@@ -35,9 +35,9 @@ declare const RunSchema: z.ZodObject<{
     running: "running";
   }>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   drift: z.ZodDefault<z.ZodNullable<z.ZodObject<{
     specs: z.ZodNumber;
@@ -831,9 +831,9 @@ type ReportSpecResult = z.infer<typeof ReportSpecResultSchema>;
 declare const RunReportDataSchema: z.ZodObject<{
   schemaVersion: z.ZodLiteral<1>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   createdAt: z.ZodString;
   runId: z.ZodNullable<z.ZodString>;

package/dist/hub-client/index.d.mts

@@ -35,9 +35,9 @@ declare const RunSchema: z.ZodObject<{
     running: "running";
   }>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   drift: z.ZodDefault<z.ZodNullable<z.ZodObject<{
     specs: z.ZodNumber;
@@ -831,9 +831,9 @@ type ReportSpecResult = z.infer<typeof ReportSpecResultSchema>;
 declare const RunReportDataSchema: z.ZodObject<{
   schemaVersion: z.ZodLiteral<1>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   createdAt: z.ZodString;
   runId: z.ZodNullable<z.ZodString>;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {