ccqa 1.52.0 → 1.53.0

package/dist/bin/ccqa.mjs

@@ -19,7 +19,7 @@ import { createInterface as createInterface$1 } from "node:readline/promises";
 import { createServer } from "node:http";
 import { connect, createServer as createServer$1 } from "node:net";
 import { connect as connect$1 } from "node:tls";
-import { gunzipSync, gzipSync } from "node:zlib";
+import { gunzipSync, gzipSync, inflateRawSync } from "node:zlib";
 import { pipeline } from "node:stream/promises";
 //#region src/spec/yaml-schema.ts
 /**
@@ -3876,6 +3876,17 @@ async function fireMockPreToolUseHooks(msg, options) {
 * drift). Centralised so the prompts cannot drift apart on mechanics that
 * must stay consistent across commands.
 */
+/**
+* `body` inside a fence the body itself cannot close. What prompts embed this
+* way — the project's guides, a markdown draft — carries fences of its own, and
+* a three-backtick wrapper around one ends at the first of them: everything
+* after it then reads as the prompt's own words.
+*/
+function fencedBlock(body) {
+	const longest = Math.max(0, ...[...body.matchAll(/`+/g)].map((m) => m[0].length));
+	const fence = "`".repeat(Math.max(3, longest + 1));
+	return `${fence}\n${body}\n${fence}`;
+}
 /** Prefix every line with its 1-based number, the form fix suggestions cite. */
 function numberLines(script) {
 	return script.split("\n").map((l, i) => `${i + 1}: ${l}`).join("\n");
@@ -5616,6 +5627,12 @@ const ARTIFACTS_DIR_VAR = "{artifactsDir}";
 const ARTIFACTS_DIR_ENV = "CCQA_ARTIFACTS_DIR";
 /** The runner's full stdout+stderr capture, always written into the artifacts dir. */
 const OUTPUT_LOG_FILE = "output.log";
+/** What Playwright names the trace it writes under the output dir, one per test. */
+const TRACE_ARCHIVE_FILE = "trace.zip";
+/** Whether a path under the artifacts dir names one of those traces. */
+function isTraceArchive(rel) {
+	return rel === TRACE_ARCHIVE_FILE || rel.endsWith(`/${TRACE_ARCHIVE_FILE}`);
+}
 /** `<reportDir>/artifacts/<feature>__<spec>` — created before the runCommand runs. */
 function specArtifactsDir(reportDir, feature, spec) {
 	return join(reportDir, ARTIFACTS_SUBDIR, `${feature}__${spec}`);
@@ -5628,6 +5645,7 @@ function specArtifactsDir(reportDir, feature, spec) {
 function substituteArtifactsDir(command, artifactsDir) {
 	return command.replaceAll(ARTIFACTS_DIR_VAR, quoteForShell(artifactsDir));
 }
+/** Single quotes survive every shell metacharacter except themselves. */
 function quoteForShell(s) {
 	return /^[A-Za-z0-9_./-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`;
 }
@@ -5665,8 +5683,8 @@ async function collectSpecArtifacts(args) {
 	};
 	const dir = specArtifactsDir(args.reportDir, args.feature, args.spec);
 	const relPrefix = posix.join(ARTIFACTS_SUBDIR, `${args.feature}__${args.spec}`);
-	const relFiles = await walkFiles$1(dir, "");
-	relFiles.sort((a, b) => a === "output.log" ? -1 : b === "output.log" ? 1 : a.localeCompare(b));
+	const relFiles = await walkFiles$1(dir);
+	relFiles.sort((a, b) => rowRank(a) - rowRank(b) || a.localeCompare(b));
 	const kept = [];
 	const dropped = [];
 	let totalBytes = 0;
@@ -5691,8 +5709,21 @@ async function collectSpecArtifacts(args) {
 	}
 	return kept;
 }
+/**
+* Where a file sits in the row order, and so which files the caps cut first.
+*
+* A Playwright trace is tens of megabytes and ccqa asks for one on every run
+* it can — taken before the rest of the budget it would be the whole of it,
+* and the screenshots and reports a reader actually opens would be the files
+* dropped. Ranked last it takes only what is left, and it is still on disk and
+* in the pushed bundle either way.
+*/
+function rowRank(rel) {
+	if (rel === "output.log") return 0;
+	return isTraceArchive(rel) ? 2 : 1;
+}
 /** All files under `dir` as posix paths relative to it; missing dir → []. */
-async function walkFiles$1(dir, relBase) {
+async function walkFiles$1(dir, relBase = "") {
 	let entries;
 	try {
 		entries = await readdir(dir, { withFileTypes: true });
@@ -6361,12 +6392,28 @@ function askCdpUrl(session) {
 * which step, and a format that only one side knew would silently produce a
 * table with every row empty.
 */
-/** `// step: step-01 [case]` — the identifier form, for a `spec.yaml` step. */
-const ID_FORM = /^\s*\/\/\s*step:\s*(\S+)\s*\[/;
-/** `// step 1: <text>` / `// cleanup 1: <text>` — the English cited form. */
-const CITED_EN = /^\s*\/\/\s*(step|cleanup)\s+(\d+)\s*:/;
-/** `// 1. <text>` / `// 後処理 1. <text>` — the Japanese cited form. */
-const CITED_JA = /^\s*\/\/\s*(後処理\s*)?(\d+)\s*[.．]\s/;
+/**
+* `step: step-01 [case]` — the identifier form, for a `spec.yaml` step.
+*
+* Anchored, and the bracket is read only as part of it: a cited step's text is
+* prose, and prose holds brackets of its own ("click the [Save] button") that
+* would otherwise be read as the step's source.
+*/
+const ID_FORM = /^\s*step:\s*(\S+?)\s*\[([^\]]+)\]/;
+/** `step 1: <text>` / `cleanup 1: <text>` — the English cited form. */
+const CITED_EN = /^\s*(step|cleanup)\s+(\d+)\s*:/;
+/** `1. <text>` / `後処理 1. <text>` — the Japanese cited form. */
+const CITED_JA = /^\s*(後処理\s*)?(\d+)\s*[.．]\s/;
+/**
+* `await test.step("step 1: ...", async () => {` — the label as a step title.
+*
+* The title is the same label the comment form carries, so both are read by
+* the one parser below. The quote is captured and required back so an
+* apostrophe inside the title cannot end it early. Global so it can be run
+* over a whole file; `matchAll` and `replace` both leave `lastIndex` alone, so
+* the single instance is safe to share.
+*/
+const STEP_CALL = /\btest\.step\(\s*(["'`])((?:\\.|(?!\1).)*)\1/g;
 /** Sources whose steps come from the project's own case document. */
 const CASE_SOURCES = new Set(["case", "cleanup"]);
 /** `step-03` → 3; `cleanup-01` → 1. Absent when the id is not numbered. */
@@ -6379,26 +6426,88 @@ function stepNumber(stepId) {
 * no effect on a `spec.yaml` step, whose comment is an identifier either way.
 */
 function renderStepComment(marker, japanese = false) {
+	return `// ${renderStepLabel(marker, japanese)}`;
+}
+/**
+* The same label without the comment marker, for a `test.step` title.
+*
+* One renderer for both placements: the title is what the Playwright report
+* shows and what the evidence table reads back, and a second wording would
+* mean a test whose report and whose table disagree about a step's name.
+*/
+function renderStepLabel(marker, japanese = false) {
 	const number = CASE_SOURCES.has(marker.source) ? stepNumber(marker.stepId) : null;
 	const text = marker.text?.trim().split("\n")[0]?.trim();
-	if (number === null || !text) return `// step: ${marker.stepId} [${marker.source}]`;
+	if (number === null || !text) return `step: ${marker.stepId} [${marker.source}]`;
 	const isCleanup = marker.source === "cleanup";
-	if (japanese) return `// ${isCleanup ? "後処理 " : ""}${number}. ${text}`;
-	return `// ${isCleanup ? "cleanup" : "step"} ${number}: ${text}`;
+	if (japanese) return `${isCleanup ? "後処理 " : ""}${number}. ${text}`;
+	return `${isCleanup ? "cleanup" : "step"} ${number}: ${text}`;
 }
-/** The step id a comment line names, or null when the line is not one. */
+/**
+* The step id a line opens, or null when it opens none. Both placements are
+* accepted — a `test.step` title for a Playwright test, a comment for the
+* agent-browser emitter and for every test generated before the titles.
+*/
 function parseStepComment(line) {
-	const byId = ID_FORM.exec(line);
-	if (byId) return byId[1];
-	const en = CITED_EN.exec(line);
-	if (en) return idFor(en[1] === "cleanup", Number.parseInt(en[2], 10));
-	const ja = CITED_JA.exec(line);
-	if (ja) return idFor(ja[1] !== void 0, Number.parseInt(ja[2], 10));
+	const block = parseStepBlock(line);
+	if (block !== null) return block;
+	const comment = /^\s*\/\/\s*(.*)$/.exec(line);
+	return comment ? parseStepLabel(comment[1])?.stepId ?? null : null;
+}
+/**
+* A file's lines, with a `test.step` header a formatter broke across lines
+* folded back onto the line it opens.
+*
+* Both readers of a step boundary walk lines — the evidence table attributes
+* the assertions under one, the generation gate collects the ids a file titles
+* — and neither can see a call whose title sits on the next line. Prettier
+* wraps `test.step` like any other call (it is not in its test-call
+* allowlist), and a line walk over the wrapped form finds no steps at all:
+* every step then reads as deciding nothing and every rewrite is rejected.
+*/
+function stepLines(source) {
+	return source.replace(STEP_CALL, (call) => call.replace(/\s*\n\s*/g, " ")).split("\n");
+}
+/**
+* The step id a `test.step` title names — the block form only.
+*
+* Split out from {@link parseStepComment} because reading and writing want
+* different strictness. Anything ccqa has ever generated has to stay readable,
+* so attribution accepts the comment form too; a file ccqa writes today has no
+* reason to be in it, so the generation gate asks this narrower question and
+* rejects a rewrite that fell back to comments.
+*/
+function parseStepBlock(line) {
+	const [call] = line.matchAll(STEP_CALL);
+	return call ? parseStepLabel(call[2])?.stepId ?? null : null;
+}
+/**
+* The step a rendered label names, or null when it names none — the single
+* inverse of {@link renderStepLabel}, wherever a label is read back from: a
+* comment, a `test.step` title in the file, or the same title as a Playwright
+* trace recorded it.
+*/
+function parseStepLabel(label) {
+	const byId = ID_FORM.exec(label);
+	if (byId) return {
+		stepId: byId[1],
+		source: byId[2]
+	};
+	const en = CITED_EN.exec(label);
+	if (en) return labelFor(en[1] === "cleanup", Number.parseInt(en[2], 10));
+	const ja = CITED_JA.exec(label);
+	if (ja) return labelFor(ja[1] !== void 0, Number.parseInt(ja[2], 10));
 	return null;
 }
 /** Built by the same functions that named the step, so the two cannot drift. */
-function idFor(cleanup, number) {
-	return cleanup ? cleanupId(number) : stepId(number);
+function labelFor(cleanup, number) {
+	return cleanup ? {
+		stepId: cleanupId(number),
+		source: "cleanup"
+	} : {
+		stepId: stepId(number),
+		source: "case"
+	};
 }
 //#endregion
 //#region src/codegen/actions-to-script.ts
@@ -7801,1314 +7910,1519 @@ function renderTitleTag(tags, values) {
 	return mapped === void 0 ? "" : ` ${tags.format.replaceAll("{value}", mapped)}`;
 }
 //#endregion
-//#region src/ir/types.ts
-/**
-* Tool-neutral intermediate representation (IR) for recorded browser
-* interactions. A trace produces `RecordedAction[]` (persisted as `ir.json`);
-* emitters translate it into target-specific test code and the replay
-* validator re-executes it. The IR replaces the old dual addressing
-* (raw selector strings vs `find_*` + findLocator fields) with a single
-* `Locator` model.
-*/
-/**
-* The step id the recorder marks work that precedes the case's first step —
-* signing in, reaching the starting screen. Not a step of the case, and not
-* the same thing as an action it could not attribute at all.
-*/
-const SETUP_STEP_ID = "setup";
-//#endregion
-//#region src/ir/route-diff.ts
+//#region src/prompts/llm-gen.ts
 /**
-* What changed between two recordings of the same spec.
-*
-* Re-recording replaces the route wholesale, and the interesting question
-* afterwards is never "what does the new route do" but "what moved". A locator
-* that changed shape says the screen was rebuilt; a check whose wording changed
-* says the copy moved; a step that gained operations says the flow grew. That
-* is the evidence a reviewer needs, and reading it out of two JSON files by eye
-* is exactly the work nobody does.
-*
-* The diff is per spec step, because a step is the unit the spec author wrote
-* and the unit a reviewer reasons in. Actions carry their `stepId` from the
-* trace, so the grouping is recorded, not guessed.
+* The reuse-first contract — the rules that make generated tests build on the
+* consumer repo's existing assets instead of re-implementing them. `draft*`
+* rules apply only when a mechanical draft is present; `draftInvariant`, when
+* supplied by the target, adds one more "do not drop this from the draft" rule
+* (e.g. Playwright's `test.step` blocks).
 */
-const NO_STEP = "(no step)";
-/** One action as a reviewer reads it: what it did, to what, with which value. */
-function describeAction(action) {
-	const parts = [action.assert ? `assert ${action.assert}` : action.action];
-	if (action.locator) parts.push(renderLocator(action.locator));
-	if (action.index !== void 0) parts.push(`[${action.index}]`);
-	if (action.value !== void 0 && action.value !== "") parts.push(JSON.stringify(action.value));
-	if (action.target) parts.push(`→ ${renderLocator(action.target)}`);
-	if (action.files?.length) parts.push(action.files.join(", "));
-	return parts.join(" ");
+function reuseFirstContract(hasDraft, draftInvariant) {
+	const rules = [
+		"1. **Reuse first.** Before writing any code, search the declared resources (path resources with Glob/Grep/Read; package resources under their resolved roots) and import every asset you can use: page objects, step helpers, fixtures, custom selectors, shared constants and regular expressions. Re-implementing an equivalent of an existing asset — including copy-pasting a constant or a regex — is forbidden.",
+		"2. **Create missing parts as support files.** When a needed part does not exist (e.g. a page object for a screen no resource covers), create it following the conventions guides and the style of the existing resources, and output it with `\"kind\": \"support\"`. Package resources are read-only: never modify their contents — if a package lacks something, create the missing piece as a new support file in the repo and mention it in `summary`.",
+		"3. **Match the examples.** Write in the same style as the conventions examples: naming, structure, assertion phrasing, import layout. Where you follow an existing file rather than the plain reading of a guideline — a waiting pattern, a locator shape, a teardown structure — say which file, by path, in the comment. \"Following the existing implementation\" without naming it cannot be checked by the next reader, and it is how a pattern that was right once outlives the reason for it."
+	];
+	if (hasDraft) {
+		rules.push("4. **The draft is ground truth.** The mechanical draft below encodes the recorded route. Do not change the meaning of its operation sequence or its assertions — no reordering, dropping, or weakening. You may rewrite locators when the conventions or the sources you read justify a better one.");
+		if (draftInvariant) rules.push(`5. ${draftInvariant}`);
+	}
+	return `## Reuse contract\n\n${rules.join("\n")}`;
 }
 /**
-* The same, prefixed by the step it belongs to. What a warning about one
-* action says, so a reader can find it in the case rather than counting
-* positions in a list.
+* The JSON output contract shared by every LLM generation pass. Mirrors the
+* cleanup prompt's "output ONLY JSON" style so parsing stays uniform.
 */
-function describeStepAction(action) {
-	return `${action.stepId ? `${action.stepId} ` : ""}${describeAction(action)}`;
+function outputContract(testPath, writeRoots) {
+	return `## Output format
+
+When you are done exploring, reply with ONLY a JSON object (no explanation, no markdown code fences):
+
+{"files": [{"path": "<project-root-relative path>", "contents": "<full file contents>", "kind": "test" | "support"}], "summary": "<one-paragraph human-readable summary>"}
+
+- \`kind\` MUST be exactly \`"test"\` or \`"support"\` (no other value): \`"test"\` marks an executable test; \`"support"\` marks a companion file (page object, helper, ...).
+- The \`"kind": "test"\` file goes to exactly \`${testPath}\`. That path is the project's, not yours: never move, rename, or split the test.
+- Every \`"kind": "support"\` file must stay under one of: ${[posix.dirname(testPath), ...writeRoots].map((r) => `\`${r}\``).join(", ")}.
+- Those roots are also yours to **correct**, not only to add to. A page object
+  there that this case uses, and whose locator or waiting is wrong for what
+  this case needs, is output again with the fix — as \`"kind": "support"\`, whole.
+  Reusing something is not the same as leaving it as it is; anywhere else, and
+  anything you only read, stays untouched.
+- Absolute paths, \`..\` segments, and anything under \`node_modules/\` are rejected.
+- Emit the complete contents of every file you output — no placeholders or elisions.`;
+}
+/** Corrective note appended when the previous reply failed the output contract. */
+function retryNote(error) {
+	return `\n\n## Previous attempt rejected\n\nYour previous reply violated the output contract: ${error}\nReply again with ONLY the JSON object described in "Output format".`;
+}
+function formatStep(step) {
+	if (isExpandedActionStep(step)) return `- ${step.id}: ${body(step.instruction)}\n  expected: ${body(step.expected)}`;
+	const source = step.from ? ` (read from \`${step.from}\`)` : "";
+	return `- ${step.id}: judge by LLM${source}\n  claim: ${body(step.judgeByLlm)}`;
 }
 /**
-* A locator in full, unlike `describeLocator`'s log-line summary: two locators
-* that differ must render differently, or the diff reports a re-addressed
-* element as unchanged — the very thing it exists to show.
+* Step text is usually a block scalar, so it arrives with newlines. Left as-is
+* its later lines sit flush against the list and read as further steps.
 */
-function renderLocator(locator) {
-	if (locator.by === "css") return locator.value;
-	const exact = locator.exact ? " exact" : "";
-	if (locator.by === "role") {
-		const name = locator.name === void 0 ? "" : `[name=${JSON.stringify(locator.name)}]`;
-		return `role=${locator.value}${name}${exact}`;
+function body(text) {
+	return text.trim().split("\n").join("\n    ");
+}
+function buildLlmGenPrompt(input) {
+	const sections = [];
+	sections.push(input.taskInstructions);
+	const steps = input.steps.map(formatStep).join("\n");
+	sections.push(`## Test spec\n\nTitle: ${input.specTitle}\n\nSteps:\n${steps}`);
+	if (input.draft) sections.push(`## Mechanical draft (recorded ground truth)\n\nPath: ${input.draft.path}\n\n\`\`\`
+` + input.draft.contents + "\n```");
+	if (input.resources.length > 0) {
+		const lines = input.resources.map((r) => {
+			return `- ${r.kind === "package" ? `npm package \`${r.ref}\`` : `repo code \`${r.ref}\``}${r.description ? ` — ${r.description}` : ""}\n  explore under: ${r.root}`;
+		});
+		sections.push(`## Reusable resources\n\nExisting code assets the generated test MUST reuse (import path resources the way this repo does; import package resources by name):\n\n${lines.join("\n")}`);
 	}
-	return `${locator.by}=${JSON.stringify(locator.value)}${exact}`;
+	if (input.conventionSections.length > 0) {
+		const bodies = input.conventionSections.map((c) => `### ${c.path}\n\n${fencedBlock(c.body)}`).join("\n\n");
+		sections.push(`## Conventions
+
+These are the project's rules for the code you write, not background reading. Code that breaks one of them is defective: the review that follows this pass quotes the rule back at it and sends it here again to be fixed.\n\n${bodies}`);
+	}
+	if (input.promptBundle) sections.push(`## Project prompt guidance\n\n${input.promptBundle}`);
+	sections.push(reuseFirstContract(input.draft !== void 0, input.draftInvariant));
+	sections.push(outputContract(input.testPath, input.writeRoots));
+	return sections.join("\n\n") + languageDirective(input.language);
 }
 /**
-* Identity of an action across recordings: what it did and to which named
-* thing. Deliberately blind to the locator and the exact value, so a button
-* addressed a new way still pairs with its old self and reads as "changed"
-* rather than as one removal plus one addition.
+* Prompt for one iteration of the verification loop: the generated files
+* failed their run command; ask for corrected files under the same contract.
 */
-function identity(action) {
+function buildLlmFixPrompt(input) {
+	const files = input.files.map((f) => `### ${f.path} (${f.kind})\n\n\`\`\`\n${f.contents}\n\`\`\``).join("\n\n");
 	return [
-		action.action,
-		action.assert ?? "",
-		action.label ?? action.locator?.value ?? ""
-	].join("|");
-}
-function diffRoutes(before, after) {
-	const moved = findMoves(before, after);
-	const movedForms = new Set(moved.map((m) => m.action));
-	const stayed = (a) => !movedForms.has(describeAction(a));
-	const inStep = (actions, step) => actions.filter((a) => (a.stepId ?? NO_STEP) === step && stayed(a));
-	const changes = [];
-	const unchangedSteps = [];
-	for (const step of orderedSteps(before, after)) {
-		const wasIn = inStep(before, step);
-		const isIn = inStep(after, step);
-		if (wasIn.length === 0 && isIn.length === 0) continue;
-		const stepChanges = diffStep(step, wasIn, isIn);
-		if (stepChanges.length === 0) unchangedSteps.push(step);
-		else changes.push(...stepChanges);
-	}
-	return {
-		changes,
-		moved,
-		unchangedSteps
-	};
+		`You generated ${input.targetId} test files for this project, but their verification run failed. Fix the files so the command passes. Keep the tested behaviour identical — fix locators, imports, syntax, and setup, never delete or weaken assertions to force a pass. You may Read/Grep/Glob the project to investigate.`,
+		`## Failing command\n\n\`${input.command}\``,
+		`## Command output (tail)\n\n\`\`\`\n${input.outputTail}\n\`\`\``,
+		`## Current files\n\n${files}`,
+		outputContract(input.testPath, input.writeRoots) + "\n- Output only the files that need changes; files you omit stay as they are.\n- If the failure is NOT caused by the generated files (an environment/setup issue) or the files are already correct, reply `{\"files\": [], \"summary\": \"<why no file change is needed>\"}` — verification is then simply re-run."
+	].join("\n\n") + languageDirective(input.language);
 }
 /**
-* Operations both recordings hold under a different step id, matched on the
-* rendered form: same operation, same locator, same value. A form appearing
-* more than once in either recording is left to the per-step diff — which of
-* two identical operations moved is a question the recording cannot answer.
+* Playwright rewrite pass: turn the mechanical draft into a library-reusing
+* spec. The draft carries the recorded route; the resources carry the assets.
 */
-function findMoves(before, after) {
-	const index = (actions) => {
-		const seen = /* @__PURE__ */ new Map();
-		const repeated = /* @__PURE__ */ new Set();
-		for (const action of actions) {
-			const form = describeAction(action);
-			if (seen.has(form)) repeated.add(form);
-			seen.set(form, action);
-		}
-		for (const form of repeated) seen.delete(form);
-		return seen;
-	};
-	const b = index(before);
-	const moved = [];
-	for (const [form, action] of index(after)) {
-		const was = b.get(form);
-		if (was === void 0) continue;
-		const from = was.stepId ?? NO_STEP;
-		const to = action.stepId ?? NO_STEP;
-		if (from !== to) moved.push({
-			action: form,
-			from,
-			to
-		});
-	}
-	return moved;
-}
-/** Every step id either recording mentions, in the new recording's order first. */
-function orderedSteps(before, after) {
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const action of [...after, ...before]) {
-		const step = action.stepId ?? NO_STEP;
-		if (seen.has(step)) continue;
-		seen.add(step);
-		out.push(step);
-	}
-	return out;
+function playwrightTaskInstructions(suggestedPath) {
+	return `You are rewriting a machine-generated Playwright test so it reuses this repository's existing test assets.
+
+The mechanical draft below was compiled 1:1 from a recorded browser session — it is plain \`@playwright/test\` code with raw locators (e.g. \`page.getByRole("button", { name: "Submit" })\`). Rewrite it into the shape this repository's test suite actually uses: import and call the declared resources (page objects, step helpers, fixtures, shared constants) instead of inlining raw interactions, and follow the conventions.
+
+Keep each step's assertions in the test body, under that step's own comment. A step's actions may move into a page object; what the step decides may not — it is the one thing a reviewer reads the file for, and an assertion inside a helper is invisible both to them and to the review that follows this pass.
+
+Write the rewritten test to \`${suggestedPath}\` unless the conventions/examples clearly place tests elsewhere under the output directory. Locator preference when you do write raw locators: test id > accessible text > role > CSS.`;
 }
 /**
-* Align one step's actions by identity (longest common subsequence), then
-* report the leftovers. An aligned pair whose rendered form differs is the
-* interesting case: same operation, new locator or new wording.
+* runn generation pass: compile the spec into a runbook. Only the generic
+* runbook shape is prescribed here — concrete endpoints, payloads, and
+* response shapes must be verified against the backend sources, found via
+* Read/Grep/Glob.
 */
-function diffStep(step, before, after) {
-	const changes = [];
-	for (const entry of alignByIdentity(before, after)) if (entry.before && entry.after) {
-		const b = describeAction(entry.before);
-		const a = describeAction(entry.after);
-		if (b !== a) changes.push({
-			kind: "changed",
-			step,
-			before: b,
-			after: a
-		});
-	} else if (entry.after) changes.push({
-		kind: "added",
-		step,
-		after: describeAction(entry.after)
-	});
-	else if (entry.before) changes.push({
-		kind: "removed",
-		step,
-		before: describeAction(entry.before)
-	});
-	return changes;
+function runnTaskInstructions(suggestedPath) {
+	return `You are generating a runn runbook (YAML) that covers the test spec below against this repository's backend.
+
+Runbook shape (generic runn structure):
+- \`desc:\` — a one-line description of the scenario.
+- \`runners:\` — the runners the steps use (typically an HTTP runner, e.g. \`req: \${API_ENDPOINT}\`; use env-var placeholders for endpoints, never hardcode hosts).
+- \`vars:\` — variable bindings for values reused across steps (test inputs, ids captured from responses).
+- \`steps:\` — one entry per spec step where possible: \`req\` steps perform the API calls, \`test\` steps assert on \`current.res\` (status, body fields). Bind values from earlier responses via \`steps[N]\` references when later steps need them.
+
+Do NOT invent endpoints, request bodies, or response fields: use Read/Grep/Glob to find the backend sources (routing tables, handlers, schemas) and derive the concrete paths, methods, parameters, and response shapes from them. If a detail cannot be confirmed from the sources, say so in \`summary\` instead of guessing silently.
+
+Write the runbook to \`${suggestedPath}\` unless the conventions/examples clearly use another layout under the output directory. If shared setup deserves its own helper runbook, output it as \`kind: "support"\`.`;
 }
-function alignByIdentity(before, after) {
-	const lengths = Array.from({ length: before.length + 1 }, () => new Array(after.length + 1).fill(0));
-	for (let i = before.length - 1; i >= 0; i--) for (let j = after.length - 1; j >= 0; j--) lengths[i][j] = identity(before[i]) === identity(after[j]) ? lengths[i + 1][j + 1] + 1 : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
-	const out = [];
-	let i = 0;
-	let j = 0;
-	while (i < before.length && j < after.length) if (identity(before[i]) === identity(after[j])) {
-		out.push({
-			before: before[i],
-			after: after[j]
-		});
-		i++;
-		j++;
-	} else if (lengths[i + 1][j] >= lengths[i][j + 1]) out.push({ before: before[i++] });
-	else out.push({ after: after[j++] });
-	while (i < before.length) out.push({ before: before[i++] });
-	while (j < after.length) out.push({ after: after[j++] });
-	return out;
+/**
+* How many files the walk may collect. Depth alone does not bound it: one
+* barrel `index.ts` re-exporting a directory fans out to everything in it, and
+* the caller reads what the walk returns. Far more than an audit's budget can
+* hold, so the cap only stops the pathological case.
+*/
+const MAX_SUPPORT_FILES = 200;
+/** Extensions tried when a specifier names no file, TypeScript sources first. */
+const EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+];
+/**
+* Module specifiers, in the forms generated tests use: `from "x"`, a
+* side-effect `import "x"`, `import("x")`, and `require("x")`. Anchored on the
+* import syntax rather than on the string alone, so a specifier-looking string
+* in a locator or an asserted text is not one. A string this over-matches
+* (prose after the word "from" in a comment) resolves to no file and drops out.
+*/
+const IMPORT_SPECIFIER = /(?:\bfrom|\bimport\s*\(|\brequire\s*\(|\bimport)\s*(["'`])([^"'`]+)\1/g;
+/**
+* Every module specifier `source` loads, in source order. Shared with the gate
+* over what a generated test may import: which strings count as imports must
+* not differ between the walk that follows them and the check that refuses
+* some of them.
+*/
+function importedSpecifiers(source) {
+	return [...source.matchAll(IMPORT_SPECIFIER)].map((m) => m[2]);
 }
-/** The diff as markdown — what `ccqa record` saves beside the spec. */
-function renderRouteDiff(diff, report) {
-	const { changes, moved, unchangedSteps } = diff;
-	const lines = [`# Route diff — ${report.specKey}`, ""];
-	lines.push(`Recorded ${report.before.recordedAt ?? "(unknown)"} → ${report.after.recordedAt ?? "(unknown)"}.`, "");
-	if (report.before.origin !== report.after.origin) lines.push(`Origin: \`${report.before.origin ?? "(none)"}\` → \`${report.after.origin ?? "(none)"}\``, "");
-	if (changes.length === 0 && moved.length === 0) {
-		lines.push("The route is unchanged: same operations, locators and checks.", "");
-		return lines.join("\n");
-	}
-	if (changes.length === 0) lines.push("The route does the same things, in the same way. Only which step each was recorded under moved.", "");
-	for (const step of groupByStep$1(changes)) {
-		const title = report.stepTitles?.get(step.step);
-		lines.push(`## ${step.step}${title ? ` — ${title}` : ""}`, "");
-		for (const change of step.changes) lines.push(change.kind === "changed" ? `- changed: \`${change.before}\` → \`${change.after}\`` : change.kind === "added" ? `- added: \`${change.after}\`` : `- removed: \`${change.before}\``);
-		lines.push("");
+/**
+* Read `<cwd>/tsconfig.json`'s `baseUrl` / `paths`, following a relative
+* `extends` chain — a workspace commonly keeps its aliases in a base config,
+* and stopping at the leaf would drop exactly the page objects an audit needs.
+* A config published as a package is not followed: its aliases would resolve
+* inside `node_modules`, which this walker never reads anyway. Absent,
+* unreadable, or aliasless: null, and only relative imports are followed.
+*/
+async function loadTsconfigPaths(cwd) {
+	let configPath = join(cwd, "tsconfig.json");
+	const seen = /* @__PURE__ */ new Set();
+	while (configPath !== null && !seen.has(configPath)) {
+		seen.add(configPath);
+		const parsed = await readTsconfig(configPath);
+		if (parsed === null) return null;
+		const options = parsed.compilerOptions;
+		if (options?.paths) return {
+			baseUrlAbs: resolve(dirname(configPath), options.baseUrl ?? "."),
+			paths: options.paths
+		};
+		configPath = typeof parsed.extends === "string" && parsed.extends.startsWith(".") ? withJsonExtension(resolve(dirname(configPath), parsed.extends)) : null;
 	}
-	if (moved.length > 0) {
-		lines.push("## Recorded under a different step", "", "Same operation, same locator, same value — only its step attribution moved.", "");
-		for (const move of moved) lines.push(`- \`${move.action}\`: ${move.from} → ${move.to}`);
-		lines.push("");
+	return null;
+}
+async function readTsconfig(path) {
+	const raw = await readFile(path, "utf8").catch(() => null);
+	if (raw === null) return null;
+	try {
+		return JSON.parse(stripJsonComments(raw));
+	} catch {
+		return null;
 	}
-	if (unchangedSteps.length > 0) lines.push(`Unchanged: ${unchangedSteps.join(", ")}`, "");
-	return lines.join("\n");
 }
-function groupByStep$1(changes) {
-	const grouped = [];
-	for (const change of changes) {
-		const last = grouped.at(-1);
-		if (last && last.step === change.step) last.changes.push(change);
-		else grouped.push({
-			step: change.step,
-			changes: [change]
-		});
+/** `extends` may name a config with the extension left off. */
+function withJsonExtension(path) {
+	return path.endsWith(".json") ? path : `${path}.json`;
+}
+/** Strip line and block comments and trailing commas — tsconfig.json is JSONC. */
+function stripJsonComments(text) {
+	return text.replace(/"(?:[^"\\]|\\.)*"|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (match) => match.startsWith("\"") ? match : "").replace(/,(\s*[}\]])/g, "$1");
+}
+/**
+* Files reachable from `entryAbs` by following project-internal imports, in
+* breadth-first order and excluding the entry itself. Reading a file that
+* cannot be read yields no imports rather than an error: a missing import
+* target is the audit's business, not this walker's.
+*/
+async function collectSupportFiles(entryAbs, cwd, opts = {}) {
+	return (await walkSupportFiles(entryAbs, cwd, opts)).files;
+}
+/** {@link collectSupportFiles}, saying whether a cap cut the walk short. */
+async function walkSupportFiles(entryAbs, cwd, opts = {}) {
+	const maxDepth = opts.maxDepth ?? 3;
+	const tsconfig = opts.tsconfig !== void 0 ? opts.tsconfig : await loadTsconfigPaths(cwd);
+	const seen = new Set([entryAbs]);
+	const found = [];
+	let frontier = [{
+		abs: entryAbs,
+		source: await readSource(entryAbs)
+	}];
+	for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+		const levels = await Promise.all(frontier.map(async (file) => (await resolveImportsOf(file, cwd, tsconfig)).map((abs) => ({
+			abs,
+			from: file.abs
+		}))));
+		const next = [];
+		let capped = false;
+		for (const entry of levels.flat()) {
+			if (seen.has(entry.abs)) continue;
+			seen.add(entry.abs);
+			next.push(entry);
+			if (found.length + next.length >= MAX_SUPPORT_FILES) {
+				capped = true;
+				break;
+			}
+		}
+		const sources = await Promise.all(next.map((entry) => readSource(entry.abs)));
+		found.push(...next.map((entry, i) => ({
+			...entry,
+			source: sources[i]
+		})));
+		if (capped) return {
+			files: found,
+			truncated: true
+		};
+		frontier = next.map((entry, i) => ({
+			abs: entry.abs,
+			source: sources[i]
+		}));
 	}
-	return grouped;
+	return {
+		files: found,
+		truncated: frontier.length > 0
+	};
+}
+/** A file that cannot be read is empty here: it imports nothing and shows nothing. */
+function readSource(fileAbs) {
+	return readFile(fileAbs, "utf8").catch(() => "");
+}
+/** Every project file one file imports, in source order. */
+async function resolveImportsOf(file, cwd, tsconfig) {
+	return (await Promise.all(importedSpecifiers(file.source).map((s) => resolveSpecifier(s, dirname(file.abs), cwd, tsconfig)))).filter((p) => p !== null);
 }
-//#endregion
-//#region src/claude/extract-json.ts
 /**
-* Pulls a JSON object out of a Claude completion. Accepts either a fenced
-* ```json block or a bare `{...}` payload that constitutes the whole reply.
-* Returns null when neither shape is present.
+* One specifier → an existing file inside the project, or null. Anything that
+* escapes the project root, or lands in `node_modules`, is dropped: it is not
+* the consumer's code to read.
 */
-function extractJsonBlock(text) {
-	const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
-	if (fenced && fenced[1]) return fenced[1].trim();
-	const trimmed = text.trim();
-	if (trimmed.startsWith("{") && trimmed.endsWith("}")) return trimmed;
+async function resolveSpecifier(specifier, fromDirAbs, cwd, tsconfig) {
+	const candidates = specifier.startsWith(".") ? [resolve(fromDirAbs, specifier)] : isAbsolute(specifier) ? [] : aliasCandidates(specifier, tsconfig);
+	for (const candidate of candidates) {
+		const file = await resolveFile(candidate);
+		if (file === null) continue;
+		if (file.split(/[\\/]/).includes("node_modules")) return null;
+		return file.startsWith(`${cwd}/`) ? file : null;
+	}
 	return null;
 }
-//#endregion
-//#region src/prompts/verifies-spec.ts
+/** Every path a `paths` alias maps this specifier to, in config order. */
+function aliasCandidates(specifier, tsconfig) {
+	if (!tsconfig) return [];
+	const out = [];
+	for (const [pattern, targets] of Object.entries(tsconfig.paths)) {
+		const star = pattern.indexOf("*");
+		if (star === -1) {
+			if (pattern === specifier) out.push(...targets.map((t) => resolve(tsconfig.baseUrlAbs, t)));
+			continue;
+		}
+		const prefix = pattern.slice(0, star);
+		const suffix = pattern.slice(star + 1);
+		if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue;
+		const matched = specifier.slice(prefix.length, specifier.length - suffix.length);
+		out.push(...targets.map((t) => resolve(tsconfig.baseUrlAbs, t.replace("*", matched))));
+	}
+	return out;
+}
+/** A path → the file it names: itself, `<path><ext>`, or `<path>/index<ext>`. */
+async function resolveFile(pathAbs) {
+	if (await isFile(pathAbs)) return pathAbs;
+	const rewritten = pathAbs.replace(/\.(js|mjs|cjs)$/, "");
+	if (rewritten !== pathAbs) {
+		for (const ext of EXTENSIONS) if (await isFile(rewritten + ext)) return rewritten + ext;
+	}
+	for (const ext of EXTENSIONS) if (await isFile(pathAbs + ext)) return pathAbs + ext;
+	for (const ext of EXTENSIONS) {
+		const indexed = join(pathAbs, `index${ext}`);
+		if (await isFile(indexed)) return indexed;
+	}
+	return null;
+}
+function isFile(pathAbs) {
+	return stat(pathAbs).then((s) => s.isFile(), () => false);
+}
+/** `export const NAME` / `export function NAME` / `export class NAME`, and `export { A, B }`. */
+const EXPORTED = /export\s+(?:async\s+)?(?:const|let|function|class|enum)\s+([A-Za-z_$][\w$]*)/g;
+const EXPORT_LIST = /export\s*\{([^}]*)\}/g;
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
+/** A `//` that is not the tail of a `://` — the shape a URL in a string has. */
+const LINE_COMMENT = /(^|[^:])\/\/.*$/gm;
 /**
-* Asks whether a generated test actually decides what its spec claims.
-*
-* The generation loop's only bar is "the test goes green", and a rewrite that
-* weakens an assertion clears that bar as easily as one that keeps it. Green
-* therefore does not mean checked, and nothing else looks. Observed cases: a
-* step whose expectation was "the linked page opens" asserting instead that
-* the *link* is still visible on the page it clicked from; another asserting
-* on a navigation element unrelated to the step.
+* The value names a file exports, as a reader would list them.
 *
-* Deliberately narrow. It reads only what the step says and what the code
-* does, and reports the step as unchecked when the two do not line up. It
-* does not review style, coverage, or whether the expectation is a good one.
+* Text, not a parser: this answers a warning, not a refusal, and a name missed
+* because it was written in a form this does not know costs nothing. A name
+* invented would cost a false warning, so the patterns only match declarations
+* that plainly are one, and comments are stripped first. Types are left out
+* for the same reason: a page object's own row type is referenced only inside
+* it, so listing it would report a definition that is used.
 */
-function verifiesSpecPrompt(input) {
-	return [
-		"You are reviewing whether a generated end-to-end test decides what its spec says.",
-		"",
-		"For each step below, the test must contain assertions that could FAIL if the",
-		"step's `expected` stopped holding. Report a step when:",
-		"",
-		"- its assertions cannot fail while the product is broken in the way the",
-		"  expectation describes — because they check something weaker than it",
-		"  states (the expectation says a page opens and the code re-checks the",
-		"  element it clicked; the expectation names a path with an id in it and the",
-		"  pattern also matches the path without one);",
-		"- what it asserts on is unrelated to what the step did (e.g. a navigation",
-		"  element that is present on every page);",
-		"- it depends on something that varies between runs and is not part of the",
-		"  expectation (a count, an index, a position, wording that changes);",
-		"- the expectation names WHICH screen the run arrives at, and the code",
-		"  checks only the address's shape. A pattern matches every screen shaped",
-		"  like that one — and screens that are made per category, per folder, per",
-		"  account are shaped alike by design, so arriving at the wrong one passes.",
-		"  Something the named screen shows has to be checked too;",
-		"- it checks that something is ABSENT, and nothing in the test has waited",
-		"  for the screen that would show it to finish drawing. Absence is true of",
-		"  a page that has not rendered yet, so the check passes on an empty screen",
-		"  and passes again when the thing is really there but slow. Something the",
-		"  screen shows when it is ready has to be established first;",
-		"- the expectation ties two things together — this row AND the count beside",
-		"  it, this screen AND what it shows — and the assertions check them apart.",
-		"  Read the expectation's own grammar: \"the row, with its count\" is one",
-		"  claim about one row, and two assertions that each search the whole page",
-		"  hold just as well when the count belongs to a different row. Two things",
-		"  the expectation merely lists (\"the heading and the description are",
-		"  shown\") are two claims, and checking them apart is right;",
-		"- the expectation is about EACH of several things the case names, and the",
-		"  assertions reach only one of them. The others are not checked at all, and",
-		"  a comment saying they look alike is the fault being written down, not a",
-		"  reason — the case asked for each because any one of them can be the one",
-		"  that breaks;",
-		"- it has no assertion at all.",
-		"",
-		"Do NOT report: style, naming, structure, missing coverage the spec never",
-		"asked for, or an expectation you merely disagree with. A step that checks",
-		"less than you would have written, but still fails when the expectation",
-		"breaks, is fine — unless the expectation covers several things and the",
-		"code can only break on one of them, which is the bullet above.",
-		"",
-		"## Steps",
-		"",
-		...input.steps.map(stepLine),
-		"",
-		...input.expectations && input.expectations.length > 0 ? [
-			"## What the case expects",
-			"",
-			"Stated for the flow, not per step. Each belongs to the step that first",
-			"makes it true; a step is unchecked when nothing decides the one that",
-			"belongs to it.",
-			"",
-			...input.expectations.map((e) => `- ${e}`),
-			""
-		] : [],
-		...input.cleanup && input.cleanup.length > 0 ? [
-			"## Cleanup steps",
-			"",
-			...input.cleanup.map(stepLine),
-			""
-		] : [],
-		"## Generated test",
-		"",
-		"```",
-		input.source,
-		"```",
-		"",
-		...input.support && input.support.length > 0 ? [
-			"## What it leans on",
-			"",
-			"The locators the assertions above resolve through. An assertion is",
-			"only as strong as its locator, so read them, and report the step when",
-			"its locator makes the assertion unable to fail the way the",
-			"expectation describes. Two shapes to look for:",
-			"",
-			"- it takes the first (or last) of several matching elements, and the",
-			"  step claims something about each of them — the others go unchecked;",
-			"- it matches by a string that also appears elsewhere on the page (a",
-			"  nav item, a breadcrumb, a menu), so it is satisfied by that element",
-			"  even when the one the step names is absent;",
-			"- it matches only the words, where the step is about a control — a",
-			"  button, a link, a field. Text with that wording is not the control,",
-			"  so the assertion holds on a page where the control is gone.",
-			"",
-			"Judge these only through the steps — a definition no step depends on",
-			"is not a finding.",
-			"",
-			...input.support.flatMap((f) => [
-				`### ${f.path}`,
-				"",
-				"```",
-				f.source,
-				"```",
-				""
-			])
-		] : [],
-		"Answer with one json block and nothing else:",
-		"",
-		"```json",
-		"{ \"findings\": [ { \"stepId\": \"step-05\", \"problem\": \"…\" } ] }",
-		"```",
-		"",
-		"`problem` is one sentence naming what the step claims and what the code",
-		"checks instead. Empty `findings` means every step is decided.",
-		languageDirective(input.language)
-	].join("\n");
+function exportedNames(source) {
+	const code = source.replace(BLOCK_COMMENT, "").replace(LINE_COMMENT, "$1");
+	const names = /* @__PURE__ */ new Set();
+	for (const m of code.matchAll(EXPORTED)) names.add(m[1]);
+	for (const m of code.matchAll(EXPORT_LIST)) for (const part of m[1].split(",")) {
+		const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+		if (name && /^[A-Za-z_$][\w$]*$/.test(name) && name !== "default") names.add(name);
+	}
+	return [...names];
 }
-function stepLine(step) {
-	if (!isExpandedActionStep(step)) return `- ${step.id}: judged by a model at run time — its claim is asserted by the injected call, so it needs no other assertion.`;
+//#endregion
+//#region src/targets/emitted-review.ts
+function reviewEmittedFiles(input) {
+	const locators = collectLocators(input.files);
+	const said = input.caseText.join("\n");
 	return [
-		`- ${step.id}`,
-		`  does: ${oneLine$3(step.instruction)}`,
-		`  expected: ${oneLine$3(step.expected)}`
-	].join("\n");
+		...decidesNothing(input),
+		...unassertedPath(input),
+		...[...input.files].flatMap(([file, source]) => [
+			...toolIdentifiers(file, source),
+			...containerOfPageText(file, source),
+			...unjustifiedFirst(file, source),
+			...describeEcho(file, source),
+			...unaskedAssertions(file, source, locators, said),
+			...weakerTwin(file, source),
+			...unreached(file, source, input)
+		])
+	];
 }
-function oneLine$3(text) {
-	return text.trim().split("\n").map((l) => l.trim()).join(" ");
+/**
+* A path with a placeholder segment in it — `/orders/{orderId}`. Writing one
+* in prose is a statement about the address, not about the page's contents:
+* there is no other reason to name the part that changes per run.
+*/
+const PLACEHOLDER_PATH = /\/[A-Za-z0-9_\-]+(?:\/[A-Za-z0-9_\-]+)*\/\{[A-Za-z0-9_]+\}/;
+/**
+* A case that says where the run must end up, and a test that never looks at
+* the address.
+*
+* The row being on screen is not the same claim as being on the screen that
+* shows it — a product that rendered the row without navigating passes, and
+* that is the failure the expectation was written to catch. Scoped to
+* placeholder paths because those are unambiguous; a path mentioned as scenery
+* ("on /settings, the button is shown") is not a claim about the address.
+*
+* Calibrated against a small set of hand-written case definitions: a few
+* name a placeholder path in their expectations, most of those already
+* assert on the URL, and the one that does not is the defect this was
+* written for.
+*/
+function unassertedPath(input) {
+	const source = input.files.get(input.testPath);
+	if (source === void 0) return [];
+	const stated = input.caseText.find((text) => PLACEHOLDER_PATH.test(text));
+	if (stated === void 0 || /\btoHaveURL\b/.test(source)) return [];
+	return [{
+		file: input.testPath,
+		line: 1,
+		rule: "unasserted-path",
+		message: `the case says where the run ends up — "${PLACEHOLDER_PATH.exec(stated)?.[0]}" — and nothing here looks at the address. What the screen shows can be right while the screen is wrong. Assert the URL where the case says it changes`
+	}];
 }
-//#endregion
-//#region src/targets/verifies-spec.ts
-const FindingsSchema = z.object({ findings: z.array(z.object({
-	stepId: z.string(),
-	problem: z.string()
-})) });
+/** `readonly name =`, `name(...): Locator {`, and `export … name`. */
+const DECLARED = /(?:readonly\s+([A-Za-z0-9_]+)\s*=|\b([A-Za-z0-9_]+)\([^)]*\)\s*:\s*Locator\b|export\s+(?:async\s+)?(?:const|let|function|class)\s+([A-Za-z0-9_]+))/g;
 /**
-* Findings in the model's answer, or null when it did not answer in the
-* agreed shape. Null is not "no findings": the caller says so rather than
-* reporting a clean review it never got.
+* A definition in a file this generation wrote that nothing reaches — not the
+* test it generated, and not the project's own test assets either.
+*
+* Both halves are needed. Without the first it is not this generation's
+* business; without the second every shared definition another case uses would
+* be reported. Together they say only what is true: nobody reaches this.
 */
-function parseVerifiesSpecFindings(answer) {
-	const json = extractJsonBlock(answer);
-	if (!json) return null;
-	try {
-		return FindingsSchema.parse(JSON.parse(json)).findings;
-	} catch {
-		return null;
-	}
+function unreached(file, source, input) {
+	const elsewhere = input.usedInProject?.get(file);
+	if (elsewhere === void 0) return [];
+	const corpus = [...input.files.values()].join("\n");
+	return lines(source).flatMap((text, i) => {
+		const declared = DECLARED.exec(text);
+		DECLARED.lastIndex = 0;
+		if (!declared) return [];
+		const name = named(declared);
+		if (!name || elsewhere.has(name)) return [];
+		if (corpus.split(new RegExp(`\\b${name}\\b`)).length - 1 > 1) return [];
+		return [{
+			file,
+			line: i + 1,
+			rule: "unreached",
+			message: `\`${name}\` is defined here and nothing reaches it — not this case's test, and nothing else in the project. Remove it`
+		}];
+	});
 }
+const named = (m) => m[1] ?? m[2] ?? m[3] ?? "";
 /**
-* Whether a step claims an outcome of its own. "Open the list", "click Add",
-* "type a title" do not: nothing follows from them that a test could check,
-* and a hand-written test asserts nothing after them either. A markdown case
-* states its expectations for the flow, so none of its steps claim one.
+* Two names for one visible string, where one of them is strictly weaker: a
+* role and its accessible name next to a bare page-wide text match that then
+* picks a position out of the matches.
+*
+* The weak one adds no check — anything it could catch, the other catches
+* first — and it is satisfied by whichever element the page happens to order
+* first, which on a real page was the navigation entry rather than the heading
+* the case names. Both assertions then read as two checks and are one.
 *
-* One predicate, two readers — the review below and the evidence table, which
-* reach the same verdict from the same file and must not be able to disagree
-* about which steps were supposed to decide something.
+* Calibrated against a hand-written corpus: the shape appears only in a file
+* a generation wrote. People do not write it.
 */
-function claimsAnOutcome(step) {
-	return (step.expected ?? "").trim().length > 0;
+function weakerTwin(file, source) {
+	const byString = /* @__PURE__ */ new Map();
+	lines(source).forEach((text, i) => {
+		const declared = /(?:readonly|const)\s+([A-Za-z0-9_]+)\s*=\s*(.+?);\s*$/.exec(text);
+		if (!declared) return;
+		const [, name, expression] = declared;
+		const weak = /\.(?:first|last|nth)\(/.test(expression) && expression.includes("getByText(");
+		const strong = expression.includes("getByRole(") && !/\.(?:first|last|nth)\(/.test(expression);
+		if (!weak && !strong) return;
+		for (const m of expression.matchAll(VISIBLE_STRING)) {
+			const value = m[1] ?? m[2];
+			if (!value || value.includes("${")) continue;
+			const seen = byString.get(value) ?? [];
+			seen.push({
+				name,
+				line: i + 1,
+				weak
+			});
+			byString.set(value, seen);
+		}
+	});
+	const findings = [];
+	for (const [value, defs] of byString) {
+		const weak = defs.filter((d) => d.weak);
+		if (weak.length === 0 || defs.every((d) => d.weak)) continue;
+		const strong = defs.find((d) => !d.weak);
+		for (const d of weak) findings.push({
+			file,
+			line: d.line,
+			rule: "weaker-twin",
+			message: `\`${d.name}\` and \`${strong.name}\` are both "${value}", and this one searches the whole page and takes a position out of the matches. It can only be satisfied by something \`${strong.name}\` already covers, or by the wrong element. Assert one of them`
+		});
+	}
+	return findings;
 }
 /**
-* What a step that states an outcome, and carries no assertion under it, is
-* told. Shared with the evidence table, which reaches the same verdict from
-* the same file — a reader must not meet two wordings for one fact.
+* A test with no assertion anywhere in it, for a case that states something.
 *
-* It reports what was seen, not what was concluded. An assertion a rewrite
-* moved into a page object is invisible here, and calling that "decides
-* nothing" would be ccqa claiming more than it looked at.
-*/
-const NOTHING_DECIDED = "no assertion is visible under this step in the generated test — one moved into a helper does not show here, and does not show to a reviewer reading the file either";
-/**
-* The warning a finding becomes, phrased so the reader knows the test is green
-* for nothing. A step deciding nothing is its own explanation, so only the
-* model's own words are worth appending.
+* The per-step version of this question belongs to the reading, which knows
+* that "open the list" claims nothing and expects no assertion under it. This
+* one needs no judgement: whatever the case says, a file that decides nothing
+* at all does not check it. It is the floor under a case whose expectations
+* are stated for the flow rather than per step — the shape a markdown case has
+* — where the reading is otherwise the only thing looking.
+*
+* Calibrated like the rest: in the corpus this was calibrated on, not one
+* hand-written spec had zero assertions.
 */
-function formatFinding(finding, labels = evidenceLabels()) {
-	const nothing = finding.problem === NOTHING_DECIDED;
-	const claim = nothing ? labels.findingNothing : labels.findingUndecided;
-	return `${finding.stepId}: ${claim}${nothing ? "" : ` — ${finding.problem}`}`;
+function decidesNothing(input) {
+	const source = input.files.get(input.testPath);
+	if (source === void 0 || input.caseText.join("").trim().length === 0) return [];
+	if (/\bexpect\(|\bjudgeByLlm\b/.test(source)) return [];
+	return [{
+		file: input.testPath,
+		line: 1,
+		rule: "decides-nothing",
+		message: "this test contains no assertion at all, so it passes whatever the product does. Decide what the case says must be true"
+	}];
 }
-/**
-* Read the generated test back and ask whether each step is actually decided
-* (see `verifiesSpecPrompt`). A review that could not be obtained answers
-* `findings: null` and is logged — it must not read as a pass, and it must
-* also not fail the generate that produced working files.
-*/
-async function reviewGeneratedTest(input) {
-	const source = input.source;
-	if (source.trim().length === 0) {
-		warn("could not check whether the generated test decides its spec (no test file to read)");
-		return {
-			findings: null,
-			complete: false,
-			warnings: []
-		};
-	}
-	const checked = assertionsByStep(source);
-	const undecided = [...input.steps, ...input.cleanup ?? []].filter(isExpandedActionStep).filter(claimsAnOutcome).filter((step) => (checked.get(step.id) ?? []).length === 0).map((step) => ({
-		stepId: step.id,
-		problem: NOTHING_DECIDED
-	}));
-	const { result: answer, isError } = await (input.invoke ?? invokeClaudeStreaming)({
-		prompt: verifiesSpecPrompt({
-			steps: input.steps,
-			source,
-			language: input.language,
-			...input.expectations && input.expectations.length > 0 ? { expectations: [...input.expectations] } : {},
-			...input.cleanup && input.cleanup.length > 0 ? { cleanup: [...input.cleanup] } : {},
-			...input.support && input.support.length > 0 ? { support: input.support } : {}
-		}),
-		allowedTools: [],
-		maxTurns: 1,
-		silenceBashLog: true,
-		...input.model ? { model: input.model } : {},
-		cwd: input.cwd
-	}, () => {});
-	const fromModel = isError ? null : parseVerifiesSpecFindings(answer);
-	if (fromModel === null) warn(`could not check whether the generated test decides its spec (${isError ? "Claude returned an error" : "no usable answer"})`);
-	const findings = mergeFindings(undecided, fromModel ?? []);
-	return {
-		findings,
-		complete: fromModel !== null,
-		warnings: findings.map((finding) => formatFinding(finding))
-	};
+const lines = (source) => source.split("\n");
+/** ccqa's name has no business in a name the project now owns and maintains. */
+function toolIdentifiers(file, source) {
+	return lines(source).flatMap((text, i) => {
+		const m = /\b(?:const|let|var|readonly)\s+(ccqa[A-Za-z0-9_]*)/i.exec(text);
+		return m ? [{
+			file,
+			line: i + 1,
+			rule: "tool-identifier",
+			message: `\`${m[1]}\` names the tool that wrote it. Name it for what it holds`
+		}] : [];
+	});
 }
 /**
-* The mechanical finding wins its step: it is a fact, not a reading. Shared
-* with the evidence table, which merges the same two sources — one of them
-* recomputed from the file as it is now — and must show each step once.
+* Searching the whole page for something a name calls a container: its text,
+* or a structural tag that says nothing about what the element is.
+*
+* Both forms, because the first version tested only `getByText` and the fix
+* pass answered it with `page.locator("div").filter({ hasText }).last()` —
+* the same page-wide search, now resting on DOM order, and invisible to a
+* rule that only knew one shape. A generation that escapes a finding by
+* changing shape is worse than one that never drew it.
 */
-function mergeFindings(undecided, fromModel) {
-	const claimed = new Set(undecided.map((f) => f.stepId));
-	return [...undecided, ...fromModel.filter((f) => !claimed.has(f.stepId))];
-}
-//#endregion
-//#region src/evidence/table.ts
-/** Assertion lines a reviewer can check without reading the whole file. */
-const ASSERTION = /^\s*(?:await\s+)?(?:expect|judgeByLlm)\b.*$/;
+const PAGE_ROOTED = /^this\.page\.(?:getByText\(|locator\(["'](?:div|span|p|li|ul|ol|section|article)["']\))/;
+const CONTAINER = /\b(?:readonly\s+)?([a-zA-Z0-9_]*(?:Row|Cell|Card|Item|List))\s*(?:=\s*|\([^)]*\)\s*:\s*Locator\s*\{\s*(?:return\s+)?)(.*)$/;
 /**
-* Assertions grouped by the step they sit under, read from the step comments
-* the emitter leaves. A rewrite that moved an assertion into a page object
-* leaves nothing here, which is the honest answer: the reviewer cannot see it
-* either, and the row says so rather than implying coverage.
+* A name that says "one of the things in a list" built from a match against
+* the whole page. It finds the string anywhere — a heading, a toast, another
+* row — so what it proves is not what its name claims.
+*
+* The message names the shapes that fix it, because the first version said
+* only "scope it" and the fix pass answered with `page.locator("div")` filtered
+* by the same text and narrowed with `.last()` — page-wide still, and now
+* resting on which match the DOM happens to put last.
 */
-function assertionsByStep(source) {
-	const byStep = /* @__PURE__ */ new Map();
-	let current = null;
-	for (const line of source.split("\n")) {
-		const boundary = parseStepComment(line);
-		if (boundary) {
-			current = boundary;
-			if (!byStep.has(current)) byStep.set(current, []);
-			continue;
-		}
-		if (current && ASSERTION.test(line)) byStep.get(current).push(line.trim());
-	}
-	return byStep;
+function containerOfPageText(file, source) {
+	const all = lines(source);
+	return all.flatMap((text, i) => {
+		const m = CONTAINER.exec(text);
+		if (!m) return [];
+		const body = m[2].trim() || (all[i + 1] ?? "").trim().replace(/^return\s+/, "");
+		if (!PAGE_ROOTED.test(body)) return [];
+		return [{
+			file,
+			line: i + 1,
+			rule: "unscoped-container",
+			message: `\`${m[1]}\` is named for one element among others, but matches that text anywhere on the page — a heading or a toast carrying it satisfies this too. Address the element itself: the role it has (\`getByRole("row"|"listitem"|"article"|...)\` narrowed with \`.filter({ hasText })\`), or its test id. Where the page offers neither, scope from a container this page object already addresses — searching the whole page for a bare \`div\` and taking \`.first()\`/\`.last()\` is not scoping, it only picks whichever the DOM happens to order that way.`
+		}];
+	});
 }
 /**
-* Recorded actions grouped by the step that produced them. `"(no step)"` is
-* the bucket for an action the recorder could not attribute — kept rather than
-* dropped, since it still happened.
+* Whether a written reason sits above this line.
+*
+* The comment belongs to the run of assertions it explains, not to each one,
+* so two consecutive checks under one note are one explanation. Both rules
+* that use this are the same rule underneath: an unusual choice is allowed,
+* and has to be said out loud — which is what a project's own guidelines ask
+* of the people writing these by hand.
 */
-function groupByStep(actions) {
-	const byStep = /* @__PURE__ */ new Map();
-	for (const action of actions) {
-		const id = action.stepId ?? "(no step)";
-		const list = byStep.get(id);
-		if (list) list.push(action);
-		else byStep.set(id, [action]);
-	}
-	return byStep;
-}
-/** The same grouping, each action rendered for a reader. */
-function actionsByStep(actions) {
-	return new Map([...groupByStep(actions)].map(([id, grouped]) => [id, grouped.map(describeAction)]));
+function explained(all, i) {
+	let above = i - 1;
+	while (above >= 0 && /\bexpect\(|^\s*$|^\s*\)/.test(all[above] ?? "")) above -= 1;
+	return /^\s*\/\//.test(all[above] ?? "");
 }
 /**
-* The locator/assertion literals worth anchoring to the product's own source:
-* a testid, an accessible name, a placeholder, a label, an asserted text. Not
-* every locator strategy — `css`, `text` and `alt`/`title` locators are as
-* often a CSS/testing artifact as product copy, and would anchor to noise.
+* `.first()` written on an assertion narrows a locator that matched several
+* things, so the assertion holds for whichever came first. Sometimes that is
+* the point — "the newest row is at the top" — and then it is written down.
 *
-* A value containing `${...}` is a run-id-substituted value at replay time
-* and has no literal counterpart in the source, so it is dropped rather than
-* searched for and reported "not found".
+* Only where the assertion itself narrows. Following it into the definitions
+* fired throughout the hand-written corpus: a page object that resolves a
+* repeated element once, for every caller, is how that is normally written.
 */
-function sourceNeedles(actions) {
-	const needles = [];
-	const seen = /* @__PURE__ */ new Set();
-	const add = (value, kind = "text") => {
-		if (value === void 0 || value.includes("${") || seen.has(value)) return;
-		seen.add(value);
-		needles.push({
-			value,
-			kind
-		});
-	};
-	for (const action of actions) {
-		for (const locator of [action.locator, action.target]) {
-			if (!locator) continue;
-			if (locator.by === "testid") add(locator.value, "testid");
-			else if (locator.by === "placeholder" || locator.by === "label") add(locator.value);
-			else if (locator.by === "role") add(locator.name);
-		}
-		if (action.assert === "text_visible" || action.assert === "text_not_visible") add(action.value);
-	}
-	return needles;
-}
-function buildEvidenceSteps(input) {
-	const byStep = groupByStep([...input.recording.actions, ...input.recording.cleanup ?? []]);
-	const assertions = assertionsByStep(input.test.source);
-	return [...input.testCase.steps, ...input.testCase.cleanup].map((step) => {
-		const actions = byStep.get(step.id) ?? [];
-		return {
-			id: step.id,
-			instruction: "instruction" in step ? step.instruction : step.judgeByLlm,
-			expected: "expected" in step ? step.expected : "",
-			actions: actions.map(describeAction),
-			assertions: assertions.get(step.id) ?? [],
-			screenshots: input.screenshots.get(step.id) ?? [],
-			needles: sourceNeedles(actions)
-		};
+function unjustifiedFirst(file, source) {
+	const all = lines(source);
+	return all.flatMap((text, i) => {
+		if (!/\bexpect\(/.test(text) || !/\.first\(\)/.test(text)) return [];
+		if (explained(all, i)) return [];
+		return [{
+			file,
+			line: i + 1,
+			rule: "unjustified-first",
+			message: "`.first()` in an assertion holds for whichever element came first. Say why that is the one, or address the element itself"
+		}];
 	});
 }
-/** Entries past this many fold away: a cell taller than the eye stops being read. */
-const FOLD_OVER = 2;
-/** The evidence as markdown — a fragment, for whoever assembles the PR body. */
-function renderEvidence(input) {
-	const labels = evidenceLabels(input.labels, input.language);
-	const steps = buildEvidenceSteps(input);
-	const anchors = input.anchors;
-	const lines = [
-		`# ${input.testCase.title}`,
-		"",
-		`${labels.case}: \`${input.testCase.ref.id}\``,
-		`${labels.test}: \`${input.test.path}\``,
-		`${labels.recordedAt}: ${input.recording.recordedAt ?? "(unknown)"}`,
-		...input.recording.origin ? [`${labels.from}: \`${input.recording.origin}\``] : [],
-		""
-	];
-	for (const [label, actions] of outsideTheCase(input, steps, labels)) lines.push(`${label}: ${fold(actions, labels)}`, "");
-	lines.push(`| ${labels.step} | ${labels.instruction} | ${labels.recorded} | ${labels.decides}` + (anchors ? ` | ${labels.source}` : "") + ` | ${labels.screens} |`, "|---|---|---|---|" + (anchors ? "---|" : "") + "---|");
-	for (const step of steps) {
-		const cells = [
-			step.id,
-			cell$1(step.instruction),
-			fold(step.actions, labels),
-			step.assertions.length > 0 ? cell$1(step.assertions.join("<br>")) : `**${labels.nothing}**`,
-			...anchors ? [sourceAnchorCells(step.needles, anchors, labels)] : [],
-			step.screenshots.map((path) => `![${step.id}](${path})`).join(" ") || "—"
-		];
-		lines.push(`| ${cells.join(" | ")} |`);
-	}
-	lines.push("");
-	if (input.testCase.expectations.length > 0) {
-		lines.push(`## ${labels.expects}`, "");
-		for (const expectation of input.testCase.expectations) lines.push(`- ${expectation}`);
-		lines.push("");
-	}
-	if (input.cleanupUnchecked && input.cleanupUnchecked.length > 0) {
-		lines.push(labels.cleanupUnchecked, "");
-		for (const expectation of input.cleanupUnchecked) lines.push(`- ${expectation}`);
-		lines.push("");
-	}
-	const findings = mergeFindings(steps.filter((step) => claimsAnOutcome(step) && step.assertions.length === 0).map((step) => ({
-		stepId: step.id,
-		problem: NOTHING_DECIDED
-	})), input.review ?? []);
-	lines.push(`## ${labels.review}`, "");
-	if (findings.length === 0) lines.push(input.review === void 0 ? labels.reviewAbsent : labels.reviewClean);
-	else {
-		for (const finding of findings) lines.push(`- ${formatFinding(finding, labels)}`);
-		if (input.review === void 0) lines.push("", labels.reviewPartial);
-	}
-	lines.push("");
-	return lines.join("\n");
+/** A describe that repeats its only test reads as "X › X" in every report. */
+function describeEcho(file, source) {
+	const describe = /test\.describe\(\s*["'](.+?)["']/.exec(source);
+	if (!describe) return [];
+	const titles = [...source.matchAll(/\n\s*test\(\s*["'](.+?)["']/g)].map((m) => m[1]);
+	if (titles.length !== 1) return [];
+	const bare = (s) => s.replace(/\s+@[\w-]+\s*$/, "").trim();
+	if (bare(titles[0]) !== bare(describe[1])) return [];
+	const line = lines(source).findIndex((t) => t.includes("test.describe(")) + 1;
+	return [{
+		file,
+		line: Math.max(line, 1),
+		rule: "describe-echo",
+		message: "the describe repeats its only test's name. Drop it, or name the screen the test is about"
+	}];
 }
-/** A table cell: pipes escaped, newlines folded, code voice for the machine parts. */
-function cell$1(text) {
-	const clean = text.replaceAll("|", "\\|").replaceAll("\n", "<br>");
-	return clean.length === 0 ? "—" : clean;
+/** `name` → the expression it is defined as, across every file written. */
+function collectLocators(files) {
+	const out = /* @__PURE__ */ new Map();
+	for (const source of files.values()) {
+		for (const m of source.matchAll(/\breadonly\s+([a-zA-Z0-9_]+)\s*=\s*([^;]+);/g)) out.set(m[1], m[2]);
+		for (const m of source.matchAll(/\b([a-zA-Z0-9_]+)\([^)]*\)\s*:\s*Locator\s*\{\s*return\s+([^;]+);/g)) out.set(m[1], m[2]);
+	}
+	return out;
 }
 /**
-* One line per needle. "not found" is a claim about the product, so a needle
-* the scan never looked for says so instead — the reviewer's whole use of this
-* column is telling those two apart.
+* The forms that carry a string a person sees on screen. A whitelist, not a
+* blacklist: a test id, an ARIA role name and a CSS selector are all strings
+* too, and none of them is something a test case would ever mention — counted
+* as "what this assertion looks for", every `getByTestId` in a project that
+* prefers them would read as an assertion nobody asked for.
 */
-function sourceAnchorCells(needles, anchors, labels) {
-	const confirmed = [];
-	const rest = [];
-	for (const { value } of needles) {
-		const anchor = anchors.found.get(value);
-		if (!anchor) rest.push(`\`${value}\` — ${anchors.unsearched.has(value) ? labels.notSearched : labels.notFound}`);
-		else if (anchor.places.length > 1) rest.push(`\`${value}\` — ${labels.ambiguous}: ${anchor.places.join(", ")}`);
-		else {
-			const partial = anchor.partial ? ` (${labels.partialMatch})` : "";
-			confirmed.push(`\`${value}\` — ${anchor.places[0]}${partial}`);
-		}
+const VISIBLE_STRING = /(?:getByText|getByLabel|getByPlaceholder|getByTitle|getByAltText|toHaveText|toContainText|toHaveValue)\(\s*["'`]([^"'`]+)|name:\s*["'`]([^"'`]+)/g;
+/**
+* The strings an assertion actually looks for: the ones on its own line plus
+* the ones in whatever page-object members it names.
+*/
+function expandLocators(text, locators) {
+	let expanded = text;
+	for (const m of text.matchAll(/\.([a-zA-Z0-9_]+)\b/g)) {
+		const definition = locators.get(m[1]);
+		if (definition) expanded += `\n${definition}`;
 	}
-	const folded = rest.length === 0 ? [] : [`<details><summary>${rest.length} ${labels.unconfirmed}</summary>${rest.join("<br>")}</details>`];
-	return cell$1([...confirmed, ...folded].join("<br>"));
+	return expanded;
 }
-/** A cell that stays one line: past a couple of entries, the rest folds away. */
-function fold(entries, labels) {
-	if (entries.length <= FOLD_OVER) return cell$1(entries.join("<br>"));
-	return `<details><summary>${entries.length} ${labels.operations}</summary>${cell$1(entries.join("<br>"))}</details>`;
+function assertedStrings(text, locators) {
+	return [...expandLocators(text, locators).matchAll(VISIBLE_STRING)].map((m) => (m[1] ?? m[2] ?? "").trim()).filter((s) => s.length > 1 && !s.includes("${"));
 }
-/** Recorded actions belonging to no step of the case, kept apart by why. */
-function outsideTheCase(input, steps, labels) {
-	const ofTheCase = new Set(steps.map((step) => step.id));
-	const grouped = actionsByStep([...input.recording.actions, ...input.recording.cleanup ?? []]);
-	const setup = [];
-	const rest = [];
-	for (const [id, actions] of grouped) if (!ofTheCase.has(id)) (id === "setup" ? setup : rest).push(...actions);
-	const rows = [];
-	if (setup.length > 0) rows.push([labels.setup, setup]);
-	if (rest.length > 0) rows.push([labels.unattributed, rest]);
-	return rows;
+/**
+* An assertion about something the case never mentions.
+*
+* The case is the contract. Anything else seen along the way adds no
+* coverage, differs between recordings, and is the first thing to break —
+* and a reviewer reading the case cannot tell why the test checks it.
+*
+* Only fires when the assertion looks for a string at all: a URL pattern or
+* a value the test itself computed has nothing to compare against, and
+* silence is the honest answer there. And not when a reason sits above it —
+* checking that a precondition still holds, so the test fails where the
+* precondition broke rather than four steps later, is worth doing and is
+* written down when it is.
+*/
+function unaskedAssertions(file, source, locators, said) {
+	const all = lines(source);
+	return all.flatMap((text, i) => {
+		if (!/\bexpect\(/.test(text)) return [];
+		const strings = assertedStrings(text, locators);
+		if (strings.length === 0 || strings.some((s) => said.includes(s))) return [];
+		if (explained(all, i)) return [];
+		return [{
+			file,
+			line: i + 1,
+			rule: "unasked-assertion",
+			message: `nothing in the case asks about ${strings.map((s) => `"${s}"`).join(", ")}. Assert what the case states, and drop the rest`
+		}];
+	});
+}
+/** The findings as the fix loop's other inputs look: a command and its output. */
+function formatEmittedReview(findings) {
+	return findings.map((f) => `${f.file}:${f.line} [${f.rule}] ${f.message}`).join("\n");
 }
 //#endregion
-//#region src/prompts/llm-gen.ts
+//#region src/claude/extract-json.ts
 /**
-* The reuse-first contract — the rules that make generated tests build on the
-* consumer repo's existing assets instead of re-implementing them. `draft*`
-* rules apply only when a mechanical draft is present; `draftInvariant`, when
-* supplied by the target, adds one more "do not drop this from the draft" rule
-* (e.g. Playwright's step-evidence calls).
+* Pulls a JSON object out of a Claude completion. Accepts either a fenced
+* ```json block or a bare `{...}` payload that constitutes the whole reply.
+* Returns null when neither shape is present.
 */
-function reuseFirstContract(hasDraft, draftInvariant) {
-	const rules = [
-		"1. **Reuse first.** Before writing any code, search the declared resources (path resources with Glob/Grep/Read; package resources under their resolved roots) and import every asset you can use: page objects, step helpers, fixtures, custom selectors, shared constants and regular expressions. Re-implementing an equivalent of an existing asset — including copy-pasting a constant or a regex — is forbidden.",
-		"2. **Create missing parts as support files.** When a needed part does not exist (e.g. a page object for a screen no resource covers), create it following the conventions guides and the style of the existing resources, and output it with `\"kind\": \"support\"`. Package resources are read-only: never modify their contents — if a package lacks something, create the missing piece as a new support file in the repo and mention it in `summary`.",
-		"3. **Match the examples.** Write in the same style as the conventions examples: naming, structure, assertion phrasing, import layout. Where you follow an existing file rather than the plain reading of a guideline — a waiting pattern, a locator shape, a teardown structure — say which file, by path, in the comment. \"Following the existing implementation\" without naming it cannot be checked by the next reader, and it is how a pattern that was right once outlives the reason for it."
-	];
-	if (hasDraft) {
-		rules.push("4. **The draft is ground truth.** The mechanical draft below encodes the recorded route. Do not change the meaning of its operation sequence or its assertions — no reordering, dropping, or weakening. You may rewrite locators when the conventions or the sources you read justify a better one.");
-		if (draftInvariant) rules.push(`5. ${draftInvariant}`);
-	}
-	return `## Reuse contract\n\n${rules.join("\n")}`;
+function extractJsonBlock(text) {
+	const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+	if (fenced && fenced[1]) return fenced[1].trim();
+	const trimmed = text.trim();
+	if (trimmed.startsWith("{") && trimmed.endsWith("}")) return trimmed;
+	return null;
 }
+//#endregion
+//#region src/prompts/verifies-spec.ts
 /**
-* The JSON output contract shared by every LLM generation pass. Mirrors the
-* cleanup prompt's "output ONLY JSON" style so parsing stays uniform.
+* Asks a reviewer who knows nothing about how the files came to exist whether
+* they would let them into this suite.
+*
+* The generation loop's only bar is "the test goes green", and a rewrite that
+* weakens an assertion clears that bar as easily as one that keeps it. Green
+* therefore does not mean checked, and nothing else looks. Observed cases: a
+* step whose expectation was "the linked page opens" asserting instead that
+* the *link* is still visible on the page it clicked from; another asserting
+* on a navigation element unrelated to the step.
+*
+* The prompt carries paths, not source: the reviewer opens the files itself,
+* which is also what lets it read the rest of the repository. That reading is
+* the point — "follow the existing implementation" is a rule no inline copy of
+* two files can be checked against, because the evidence for it is how many
+* other files do it that way.
+*
+* Nothing here may say, or let the reader infer, that the files were written
+* by a model. A reviewer told that judges the author instead of the code, and
+* the question this asks is what a colleague would say on the pull request.
 */
-function outputContract(testPath, writeRoots) {
-	return `## Output format
-
-When you are done exploring, reply with ONLY a JSON object (no explanation, no markdown code fences):
-
-{"files": [{"path": "<project-root-relative path>", "contents": "<full file contents>", "kind": "test" | "support"}], "summary": "<one-paragraph human-readable summary>"}
-
-- \`kind\` MUST be exactly \`"test"\` or \`"support"\` (no other value): \`"test"\` marks an executable test; \`"support"\` marks a companion file (page object, helper, ...).
-- The \`"kind": "test"\` file goes to exactly \`${testPath}\`. That path is the project's, not yours: never move, rename, or split the test.
-- Every \`"kind": "support"\` file must stay under one of: ${[posix.dirname(testPath), ...writeRoots].map((r) => `\`${r}\``).join(", ")}.
-- Those roots are also yours to **correct**, not only to add to. A page object
-  there that this case uses, and whose locator or waiting is wrong for what
-  this case needs, is output again with the fix — as \`"kind": "support"\`, whole.
-  Reusing something is not the same as leaving it as it is; anywhere else, and
-  anything you only read, stays untouched.
-- Absolute paths, \`..\` segments, and anything under \`node_modules/\` are rejected.
-- Emit the complete contents of every file you output — no placeholders or elisions.`;
+function verifiesSpecPrompt(input) {
+	const rules = rulesReview(input.guides ?? []);
+	return [
+		"You are the QA lead who owns this end-to-end suite. A colleague has put the",
+		"files below up for review. Open them, read whatever else in the repository you",
+		"need in order to judge them, and answer as you would on their pull request.",
+		"",
+		"## Files under review",
+		"",
+		"Written by this change:",
+		"",
+		`- ${input.testPath} (the test)`,
+		...(input.submitted ?? []).map((path) => `- ${path}`),
+		"",
+		...input.leansOn && input.leansOn.length > 0 ? [
+			"Already in the repository, and imported by the test:",
+			"",
+			...input.leansOn.map((path) => `- ${path}`),
+			""
+		] : [],
+		"A path listed here that you cannot open is itself a finding: report every step",
+		"that depended on it and name the path, rather than passing over it as if it",
+		"were clean.",
+		"",
+		"## The case this test must cover",
+		"",
+		"The only statement of what the test has to decide. Not its comments, not its",
+		"name, not what the code looks like it is doing.",
+		"",
+		...input.steps.map(stepLine),
+		"",
+		...input.expectations && input.expectations.length > 0 ? [
+			"### What the case expects",
+			"",
+			"Stated for the flow, not per step. Each belongs to the step that first",
+			"makes it true; a step is unchecked when nothing decides the one that",
+			"belongs to it.",
+			"",
+			...input.expectations.map((e) => `- ${e}`),
+			""
+		] : [],
+		...input.cleanup && input.cleanup.length > 0 ? [
+			"### Cleanup steps",
+			"",
+			...input.cleanup.map(stepLine),
+			""
+		] : [],
+		"## Does the test decide the case",
+		"",
+		"For each step above, the test must contain assertions that could FAIL if the",
+		"step's `expected` stopped holding. Report a step when:",
+		"",
+		"- its assertions cannot fail while the product is broken in the way the",
+		"  expectation describes — because they check something weaker than it",
+		"  states (the expectation says a page opens and the code re-checks the",
+		"  element it clicked; the expectation names a path with an id in it and the",
+		"  pattern also matches the path without one);",
+		"- what it asserts on is unrelated to what the step did (e.g. a navigation",
+		"  element that is present on every page);",
+		"- it depends on something that varies between runs and is not part of the",
+		"  expectation (a count, an index, a position, wording that changes);",
+		"- the expectation names WHICH screen the run arrives at, and the code",
+		"  checks only the address's shape. A pattern matches every screen shaped",
+		"  like that one — and screens that are made per category, per folder, per",
+		"  account are shaped alike by design, so arriving at the wrong one passes.",
+		"  Something the named screen shows has to be checked too;",
+		"- it checks that something is ABSENT, and nothing in the test has waited",
+		"  for the screen that would show it to finish drawing. Absence is true of",
+		"  a page that has not rendered yet, so the check passes on an empty screen",
+		"  and passes again when the thing is really there but slow. Something the",
+		"  screen shows when it is ready has to be established first;",
+		"- the expectation ties two things together — this row AND the count beside",
+		"  it, this screen AND what it shows — and the assertions check them apart.",
+		"  Read the expectation's own grammar: \"the row, with its count\" is one",
+		"  claim about one row, and two assertions that each search the whole page",
+		"  hold just as well when the count belongs to a different row. Two things",
+		"  the expectation merely lists (\"the heading and the description are",
+		"  shown\") are two claims, and checking them apart is right;",
+		"- the expectation is about EACH of several things the case names, and the",
+		"  assertions reach only one of them. The others are not checked at all, and",
+		"  a comment saying they look alike is the fault being written down, not a",
+		"  reason — the case asked for each because any one of them can be the one",
+		"  that breaks;",
+		"- it has no assertion at all.",
+		"",
+		"An assertion is only as strong as the locator it names, and the locator is",
+		"usually not in the test file. Open what the test resolves through, and report",
+		"the step when its locator makes the assertion unable to fail the way the",
+		"expectation describes. Three shapes to look for:",
+		"",
+		"- it takes the first (or last) of several matching elements, and the step",
+		"  claims something about each of them — the others go unchecked;",
+		"- it matches by a string that also appears elsewhere on the page (a nav",
+		"  item, a breadcrumb, a menu), so it is satisfied by that element even when",
+		"  the one the step names is absent;",
+		"- it matches only the words, where the step is about a control — a button,",
+		"  a link, a field. Text with that wording is not the control, so the",
+		"  assertion holds on a page where the control is gone.",
+		"",
+		"Judge a locator only through the steps — a definition no step depends on is",
+		"not a finding.",
+		"",
+		"Do NOT report here: style, naming, structure, missing coverage the case never",
+		"asked for, or an expectation you merely disagree with. A step that checks",
+		"less than you would have written, but still fails when the expectation",
+		"breaks, is fine — unless the expectation covers several things and the",
+		"code can only break on one of them, which is the bullet above.",
+		"",
+		...rules.section,
+		"When you have read enough to decide, answer with one json block and nothing",
+		"else:",
+		"",
+		"```json",
+		rules.answerShape,
+		"```",
+		"",
+		"`problem` is one sentence naming what the step claims and what the code",
+		"checks instead. Empty `findings` means every step is decided.",
+		...rules.answerNote,
+		languageDirective(input.language)
+	].join("\n");
 }
-/** Corrective note appended when the previous reply failed the output contract. */
-function retryNote(error) {
-	return `\n\n## Previous attempt rejected\n\nYour previous reply violated the output contract: ${error}\nReply again with ONLY the JSON object described in "Output format".`;
+function stepLine(step) {
+	if (!isExpandedActionStep(step)) return `- ${step.id}: judged by a model at run time — its claim is asserted by the injected call, so it needs no other assertion.`;
+	return [
+		`- ${step.id}`,
+		`  does: ${oneLine$3(step.instruction)}`,
+		`  expected: ${oneLine$3(step.expected)}`
+	].join("\n");
 }
-function formatStep(step) {
-	if (isExpandedActionStep(step)) return `- ${step.id}: ${body(step.instruction)}\n  expected: ${body(step.expected)}`;
-	const source = step.from ? ` (read from \`${step.from}\`)` : "";
-	return `- ${step.id}: judge by LLM${source}\n  claim: ${body(step.judgeByLlm)}`;
+function oneLine$3(text) {
+	return text.trim().split("\n").map((l) => l.trim()).join(" ");
 }
 /**
-* Step text is usually a block scalar, so it arrives with newlines. Left as-is
-* its later lines sit flush against the list and read as further steps.
+* The second review: the same files, read against the rule documents the
+* project wrote and against what the rest of the suite already does.
+*
+* Every rule the generation loop could already check — a type error, a lint
+* rule, a gate of ccqa's own — is followed by the code it produces. A rule
+* that only exists as prose is not, and nothing looked: green, compiled, lint
+* clean and decides its case is the whole bar, and none of it reads the
+* project's own guides. Reused code is the worse half of it — a helper the
+* test imports was written under whatever rules existed when it was written,
+* and no later rule has ever been applied to it.
+*
+* The evidence is what keeps this honest in both directions. A model asked to
+* judge code against prose will find something to say about any code; asked to
+* quote the line it is judging by — or, where the convention is only in the
+* corpus, to say which files it read and how many of them agree — it can only
+* report what is there.
+*
+* Asked once for everything it decides: a project that wrote no rule document
+* gets no section, no second key in the answer, and nothing said about one.
 */
-function body(text) {
-	return text.trim().split("\n").join("\n    ");
-}
-function buildLlmGenPrompt(input) {
-	const sections = [];
-	sections.push(input.taskInstructions);
-	const steps = input.steps.map(formatStep).join("\n");
-	sections.push(`## Test spec\n\nTitle: ${input.specTitle}\n\nSteps:\n${steps}`);
-	if (input.draft) sections.push(`## Mechanical draft (recorded ground truth)\n\nPath: ${input.draft.path}\n\n\`\`\`
-` + input.draft.contents + "\n```");
-	if (input.resources.length > 0) {
-		const lines = input.resources.map((r) => {
-			return `- ${r.kind === "package" ? `npm package \`${r.ref}\`` : `repo code \`${r.ref}\``}${r.description ? ` — ${r.description}` : ""}\n  explore under: ${r.root}`;
-		});
-		sections.push(`## Reusable resources\n\nExisting code assets the generated test MUST reuse (import path resources the way this repo does; import package resources by name):\n\n${lines.join("\n")}`);
-	}
-	if (input.conventionSections.length > 0) {
-		const bodies = input.conventionSections.map((c) => `### ${c.path}\n\n\`\`\`\n${c.body}\n\`\`\``).join("\n\n");
-		sections.push(`## Conventions\n\nHow generated code should be written:\n\n${bodies}`);
-	}
-	if (input.promptBundle) sections.push(`## Project prompt guidance\n\n${input.promptBundle}`);
-	sections.push(reuseFirstContract(input.draft !== void 0, input.draftInvariant));
-	sections.push(outputContract(input.testPath, input.writeRoots));
-	return sections.join("\n\n") + languageDirective(input.language);
+function rulesReview(guides) {
+	if (guides.length === 0) return {
+		section: [],
+		answerShape: "{ \"findings\": [ { \"stepId\": \"step-05\", \"problem\": \"…\" } ] }",
+		answerNote: []
+	};
+	return {
+		section: [
+			"## Does the code belong in this suite",
+			"",
+			"A second review of the same files, separate from the one above.",
+			"",
+			"These are the rule documents this project wrote. Report a file when its code",
+			"breaks a rule one of them states, and quote the line that states it. The",
+			"quote is the check: a rule you cannot quote is a rule the project did not",
+			"write, and reporting one of those is as wrong as missing one it did. A",
+			"preference of your own is not a rule here, however reasonable.",
+			"",
+			"How the rest of the suite is written is the other half of this question, and",
+			"it is not in the documents: the helper every other case navigates through,",
+			"the fixture they all take, where page objects live and what they are called.",
+			"Search the repository before you claim one — a convention is what the code",
+			"does, not what you would have written — and report it with what you found:",
+			"which files you read, and how many of them do it that way.",
+			"",
+			"\"Do NOT report here: style, naming, structure\" above governs the step",
+			"findings. Those belong in this half instead, and only where a document",
+			"states them or the corpus shows them.",
+			"",
+			"Read what the test leans on, not only what this change wrote. A helper it",
+			"imports was written under whatever rules existed then, and nothing has read",
+			"it against these since.",
+			"",
+			...guides.flatMap((g) => [
+				`### ${g.path}`,
+				"",
+				fencedBlock(g.body),
+				""
+			])
+		],
+		answerShape: "{ \"findings\": [ { \"stepId\": \"step-05\", \"problem\": \"…\" } ], \"ruleViolations\": [ { \"file\": \"…\", \"guide\": \"…\", \"rule\": \"…\", \"code\": \"…\", \"severity\": \"blocking\" } ] }",
+		answerNote: [
+			"",
+			"In `ruleViolations`: `file` is the file's path in this repository, and `code`",
+			"the lines that break the rule. `guide` and `rule` are where the rule comes",
+			"from and what it says — the document's path and its own words when you can",
+			"quote one; otherwise the path of a file you read that shows the convention,",
+			"and what you counted (\"N of M files under <dir> do X\"). `severity` is",
+			"\"blocking\" when you would hold the change until it is fixed, and \"advisory\"",
+			"when it is worth saying but you would approve anyway. An empty",
+			"`ruleViolations` means every file follows every rule you could quote or",
+			"count — write the key either way."
+		]
+	};
 }
+//#endregion
+//#region src/ir/types.ts
 /**
-* Prompt for one iteration of the verification loop: the generated files
-* failed their run command; ask for corrected files under the same contract.
+* Tool-neutral intermediate representation (IR) for recorded browser
+* interactions. A trace produces `RecordedAction[]` (persisted as `ir.json`);
+* emitters translate it into target-specific test code and the replay
+* validator re-executes it. The IR replaces the old dual addressing
+* (raw selector strings vs `find_*` + findLocator fields) with a single
+* `Locator` model.
 */
-function buildLlmFixPrompt(input) {
-	const files = input.files.map((f) => `### ${f.path} (${f.kind})\n\n\`\`\`\n${f.contents}\n\`\`\``).join("\n\n");
-	return [
-		`You generated ${input.targetId} test files for this project, but their verification run failed. Fix the files so the command passes. Keep the tested behaviour identical — fix locators, imports, syntax, and setup, never delete or weaken assertions to force a pass. You may Read/Grep/Glob the project to investigate.`,
-		`## Failing command\n\n\`${input.command}\``,
-		`## Command output (tail)\n\n\`\`\`\n${input.outputTail}\n\`\`\``,
-		`## Current files\n\n${files}`,
-		outputContract(input.testPath, input.writeRoots) + "\n- Output only the files that need changes; files you omit stay as they are.\n- If the failure is NOT caused by the generated files (an environment/setup issue) or the files are already correct, reply `{\"files\": [], \"summary\": \"<why no file change is needed>\"}` — verification is then simply re-run."
-	].join("\n\n") + languageDirective(input.language);
-}
 /**
-* Playwright rewrite pass: turn the mechanical draft into a library-reusing
-* spec. The draft carries the recorded route; the resources carry the assets.
+* The step id the recorder marks work that precedes the case's first step —
+* signing in, reaching the starting screen. Not a step of the case, and not
+* the same thing as an action it could not attribute at all.
 */
-function playwrightTaskInstructions(suggestedPath) {
-	return `You are rewriting a machine-generated Playwright test so it reuses this repository's existing test assets.
-
-The mechanical draft below was compiled 1:1 from a recorded browser session — it is plain \`@playwright/test\` code with raw locators (e.g. \`page.getByRole("button", { name: "Submit" })\`). Rewrite it into the shape this repository's test suite actually uses: import and call the declared resources (page objects, step helpers, fixtures, shared constants) instead of inlining raw interactions, and follow the conventions.
-
-Keep each step's assertions in the test body, under that step's own comment. A step's actions may move into a page object; what the step decides may not — it is the one thing a reviewer reads the file for, and an assertion inside a helper is invisible both to them and to the review that follows this pass.
-
-Write the rewritten test to \`${suggestedPath}\` unless the conventions/examples clearly place tests elsewhere under the output directory. Locator preference when you do write raw locators: test id > accessible text > role > CSS.`;
-}
+const SETUP_STEP_ID = "setup";
+//#endregion
+//#region src/ir/route-diff.ts
 /**
-* runn generation pass: compile the spec into a runbook. Only the generic
-* runbook shape is prescribed here — concrete endpoints, payloads, and
-* response shapes must be verified against the backend sources, found via
-* Read/Grep/Glob.
+* What changed between two recordings of the same spec.
+*
+* Re-recording replaces the route wholesale, and the interesting question
+* afterwards is never "what does the new route do" but "what moved". A locator
+* that changed shape says the screen was rebuilt; a check whose wording changed
+* says the copy moved; a step that gained operations says the flow grew. That
+* is the evidence a reviewer needs, and reading it out of two JSON files by eye
+* is exactly the work nobody does.
+*
+* The diff is per spec step, because a step is the unit the spec author wrote
+* and the unit a reviewer reasons in. Actions carry their `stepId` from the
+* trace, so the grouping is recorded, not guessed.
 */
-function runnTaskInstructions(suggestedPath) {
-	return `You are generating a runn runbook (YAML) that covers the test spec below against this repository's backend.
-
-Runbook shape (generic runn structure):
-- \`desc:\` — a one-line description of the scenario.
-- \`runners:\` — the runners the steps use (typically an HTTP runner, e.g. \`req: \${API_ENDPOINT}\`; use env-var placeholders for endpoints, never hardcode hosts).
-- \`vars:\` — variable bindings for values reused across steps (test inputs, ids captured from responses).
-- \`steps:\` — one entry per spec step where possible: \`req\` steps perform the API calls, \`test\` steps assert on \`current.res\` (status, body fields). Bind values from earlier responses via \`steps[N]\` references when later steps need them.
-
-Do NOT invent endpoints, request bodies, or response fields: use Read/Grep/Glob to find the backend sources (routing tables, handlers, schemas) and derive the concrete paths, methods, parameters, and response shapes from them. If a detail cannot be confirmed from the sources, say so in \`summary\` instead of guessing silently.
-
-Write the runbook to \`${suggestedPath}\` unless the conventions/examples clearly use another layout under the output directory. If shared setup deserves its own helper runbook, output it as \`kind: "support"\`.`;
+const NO_STEP = "(no step)";
+/** One action as a reviewer reads it: what it did, to what, with which value. */
+function describeAction(action) {
+	const parts = [action.assert ? `assert ${action.assert}` : action.action];
+	if (action.locator) parts.push(renderLocator(action.locator));
+	if (action.index !== void 0) parts.push(`[${action.index}]`);
+	if (action.value !== void 0 && action.value !== "") parts.push(JSON.stringify(action.value));
+	if (action.target) parts.push(`→ ${renderLocator(action.target)}`);
+	if (action.files?.length) parts.push(action.files.join(", "));
+	return parts.join(" ");
 }
 /**
-* How many files the walk may collect. Depth alone does not bound it: one
-* barrel `index.ts` re-exporting a directory fans out to everything in it, and
-* the caller reads what the walk returns. Far more than an audit's budget can
-* hold, so the cap only stops the pathological case.
-*/
-const MAX_SUPPORT_FILES = 200;
-/** Extensions tried when a specifier names no file, TypeScript sources first. */
-const EXTENSIONS = [
-	".ts",
-	".tsx",
-	".mts",
-	".cts",
-	".js",
-	".jsx",
-	".mjs",
-	".cjs"
-];
-/**
-* Module specifiers, in the forms generated tests use: `from "x"`, a
-* side-effect `import "x"`, `import("x")`, and `require("x")`. A string this
-* over-matches (prose after the word "from" in a comment) resolves to no file
-* and drops out.
+* The same, prefixed by the step it belongs to. What a warning about one
+* action says, so a reader can find it in the case rather than counting
+* positions in a list.
 */
-const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)["']([^"']+)["']/g;
+function describeStepAction(action) {
+	return `${action.stepId ? `${action.stepId} ` : ""}${describeAction(action)}`;
+}
 /**
-* Read `<cwd>/tsconfig.json`'s `baseUrl` / `paths`, following a relative
-* `extends` chain — a workspace commonly keeps its aliases in a base config,
-* and stopping at the leaf would drop exactly the page objects an audit needs.
-* A config published as a package is not followed: its aliases would resolve
-* inside `node_modules`, which this walker never reads anyway. Absent,
-* unreadable, or aliasless: null, and only relative imports are followed.
+* A locator in full, unlike `describeLocator`'s log-line summary: two locators
+* that differ must render differently, or the diff reports a re-addressed
+* element as unchanged — the very thing it exists to show.
 */
-async function loadTsconfigPaths(cwd) {
-	let configPath = join(cwd, "tsconfig.json");
-	const seen = /* @__PURE__ */ new Set();
-	while (configPath !== null && !seen.has(configPath)) {
-		seen.add(configPath);
-		const parsed = await readTsconfig(configPath);
-		if (parsed === null) return null;
-		const options = parsed.compilerOptions;
-		if (options?.paths) return {
-			baseUrlAbs: resolve(dirname(configPath), options.baseUrl ?? "."),
-			paths: options.paths
-		};
-		configPath = typeof parsed.extends === "string" && parsed.extends.startsWith(".") ? withJsonExtension(resolve(dirname(configPath), parsed.extends)) : null;
-	}
-	return null;
-}
-async function readTsconfig(path) {
-	const raw = await readFile(path, "utf8").catch(() => null);
-	if (raw === null) return null;
-	try {
-		return JSON.parse(stripJsonComments(raw));
-	} catch {
-		return null;
+function renderLocator(locator) {
+	if (locator.by === "css") return locator.value;
+	const exact = locator.exact ? " exact" : "";
+	if (locator.by === "role") {
+		const name = locator.name === void 0 ? "" : `[name=${JSON.stringify(locator.name)}]`;
+		return `role=${locator.value}${name}${exact}`;
 	}
-}
-/** `extends` may name a config with the extension left off. */
-function withJsonExtension(path) {
-	return path.endsWith(".json") ? path : `${path}.json`;
-}
-/** Strip line and block comments and trailing commas — tsconfig.json is JSONC. */
-function stripJsonComments(text) {
-	return text.replace(/"(?:[^"\\]|\\.)*"|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (match) => match.startsWith("\"") ? match : "").replace(/,(\s*[}\]])/g, "$1");
+	return `${locator.by}=${JSON.stringify(locator.value)}${exact}`;
 }
 /**
-* Files reachable from `entryAbs` by following project-internal imports, in
-* breadth-first order and excluding the entry itself. Reading a file that
-* cannot be read yields no imports rather than an error: a missing import
-* target is the audit's business, not this walker's.
+* Identity of an action across recordings: what it did and to which named
+* thing. Deliberately blind to the locator and the exact value, so a button
+* addressed a new way still pairs with its old self and reads as "changed"
+* rather than as one removal plus one addition.
 */
-async function collectSupportFiles(entryAbs, cwd, opts = {}) {
-	return (await walkSupportFiles(entryAbs, cwd, opts)).files;
+function identity(action) {
+	return [
+		action.action,
+		action.assert ?? "",
+		action.label ?? action.locator?.value ?? ""
+	].join("|");
 }
-/** {@link collectSupportFiles}, saying whether a cap cut the walk short. */
-async function walkSupportFiles(entryAbs, cwd, opts = {}) {
-	const maxDepth = opts.maxDepth ?? 3;
-	const tsconfig = opts.tsconfig !== void 0 ? opts.tsconfig : await loadTsconfigPaths(cwd);
-	const seen = new Set([entryAbs]);
-	const found = [];
-	let frontier = [entryAbs];
-	for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
-		const levels = await Promise.all(frontier.map(async (fileAbs) => (await resolveImportsOf(fileAbs, cwd, tsconfig)).map((abs) => ({
-			abs,
-			from: fileAbs
-		}))));
-		const next = [];
-		for (const entry of levels.flat()) {
-			if (seen.has(entry.abs)) continue;
-			seen.add(entry.abs);
-			found.push(entry);
-			next.push(entry.abs);
-			if (found.length >= MAX_SUPPORT_FILES) return {
-				files: found,
-				truncated: true
-			};
-		}
-		frontier = next;
+function diffRoutes(before, after) {
+	const moved = findMoves(before, after);
+	const movedForms = new Set(moved.map((m) => m.action));
+	const stayed = (a) => !movedForms.has(describeAction(a));
+	const inStep = (actions, step) => actions.filter((a) => (a.stepId ?? NO_STEP) === step && stayed(a));
+	const changes = [];
+	const unchangedSteps = [];
+	for (const step of orderedSteps(before, after)) {
+		const wasIn = inStep(before, step);
+		const isIn = inStep(after, step);
+		if (wasIn.length === 0 && isIn.length === 0) continue;
+		const stepChanges = diffStep(step, wasIn, isIn);
+		if (stepChanges.length === 0) unchangedSteps.push(step);
+		else changes.push(...stepChanges);
 	}
 	return {
-		files: found,
-		truncated: frontier.length > 0
+		changes,
+		moved,
+		unchangedSteps
 	};
 }
-/** Every project file one file imports, in source order. */
-async function resolveImportsOf(fileAbs, cwd, tsconfig) {
-	const source = await readFile(fileAbs, "utf8").catch(() => null);
-	if (source === null) return [];
-	const specifiers = [...source.matchAll(IMPORT_SPECIFIER)].map((m) => m[1]);
-	return (await Promise.all(specifiers.map((s) => resolveSpecifier(s, dirname(fileAbs), cwd, tsconfig)))).filter((p) => p !== null);
-}
 /**
-* One specifier → an existing file inside the project, or null. Anything that
-* escapes the project root, or lands in `node_modules`, is dropped: it is not
-* the consumer's code to read.
+* Operations both recordings hold under a different step id, matched on the
+* rendered form: same operation, same locator, same value. A form appearing
+* more than once in either recording is left to the per-step diff — which of
+* two identical operations moved is a question the recording cannot answer.
 */
-async function resolveSpecifier(specifier, fromDirAbs, cwd, tsconfig) {
-	const candidates = specifier.startsWith(".") ? [resolve(fromDirAbs, specifier)] : isAbsolute(specifier) ? [] : aliasCandidates(specifier, tsconfig);
-	for (const candidate of candidates) {
-		const file = await resolveFile(candidate);
-		if (file === null) continue;
-		if (file.split(/[\\/]/).includes("node_modules")) return null;
-		return file.startsWith(`${cwd}/`) ? file : null;
+function findMoves(before, after) {
+	const index = (actions) => {
+		const seen = /* @__PURE__ */ new Map();
+		const repeated = /* @__PURE__ */ new Set();
+		for (const action of actions) {
+			const form = describeAction(action);
+			if (seen.has(form)) repeated.add(form);
+			seen.set(form, action);
+		}
+		for (const form of repeated) seen.delete(form);
+		return seen;
+	};
+	const b = index(before);
+	const moved = [];
+	for (const [form, action] of index(after)) {
+		const was = b.get(form);
+		if (was === void 0) continue;
+		const from = was.stepId ?? NO_STEP;
+		const to = action.stepId ?? NO_STEP;
+		if (from !== to) moved.push({
+			action: form,
+			from,
+			to
+		});
 	}
-	return null;
+	return moved;
 }
-/** Every path a `paths` alias maps this specifier to, in config order. */
-function aliasCandidates(specifier, tsconfig) {
-	if (!tsconfig) return [];
+/** Every step id either recording mentions, in the new recording's order first. */
+function orderedSteps(before, after) {
+	const seen = /* @__PURE__ */ new Set();
 	const out = [];
-	for (const [pattern, targets] of Object.entries(tsconfig.paths)) {
-		const star = pattern.indexOf("*");
-		if (star === -1) {
-			if (pattern === specifier) out.push(...targets.map((t) => resolve(tsconfig.baseUrlAbs, t)));
-			continue;
-		}
-		const prefix = pattern.slice(0, star);
-		const suffix = pattern.slice(star + 1);
-		if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue;
-		const matched = specifier.slice(prefix.length, specifier.length - suffix.length);
-		out.push(...targets.map((t) => resolve(tsconfig.baseUrlAbs, t.replace("*", matched))));
+	for (const action of [...after, ...before]) {
+		const step = action.stepId ?? NO_STEP;
+		if (seen.has(step)) continue;
+		seen.add(step);
+		out.push(step);
 	}
 	return out;
 }
-/** A path → the file it names: itself, `<path><ext>`, or `<path>/index<ext>`. */
-async function resolveFile(pathAbs) {
-	if (await isFile(pathAbs)) return pathAbs;
-	const rewritten = pathAbs.replace(/\.(js|mjs|cjs)$/, "");
-	if (rewritten !== pathAbs) {
-		for (const ext of EXTENSIONS) if (await isFile(rewritten + ext)) return rewritten + ext;
+/**
+* Align one step's actions by identity (longest common subsequence), then
+* report the leftovers. An aligned pair whose rendered form differs is the
+* interesting case: same operation, new locator or new wording.
+*/
+function diffStep(step, before, after) {
+	const changes = [];
+	for (const entry of alignByIdentity(before, after)) if (entry.before && entry.after) {
+		const b = describeAction(entry.before);
+		const a = describeAction(entry.after);
+		if (b !== a) changes.push({
+			kind: "changed",
+			step,
+			before: b,
+			after: a
+		});
+	} else if (entry.after) changes.push({
+		kind: "added",
+		step,
+		after: describeAction(entry.after)
+	});
+	else if (entry.before) changes.push({
+		kind: "removed",
+		step,
+		before: describeAction(entry.before)
+	});
+	return changes;
+}
+function alignByIdentity(before, after) {
+	const lengths = Array.from({ length: before.length + 1 }, () => new Array(after.length + 1).fill(0));
+	for (let i = before.length - 1; i >= 0; i--) for (let j = after.length - 1; j >= 0; j--) lengths[i][j] = identity(before[i]) === identity(after[j]) ? lengths[i + 1][j + 1] + 1 : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
+	const out = [];
+	let i = 0;
+	let j = 0;
+	while (i < before.length && j < after.length) if (identity(before[i]) === identity(after[j])) {
+		out.push({
+			before: before[i],
+			after: after[j]
+		});
+		i++;
+		j++;
+	} else if (lengths[i + 1][j] >= lengths[i][j + 1]) out.push({ before: before[i++] });
+	else out.push({ after: after[j++] });
+	while (i < before.length) out.push({ before: before[i++] });
+	while (j < after.length) out.push({ after: after[j++] });
+	return out;
+}
+/** The diff as markdown — what `ccqa record` saves beside the spec. */
+function renderRouteDiff(diff, report) {
+	const { changes, moved, unchangedSteps } = diff;
+	const lines = [`# Route diff — ${report.specKey}`, ""];
+	lines.push(`Recorded ${report.before.recordedAt ?? "(unknown)"} → ${report.after.recordedAt ?? "(unknown)"}.`, "");
+	if (report.before.origin !== report.after.origin) lines.push(`Origin: \`${report.before.origin ?? "(none)"}\` → \`${report.after.origin ?? "(none)"}\``, "");
+	if (changes.length === 0 && moved.length === 0) {
+		lines.push("The route is unchanged: same operations, locators and checks.", "");
+		return lines.join("\n");
 	}
-	for (const ext of EXTENSIONS) if (await isFile(pathAbs + ext)) return pathAbs + ext;
-	for (const ext of EXTENSIONS) {
-		const indexed = join(pathAbs, `index${ext}`);
-		if (await isFile(indexed)) return indexed;
+	if (changes.length === 0) lines.push("The route does the same things, in the same way. Only which step each was recorded under moved.", "");
+	for (const step of groupByStep$1(changes)) {
+		const title = report.stepTitles?.get(step.step);
+		lines.push(`## ${step.step}${title ? ` — ${title}` : ""}`, "");
+		for (const change of step.changes) lines.push(change.kind === "changed" ? `- changed: \`${change.before}\` → \`${change.after}\`` : change.kind === "added" ? `- added: \`${change.after}\`` : `- removed: \`${change.before}\``);
+		lines.push("");
 	}
-	return null;
-}
-function isFile(pathAbs) {
-	return stat(pathAbs).then((s) => s.isFile(), () => false);
+	if (moved.length > 0) {
+		lines.push("## Recorded under a different step", "", "Same operation, same locator, same value — only its step attribution moved.", "");
+		for (const move of moved) lines.push(`- \`${move.action}\`: ${move.from} → ${move.to}`);
+		lines.push("");
+	}
+	if (unchangedSteps.length > 0) lines.push(`Unchanged: ${unchangedSteps.join(", ")}`, "");
+	return lines.join("\n");
 }
-/** `export const NAME` / `export function NAME` / `export class NAME`, and `export { A, B }`. */
-const EXPORTED = /export\s+(?:async\s+)?(?:const|let|function|class|enum)\s+([A-Za-z_$][\w$]*)/g;
-const EXPORT_LIST = /export\s*\{([^}]*)\}/g;
-const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
-/** A `//` that is not the tail of a `://` — the shape a URL in a string has. */
-const LINE_COMMENT = /(^|[^:])\/\/.*$/gm;
-/**
-* The value names a file exports, as a reader would list them.
-*
-* Text, not a parser: this answers a warning, not a refusal, and a name missed
-* because it was written in a form this does not know costs nothing. A name
-* invented would cost a false warning, so the patterns only match declarations
-* that plainly are one, and comments are stripped first. Types are left out
-* for the same reason: a page object's own row type is referenced only inside
-* it, so listing it would report a definition that is used.
-*/
-function exportedNames(source) {
-	const code = source.replace(BLOCK_COMMENT, "").replace(LINE_COMMENT, "$1");
-	const names = /* @__PURE__ */ new Set();
-	for (const m of code.matchAll(EXPORTED)) names.add(m[1]);
-	for (const m of code.matchAll(EXPORT_LIST)) for (const part of m[1].split(",")) {
-		const name = part.trim().split(/\s+as\s+/).pop()?.trim();
-		if (name && /^[A-Za-z_$][\w$]*$/.test(name) && name !== "default") names.add(name);
+function groupByStep$1(changes) {
+	const grouped = [];
+	for (const change of changes) {
+		const last = grouped.at(-1);
+		if (last && last.step === change.step) last.changes.push(change);
+		else grouped.push({
+			step: change.step,
+			changes: [change]
+		});
 	}
-	return [...names];
+	return grouped;
 }
 //#endregion
-//#region src/targets/emitted-review.ts
-function reviewEmittedFiles(input) {
-	const locators = collectLocators(input.files);
-	const said = input.caseText.join("\n");
-	return [
-		...decidesNothing(input),
-		...unassertedPath(input),
-		...[...input.files].flatMap(([file, source]) => [
-			...toolIdentifiers(file, source),
-			...containerOfPageText(file, source),
-			...unjustifiedFirst(file, source),
-			...describeEcho(file, source),
-			...unaskedAssertions(file, source, locators, said),
-			...weakerTwin(file, source),
-			...unreached(file, source, input)
-		])
-	];
-}
-/**
-* A path with a placeholder segment in it — `/orders/{orderId}`. Writing one
-* in prose is a statement about the address, not about the page's contents:
-* there is no other reason to name the part that changes per run.
+//#region src/evidence/table.ts
+/** Assertion lines a reviewer can check without reading the whole file. */
+const ASSERTION = /^\s*(?:await\s+)?(?:expect|judgeByLlm)\b.*$/;
+/**
+* Assertions grouped by the step they sit under, read from the boundary the
+* emitter leaves — a `test.step` title for a Playwright test, a comment for an
+* agent-browser one. A rewrite that moved an assertion into a page object
+* leaves nothing here, which is the honest answer: the reviewer cannot see it
+* either, and the row says so rather than implying coverage.
 */
-const PLACEHOLDER_PATH = /\/[A-Za-z0-9_\-]+(?:\/[A-Za-z0-9_\-]+)*\/\{[A-Za-z0-9_]+\}/;
+function assertionsByStep(source) {
+	const byStep = /* @__PURE__ */ new Map();
+	let current = null;
+	for (const line of stepLines(source)) {
+		const boundary = parseStepComment(line);
+		if (boundary) {
+			current = boundary;
+			if (!byStep.has(current)) byStep.set(current, []);
+			continue;
+		}
+		if (current && ASSERTION.test(line)) byStep.get(current).push(line.trim());
+	}
+	return byStep;
+}
 /**
-* A case that says where the run must end up, and a test that never looks at
-* the address.
-*
-* The row being on screen is not the same claim as being on the screen that
-* shows it — a product that rendered the row without navigating passes, and
-* that is the failure the expectation was written to catch. Scoped to
-* placeholder paths because those are unambiguous; a path mentioned as scenery
-* ("on /settings, the button is shown") is not a claim about the address.
-*
-* Calibrated against a small set of hand-written case definitions: a few
-* name a placeholder path in their expectations, most of those already
-* assert on the URL, and the one that does not is the defect this was
-* written for.
+* Recorded actions grouped by the step that produced them. `"(no step)"` is
+* the bucket for an action the recorder could not attribute — kept rather than
+* dropped, since it still happened.
 */
-function unassertedPath(input) {
-	const source = input.files.get(input.testPath);
-	if (source === void 0) return [];
-	const stated = input.caseText.find((text) => PLACEHOLDER_PATH.test(text));
-	if (stated === void 0 || /\btoHaveURL\b/.test(source)) return [];
-	return [{
-		file: input.testPath,
-		line: 1,
-		rule: "unasserted-path",
-		message: `the case says where the run ends up — "${PLACEHOLDER_PATH.exec(stated)?.[0]}" — and nothing here looks at the address. What the screen shows can be right while the screen is wrong. Assert the URL where the case says it changes`
-	}];
+function groupByStep(actions) {
+	const byStep = /* @__PURE__ */ new Map();
+	for (const action of actions) {
+		const id = action.stepId ?? "(no step)";
+		const list = byStep.get(id);
+		if (list) list.push(action);
+		else byStep.set(id, [action]);
+	}
+	return byStep;
+}
+/** The same grouping, each action rendered for a reader. */
+function actionsByStep(actions) {
+	return new Map([...groupByStep(actions)].map(([id, grouped]) => [id, grouped.map(describeAction)]));
 }
-/** `readonly name =`, `name(...): Locator {`, and `export … name`. */
-const DECLARED = /(?:readonly\s+([A-Za-z0-9_]+)\s*=|\b([A-Za-z0-9_]+)\([^)]*\)\s*:\s*Locator\b|export\s+(?:async\s+)?(?:const|let|function|class)\s+([A-Za-z0-9_]+))/g;
 /**
-* A definition in a file this generation wrote that nothing reaches — not the
-* test it generated, and not the project's own test assets either.
+* The locator/assertion literals worth anchoring to the product's own source:
+* a testid, an accessible name, a placeholder, a label, an asserted text. Not
+* every locator strategy — `css`, `text` and `alt`/`title` locators are as
+* often a CSS/testing artifact as product copy, and would anchor to noise.
 *
-* Both halves are needed. Without the first it is not this generation's
-* business; without the second every shared definition another case uses would
-* be reported. Together they say only what is true: nobody reaches this.
+* A value containing `${...}` is a run-id-substituted value at replay time
+* and has no literal counterpart in the source, so it is dropped rather than
+* searched for and reported "not found".
 */
-function unreached(file, source, input) {
-	const elsewhere = input.usedInProject?.get(file);
-	if (elsewhere === void 0) return [];
-	const corpus = [...input.files.values()].join("\n");
-	return lines(source).flatMap((text, i) => {
-		const declared = DECLARED.exec(text);
-		DECLARED.lastIndex = 0;
-		if (!declared) return [];
-		const name = named(declared);
-		if (!name || elsewhere.has(name)) return [];
-		if (corpus.split(new RegExp(`\\b${name}\\b`)).length - 1 > 1) return [];
-		return [{
-			file,
-			line: i + 1,
-			rule: "unreached",
-			message: `\`${name}\` is defined here and nothing reaches it — not this case's test, and nothing else in the project. Remove it`
-		}];
+function sourceNeedles(actions) {
+	const needles = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (value, kind = "text") => {
+		if (value === void 0 || value.includes("${") || seen.has(value)) return;
+		seen.add(value);
+		needles.push({
+			value,
+			kind
+		});
+	};
+	for (const action of actions) {
+		for (const locator of [action.locator, action.target]) {
+			if (!locator) continue;
+			if (locator.by === "testid") add(locator.value, "testid");
+			else if (locator.by === "placeholder" || locator.by === "label") add(locator.value);
+			else if (locator.by === "role") add(locator.name);
+		}
+		if (action.assert === "text_visible" || action.assert === "text_not_visible") add(action.value);
+	}
+	return needles;
+}
+function buildEvidenceSteps(input) {
+	const byStep = groupByStep([...input.recording.actions, ...input.recording.cleanup ?? []]);
+	const assertions = assertionsByStep(input.test.source);
+	return [...input.testCase.steps, ...input.testCase.cleanup].map((step) => {
+		const actions = byStep.get(step.id) ?? [];
+		return {
+			id: step.id,
+			instruction: "instruction" in step ? step.instruction : step.judgeByLlm,
+			expected: "expected" in step ? step.expected : "",
+			actions: actions.map(describeAction),
+			assertions: assertions.get(step.id) ?? [],
+			screenshots: input.screenshots.get(step.id) ?? [],
+			needles: sourceNeedles(actions)
+		};
 	});
 }
-const named = (m) => m[1] ?? m[2] ?? m[3] ?? "";
+/** Entries past this many fold away: a cell taller than the eye stops being read. */
+const FOLD_OVER = 2;
+/** The evidence as markdown — a fragment, for whoever assembles the PR body. */
+function renderEvidence(input) {
+	const labels = evidenceLabels(input.labels, input.language);
+	const steps = buildEvidenceSteps(input);
+	const anchors = input.anchors;
+	const lines = [
+		`# ${input.testCase.title}`,
+		"",
+		`${labels.case}: \`${input.testCase.ref.id}\``,
+		`${labels.test}: \`${input.test.path}\``,
+		`${labels.recordedAt}: ${input.recording.recordedAt ?? "(unknown)"}`,
+		...input.recording.origin ? [`${labels.from}: \`${input.recording.origin}\``] : [],
+		""
+	];
+	for (const [label, actions] of outsideTheCase(input, steps, labels)) lines.push(`${label}: ${fold(actions, labels)}`, "");
+	lines.push(`| ${labels.step} | ${labels.instruction} | ${labels.recorded} | ${labels.decides}` + (anchors ? ` | ${labels.source}` : "") + ` | ${labels.screens} |`, "|---|---|---|---|" + (anchors ? "---|" : "") + "---|");
+	for (const step of steps) {
+		const cells = [
+			step.id,
+			cell$1(step.instruction),
+			fold(step.actions, labels),
+			step.assertions.length > 0 ? cell$1(step.assertions.join("<br>")) : `**${labels.nothing}**`,
+			...anchors ? [sourceAnchorCells(step.needles, anchors, labels)] : [],
+			step.screenshots.map((path) => `![${step.id}](${path})`).join(" ") || "—"
+		];
+		lines.push(`| ${cells.join(" | ")} |`);
+	}
+	lines.push("");
+	if (input.testCase.expectations.length > 0) {
+		lines.push(`## ${labels.expects}`, "");
+		for (const expectation of input.testCase.expectations) lines.push(`- ${expectation}`);
+		lines.push("");
+	}
+	if (input.cleanupUnchecked && input.cleanupUnchecked.length > 0) {
+		lines.push(labels.cleanupUnchecked, "");
+		for (const expectation of input.cleanupUnchecked) lines.push(`- ${expectation}`);
+		lines.push("");
+	}
+	const findings = mergeFindings(steps.filter((step) => claimsAnOutcome(step) && step.assertions.length === 0).map((step) => ({
+		stepId: step.id,
+		problem: NOTHING_DECIDED
+	})), input.review ?? []);
+	lines.push(`## ${labels.review}`, "");
+	if (findings.length === 0) lines.push(input.review === void 0 ? labels.reviewAbsent : labels.reviewClean);
+	else {
+		for (const finding of findings) lines.push(`- ${formatFinding(finding, labels)}`);
+		if (input.review === void 0) lines.push("", labels.reviewPartial);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+/** A table cell: pipes escaped, newlines folded, code voice for the machine parts. */
+function cell$1(text) {
+	const clean = text.replaceAll("|", "\\|").replaceAll("\n", "<br>");
+	return clean.length === 0 ? "—" : clean;
+}
 /**
-* Two names for one visible string, where one of them is strictly weaker: a
-* role and its accessible name next to a bare page-wide text match that then
-* picks a position out of the matches.
-*
-* The weak one adds no check — anything it could catch, the other catches
-* first — and it is satisfied by whichever element the page happens to order
-* first, which on a real page was the navigation entry rather than the heading
-* the case names. Both assertions then read as two checks and are one.
-*
-* Calibrated against a hand-written corpus: the shape appears only in a file
-* a generation wrote. People do not write it.
+* One line per needle. "not found" is a claim about the product, so a needle
+* the scan never looked for says so instead — the reviewer's whole use of this
+* column is telling those two apart.
 */
-function weakerTwin(file, source) {
-	const byString = /* @__PURE__ */ new Map();
-	lines(source).forEach((text, i) => {
-		const declared = /(?:readonly|const)\s+([A-Za-z0-9_]+)\s*=\s*(.+?);\s*$/.exec(text);
-		if (!declared) return;
-		const [, name, expression] = declared;
-		const weak = /\.(?:first|last|nth)\(/.test(expression) && expression.includes("getByText(");
-		const strong = expression.includes("getByRole(") && !/\.(?:first|last|nth)\(/.test(expression);
-		if (!weak && !strong) return;
-		for (const m of expression.matchAll(VISIBLE_STRING)) {
-			const value = m[1] ?? m[2];
-			if (!value || value.includes("${")) continue;
-			const seen = byString.get(value) ?? [];
-			seen.push({
-				name,
-				line: i + 1,
-				weak
-			});
-			byString.set(value, seen);
+function sourceAnchorCells(needles, anchors, labels) {
+	const confirmed = [];
+	const rest = [];
+	for (const { value } of needles) {
+		const anchor = anchors.found.get(value);
+		if (!anchor) rest.push(`\`${value}\` — ${anchors.unsearched.has(value) ? labels.notSearched : labels.notFound}`);
+		else if (anchor.places.length > 1) rest.push(`\`${value}\` — ${labels.ambiguous}: ${anchor.places.join(", ")}`);
+		else {
+			const partial = anchor.partial ? ` (${labels.partialMatch})` : "";
+			confirmed.push(`\`${value}\` — ${anchor.places[0]}${partial}`);
 		}
-	});
-	const findings = [];
-	for (const [value, defs] of byString) {
-		const weak = defs.filter((d) => d.weak);
-		if (weak.length === 0 || defs.every((d) => d.weak)) continue;
-		const strong = defs.find((d) => !d.weak);
-		for (const d of weak) findings.push({
-			file,
-			line: d.line,
-			rule: "weaker-twin",
-			message: `\`${d.name}\` and \`${strong.name}\` are both "${value}", and this one searches the whole page and takes a position out of the matches. It can only be satisfied by something \`${strong.name}\` already covers, or by the wrong element. Assert one of them`
-		});
 	}
-	return findings;
+	const folded = rest.length === 0 ? [] : [`<details><summary>${rest.length} ${labels.unconfirmed}</summary>${rest.join("<br>")}</details>`];
+	return cell$1([...confirmed, ...folded].join("<br>"));
+}
+/** A cell that stays one line: past a couple of entries, the rest folds away. */
+function fold(entries, labels) {
+	if (entries.length <= FOLD_OVER) return cell$1(entries.join("<br>"));
+	return `<details><summary>${entries.length} ${labels.operations}</summary>${cell$1(entries.join("<br>"))}</details>`;
+}
+/** Recorded actions belonging to no step of the case, kept apart by why. */
+function outsideTheCase(input, steps, labels) {
+	const ofTheCase = new Set(steps.map((step) => step.id));
+	const grouped = actionsByStep([...input.recording.actions, ...input.recording.cleanup ?? []]);
+	const setup = [];
+	const rest = [];
+	for (const [id, actions] of grouped) if (!ofTheCase.has(id)) (id === "setup" ? setup : rest).push(...actions);
+	const rows = [];
+	if (setup.length > 0) rows.push([labels.setup, setup]);
+	if (rest.length > 0) rows.push([labels.unattributed, rest]);
+	return rows;
 }
+//#endregion
+//#region src/targets/verifies-spec.ts
+const FindingsSchema = z.object({ findings: z.array(z.object({
+	stepId: z.string(),
+	problem: z.string()
+})) });
+const ViolationSchema = z.object({
+	file: z.string(),
+	guide: z.string(),
+	rule: z.string(),
+	code: z.string(),
+	severity: z.enum(["blocking", "advisory"]).catch("blocking")
+});
+const ViolationsSchema = z.object({ ruleViolations: z.array(z.unknown()) });
 /**
-* A test with no assertion anywhere in it, for a case that states something.
-*
-* The per-step version of this question belongs to the reading, which knows
-* that "open the list" claims nothing and expects no assertion under it. This
-* one needs no judgement: whatever the case says, a file that decides nothing
-* at all does not check it. It is the floor under a case whose expectations
-* are stated for the flow rather than per step — the shape a markdown case has
-* — where the reading is otherwise the only thing looking.
+* How much reading one review may do.
 *
-* Calibrated like the rest: in the corpus this was calibrated on, not one
-* hand-written spec had zero assertions.
+* A runaway guard, not a working limit: the reviewer opens the files under
+* review, then searches the suite for each convention it wants to check, and a
+* review that reaches this is looping rather than working. Reaching it costs
+* the review, not the generate — the answer comes back unusable and the loop
+* treats it as one it could not obtain.
 */
-function decidesNothing(input) {
-	const source = input.files.get(input.testPath);
-	if (source === void 0 || input.caseText.join("").trim().length === 0) return [];
-	if (/\bexpect\(|\bjudgeByLlm\b/.test(source)) return [];
-	return [{
-		file: input.testPath,
-		line: 1,
-		rule: "decides-nothing",
-		message: "this test contains no assertion at all, so it passes whatever the product does. Decide what the case says must be true"
-	}];
-}
-const lines = (source) => source.split("\n");
-/** ccqa's name has no business in a name the project now owns and maintains. */
-function toolIdentifiers(file, source) {
-	return lines(source).flatMap((text, i) => {
-		const m = /\b(?:const|let|var|readonly)\s+(ccqa[A-Za-z0-9_]*)/i.exec(text);
-		return m ? [{
-			file,
-			line: i + 1,
-			rule: "tool-identifier",
-			message: `\`${m[1]}\` names the tool that wrote it. Name it for what it holds`
-		}] : [];
-	});
+const MAX_REVIEW_TURNS = 80;
+/** A wedged call, not a slow one: a review still silent after this is stuck. */
+const REVIEW_TIMEOUT_MS = 10 * 6e4;
+/** Read-only: a reviewer reads the repository and changes nothing in it. */
+const REVIEW_TOOLS = [
+	"Read",
+	"Grep",
+	"Glob"
+];
+function parseAnswer(answer, schema) {
+	const json = extractJsonBlock(answer);
+	if (!json) return null;
+	try {
+		return schema.parse(JSON.parse(json));
+	} catch {
+		return null;
+	}
 }
 /**
-* Searching the whole page for something a name calls a container: its text,
-* or a structural tag that says nothing about what the element is.
-*
-* Both forms, because the first version tested only `getByText` and the fix
-* pass answered it with `page.locator("div").filter({ hasText }).last()` —
-* the same page-wide search, now resting on DOM order, and invisible to a
-* rule that only knew one shape. A generation that escapes a finding by
-* changing shape is worse than one that never drew it.
+* Findings in the model's answer, or null when it did not answer in the
+* agreed shape. Null is not "no findings": the caller says so rather than
+* reporting a clean review it never got.
 */
-const PAGE_ROOTED = /^this\.page\.(?:getByText\(|locator\(["'](?:div|span|p|li|ul|ol|section|article)["']\))/;
-const CONTAINER = /\b(?:readonly\s+)?([a-zA-Z0-9_]*(?:Row|Cell|Card|Item|List))\s*(?:=\s*|\([^)]*\)\s*:\s*Locator\s*\{\s*(?:return\s+)?)(.*)$/;
+function parseVerifiesSpecFindings(answer) {
+	return parseAnswer(answer, FindingsSchema)?.findings ?? null;
+}
 /**
-* A name that says "one of the things in a list" built from a match against
-* the whole page. It finds the string anywhere — a heading, a toast, another
-* row — so what it proves is not what its name claims.
-*
-* The message names the shapes that fix it, because the first version said
-* only "scope it" and the fix pass answered with `page.locator("div")` filtered
-* by the same text and narrowed with `.last()` — page-wide still, and now
-* resting on which match the DOM happens to put last.
+* Rule violations in the same answer, or null when that half did not come
+* back. Read apart from the findings on purpose: one answer carries two
+* reviews, and a malformed half must not discard the other.
 */
-function containerOfPageText(file, source) {
-	const all = lines(source);
-	return all.flatMap((text, i) => {
-		const m = CONTAINER.exec(text);
-		if (!m) return [];
-		const body = m[2].trim() || (all[i + 1] ?? "").trim().replace(/^return\s+/, "");
-		if (!PAGE_ROOTED.test(body)) return [];
-		return [{
-			file,
-			line: i + 1,
-			rule: "unscoped-container",
-			message: `\`${m[1]}\` is named for one element among others, but matches that text anywhere on the page — a heading or a toast carrying it satisfies this too. Address the element itself: the role it has (\`getByRole("row"|"listitem"|"article"|...)\` narrowed with \`.filter({ hasText })\`), or its test id. Where the page offers neither, scope from a container this page object already addresses — searching the whole page for a bare \`div\` and taking \`.first()\`/\`.last()\` is not scoping, it only picks whichever the DOM happens to order that way.`
-		}];
+function parseGuideViolations(answer) {
+	const entries = parseAnswer(answer, ViolationsSchema)?.ruleViolations;
+	if (entries === void 0) return null;
+	const violations = entries.flatMap((entry) => {
+		const parsed = ViolationSchema.safeParse(entry);
+		return parsed.success ? [parsed.data] : [];
 	});
+	if (violations.length < entries.length) warn(`${entries.length - violations.length} rule violation(s) came back unreadable and were dropped`);
+	return violations;
 }
 /**
-* Whether a written reason sits above this line.
+* Whether a step claims an outcome of its own. "Open the list", "click Add",
+* "type a title" do not: nothing follows from them that a test could check,
+* and a hand-written test asserts nothing after them either. A markdown case
+* states its expectations for the flow, so none of its steps claim one.
 *
-* The comment belongs to the run of assertions it explains, not to each one,
-* so two consecutive checks under one note are one explanation. Both rules
-* that use this are the same rule underneath: an unusual choice is allowed,
-* and has to be said out loud — which is what a project's own guidelines ask
-* of the people writing these by hand.
+* One predicate, two readers — the review below and the evidence table, which
+* reach the same verdict from the same file and must not be able to disagree
+* about which steps were supposed to decide something.
 */
-function explained(all, i) {
-	let above = i - 1;
-	while (above >= 0 && /\bexpect\(|^\s*$|^\s*\)/.test(all[above] ?? "")) above -= 1;
-	return /^\s*\/\//.test(all[above] ?? "");
+function claimsAnOutcome(step) {
+	return (step.expected ?? "").trim().length > 0;
 }
 /**
-* `.first()` written on an assertion narrows a locator that matched several
-* things, so the assertion holds for whichever came first. Sometimes that is
-* the point — "the newest row is at the top" — and then it is written down.
+* What a step that states an outcome, and carries no assertion under it, is
+* told. Shared with the evidence table, which reaches the same verdict from
+* the same file — a reader must not meet two wordings for one fact.
 *
-* Only where the assertion itself narrows. Following it into the definitions
-* fired throughout the hand-written corpus: a page object that resolves a
-* repeated element once, for every caller, is how that is normally written.
+* It reports what was seen, not what was concluded. An assertion a rewrite
+* moved into a page object is invisible here, and calling that "decides
+* nothing" would be ccqa claiming more than it looked at.
 */
-function unjustifiedFirst(file, source) {
-	const all = lines(source);
-	return all.flatMap((text, i) => {
-		if (!/\bexpect\(/.test(text) || !/\.first\(\)/.test(text)) return [];
-		if (explained(all, i)) return [];
-		return [{
-			file,
-			line: i + 1,
-			rule: "unjustified-first",
-			message: "`.first()` in an assertion holds for whichever element came first. Say why that is the one, or address the element itself"
-		}];
-	});
-}
-/** A describe that repeats its only test reads as "X › X" in every report. */
-function describeEcho(file, source) {
-	const describe = /test\.describe\(\s*["'](.+?)["']/.exec(source);
-	if (!describe) return [];
-	const titles = [...source.matchAll(/\n\s*test\(\s*["'](.+?)["']/g)].map((m) => m[1]);
-	if (titles.length !== 1) return [];
-	const bare = (s) => s.replace(/\s+@[\w-]+\s*$/, "").trim();
-	if (bare(titles[0]) !== bare(describe[1])) return [];
-	const line = lines(source).findIndex((t) => t.includes("test.describe(")) + 1;
-	return [{
-		file,
-		line: Math.max(line, 1),
-		rule: "describe-echo",
-		message: "the describe repeats its only test's name. Drop it, or name the screen the test is about"
-	}];
-}
-/** `name` → the expression it is defined as, across every file written. */
-function collectLocators(files) {
-	const out = /* @__PURE__ */ new Map();
-	for (const source of files.values()) {
-		for (const m of source.matchAll(/\breadonly\s+([a-zA-Z0-9_]+)\s*=\s*([^;]+);/g)) out.set(m[1], m[2]);
-		for (const m of source.matchAll(/\b([a-zA-Z0-9_]+)\([^)]*\)\s*:\s*Locator\s*\{\s*return\s+([^;]+);/g)) out.set(m[1], m[2]);
-	}
-	return out;
-}
+const NOTHING_DECIDED = "no assertion is visible under this step in the generated test — one moved into a helper does not show here, and does not show to a reviewer reading the file either";
 /**
-* The forms that carry a string a person sees on screen. A whitelist, not a
-* blacklist: a test id, an ARIA role name and a CSS selector are all strings
-* too, and none of them is something a test case would ever mention — counted
-* as "what this assertion looks for", every `getByTestId` in a project that
-* prefers them would read as an assertion nobody asked for.
+* The warning a finding becomes, phrased so the reader knows the test is green
+* for nothing. A step deciding nothing is its own explanation, so only the
+* model's own words are worth appending.
 */
-const VISIBLE_STRING = /(?:getByText|getByLabel|getByPlaceholder|getByTitle|getByAltText|toHaveText|toContainText|toHaveValue)\(\s*["'`]([^"'`]+)|name:\s*["'`]([^"'`]+)/g;
+function formatFinding(finding, labels = evidenceLabels()) {
+	const nothing = finding.problem === NOTHING_DECIDED;
+	const claim = nothing ? labels.findingNothing : labels.findingUndecided;
+	return `${finding.stepId}: ${claim}${nothing ? "" : ` — ${finding.problem}`}`;
+}
 /**
-* The strings an assertion actually looks for: the ones on its own line plus
-* the ones in whatever page-object members it names.
+* The warning a rule violation becomes: the file, the rule in the words it was
+* judged by, and where that came from. An advisory one says so — a reader must
+* be able to tell a line that was worth a fix round from one that was not. The
+* offending code is left out: it is what the fix pass needs, not what a reader
+* scanning a log does.
 */
-function expandLocators(text, locators) {
-	let expanded = text;
-	for (const m of text.matchAll(/\.([a-zA-Z0-9_]+)\b/g)) {
-		const definition = locators.get(m[1]);
-		if (definition) expanded += `\n${definition}`;
-	}
-	return expanded;
-}
-function assertedStrings(text, locators) {
-	return [...expandLocators(text, locators).matchAll(VISIBLE_STRING)].map((m) => (m[1] ?? m[2] ?? "").trim()).filter((s) => s.length > 1 && !s.includes("${"));
+function formatViolation(violation) {
+	const advisory = violation.severity === "advisory" ? ", advisory" : "";
+	return `${violation.file}: ${violation.rule} (${violation.guide}${advisory})`;
 }
 /**
-* An assertion about something the case never mentions.
+* Hand the written files to a reviewer who knows nothing about where they came
+* from, and ask what it would say on the pull request: whether each step is
+* decided (see `verifiesSpecPrompt`), and — where the project wrote rule
+* documents of its own — whether the code follows them and the suite it joins.
 *
-* The case is the contract. Anything else seen along the way adds no
-* coverage, differs between recordings, and is the first thing to break —
-* and a reviewer reading the case cannot tell why the test checks it.
+* It reads the files off disk with read-only tools rather than being shown
+* them, which is also what lets it read the rest of the repository: "follow
+* the existing implementation" cannot be checked against an inline copy of two
+* files, because the evidence for it is how many other files do it that way.
 *
-* Only fires when the assertion looks for a string at all: a URL pattern or
-* a value the test itself computed has nothing to compare against, and
-* silence is the honest answer there. And not when a reason sits above it —
-* checking that a precondition still holds, so the test fails where the
-* precondition broke rather than four steps later, is worth doing and is
-* written down when it is.
+* Every invocation is a fresh session. The reviewer must not remember arguing
+* for a finding the previous round declined to act on, and what has already
+* been asked for is the loop's business, not the reviewer's.
+*
+* A review that could not be obtained answers `findings: null` and is logged —
+* it must not read as a pass, and it must also not fail the generate that
+* produced working files.
 */
-function unaskedAssertions(file, source, locators, said) {
-	const all = lines(source);
-	return all.flatMap((text, i) => {
-		if (!/\bexpect\(/.test(text)) return [];
-		const strings = assertedStrings(text, locators);
-		if (strings.length === 0 || strings.some((s) => said.includes(s))) return [];
-		if (explained(all, i)) return [];
-		return [{
-			file,
-			line: i + 1,
-			rule: "unasked-assertion",
-			message: `nothing in the case asks about ${strings.map((s) => `"${s}"`).join(", ")}. Assert what the case states, and drop the rest`
-		}];
-	});
+async function reviewGeneratedTest(input) {
+	const tests = input.files.filter((f) => f.kind === "test");
+	const source = tests.map((f) => f.contents).join("\n\n");
+	if (source.trim().length === 0) {
+		warn("could not check whether the generated test decides its spec (no test file to read)");
+		return {
+			findings: null,
+			complete: false,
+			warnings: []
+		};
+	}
+	const checked = assertionsByStep(source);
+	const undecided = [...input.steps, ...input.cleanup ?? []].filter(isExpandedActionStep).filter(claimsAnOutcome).filter((step) => (checked.get(step.id) ?? []).length === 0).map((step) => ({
+		stepId: step.id,
+		problem: NOTHING_DECIDED
+	}));
+	if (input.askModel === false) return {
+		findings: undecided,
+		complete: false,
+		warnings: undecided.map((f) => formatFinding(f))
+	};
+	const invoke = input.invoke ?? invokeClaudeStreaming;
+	const guides = input.guides ?? [];
+	const { result: answer, isError } = await invoke({
+		prompt: verifiesSpecPrompt({
+			steps: input.steps,
+			testPath: tests[0].path,
+			submitted: input.files.filter((f) => f.kind !== "test").map((f) => f.path),
+			language: input.language,
+			...input.expectations && input.expectations.length > 0 ? { expectations: [...input.expectations] } : {},
+			...input.cleanup && input.cleanup.length > 0 ? { cleanup: [...input.cleanup] } : {},
+			...input.leansOn && input.leansOn.length > 0 ? { leansOn: input.leansOn } : {},
+			guides
+		}),
+		allowedTools: REVIEW_TOOLS,
+		maxTurns: MAX_REVIEW_TURNS,
+		timeoutMs: REVIEW_TIMEOUT_MS,
+		silenceBashLog: true,
+		...input.model ? { model: input.model } : {},
+		cwd: input.cwd
+	}, () => {});
+	const fromModel = isError ? null : parseVerifiesSpecFindings(answer);
+	if (fromModel === null) warn(`could not check whether the generated test decides its spec (${isError ? "Claude returned an error" : "no usable answer"})`);
+	const violations = guides.length === 0 || isError ? null : parseGuideViolations(answer);
+	if (guides.length > 0 && !isError && violations === null) warn("could not check the generated code against the project's conventions (no usable answer)");
+	const findings = mergeFindings(undecided, fromModel ?? []);
+	return {
+		findings,
+		complete: fromModel !== null,
+		...isError ? { reviewerFailed: true } : {},
+		warnings: [...findings.map((finding) => formatFinding(finding)), ...(violations ?? []).map(formatViolation)],
+		...violations ? { ruleViolations: violations } : {}
+	};
 }
-/** The findings as the fix loop's other inputs look: a command and its output. */
-function formatEmittedReview(findings) {
-	return findings.map((f) => `${f.file}:${f.line} [${f.rule}] ${f.message}`).join("\n");
+/**
+* The mechanical finding wins its step: it is a fact, not a reading. Shared
+* with the evidence table, which merges the same two sources — one of them
+* recomputed from the file as it is now — and must show each step once.
+*/
+function mergeFindings(undecided, fromModel) {
+	const claimed = new Set(undecided.map((f) => f.stepId));
+	return [...undecided, ...fromModel.filter((f) => !claimed.has(f.stepId))];
 }
 //#endregion
 //#region src/runtime/evidence-constants.ts
@@ -9116,14 +9430,16 @@ function formatEmittedReview(findings) {
 * Shared constants + helpers for step-boundary evidence: the env var that
 * enables capture, the file-name sanitizer, and the reserved failure ids.
 *
-* Three producers write the `<id>.png` + `<id>.json` pairs — `abStepEvidence()`
-* / `captureFailureEvidence()` in `test-helpers.ts` (agent-browser replays) and
-* `ccqaStepBefore`/`ccqaStepAfter` in `step-evidence.ts` (external targets) —
-* and one consumer reads them back (`loadEvidenceForSpec` in
-* `report/evidence.ts`). All four agree only on the contract here, so it is
-* kept under `runtime/` (free of CLI-side imports) so the generated-test
-* modules — imported via `ccqa/test-helpers` and `ccqa/step-evidence` — can
-* share it without dragging the CLI in.
+* Several producers write the `<id>.png` + `<id>.json` pairs —
+* `abStepEvidence()` / `captureFailureEvidence()` in `test-helpers.ts`
+* (agent-browser replays), `targets/playwright/trace-capture.ts` (frames read
+* out of a run's Playwright trace), and `ccqaStepBefore`/`ccqaStepAfter` in
+* `step-evidence.ts` for tests generated before the capture calls left the
+* committed file — and one consumer reads them back (`loadEvidenceForSpec` in
+* `report/evidence.ts`). They agree only on the contract here, so it is kept
+* under `runtime/` (free of CLI-side imports) so the generated-test modules —
+* imported via `ccqa/test-helpers` and `ccqa/step-evidence` — can share it
+* without dragging the CLI in.
 */
 /**
 * Env var naming the directory a spec's step evidence is written to. `ccqa
@@ -9132,6 +9448,15 @@ function formatEmittedReview(findings) {
 * scattering screenshots.
 */
 const EVIDENCE_DIR_ENV = "CCQA_EVIDENCE_DIR";
+/**
+* Make a step id safe to use as an evidence file-name stem. Both evidence
+* producers (agent-browser `abStepEvidence`, external `ccqa/step-evidence`)
+* name their PNG/JSON pair `<stem>.png` / `<stem>.json`, so they must agree on
+* this exact mapping.
+*/
+function sanitizeStepId(stepId) {
+	return stepId.replace(/[^A-Za-z0-9_.-]/g, "_");
+}
 //#endregion
 //#region src/drift/affected.ts
 const execFileP = promisify(execFile);
@@ -9404,37 +9729,51 @@ async function resolveResources(cwd, refs) {
 const CONVENTIONS_MAX_BYTES = 64 * 1024;
 /**
 * Expand and read the conventions guides + examples, in declared order, into
-* prompt sections. Files are kept whole while they fit the byte budget; a
-* file that does not fit is dropped with a warning naming it (never a silent
-* truncation). Only when the very first file alone exceeds the budget is it
-* truncated instead — an empty conventions injection would be worse.
-*/
-async function loadConventions(cwd, patterns, maxBytes = CONVENTIONS_MAX_BYTES) {
-	const files = [];
-	for (const pattern of patterns) {
-		const matched = await expandPatternToFiles(cwd, pattern).catch((e) => {
-			throw new Error(`conventions entry ${e.message}`);
-		});
-		for (const f of matched) if (!files.includes(f)) files.push(f);
-	}
+* prompt sections, each saying which of the two it came from. Files are kept
+* whole while they fit the byte budget; a file that does not fit is dropped
+* with a warning naming it (never a silent truncation). Only when the very
+* first file alone exceeds the budget is it truncated instead — an empty
+* conventions injection would be worse.
+*/
+async function loadConventions(cwd, conventions, maxBytes = CONVENTIONS_MAX_BYTES) {
+	const expand = async (patterns) => {
+		const out = [];
+		for (const pattern of patterns) {
+			const matched = await expandPatternToFiles(cwd, pattern).catch((e) => {
+				throw new Error(`conventions entry ${e.message}`);
+			});
+			for (const f of matched) if (!out.includes(f)) out.push(f);
+		}
+		return out;
+	};
+	const files = (await expand(conventions.guides)).map((path) => ({
+		path,
+		kind: "guide"
+	}));
+	for (const path of await expand(conventions.examples ?? [])) if (!files.some((f) => f.path === path)) files.push({
+		path,
+		kind: "example"
+	});
 	const sections = [];
 	const warnings = [];
 	const dropped = [];
 	let used = 0;
-	for (const file of files) {
+	for (const { path: file, kind } of files) {
 		const body = await readFile(resolve(cwd, file), "utf8");
 		const size = Buffer.byteLength(body, "utf8");
 		if (used + size <= maxBytes) {
 			sections.push({
 				path: file,
-				body
+				body,
+				kind
 			});
 			used += size;
 		} else if (sections.length === 0) {
 			const truncated = Buffer.from(body, "utf8").subarray(0, maxBytes).toString("utf8");
 			sections.push({
 				path: file,
-				body: truncated
+				body: truncated,
+				kind
 			});
 			used = maxBytes;
 			warnings.push(`conventions file ${file} exceeds the ${maxBytes}-byte prompt budget alone — injected truncated`);
@@ -13465,11 +13804,12 @@ function emptySpecRow(args) {
 * Step-boundary screenshot evidence: where it lives on disk and how a
 * directory of `<id>.png` + `<id>.json` pairs becomes report rows.
 *
-* Producer-agnostic on purpose. Two very different writers fill these
-* directories — `abStepEvidence()` for agent-browser replays and
-* `ccqa/step-evidence` for external targets' generated tests — and both only
-* have to agree on the file-pair convention documented here, not on how the
-* screenshot was taken.
+* Producer-agnostic on purpose. Very different writers fill these directories
+* — `abStepEvidence()` during an agent-browser replay, and, for a Playwright
+* target, frames read back out of the run's trace once the command has exited
+* — and they only have to agree on the file-pair convention documented here,
+* not on how or when the screenshot was taken. `pngFile` names the image
+* whatever its format: a trace's screencast frames are JPEG.
 */
 /** `<reportDir>/evidence/<feature>/<spec>` — one directory per spec. */
 function specEvidenceDir(reportDir, feature, spec) {
@@ -13555,6 +13895,296 @@ function toPosix(p) {
 	return p.split(/[\\/]/).join("/");
 }
 //#endregion
+//#region src/targets/playwright/trace-evidence.ts
+const EOCD_SIGNATURE = 101010256;
+const EOCD_SEARCH_WINDOW = 65557;
+/** A zip archive's directory, read up front. Stored (method 0) and deflate (method 8) only. */
+async function readZip(path) {
+	const buf = await readFile(path);
+	const eocd = findEndOfCentralDirectory(buf, path);
+	const entryCount = buf.readUInt16LE(eocd + 10);
+	const centralDirectoryOffset = buf.readUInt32LE(eocd + 16);
+	if (entryCount === 65535 || centralDirectoryOffset === 4294967295) throw new Error(`${path} uses zip64, which this reader does not support`);
+	const entries = readCentralDirectory(buf, centralDirectoryOffset, entryCount);
+	return {
+		names: [...entries.keys()],
+		read(name) {
+			const entry = entries.get(name);
+			if (entry === void 0) return void 0;
+			return readLocalEntryData(buf, entry.offset, entry.method, entry.compressedSize) ?? void 0;
+		}
+	};
+}
+function findEndOfCentralDirectory(buf, path) {
+	const searchStart = Math.max(0, buf.length - EOCD_SEARCH_WINDOW);
+	for (let i = buf.length - 22; i >= searchStart; i--) if (buf.readUInt32LE(i) === EOCD_SIGNATURE) return i;
+	throw new Error(`${path}: not a zip archive (no end-of-central-directory record found)`);
+}
+function readCentralDirectory(buf, offset, entryCount) {
+	const entries = /* @__PURE__ */ new Map();
+	let pos = offset;
+	for (let i = 0; i < entryCount; i++) {
+		const method = buf.readUInt16LE(pos + 10);
+		const compressedSize = buf.readUInt32LE(pos + 20);
+		const nameLength = buf.readUInt16LE(pos + 28);
+		const extraLength = buf.readUInt16LE(pos + 30);
+		const commentLength = buf.readUInt16LE(pos + 32);
+		const localHeaderOffset = buf.readUInt32LE(pos + 42);
+		const name = buf.toString("utf8", pos + 46, pos + 46 + nameLength);
+		entries.set(name, {
+			offset: localHeaderOffset,
+			method,
+			compressedSize
+		});
+		pos += 46 + nameLength + extraLength + commentLength;
+	}
+	return entries;
+}
+function readLocalEntryData(buf, offset, method, compressedSize) {
+	const nameLength = buf.readUInt16LE(offset + 26);
+	const extraLength = buf.readUInt16LE(offset + 28);
+	const dataStart = offset + 30 + nameLength + extraLength;
+	const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+	if (method === 0) return Buffer.from(compressed);
+	if (method === 8) return inflateRawSync(compressed);
+	return null;
+}
+/**
+* The screencast frames and the `test.step` calls one trace file holds.
+*
+* A trace is JSON Lines, one event object per line; a corrupt or truncated
+* line must not sink the whole read, so parsing is best-effort per line.
+* Step events come in two shapes across Playwright versions — a `before`/
+* `after` pair sharing a `callId`, or a single merged `action` event — and
+* both are folded into the same `TraceStep` shape here so callers never see
+* the version skew.
+*/
+function parseTraceEvents(jsonl) {
+	const frames = [];
+	const steps = [];
+	const pendingByCallId = /* @__PURE__ */ new Map();
+	let maxTimestamp = -Infinity;
+	for (const line of jsonl.split("\n")) {
+		if (line.trim() === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (typeof parsed !== "object" || parsed === null) continue;
+		const event = parsed;
+		for (const field of [
+			"timestamp",
+			"startTime",
+			"endTime"
+		]) {
+			const value = event[field];
+			if (typeof value === "number") maxTimestamp = Math.max(maxTimestamp, value);
+		}
+		const type = event.type;
+		if (type === "screencast-frame") {
+			if (typeof event.sha1 === "string" && typeof event.timestamp === "number") frames.push({
+				sha1: event.sha1,
+				timestamp: event.timestamp
+			});
+		} else if (type === "action") {
+			if (typeof event.callId === "string" && typeof event.startTime === "number" && typeof event.endTime === "number") steps.push({
+				title: titleOf(event),
+				startTime: event.startTime,
+				endTime: event.endTime,
+				...errorOf(event)
+			});
+		} else if (type === "before") {
+			if (typeof event.callId === "string" && typeof event.startTime === "number") pendingByCallId.set(event.callId, {
+				title: titleOf(event),
+				startTime: event.startTime
+			});
+		} else if (type === "after") {
+			if (typeof event.callId === "string" && typeof event.endTime === "number") {
+				const pending = pendingByCallId.get(event.callId);
+				if (pending !== void 0) {
+					pendingByCallId.delete(event.callId);
+					steps.push({
+						...pending,
+						endTime: event.endTime,
+						...errorOf(event)
+					});
+				}
+			}
+		}
+	}
+	for (const pending of pendingByCallId.values()) steps.push({
+		...pending,
+		endTime: maxTimestamp
+	});
+	frames.sort((a, b) => a.timestamp - b.timestamp);
+	steps.sort((a, b) => a.startTime - b.startTime);
+	return {
+		frames,
+		steps
+	};
+}
+/** The step's failure message, in whichever shape the trace recorded it. */
+function errorOf(event) {
+	const error = event.error;
+	if (typeof error === "string") return { error };
+	if (typeof error === "object" && error !== null) {
+		const message = error.message;
+		if (typeof message === "string") return { error: message };
+	}
+	return {};
+}
+function titleOf(event) {
+	if (typeof event.apiName === "string") return event.apiName;
+	if (typeof event.title === "string") return event.title;
+	return "";
+}
+/**
+* The frame on screen at `time`: the last one captured at or before it, or —
+* when the step began before any frame was captured — the first frame after.
+* Null when the trace holds no frames at all. `frames` comes from
+* {@link parseTraceEvents}, which sorts them by timestamp.
+*/
+function frameAt(frames, time) {
+	return frames.findLast((f) => f.timestamp <= time) ?? frames[0] ?? null;
+}
+//#endregion
+//#region src/targets/playwright/trace-capture.ts
+/**
+* Per-step screenshots for a Playwright test that contains nothing of ccqa's.
+*
+* The test a project commits is plain `@playwright/test`: its steps are
+* `test.step` blocks and there is no capture call to place a screenshot at
+* either boundary. So the screenshots are not taken during the run at all —
+* ccqa asks Playwright for a trace on the invocations it owns, and afterwards
+* reads the step boundaries and the screencast out of the archive. Nothing in
+* the consumer's repository changes, and nothing ccqa does here can turn a
+* passing test red: the whole path runs after the command has exited, and a
+* trace it cannot read costs the report its pictures and says so.
+*
+* The frames are the trace's own screencast, which Playwright records
+* downscaled — they are the filmstrip a reviewer already sees in the trace
+* viewer, not `page.screenshot()` output. That is the price of taking the
+* capture code out of the committed file.
+*/
+/** Shell characters that would hand an appended flag to a different program. */
+const SHELL_OPERATORS = /[|;&<>`$]/;
+/**
+* The command has to reach `playwright test` itself for an appended flag to
+* mean anything. A package script that wraps it is one indirection too many —
+* the flag may be swallowed by the script runner, and a mangled command is a
+* worse outcome than no screenshots.
+*/
+const PLAYWRIGHT_TEST = /(^|\s)playwright\s+test(\s|$)/;
+/**
+* The runCommand as ccqa must run it to get a trace back.
+*
+* Two shapes are refused rather than mangled: a command that reaches a second
+* program (the flag would land on the wrong one) and a command that already
+* directs its output somewhere ccqa does not read (the trace would be written
+* where nothing looks for it). A command that already asks for a trace keeps
+* its own setting — the project chose it, and `on` is what ccqa needs anyway
+* only when nothing else has spoken.
+*
+* A refusal answers `skip` with the reason and the command unchanged, so a
+* caller runs what the project configured either way and has one place to read
+* why the run will leave no trace.
+*/
+function amendForTrace(command, outputDir) {
+	if (!PLAYWRIGHT_TEST.test(command)) return {
+		command,
+		skip: "ccqa reads a spec's step screenshots out of the run's Playwright trace, and can only ask for one when the target's runCommand invokes `playwright test` itself (e.g. `pnpm exec playwright test {files}`)"
+	};
+	if (SHELL_OPERATORS.test(command)) return {
+		command,
+		skip: "the target's runCommand uses shell operators, so ccqa cannot safely append the `--trace`/`--output` flags its step screenshots are read from"
+	};
+	const directsOutput = /(^|\s)--output[=\s]/.test(command);
+	if (directsOutput && !command.includes(outputDir)) return {
+		command,
+		skip: "the target's runCommand passes its own --output, so ccqa cannot find the trace its step screenshots are read from — point that flag at `{artifactsDir}` or drop it"
+	};
+	const flags = [/(^|\s)--trace[=\s]/.test(command) ? "" : "--trace=on", directsOutput ? "" : `--output=${quoteForShell(outputDir)}`].filter(Boolean);
+	return { command: flags.length > 0 ? `${command} ${flags.join(" ")}` : command };
+}
+/**
+* Make sure `evidenceDir` holds the spec's per-step screenshots, reading the
+* trace the run left in `artifactsDir` when nothing else wrote them. Returns
+* null when the directory has evidence in it, and otherwise the reason there
+* is nothing to show.
+*
+* A spec generated before the capture calls left the committed file writes its
+* own frames as it runs; those are the test's own and are left alone.
+*
+* Every step of every trace found is written, not just the first archive's: a
+* retried test leaves one archive per attempt, and the later one overwrites
+* the earlier, which is the attempt the row reports.
+*/
+async function captureStepEvidence(args) {
+	if ((await readdir(args.evidenceDir).catch(() => [])).length > 0) return null;
+	const archives = (await walkFiles$1(args.artifactsDir)).filter(isTraceArchive).sort().map((rel) => join(args.artifactsDir, ...rel.split("/")));
+	if (archives.length === 0) return "the run left no Playwright trace, so there are no per-step screenshots to read — the generated test's `test.step` blocks are what ccqa reads them from";
+	let written = 0;
+	let frames = 0;
+	const failures = [];
+	for (const archive of archives) try {
+		const archived = await writeArchiveEvidence(archive, args.evidenceDir);
+		written += archived.written;
+		frames += archived.frames;
+	} catch (err) {
+		failures.push(`${archive}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (written > 0) return null;
+	if (failures.length > 0) return `ccqa could not read the run's Playwright trace (${failures[0]})`;
+	if (frames === 0) return "the run's Playwright trace holds no screenshots — the step frames come from its screencast, which Playwright records only while the trace's `screenshots` option is on (`--trace=on` asks for it; a `trace` option in the project's config can turn it off)";
+	return "the run's Playwright trace holds no step the case names — a rewrite pass may have reshaped the `test.step` titles the draft wrote; re-run `ccqa generate` for this spec";
+}
+/** One archive's steps, written as evidence, and the frames it had to write them from. */
+async function writeArchiveEvidence(archive, evidenceDir) {
+	const entries = await readZip(archive);
+	const { frames, steps } = parseTraceEvents(entries.names.filter((name) => name.endsWith(".trace")).map((name) => entries.read(name)?.toString("utf8") ?? "").join("\n"));
+	if (frames.length === 0) return {
+		written: 0,
+		frames: 0
+	};
+	await mkdir(evidenceDir, { recursive: true });
+	let written = 0;
+	for (const step of steps) {
+		const label = parseStepLabel(step.title);
+		if (label === null) continue;
+		const stem = sanitizeStepId(label.stepId);
+		const after = await writeFrame(entries, frames, step.endTime, evidenceDir, stem);
+		if (after === null) continue;
+		const before = await writeFrame(entries, frames, step.startTime, evidenceDir, `${stem}.before`);
+		await writeFile(join(evidenceDir, `${stem}.json`), `${JSON.stringify({
+			stepId: label.stepId,
+			source: label.source,
+			pngFile: after,
+			...before !== null ? { beforePngFile: before } : {},
+			...step.error !== void 0 ? { failureSummary: step.error } : {},
+			url: null,
+			title: null,
+			capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}, null, 2)}\n`, "utf8");
+		written += 1;
+	}
+	return {
+		written,
+		frames: frames.length
+	};
+}
+/** The frame on screen at `time`, written under `stem`. Null when there is none. */
+async function writeFrame(entries, frames, time, evidenceDir, stem) {
+	const frame = frameAt(frames, time);
+	if (frame === null) return null;
+	const data = entries.read(`resources/${frame.sha1}`) ?? entries.read(`resources/${frame.sha1}.jpeg`);
+	if (data === void 0) return null;
+	const file = `${stem}.jpeg`;
+	await writeFile(join(evidenceDir, file), data);
+	return file;
+}
+//#endregion
 //#region src/targets/run-command-runner.ts
 /**
 * Substitute `{files}` in a runCommand with the (shell-quoted) cwd-relative
@@ -13565,12 +14195,9 @@ function toPosix(p) {
 */
 function substituteRunCommandFiles(runCommand, testFiles) {
 	if (!runCommand.includes("{files}")) return runCommand;
-	const joined = testFiles.map(shellQuote$1).join(" ");
+	const joined = testFiles.map(quoteForShell).join(" ");
 	return runCommand.replaceAll("{files}", joined);
 }
-function shellQuote$1(s) {
-	return /^[A-Za-z0-9_./-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`;
-}
 /**
 * Shared `TestRunner` for external (runCommand) targets: for each spec it
 * derives the test's path from the target's `testPath` and executes the
@@ -13653,13 +14280,13 @@ async function runOneSpec(ref, opts, blocks) {
 		force: true
 	});
 	await mkdir(artifactsDir, { recursive: true });
-	const evidenceDir = opts.stepEvidence.supported ? specEvidenceDir(opts.reportDir, featureName, specName) : null;
-	if (evidenceDir) {
-		await rm(evidenceDir, {
+	const evidence = opts.stepEvidence.supported ? { dir: specEvidenceDir(opts.reportDir, featureName, specName) } : { reason: opts.stepEvidence.reason };
+	if ("dir" in evidence) {
+		await rm(evidence.dir, {
 			recursive: true,
 			force: true
 		});
-		await mkdir(evidenceDir, { recursive: true });
+		await mkdir(evidence.dir, { recursive: true });
 	}
 	const measurement = opts.coverage !== void 0 && opts.browserCoverage.browser === "cdp" ? {
 		collector: opts.coverage,
@@ -13676,9 +14303,15 @@ async function runOneSpec(ref, opts, blocks) {
 	const childEnv = {
 		[ARTIFACTS_DIR_ENV]: artifactsDir,
 		CCQA_RUN_ID: buildRunId(),
-		...evidenceDir ? { [EVIDENCE_DIR_ENV]: evidenceDir } : {}
+		..."dir" in evidence ? { [EVIDENCE_DIR_ENV]: evidence.dir } : {}
 	};
 	let command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
+	let traceUnavailable;
+	if ("dir" in evidence) {
+		const amended = amendForTrace(command, artifactsDir);
+		command = amended.command;
+		traceUnavailable = amended.skip;
+	}
 	let browserHandle;
 	let browserEngine;
 	let attachError;
@@ -13741,7 +14374,14 @@ async function runOneSpec(ref, opts, blocks) {
 		warn(`could not collect artifacts for ${featureName}/${specName}: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	const artifactFields = artifacts && artifacts.length > 0 ? { artifacts } : {};
-	const evidenceFields = await loadStepEvidence(opts, evidenceDir, parsedSpec, blocks);
+	const evidenceFields = await loadStepEvidence({
+		opts,
+		evidence,
+		artifactsDir,
+		spec: parsedSpec,
+		blocks,
+		...traceUnavailable !== void 0 ? { traceUnavailable } : {}
+	});
 	if (outcome.exitCode === 0) return {
 		...emptySpecRow({
 			feature: featureName,
@@ -13780,22 +14420,28 @@ function coverageRowFields(opts, measured, attachError) {
 }
 /**
 * The row's step screenshots, or — when there are none — the reason, so the
-* report never shows an empty evidence section without explanation. A
-* supported target that produced nothing almost always means the generated
-* test lost its capture calls (a library-rewrite pass dropping them is the
-* known hazard), which is worth saying out loud.
+* report never shows an empty evidence section without explanation.
+*
+* A command ccqa could not amend left no trace to read, and its reason is the
+* more useful one — so the capture is not attempted at all in that case.
 */
-async function loadStepEvidence(opts, evidenceDir, spec, blocks) {
-	if (!opts.stepEvidence.supported) return {
+async function loadStepEvidence(args) {
+	const { opts } = args;
+	if (!("dir" in args.evidence)) return {
 		evidence: null,
-		evidenceUnavailable: opts.stepEvidence.reason
+		evidenceUnavailable: args.evidence.reason
 	};
-	const descriptions = buildStepDescriptions(spec, blocks);
+	const evidenceDir = args.evidence.dir;
+	const reason = args.traceUnavailable ?? await captureStepEvidence({
+		artifactsDir: args.artifactsDir,
+		evidenceDir
+	});
+	const descriptions = buildStepDescriptions(args.spec, args.blocks);
 	const evidence = await loadEvidenceForSpec(evidenceDir, opts.reportDir, descriptions);
 	if (evidence) return { evidence };
 	return {
 		evidence: null,
-		evidenceUnavailable: "no step screenshots were captured — the generated test may be missing its ccqa/step-evidence calls; re-run `ccqa generate` for this spec"
+		evidenceUnavailable: reason ?? "no step screenshots were captured for this spec"
 	};
 }
 /**
@@ -14035,7 +14681,10 @@ function configuredWriteRoots(ctx, resources) {
 async function generateWithLlmEngine(req) {
 	const { ctx } = req;
 	const resources = await resolveResources(ctx.cwd, ctx.resources);
-	const conventions = await loadConventions(ctx.cwd, [...ctx.conventions.guides, ...ctx.conventions.examples]);
+	const conventions = await loadConventions(ctx.cwd, {
+		guides: ctx.conventions.guides,
+		examples: ctx.conventions.examples
+	});
 	const warnings = [...conventions.warnings];
 	for (const w of conventions.warnings) warn(w);
 	meta("resources", resources.length);
@@ -14081,6 +14730,8 @@ async function generateWithLlmEngine(req) {
 		initialFiles: output.files,
 		summary: output.summary,
 		warnings,
+		guides: conventions.sections.filter((s) => s.kind === "guide"),
+		...req.stepEvidence ? { stepEvidence: req.stepEvidence } : {},
 		validateFile: req.validateFile,
 		invoke,
 		reading: req.reading
@@ -14107,6 +14758,8 @@ async function finalizePreparedFiles(req) {
 		initialFiles: req.files,
 		summary: req.summary,
 		warnings: req.warnings,
+		guides: [],
+		...req.stepEvidence ? { stepEvidence: req.stepEvidence } : {},
 		validateFile: req.validateFile,
 		invoke: req.invoke ?? invokeClaudeStreaming,
 		reading: req.reading
@@ -14130,10 +14783,14 @@ async function finalizeAndVerify(p) {
 	};
 }
 /**
-* The runCommand verification loop: run, and on failure hand the output tail
-* plus the current files to Claude for a corrected set. `fix.mode` mirrors the
-* agent-browser target's fix UX (which only ever prompts inside its own fix
-* loop, never for the first write):
+* The runCommand verification loop. One round asks the project's own commands,
+* then the review, then the run — and a round is over when all three are
+* clean. On anything else the output goes to Claude for a corrected set and
+* the next round asks all three again: a fix written for a failing run can
+* break a rule the round before it cleared.
+*
+* `fix.mode` mirrors the agent-browser target's fix UX (which only ever
+* prompts inside its own fix loop, never for the first write):
 *
 *   - `auto` — apply every fix rewrite automatically, up to `fix.maxRetries`.
 *   - `interactive` (default) — show each fix pass's per-file diff and ask
@@ -14147,82 +14804,63 @@ async function finalizeAndVerify(p) {
 */
 async function runVerificationLoop(p, state) {
 	const runCommand = p.ctx.targetConfig.runCommand;
+	let review;
+	const finish = (passed) => {
+		for (const w of review?.warnings ?? []) warn(w);
+		return {
+			passed,
+			review
+		};
+	};
 	if (!runCommand) {
 		const checks = await runCheckCommands(p.ctx);
 		if (checks !== null) {
 			warn(`${checks.command} failed (exit ${checks.exitCode}) — generated files kept`);
 			return { passed: false };
 		}
-		const review = await readingOfEmitted(p, state);
-		for (const w of review?.warnings ?? []) warn(w);
-		return {
-			passed: true,
-			review
-		};
+		await refreshFromDisk(state);
+		review = await readingOfEmitted(p, state, true);
+		return finish(true);
 	}
 	const maxRetries = p.ctx.fix.mode === "non-interactive" ? 0 : p.ctx.fix.maxRetries;
-	const captures = p.ctx.targetConfig.hooks.stepEvidence;
+	const captures = p.stepEvidence?.supported === true;
 	const outputScrub = buildProseEnvScrubMap([], []);
 	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`);
-	let review;
+	const spent = /* @__PURE__ */ new Set();
+	const askReviewer = maxRetries > 0;
+	let reviewerGone = false;
+	if (!askReviewer && p.reading) info("no fix round could act on a review — the reviewer is not asked; the mechanical read still runs");
 	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-"));
-		const evidenceDir = captures ? caseRunDir(p.ctx.ref) : null;
-		if (evidenceDir) {
-			await clearCaseRun(p.ctx.ref);
-			await mkdir(evidenceDir, { recursive: true });
-		}
-		const command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
-		run(command);
-		let result;
-		try {
-			result = await timedPhase(`verification run #${attempt + 1}`, () => runShellCommand(command, p.ctx.cwd, {
-				...process.env,
-				[ARTIFACTS_DIR_ENV]: artifactsDir,
-				CCQA_RUN_ID: buildRunId(),
-				...evidenceDir ? { [EVIDENCE_DIR_ENV]: evidenceDir } : {}
-			}), "run");
-		} finally {
-			await rm(artifactsDir, {
-				recursive: true,
-				force: true
-			});
-		}
-		let failing = command;
-		if (result.exitCode === 0) {
-			const checks = await runCheckCommands(p.ctx);
-			if (checks !== null) {
-				result = checks;
-				failing = checks.command;
+		let failing = await runCheckCommands(p.ctx);
+		let asked = [];
+		if (failing === null) {
+			await refreshFromDisk(state);
+			const [reading, mechanical] = await Promise.all([readingOfEmitted(p, state, askReviewer && !reviewerGone), reviewOfEmitted(p.ctx, state, p.writeRoots)]);
+			review = reading;
+			if (review?.reviewerFailed) reviewerGone = true;
+			const unchecked = uncheckedSteps(review, spent);
+			const violations = guideViolations(review, spent);
+			const reads = allReadings(mechanical, unchecked, violations);
+			if (reads !== null && attempt < maxRetries) {
+				asked = [...unchecked?.asked ?? [], ...violations?.asked ?? []];
+				failing = reads;
 			} else {
-				review = await readingOfEmitted(p, state);
-				const reads = bothReadings(await reviewOfEmitted(p.ctx, state, p.writeRoots), uncheckedSteps(review));
-				if (reads === null || attempt >= maxRetries) {
-					for (const w of review?.warnings ?? []) warn(w);
-					if (reads !== null) warn("generated with review findings still open — the files are kept and the findings are recorded against the case, but nothing acted on them");
-					return {
-						passed: true,
-						review
-					};
-				}
-				result = reads;
-				failing = reads.command;
+				if (reads !== null) warn("generated with review findings still open — the files are kept and the findings are recorded against the case, but nothing acted on them");
+				const run = await verifyRun(p, state, runCommand, attempt, captures);
+				if (run.exitCode === 0) return finish(true);
+				failing = run;
 			}
 		}
 		if (attempt >= maxRetries) {
 			warn(`verification still failing after ${maxRetries} fix attempt(s) — generated files kept`);
 			await clearCaseRun(p.ctx.ref);
-			return {
-				passed: false,
-				review
-			};
+			return finish(false);
 		}
-		fix(`verification failed (exit ${result.exitCode}) — requesting a fix (${attempt + 1}/${maxRetries})`);
+		fix(`verification failed (exit ${failing.exitCode}) — requesting a fix (${attempt + 1}/${maxRetries})`);
 		const fixPrompt = buildLlmFixPrompt({
 			targetId: p.target,
-			command: failing,
-			outputTail: scrubEnvValues(tail(result.output), outputScrub),
+			command: failing.command,
+			outputTail: scrubEnvValues(tail(failing.output), outputScrub),
 			files: [...state.entries()].map(([path, f]) => ({
 				path,
 				contents: f.contents,
@@ -14247,6 +14885,7 @@ async function runVerificationLoop(p, state) {
 			warn(`fix attempt ${attempt + 1} produced no usable output (${err instanceof Error ? err.message : String(err)}) — keeping current files`);
 			continue;
 		}
+		for (const key of asked) spent.add(key);
 		if (output.files.length === 0) {
 			info(`fix pass reported no file changes — re-running verification (${output.summary || "no reason given"})`);
 			continue;
@@ -14254,20 +14893,64 @@ async function runVerificationLoop(p, state) {
 		if (p.ctx.fix.mode === "interactive" && !await confirmFixWrite(output.files, p.ctx.cwd)) {
 			info("fix not applied (declined) — keeping current files");
 			await clearCaseRun(p.ctx.ref);
-			return {
-				passed: false,
-				review
-			};
+			return finish(false);
 		}
 		await writeGeneratedFiles(p.ctx.cwd, output.files, state);
 		review = void 0;
 	}
 }
 /**
-* The project's own checks over the whole repository (type check, lint), run
-* after the spec's test passes. Answers null when they all pass — or when the
-* project configured none — and the failing one's output otherwise, in the
-* shape the fix loop already consumes.
+* One verification run of the files as they are now, in the shape the fix loop
+* consumes. The round's last question and its most expensive: it is asked only
+* of files the project's own commands and the review have already cleared.
+*/
+async function verifyRun(p, state, runCommand, attempt, captures) {
+	const testFiles = [...state.entries()].filter(([, f]) => f.kind === "test").map(([rel]) => rel);
+	const artifactsDir = await mkdtemp(join(tmpdir(), "ccqa-verify-artifacts-"));
+	const evidenceDir = captures ? caseRunDir(p.ctx.ref) : null;
+	if (evidenceDir) {
+		await clearCaseRun(p.ctx.ref);
+		await mkdir(evidenceDir, { recursive: true });
+	}
+	let command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
+	let traceUnavailable;
+	if (evidenceDir) {
+		const amended = amendForTrace(command, artifactsDir);
+		command = amended.command;
+		traceUnavailable = amended.skip;
+	}
+	run(command);
+	try {
+		const result = await timedPhase(`verification run #${attempt + 1}`, () => runShellCommand(command, p.ctx.cwd, {
+			...process.env,
+			[ARTIFACTS_DIR_ENV]: artifactsDir,
+			CCQA_RUN_ID: buildRunId(),
+			...evidenceDir ? { [EVIDENCE_DIR_ENV]: evidenceDir } : {}
+		}), "run");
+		if (evidenceDir && result.exitCode === 0) {
+			const unavailable = traceUnavailable ?? await captureStepEvidence({
+				artifactsDir,
+				evidenceDir
+			});
+			if (unavailable) warn(unavailable);
+		}
+		return {
+			...result,
+			command
+		};
+	} finally {
+		await rm(artifactsDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* The project's own checks over the whole repository (type check, lint), asked
+* first in a round: they cost nothing and code that does not compile has a
+* more urgent problem than how it reads. Answers null when they all pass — or
+* when the project configured none — and the failing one's output otherwise,
+* in the shape the fix loop already consumes.
 */
 async function runCheckCommands(ctx) {
 	for (const command of ctx.targetConfig.checkCommands) {
@@ -14307,14 +14990,39 @@ async function reviewOfEmitted(ctx, state, writeRoots) {
 		output: formatEmittedReview(findings)
 	};
 }
-/** What this attempt wrote, as the target's reading opens it. */
-async function readingOfEmitted(p, state) {
-	if (!p.reading) return void 0;
-	return p.reading([...state.entries()].map(([path, f]) => ({
+/**
+* What this attempt wrote, as the target's reading opens it.
+*
+* Timed like the loop's other phases: the reading opens the repository and
+* reads it, which is minutes, and a wedged one waits out its whole timeout
+* with nothing on the terminal to say what is happening.
+*/
+async function readingOfEmitted(p, state, askModel) {
+	const { reading } = p;
+	if (!reading) return void 0;
+	const files = [...state.entries()].map(([path, f]) => ({
 		path,
 		contents: f.contents,
 		kind: f.kind
-	})));
+	}));
+	return timedPhase("review of the generated files", () => reading(files, p.guides, askModel), "fix");
+}
+/**
+* Re-read what is on disk into the engine's copy of it.
+*
+* A check command may rewrite what it checks — a formatter is the ordinary
+* case — and from here the files are read three ways: the review opens the
+* disk, while the fix prompt and the mechanical read are given what the engine
+* holds. They must not be told different things about one file.
+*/
+async function refreshFromDisk(state) {
+	for (const [rel, f] of state) {
+		const contents = await readFile(f.abs, "utf8").catch(() => null);
+		if (contents !== null) state.set(rel, {
+			...f,
+			contents
+		});
+	}
 }
 /**
 * The reading's findings, shaped like a failed check so the fix loop carries
@@ -14334,17 +15042,23 @@ async function readingOfEmitted(p, state) {
 * (restoring what passed weakly) would hide a case the product does not meet.
 *
 * A review that could not be obtained is not acted on either: spending a round
-* answering a question nobody asked is worse than leaving it unanswered.
-*/
-function uncheckedSteps(review) {
-	if (!review?.complete || review.findings === null || review.findings.length === 0) return null;
+* answering a question nobody asked is worse than leaving it unanswered. Nor
+* is a finding a round has already asked for and got back unchanged: a step
+* the fix pass could not strengthen reports the same line every round, and
+* left alone it takes the whole budget and the run happens with none of it.
+*/
+function uncheckedSteps(review, alreadyAsked = /* @__PURE__ */ new Set()) {
+	if (!review?.complete || review.findings === null) return null;
+	const findings = review.findings.filter((f) => !alreadyAsked.has(findingKey(f)));
+	if (findings.length === 0) return null;
 	return {
 		exitCode: 1,
 		command: "ccqa: reading of the generated test",
+		asked: findings.map(findingKey),
 		output: [
 			"These steps pass without deciding what the case says they must:",
 			"",
-			...review.findings.map((f) => `- ${formatFinding(f)}`),
+			...findings.map((f) => `- ${formatFinding(f)}`),
 			"",
 			"Strengthen the assertions (and the locators they resolve through) so each",
 			"step fails when its expectation stops holding. Do not weaken or delete a",
@@ -14353,6 +15067,72 @@ function uncheckedSteps(review) {
 	};
 }
 /**
+* The rule violations the reading found, shaped like a failed check so the fix
+* loop carries them the same way — or null when there is nothing to act on.
+*
+* Every rule the loop could already decide is followed by the code it
+* produces: a type error fails the check command, a lint rule fails the lint,
+* a convention ccqa itself knows fails the review above. A rule that lives
+* only in the project's prose is followed by nothing, because until here
+* nothing in the loop had read it. Reused code is the older half of the same
+* gap — a helper this generation imported rather than wrote was written under
+* whatever rules existed then, and no rule added since has been applied to it.
+*
+* Like the reading it rides with, it spends a fix round and never decides the
+* verdict: it is a model's judgement, and a judgement that could fail a
+* generate would make generation only as repeatable as the model behind it.
+* And like the reading, a violation a round has already asked for and got back
+* unchanged is not asked again — the model may decline a file it is not
+* allowed to write, and asking again spends a round that can only be declined
+* again.
+*
+* Read apart from the step findings, as it comes back: one answer carries two
+* reviews, and a half that arrived unreadable must not discard the half that
+* arrived. Absent violations are absent either way — there is nothing here to
+* act on when that half never came.
+*
+* Only what the reviewer would hold the change for. It is asked to sort its
+* own violations, because the alternative is a round spent on a line it would
+* have approved anyway. Every violation is still reported: `warnings` carries
+* the advisory ones too, marked as such.
+*/
+function guideViolations(review, alreadyAsked = /* @__PURE__ */ new Set()) {
+	const violations = (review?.ruleViolations ?? []).filter((v) => v.severity === "blocking" && !alreadyAsked.has(violationKey(v)));
+	if (violations.length === 0) return null;
+	return {
+		exitCode: 1,
+		command: "ccqa: the project's own conventions",
+		asked: violations.map(violationKey),
+		output: [
+			"These files break a rule this project's conventions state:",
+			"",
+			...violations.flatMap((v) => [
+				`- ${formatViolation(v)}`,
+				...v.code.trim().split("\n").map((line) => `      ${line}`),
+				""
+			]),
+			"Rewrite each file so it follows the rule it breaks. A support file this",
+			"generation did not write is still yours to correct while it is under a",
+			"root you may write to; one outside them is not — say so in `summary`",
+			"rather than rewriting it. Never weaken what the test checks to make a",
+			"rule fit."
+		].join("\n")
+	};
+}
+/** One finding, as the loop recognises the same one coming back. */
+function findingKey(finding) {
+	return [finding.stepId, finding.problem].join("\0");
+}
+/** One violation, as the loop recognises the same one coming back. */
+function violationKey(violation) {
+	return [
+		violation.file,
+		violation.guide,
+		violation.rule,
+		violation.code.trim()
+	].join("\0");
+}
+/**
 * Every identifier the project's own test assets mention, outside the files
 * this generation just wrote.
 *
@@ -14399,10 +15179,10 @@ async function identifiersInProject(ctx, writeRoots, emitted) {
 	return found;
 }
 /**
-* The two readings of the finished files as one report, since one fix pass
-* answers both. Either may be absent; both absent is nothing to act on.
+* The readings of the finished files as one report, since one fix pass
+* answers all of them. Any may be absent; all absent is nothing to act on.
 */
-function bothReadings(...reports) {
+function allReadings(...reports) {
 	const found = reports.filter((r) => r !== null);
 	if (found.length === 0) return null;
 	return {
@@ -14586,48 +15366,9 @@ function creationActionIndex(actions, markers) {
 	while (end > submitted && OBSERVING_ACTIONS.has(actions[end].action)) end -= 1;
 	return end;
 }
-/** Module the emitted step-boundary capture calls import from. */
-const STEP_EVIDENCE_MODULE = "ccqa/step-evidence";
 /** Module the emitted judge calls import from, and the call they make. */
 const JUDGE_MODULE = "ccqa/judge";
 const JUDGE_CALL = "judgeByLlm";
-/** Capture call emitted when a step is entered / closed. Exported for the generation gate. */
-const STEP_EVIDENCE_BEFORE = "ccqaStepBefore";
-const STEP_EVIDENCE_AFTER = "ccqaStepAfter";
-/** The exact boundary call for one step, as emitted and as the gate greps for it. */
-function stepEvidenceCall(fn, marker) {
-	return injectedCall(fn, [j(marker.stepId), j(marker.source)]);
-}
-/**
-* A receiver expression: anything up to the argument's comma, allowing one
-* level of parentheses so `await ctx.newPage()` and `page.context().pages()[1]`
-* — how a rewrite names a tab a click opened — count as receivers.
-*/
-const RECEIVER = String.raw`(?:[^,()]|\([^()]*\))+`;
-/**
-* The call as emitted, plus the pattern that accepts it back on any page. The
-* receiver is the one part a rewrite is right to change: a click that opens a
-* new tab has to act on that tab. Everything else is required verbatim, the
-* `await` and `;` included — an unawaited capture races the end of the test,
-* and a mention in a comment is not a call.
-*/
-function injectedCall(name, args) {
-	const tail = args.map(escapeRegExp).join(String.raw`\s*,\s*`);
-	return {
-		code: `await ${name}(page, ${args.join(", ")});`,
-		pattern: new RegExp(String.raw`await\s+${name}\s*\(\s*${RECEIVER}\s*,\s*${tail}\s*,?\s*\)\s*;`)
-	};
-}
-/**
-* The "preserve the step-evidence calls" rule the library-rewrite prompt must
-* carry, built from the same symbol/module constants the emitter injects and
-* the coverage gate greps for — so prompt, emitter, and gate share one truth.
-* A target that captures no step evidence simply doesn't pass this to the
-* engine, and the prompt then omits the rule entirely.
-*/
-function stepEvidencePreserveRule() {
-	return `**Keep the \`${STEP_EVIDENCE_MODULE}\` calls.** The draft's \`await ${STEP_EVIDENCE_BEFORE}(page, ...)\` / \`await ${STEP_EVIDENCE_AFTER}(page, ...)\` lines are load-bearing: ccqa run reads the per-step screenshots they capture. Keep both calls for every step, in place around that step's actions, with their exact \`"<stepId>", "<source>"\` arguments — and keep the import. Pass a different page only when the step genuinely acts on one (a click that opens a new tab). If you move a step's actions into a page-object method, leave these two calls in the test body around the call to that method; do NOT move them inside the page object. Never wrap a step in a closure to hold them.`;
-}
 /**
 * Told to the rewrite because both are conventions the project greps: a
 * missing tag drops the test out of whatever selection runs it, and a missing
@@ -14645,7 +15386,7 @@ function headerPreserveRule(header, titleSuffix) {
 * rejection, which costs a whole round.
 */
 function stepCommentPreserveRule() {
-	return "**Keep each step's opening comment exactly as the draft wrote it.** Those lines are how the evidence table and the review of this test say which assertions belong to which step. A reshaped one parses as no step at all, and every step then reads as deciding nothing. Keep the wording, the numbering and the punctuation; add your own comments on their own lines.";
+	return "**Keep every `test.step(...)` block, with its title exactly as the draft wrote it.** Those titles are how the evidence table, the run's per-step screenshots and the review of this test say which assertions belong to which step. A reshaped one parses as no step at all, and every step then reads as deciding nothing. Keep the wording, the numbering and the punctuation, and keep each step's actions inside its own block — a step's call to a page-object method belongs in the block, not outside it. Do not merge, split or reorder the blocks. A test already at this path may have been written by an older ccqa in a different shape: the draft is what this file must look like, not that one.";
 }
 /**
 * Told to the rewrite, because the alternative failure is silent: a claim
@@ -14657,51 +15398,55 @@ function judgePreserveRule() {
 }
 function emitPlaywrightDraft(input) {
 	const { actions, testName, judgements = [], japanese = false } = input;
-	const captures = input.stepEvidence !== false;
 	const stepMarkers = input.stepMarkers ?? [];
 	const markerByIndex = new Map(stepMarkers.map((m) => [m.actionIndex, m]));
-	const lines = [];
+	const body = [];
 	let prevLine = null;
-	let openMarker = null;
+	let open = null;
+	const target = () => open ?? body;
+	const openStep = (marker) => {
+		if (!marker) return;
+		open = openBlock(body, marker, japanese);
+	};
 	const flushJudgements = (afterActionIndex) => {
 		for (const { step } of judgements.filter((j) => j.afterActionIndex === afterActionIndex)) {
-			if (openMarker) {
-				if (captures) lines.push(stepEvidenceCall(STEP_EVIDENCE_AFTER, openMarker).code);
-				openMarker = null;
-			}
-			if (lines.length > 0) lines.push("");
-			lines.push(renderStepComment({
+			openBlock(body, {
 				stepId: step.id,
 				source: step.source
-			}, japanese));
-			lines.push(judgeCall(step).code);
+			}, japanese).push(judgeCall(step).code);
+			open = null;
 		}
 	};
-	const createdAt = creationActionIndex(actions, stepMarkers);
-	let createdLine = lines.length;
+	const creationIndex = creationActionIndex(actions, stepMarkers);
+	let createdAt = {
+		block: body,
+		index: 0
+	};
 	flushJudgements(-1);
 	for (let i = 0; i < actions.length; i++) {
-		openMarker = openStep(lines, markerByIndex.get(i), openMarker, japanese, captures);
+		openStep(markerByIndex.get(i));
 		const action = actions[i];
 		if (overwrittenByNext(action, actions[i + 1])) continue;
 		const line = actionToLine(action, japanese);
 		if (line !== null && line !== prevLine) {
-			if (action.replayUnstable) lines.push(`// [warn] replay-unstable: ${action.replayReason ?? "(no reason recorded)"}`);
-			lines.push(line);
+			if (action.replayUnstable) target().push(`// [warn] replay-unstable: ${action.replayReason ?? "(no reason recorded)"}`);
+			target().push(...line.split("\n"));
 			prevLine = line;
 		}
-		if (i === createdAt) createdLine = lines.length;
+		if (i === creationIndex) createdAt = {
+			block: target(),
+			index: target().length
+		};
 		flushJudgements(i);
 	}
-	closeStep(lines, openMarker, captures);
-	const cleanupLines = emitCleanup(input.cleanup, captures, japanese, input.allowExpectInCleanup ?? true);
+	const cleanupBody = emitCleanup(input.cleanup, japanese, input.allowExpectInCleanup ?? true);
 	const title = `${testName}${input.titleSuffix ?? ""}`;
-	const runId = input.runId !== void 0 && [...lines, ...cleanupLines].some((line) => line.includes(RUN_ID_READ)) ? input.runId : void 0;
-	const guarded = runId !== void 0 && cleanupLines.length > 0;
-	if (guarded) lines.splice(createdLine, 0, `${CREATED_VAR} = true;`);
-	if (judgements.length > 0) lines.unshift("test.slow();", "");
-	const testLines = [...runId ? [`${RUN_ID_VAR} = ${runId.expression};`, ""] : [], ...lines];
-	const scoped = cleanupLines.length > 0 || runId !== void 0;
+	const runId = input.runId !== void 0 && [...codeLines(body), ...codeLines(cleanupBody)].some((line) => line.includes(RUN_ID_READ)) ? input.runId : void 0;
+	const guarded = runId !== void 0 && cleanupBody.length > 0;
+	if (guarded) createdAt.block.splice(createdAt.index, 0, `${CREATED_VAR} = true;`);
+	if (judgements.length > 0) body.unshift("test.slow();", "");
+	const testLines = [...runId ? [`${RUN_ID_VAR} = ${runId.expression};`, ""] : [], ...body];
+	const scoped = cleanupBody.length > 0 || runId !== void 0;
 	const testParams = judgements.length > 0 ? "{ page }, testInfo" : "{ page }";
 	const declaration = [
 		...scoped ? [
@@ -14710,13 +15455,13 @@ function emitPlaywrightDraft(input) {
 			""
 		] : [],
 		`test(${j(title)}, async (${testParams}) => {`,
-		indent(testLines, 2),
+		...renderBody(testLines, 2),
 		"});",
-		...cleanupLines.length > 0 ? [
+		...cleanupBody.length > 0 ? [
 			"",
 			`test.afterEach(${j(cleanupTitle(input.cleanup?.stepMarkers, japanese))}, async ({ page }) => {`,
 			...guarded ? [`  if (!${CREATED_VAR}) return;`] : [],
-			indent(cleanupLines, 2),
+			...renderBody(cleanupBody, 2),
 			"});"
 		] : []
 	];
@@ -14724,7 +15469,6 @@ function emitPlaywrightDraft(input) {
 		...input.header ? [input.header.trimEnd(), ""] : [],
 		`import { test, expect } from "@playwright/test";`,
 		...judgements.length > 0 ? [`import { ${JUDGE_CALL} } from ${j(JUDGE_MODULE)};`] : [],
-		...stepMarkers.length > 0 && captures ? [`import { ${STEP_EVIDENCE_BEFORE}, ${STEP_EVIDENCE_AFTER} } from ${j(STEP_EVIDENCE_MODULE)};`] : [],
 		...runId ? [runId.import] : [],
 		"",
 		...declaration,
@@ -14732,49 +15476,61 @@ function emitPlaywrightDraft(input) {
 	].join("\n");
 	return runId ? source.replaceAll(RUN_ID_READ, RUN_ID_VAR) : source;
 }
-function indent(lines, by) {
+/**
+* Open a step's block at the end of `body` and return the array its lines go
+* in. Shared by the two places that walk an action list against markers, so a
+* change to how a boundary is written cannot apply to the steps and miss the
+* cleanup.
+*/
+function openBlock(body, marker, japanese) {
+	if (body.length > 0) body.push("");
+	const block = {
+		title: renderStepLabel(marker, japanese),
+		body: []
+	};
+	body.push(block);
+	return block.body;
+}
+function renderBody(body, by) {
 	const pad = " ".repeat(by);
-	return lines.map((l) => l === "" ? "" : `${pad}${l}`).join("\n");
+	const out = [];
+	for (const node of body) {
+		if (typeof node === "string") {
+			out.push(node === "" ? "" : `${pad}${node}`);
+			continue;
+		}
+		out.push(`${pad}await test.step(${j(node.title)}, async () => {`);
+		out.push(...renderBody(node.body, by + 2));
+		out.push(`${pad}});`);
+	}
+	return out;
+}
+/** Every code line the body holds, step blocks included. */
+function codeLines(body) {
+	return body.flatMap((node) => typeof node === "string" ? [node] : codeLines(node.body));
 }
 /**
 * The recorded undo actions, with their step comments. Emitted from the
 * recording like everything else: what the cleanup does was demonstrated in
 * the browser, not guessed from the case's prose.
 */
-function emitCleanup(cleanup, captures, japanese, allowExpect) {
+function emitCleanup(cleanup, japanese, allowExpect) {
 	if (!cleanup || cleanup.actions.length === 0) return [];
-	const lines = [];
+	const body = [];
 	const markerByIndex = new Map((cleanup.stepMarkers ?? []).map((m) => [m.actionIndex, m]));
 	let open = null;
+	const target = () => open ?? body;
 	for (let i = 0; i < cleanup.actions.length; i++) {
-		open = openStep(lines, markerByIndex.get(i), open, japanese, captures);
+		const marker = markerByIndex.get(i);
+		if (marker) open = openBlock(body, marker, japanese);
 		const action = cleanup.actions[i];
 		if (!allowExpect && action.action === "assert") continue;
 		if (overwrittenByNext(action, cleanup.actions[i + 1])) continue;
-		if (action.replayUnstable) lines.push(`// [warn] replay-unstable: ${action.replayReason ?? "(no reason recorded)"}`);
+		if (action.replayUnstable) target().push(`// [warn] replay-unstable: ${action.replayReason ?? "(no reason recorded)"}`);
 		const line = actionToLine(action, japanese);
-		if (line !== null) lines.push(line);
+		if (line !== null) target().push(...line.split("\n"));
 	}
-	closeStep(lines, open, captures);
-	return lines;
-}
-/**
-* Enter the step a marker starts: close the one before it, comment the
-* boundary, and open the capture. Shared by the two places that walk an action
-* list against markers, so a change to how a boundary is written cannot apply
-* to the steps and miss the cleanup.
-*/
-function openStep(lines, marker, open, japanese, captures) {
-	if (!marker) return open;
-	if (open && captures) lines.push(stepEvidenceCall(STEP_EVIDENCE_AFTER, open).code);
-	if (lines.length > 0) lines.push("");
-	lines.push(renderStepComment(marker, japanese));
-	if (captures) lines.push(stepEvidenceCall(STEP_EVIDENCE_BEFORE, marker).code);
-	return marker;
-}
-/** Close the step still open at the end of an action list. */
-function closeStep(lines, open, captures) {
-	if (open && captures) lines.push(stepEvidenceCall(STEP_EVIDENCE_AFTER, open).code);
+	return body;
 }
 /**
 * Render a locator (plus positional pick) as a Playwright locator expression.
@@ -14925,7 +15681,7 @@ function assertToLine(action, locator, japanese) {
 			break;
 		case void 0: break;
 	}
-	if (comment && assertLine) return `${comment}\n  ${assertLine}`;
+	if (comment && assertLine) return `${comment}\n${assertLine}`;
 	return assertLine ?? comment;
 }
 /**
@@ -14964,12 +15720,25 @@ const jExpr = (s) => envRefsToJsExpression(s);
 * require it back. `testInfo` is always passed — the case's `test(...)`
 * callback is emitted with that second parameter whenever it has a judgement
 * — so the verdict lands on the report whether the claim held or not.
+*
+* The pattern accepts the call on any page: the receiver is the one part a
+* rewrite is right to change, because a click that opens a new tab has to be
+* judged on that tab. It allows one level of parentheses so `await
+* ctx.newPage()` and `page.context().pages()[1]` count as receivers.
+* Everything else is required verbatim, the `await` and `;` included — an
+* unawaited claim races the end of the test, and a mention in a comment is not
+* a call.
 */
 function judgeCall(step) {
 	const args = [bracedRefsToJsExpression(step.judgeByLlm.trim())];
 	const optionsFields = step.from !== void 0 ? [`from: ${jExpr(step.from)}`, "testInfo"] : ["testInfo"];
 	args.push(`{ ${optionsFields.join(", ")} }`);
-	return injectedCall(JUDGE_CALL, args);
+	const receiver = String.raw`(?:[^,()]|\([^()]*\))+`;
+	const tail = args.map(escapeRegExp).join(String.raw`\s*,\s*`);
+	return {
+		code: `await ${JUDGE_CALL}(page, ${args.join(", ")});`,
+		pattern: new RegExp(String.raw`await\s+${JUDGE_CALL}\s*\(\s*${receiver}\s*,\s*${tail}\s*,?\s*\)\s*;`)
+	};
 }
 //#endregion
 //#region src/targets/playwright/browser-server.ts
@@ -15128,6 +15897,28 @@ async function waitForCdp(port) {
 	}
 }
 //#endregion
+//#region src/targets/types.ts
+/**
+* Whether a run of this target's tests yields per-step screenshots: the target
+* has to be able to produce them, and the project has to want them — asking
+* Playwright for a trace on every run is what producing them costs.
+*
+* Both halves are ANDed here, once, wherever a plugin and its config first
+* meet. A runner then reads a capability instead of deciding one again, and
+* the "no" a report row shows is written in a single place.
+*/
+function resolveStepEvidence(plugin, config) {
+	const declared = plugin.stepEvidence ?? {
+		supported: false,
+		reason: `the "${plugin.id}" target does not capture step screenshots`
+	};
+	if (!declared.supported || config.hooks.stepEvidence) return declared;
+	return {
+		supported: false,
+		reason: `the "${plugin.id}" target has step evidence turned off in .ccqa/config.yaml`
+	};
+}
+//#endregion
 //#region src/targets/playwright/index.ts
 const PLAYWRIGHT_TARGET = "playwright";
 /**
@@ -15159,7 +15950,7 @@ const playwrightTarget = {
 async function generatePlaywrightTest(ctx) {
 	if (!ctx.recording) throw new Error(`the playwright target needs a recording — run \`ccqa record ${ctx.featureName}/${ctx.specName}\` first`);
 	if (ctx.targetConfig.testPath === void 0) warn(`no \`testPath\` configured for the playwright target — writing ${ctx.testPath}, the same path the agent-browser target uses for its vitest test. Set \`targets.playwright.testPath\` in .ccqa/config.yaml (e.g. \`e2e/specs/{feature}/{spec}.spec.ts\`) to keep them apart.`);
-	return compileRecording(ctx, PLAYWRIGHT_TARGET);
+	return compileRecording(ctx, PLAYWRIGHT_TARGET, resolveStepEvidence(playwrightTarget, ctx.targetConfig));
 }
 /**
 * IR → a `@playwright/test` file, for every target whose tests are Playwright's.
@@ -15170,12 +15961,15 @@ async function generatePlaywrightTest(ctx) {
 * the same gates over what the rewrite may drop. Sharing the pipeline is what
 * keeps those gates from applying to one target and not the other — the way a
 * second copy always eventually does.
+*
+* `stepEvidence` comes from the target that entered the pipeline, already
+* resolved against the project's config: the two targets differ in which
+* plugin answers, and only they know which one it is.
 */
-async function compileRecording(ctx, guidanceKind) {
+async function compileRecording(ctx, guidanceKind, stepEvidence) {
 	const actions = ctx.recording;
 	const expanded = ctx.steps;
 	const cleanup = ctx.cleanup.filter(isExpandedActionStep);
-	const captures = ctx.targetConfig.hooks.stepEvidence;
 	const stepMarkers = buildStepMarkers(expanded.filter(isExpandedActionStep), actions);
 	const cleanupMarkers = buildStepMarkers(cleanup, ctx.cleanupRecording ?? []);
 	const unattributed = expanded.filter(isExpandedActionStep).map((s) => s.id).filter((id) => !stepMarkers.some((m) => m.stepId === id));
@@ -15196,7 +15990,6 @@ async function compileRecording(ctx, guidanceKind) {
 			stepMarkers: cleanupMarkers
 		} } : {},
 		...ctx.targetConfig.runId ? { runId: ctx.targetConfig.runId } : {},
-		stepEvidence: captures,
 		allowExpectInCleanup: ctx.targetConfig.allowExpectInCleanup,
 		japanese: useJapanesePrompts(ctx.language)
 	});
@@ -15205,28 +15998,24 @@ async function compileRecording(ctx, guidanceKind) {
 	blank();
 	const invariants = [
 		stepMarkers.length > 0 || cleanupMarkers.length > 0 ? stepCommentPreserveRule() : "",
-		stepMarkers.length > 0 && captures ? stepEvidencePreserveRule() : "",
 		judgements.length > 0 ? judgePreserveRule() : "",
 		header || titleSuffix ? headerPreserveRule(header, titleSuffix) : ""
 	].filter(Boolean).join("\n\n");
 	const injected = {
 		markers: [...stepMarkers, ...cleanupMarkers],
-		stepEvidence: captures,
 		judgements,
 		header,
 		titleSuffix
 	};
 	const validateFile = (file) => {
-		if (file.kind !== "test") return null;
-		const gaps = injectedCallGaps(file.contents, injected);
+		const gaps = file.kind === "test" ? injectedCallGaps(file.contents, injected) : runtimeImportGaps(file.contents);
 		return gaps.length === 0 ? null : gaps.join("; ");
 	};
-	const reading = (files) => reviewGeneratedTest({
-		source: files.filter((f) => f.kind === "test").map((f) => f.contents).join("\n\n"),
-		support: files.filter((f) => f.kind === "support").map((f) => ({
-			path: f.path,
-			source: f.contents
-		})),
+	const reading = async (files, guides, askModel) => reviewGeneratedTest({
+		files,
+		askModel,
+		leansOn: await leanedOn(files, ctx.cwd, ctx.testPath),
+		guides,
 		steps: expanded,
 		...ctx.expectations.length > 0 ? { expectations: ctx.expectations } : {},
 		...ctx.cleanupExpectations.length > 0 && ctx.targetConfig.allowExpectInCleanup ? { cleanup } : {},
@@ -15244,6 +16033,7 @@ async function compileRecording(ctx, guidanceKind) {
 			contents: draft
 		},
 		...invariants ? { draftInvariant: invariants } : {},
+		stepEvidence,
 		validateFile,
 		reading
 	}) : await finalizePreparedFiles({
@@ -15256,6 +16046,7 @@ async function compileRecording(ctx, guidanceKind) {
 		}],
 		summary: `test compiled from ${actions.length} recorded action(s)`,
 		warnings: [],
+		stepEvidence,
 		validateFile,
 		reading
 	});
@@ -15313,6 +16104,21 @@ async function unusedSupportExports(result, written, cwd) {
 	return warnings;
 }
 /**
+* What the written test reaches by importing it, and this generation did not
+* write — the half nobody re-reads. A page object this case reuses was written
+* under whatever the project's rules were at the time, it is imported
+* verbatim, and the locators in it decide as much of this case as the ones in
+* the test file do. Followed from the imports, because that is how the code
+* itself finds them.
+*
+* Paths only: the review opens what it decides to open, so listing a file
+* costs nothing and there is no budget to spend.
+*/
+async function leanedOn(files, cwd, testPath) {
+	const written = new Set(files.map((f) => resolve(cwd, f.path)));
+	return (await collectSupportFiles(resolve(cwd, testPath), cwd)).filter((file) => !written.has(file.abs) && file.source !== "").map((file) => relative(cwd, file.abs));
+}
+/**
 * The injected calls and stamped conventions `corpus` no longer has.
 *
 * Asked twice, of the same source: once of the reply, before it is written,
@@ -15321,21 +16127,16 @@ async function unusedSupportExports(result, written, cwd) {
 * function, because a gate that answered differently in the two moments would
 * be worse than either alone.
 */
-function injectedCallGaps(corpus, { markers, stepEvidence, judgements, header, titleSuffix }) {
-	const warnings = [];
+function injectedCallGaps(corpus, { markers, judgements, header, titleSuffix }) {
+	const warnings = [...runtimeImportGaps(corpus)];
 	const stamped = {
 		header,
 		titleSuffix
 	};
-	const commented = assertionsByStep(corpus);
+	const titled = new Set(stepLines(corpus).map(parseStepBlock).filter((id) => id !== null));
 	for (const stepId of [...markers.map((m) => m.stepId), ...judgements.map((j) => j.step.id)]) {
-		if (commented.has(stepId)) continue;
-		warnings.push(`step ${stepId}: the generated test no longer opens that step with the comment the draft wrote. The evidence table and the spec review read it back to attribute assertions, so a reshaped one makes both report the step as deciding nothing. Keep the line unchanged.`);
-	}
-	if (stepEvidence) for (const m of markers) {
-		const hasBefore = stepEvidenceCall(STEP_EVIDENCE_BEFORE, m).pattern.test(corpus);
-		const hasAfter = stepEvidenceCall(STEP_EVIDENCE_AFTER, m).pattern.test(corpus);
-		if (!hasBefore || !hasAfter) warnings.push(`step ${m.stepId}: generated test is missing its ${STEP_EVIDENCE_BEFORE}/${STEP_EVIDENCE_AFTER} call(s) — that step will have no report screenshots. A rewrite pass must not drop them.`);
+		if (titled.has(stepId)) continue;
+		warnings.push(`step ${stepId}: the generated test no longer opens that step with the \`test.step\` title the draft wrote. The evidence table, the run's screenshots and the spec review read it back to attribute assertions, so a reshaped one makes all three report the step as deciding nothing. Keep the title unchanged.`);
 	}
 	const firstHeaderLine = stamped.header.split("\n")[0]?.trim() ?? "";
 	if (firstHeaderLine && !corpus.includes(firstHeaderLine)) warnings.push("the generated test no longer opens with the configured header — a rewrite pass dropped it, so the file does not say which case it came from");
@@ -15347,6 +16148,29 @@ function injectedCallGaps(corpus, { markers, stepEvidence, judgements, header, t
 	return warnings;
 }
 /**
+* Anything of ccqa's the written test loads.
+*
+* A committed spec is the project's, and their CI type-checks it in a checkout
+* where ccqa is not installed — so an import of it is not a style question but
+* a broken build. The one exception is the judge: a claim is decided at run
+* time by a model, so a case that states one genuinely depends on it.
+*
+* Mechanical because nothing else catches it. The rewrite pass reads the
+* repository, and where an earlier ccqa already wrote a spec at this path it
+* imitates that spec's shape — which type-checks, runs, and passes every other
+* gate here.
+*/
+function runtimeImportGaps(corpus) {
+	const loaded = /* @__PURE__ */ new Set();
+	for (const specifier of importedSpecifiers(corpus)) {
+		if (specifier !== "ccqa" && !specifier.startsWith("ccqa/")) continue;
+		if (specifier === "ccqa/judge") continue;
+		loaded.add(specifier);
+	}
+	if (loaded.size === 0) return [];
+	return [`the generated test imports ${[...loaded].sort().join(", ")} — a spec ccqa writes is plain @playwright/test and must not load ccqa at run time, because the project type-checks and runs it where ccqa is not installed. Remove the import and every call into it, and write each of the case's steps as \`await test.step("<the draft's title>", async () => { ... })\` around that step's own actions. \`${JUDGE_MODULE}\` is the only ccqa import a spec may carry, and only a case with a \`judgeByLlm\` claim carries it.`];
+}
+/**
 * Each claim paired with the action index it is asserted after: the last
 * action of the nearest preceding step. A claim reads what the run has
 * produced so far, so emitting it at the end of the test would judge a page
@@ -15464,16 +16288,13 @@ function validateRunnFile(file) {
 * the config accepts, and any other is refused when the config loads.
 */
 function createExternalTarget(id, config) {
-	return {
+	const plugin = {
 		id,
 		input: "recording",
-		generate: (ctx) => compileRecording(ctx, "playwright"),
+		generate: (ctx) => compileRecording(ctx, "playwright", resolveStepEvidence(plugin, ctx.targetConfig)),
 		defaultTestPath: config.testPath ?? "",
 		runner: runCommandRunner,
-		stepEvidence: config.hooks.stepEvidence ? { supported: true } : {
-			supported: false,
-			reason: `the "${id}" target has step evidence turned off in .ccqa/config.yaml`
-		},
+		stepEvidence: { supported: true },
 		judgeSteps: { supported: true },
 		browserCoverage: {
 			browser: "cdp",
@@ -15481,6 +16302,7 @@ function createExternalTarget(id, config) {
 		},
 		guidanceKind: "playwright"
 	};
+	return plugin;
 }
 //#endregion
 //#region src/targets/registry.ts
@@ -16992,11 +17814,11 @@ z.object({
 /** Body of `DELETE /projects/:project/locks?profile=`. */
 const ReleaseLocksRequestSchema = z.object({ holder: z.string().min(1) });
 /**
-* A person's word that they checked a spec's behaviour by hand against the
-* deployed environment. It overrides the verdict, never the ledgers: the
-* drift entry that parked the spec stays open, so the repair loop keeps its
-* reason to fix the test, while the verdict stops asking a person for what a
-* person already did.
+* A person's judgement that an `ENVIRONMENT` failure's cause is gone, not a
+* hand re-test of the behaviour. It overrides the verdict, never the ledgers:
+* the drift entry that parked the spec stays open, so the repair loop keeps
+* its reason to fix the test, while the verdict stops asking a person for
+* what a person already answered.
 *
 * Anchored to the deploy head at the moment it was recorded, so it lapses on
 * its own — a deploy reaching the spec, or the spec being edited, ends its
@@ -20166,7 +20988,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 attestCommand = new Command("attest").argument("<feature/spec>", "Spec id, e.g. checkout/happy-path").description("Record that a person checked a spec's behaviour by hand against the deployed environment. The verdict answers manuallyVerified instead of asking a person for what a person already did — the drift ledger is untouched, so the repair loop keeps its reason to fix the test. The attestation lapses on its own when a deploy reaches the spec or the spec is edited.").requiredOption("--profile <name>", "Environment that was checked (e.g. 'stg'). The attestation is anchored to its current deploy head.").option("--by <name>", "Who checked. Required unless --revoke.").option("--note <text>", "What was checked and how — the reader deciding whether to trust it sees this.").option("--revoke", "Withdraw the spec's attestation instead of recording one.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Hub project. Defaults to the current directory's name.").option("--cwd <path>", "Directory the default --project name is resolved against.").action(withHubErrors(async (rawSpecId, opts) => {
+const attestCommand = new Command("attest").argument("<feature/spec>", "Spec id, e.g. checkout/happy-path").description("Record a person's judgement that an ENVIRONMENT failure's cause is gone. The verdict answers manuallyVerified instead of asking a person for what a person already answered — the drift ledger is untouched, so the repair loop keeps its reason to fix the test. The attestation lapses on its own when a deploy reaches the spec or the spec is edited, and the spec rejoins the run cycle for the next run to settle.").requiredOption("--profile <name>", "Environment the attestation covers (e.g. 'stg'). It is anchored to that environment's current deploy head.").option("--by <name>", "Whose judgement this is. Required unless --revoke.").option("--note <text>", "What was broken, and what resolved it — the reader deciding whether to trust it sees this.").option("--revoke", "Withdraw the spec's attestation instead of recording one.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Hub project. Defaults to the current directory's name.").option("--cwd <path>", "Directory the default --project name is resolved against.").action(withHubErrors(async (rawSpecId, opts) => {
 	const project = resolveProject(opts);
 	const hub = connect$2(opts);
 	const specId = requireSpecId(rawSpecId);
@@ -21049,7 +21871,7 @@ async function runLiveSpecs(cases, opts) {
 	meta("live-specs", cases.length);
 	const userPromptBundle = await loadPromptBundle(opts.hubContext ?? null, "live", cwd);
 	if (userPromptBundle !== null) meta("prompt", userPromptBundle.loaded.join(" + "));
-	const conventions = await loadConventions(cwd, opts.conventions ?? []);
+	const conventions = await loadConventions(cwd, { guides: opts.conventions ?? [] });
 	for (const w of conventions.warnings) warn(w);
 	const userPromptSuffix = [userPromptBundle?.text ?? "", ...conventions.sections.map((s) => `### ${s.path}\n\n${s.body}`)].filter((part) => part !== "").join("\n\n") || null;
 	const diffProvider = opts.diffProvider ?? null;
@@ -21576,10 +22398,7 @@ function externalGroupFor(plugin, targetConfig) {
 		runner: plugin.runner,
 		targetConfig,
 		defaultTestPath: plugin.defaultTestPath,
-		stepEvidence: plugin.stepEvidence ?? {
-			supported: false,
-			reason: `the "${plugin.id}" target does not capture step screenshots`
-		},
+		stepEvidence: resolveStepEvidence(plugin, targetConfig),
 		browserCoverage: plugin.browserCoverage
 	};
 }
@@ -24865,10 +25684,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		if (!injected.ok) throw new RunUsageError(`could not restore ${opts.sessionState}: ${injected.error ?? "unknown error"} — the case expects to start signed in, so recording was not attempted`);
 		meta("session", opts.sessionState);
 	}
-	const conventions = opts.conventions ? await loadConventions(opts.cwd ?? process.cwd(), opts.conventions) : {
-		sections: [],
-		warnings: []
-	};
+	const conventions = await loadConventions(opts.cwd ?? process.cwd(), { guides: opts.conventions ?? [] });
 	for (const w of conventions.warnings) warn(w);
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: testCase.title,
@@ -30479,11 +31295,11 @@ function createGetAttestationsHandler(storage) {
 	};
 }
 /**
-* PUT /api/v1/projects/:project/attestations?profile= — record that a person
-* checked a spec by hand. The hub stamps the time and the profile's deploy
-* head: the anchor must be what the hub knows was deployed at this moment,
-* not what the caller believes. Replaces any previous attestation for the
-* spec.
+* PUT /api/v1/projects/:project/attestations?profile= — record a person's
+* judgement that a spec's environment failure is resolved. The hub stamps the
+* time and the profile's deploy head: the anchor must be what the hub knows
+* was deployed at this moment, not what the caller believes. Replaces any
+* previous attestation for the spec.
 */
 function createPutAttestationHandler(storage) {
 	return async (ctx) => {