ccqa 1.55.0 → 1.56.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.
@@ -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}`;
@@ -28187,7 +28276,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.
@@ -28268,6 +28357,10 @@ async function buildBrief(result, cwd, ctx) {
 	const drift = result.drift;
 	const id = caseIdOf(result.target);
 	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,
@@ -28278,39 +28371,53 @@ async function buildBrief(result, cwd, ctx) {
 		reasoning: drift.reasoning,
 		evidence: drift.evidence,
 		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 +28637,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-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) => {
 	await withCostReporting("audit", () => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {

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

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

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

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

package/dist/package.json

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