ccqa 1.56.0 → 1.57.0

package/dist/bin/ccqa.mjs

@@ -28084,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++) {
@@ -28155,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);
 }
@@ -28195,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 = [];
@@ -28335,41 +28325,49 @@ 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))) };
 }
-async function buildBrief(result, 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 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,
 		document: documentOf(result, cwd),
 		repair: await buildRepair(result, test, rewrite, cwd, ctx)
@@ -28637,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, which repair the case needs (regenerate, re-record, rewrite its document, or a person), and any renamed strings to apply to that document first. 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) {
@@ -28645,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");
@@ -28678,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;
@@ -28697,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) {
@@ -28716,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;
@@ -28757,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,
@@ -28766,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;
@@ -28903,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;
@@ -652,8 +652,8 @@ declare const ReportSpecResultSchema: z.ZodObject<{
   title: z.ZodNullable<z.ZodString>;
   target: z.ZodOptional<z.ZodString>;
   mode: z.ZodOptional<z.ZodEnum<{
-    deterministic: "deterministic";
     live: "live";
+    deterministic: "deterministic";
   }>>;
   status: z.ZodEnum<{
     passed: "passed";
@@ -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>;
@@ -874,8 +874,8 @@ declare const RunReportDataSchema: z.ZodObject<{
     title: z.ZodNullable<z.ZodString>;
     target: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<{
-      deterministic: "deterministic";
       live: "live";
+      deterministic: "deterministic";
     }>>;
     status: z.ZodEnum<{
       passed: "passed";

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;
@@ -652,8 +652,8 @@ declare const ReportSpecResultSchema: z.ZodObject<{
   title: z.ZodNullable<z.ZodString>;
   target: z.ZodOptional<z.ZodString>;
   mode: z.ZodOptional<z.ZodEnum<{
-    deterministic: "deterministic";
     live: "live";
+    deterministic: "deterministic";
   }>>;
   status: z.ZodEnum<{
     passed: "passed";
@@ -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>;
@@ -874,8 +874,8 @@ declare const RunReportDataSchema: z.ZodObject<{
     title: z.ZodNullable<z.ZodString>;
     target: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<{
-      deterministic: "deterministic";
       live: "live";
+      deterministic: "deterministic";
     }>>;
     status: z.ZodEnum<{
       passed: "passed";

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.56.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.56.0",
+  "version": "1.57.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {